Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(docx): docx_engine for Word parsing, layout, and editing (#7466)

Jacob Beckerman0d7f78010bf2
diff --git a/.config/hakari.toml b/.config/hakari.toml
index 6190888918..e638a85cc8 100644
--- a/.config/hakari.toml
+++ b/.config/hakari.toml
@@ -102,6 +102,10 @@ workspace-members = [
# module in the editor's worker) as well as in the AI tools, so it must
# stay wasm-safe.
"pptx_engine",
+ # docx_engine: the Word engine runs in the browser (a wasm32 module in the
+ # document editor's worker) on top of pptx_engine, so it must stay
+ # wasm-safe too.
+ "docx_engine",
# soup-filter-projection is intentionally absent: its wasm-facing adapter
# disables the native-only default `models` feature, so the crate itself
# does not pull workspace-hack into wasm dependency traversal.
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index a758d23fa7..483154bc01 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -4892,6 +4892,10 @@
"crates/user_quota",
"crates/workspace-hack"
],
+ "docx_engine": [
+ "crates/docx_engine",
+ "crates/pptx_engine"
+ ],
"docx_unzip_handler": [
"crates/activity",
"crates/agent",
@@ -7676,7 +7680,6 @@
"crates/non_empty",
"crates/notification",
"crates/notification_state",
- "crates/pptx_engine",
"crates/prompt",
"crates/properties",
"crates/rate_limit",
diff --git a/Cargo.lock b/Cargo.lock
index 45e9721a27..7a2bb424af 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -6388,6 +6388,21 @@ dependencies = [
"workspace-hack",
]
+[[package]]
+name = "docx_engine"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "clap",
+ "console_error_panic_hook",
+ "js-sys",
+ "pptx_engine",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+ "wasm-bindgen",
+]
+
[[package]]
name = "docx_unzip_handler"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 6261788cf9..1d71eca6ae 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -91,6 +91,7 @@ members = [
"crates/notification_state",
"crates/pipedream_mcp",
"crates/onboarding",
+ "crates/docx_engine",
"crates/pptx_engine",
"crates/predicate_index",
"crates/prompt",
diff --git a/apps/web/justfile b/apps/web/justfile
index 7988946782..b7f6d6a42d 100644
--- a/apps/web/justfile
+++ b/apps/web/justfile
@@ -116,9 +116,10 @@ cache_wasm_target := justfile_directory() / "../../target/cache-wasm"
agent_fold_wasm_target := justfile_directory() / "../../target/agent-fold-wasm"
database_sql_wasm_target := justfile_directory() / "../../target/database-sql-wasm"
pptx_engine_wasm_target := justfile_directory() / "../../target/pptx-engine-wasm"
+docx_engine_wasm_target := justfile_directory() / "../../target/docx-engine-wasm"
[parallel]
-build-wasm: build-cache-wasm build-agent-fold-wasm build-database-sql-wasm build-pptx-engine-wasm
+build-wasm: build-cache-wasm build-agent-fold-wasm build-database-sql-wasm build-pptx-engine-wasm build-docx-engine-wasm
build-dev: build-wasm
MODE=development NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build
@@ -323,6 +324,23 @@ ensure-pptx-engine-wasm:
just --justfile "{{justfile()}}" build-pptx-engine-wasm
fi
+# Build the docx-engine wasm module (DOCX layout, rendering and editing, hosted
+# in a worker by the write block) into src/lib/core/docx-engine/wasm (gitignored).
+build-docx-engine-wasm:
+ CARGO_TARGET_DIR="{{docx_engine_wasm_target}}" CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUSTFLAGS="-C target-feature=+simd128" wasm-pack build {{justfile_directory()}}/../../crates/docx_engine --target web --release --out-dir {{justfile_directory()}}/src/lib/core/docx-engine/wasm
+
+# Dev fast path: build the docx-engine wasm pkg only when it is missing or any
+# engine source (including the pptx engine it builds on) is newer than it.
+ensure-docx-engine-wasm:
+ #!/usr/bin/env bash
+ set -euo pipefail
+ WASM="{{justfile_directory()}}/src/lib/core/docx-engine/wasm/docx_engine_bg.wasm"
+ CRATE="{{justfile_directory()}}/../../crates/docx_engine"
+ PPTX="{{justfile_directory()}}/../../crates/pptx_engine"
+ if [ ! -f "$WASM" ] || [ -n "$(find "$CRATE/src" "$CRATE/Cargo.toml" "$PPTX/src" "$PPTX/fonts" "$PPTX/Cargo.toml" -newer "$WASM" -print -quit)" ]; then
+ just --justfile "{{justfile()}}" build-docx-engine-wasm
+ fi
+
# Regenerate src/lib/service-clients/service-agent-fold/generated/types.ts
# from agent_fold's Rust wire types with specta. Run after changing anything
# under crates/agent_fold/src/inbound/wire.rs. Specta's own output is tabs and
diff --git a/apps/web/package.json b/apps/web/package.json
index ac1f000886..35a0fee027 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -4,7 +4,7 @@
"private": true,
"type": "module",
"scripts": {
- "dev": "just ensure-cache-wasm && just ensure-agent-fold-wasm && just ensure-database-sql-wasm && just ensure-pptx-engine-wasm && vite -c vite.config.ts",
+ "dev": "just ensure-cache-wasm && just ensure-agent-fold-wasm && just ensure-database-sql-wasm && just ensure-pptx-engine-wasm && just ensure-docx-engine-wasm && vite -c vite.config.ts",
"build": "vite build -c vite.config.ts && bun run postbuild:semver && bun run postbuild:bundle-manifest",
"postbuild:semver": "echo $npm_package_version+$(git rev-parse --short HEAD) > ./dist/semver.txt",
"postbuild:bundle-manifest": "bun ./scripts/write-bundle-manifest.mjs",
@@ -135,7 +135,6 @@
"detect-browser": "^5.3.0",
"diff": "^9.0.0",
"dinero.js": "2.0.0-alpha.8",
- "docxodus": "12.6.5",
"effect": "^4.0.0-rc.111",
"email-validator": "^2.0.4",
"emojibase-data": "^17.0.0",
diff --git a/apps/web/scripts/docxodus-runtime.ts b/apps/web/scripts/docxodus-runtime.ts
deleted file mode 100644
index 84827f98bb..0000000000
--- a/apps/web/scripts/docxodus-runtime.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { createReadStream, readdirSync, readFileSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { Plugin } from 'vite';
-
-/**
- * Serve and emit the Docxodus .NET WebAssembly runtime.
- *
- * `dotnet.js` loads its sibling assemblies by name from its own directory, so
- * the runtime has to keep its `_framework` layout and file names; bundling the
- * files individually would hash them apart. The runtime is published under a
- * versioned path (`docxodus/<version>/_framework/…`) so a deploy never mixes
- * JavaScript wrappers from one release with assemblies from another.
- * Precompressed `.br` twins are skipped: hosts negotiate compression.
- */
-export function docxodusRuntime(): Plugin {
- // The package exports only its ESM entry (dist/index.js); its root is two up.
- const packageRoot = dirname(dirname(fileURLToPath(import.meta.resolve('docxodus'))));
- const { version } = JSON.parse(
- readFileSync(join(packageRoot, 'package.json'), 'utf8')
- ) as { version: string };
- const framework = join(packageRoot, 'dist/wasm/_framework');
- const prefix = `docxodus/${version}/_framework/`;
- const files = () =>
- readdirSync(framework).filter(
- (name) => !name.endsWith('.br') && statSync(join(framework, name)).isFile()
- );
- const contentType = (name: string) =>
- name.endsWith('.wasm')
- ? 'application/wasm'
- : name.endsWith('.js')
- ? 'text/javascript'
- : name.endsWith('.json')
- ? 'application/json'
- : 'application/octet-stream';
-
- return {
- name: 'docxodus-runtime',
- config: () => ({
- define: {
- 'import.meta.env.DOCXODUS_VERSION': JSON.stringify(version),
- },
- }),
- configureServer(server) {
- server.middlewares.use((req, res, next) => {
- const path = req.url?.split('?')[0] ?? '';
- const at = path.indexOf(prefix);
- if (at < 0) return next();
- const name = path.slice(at + prefix.length);
- if (!files().includes(name)) return next();
- res.setHeader('Content-Type', contentType(name));
- res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
- createReadStream(join(framework, name)).pipe(res);
- });
- },
- generateBundle() {
- for (const name of files())
- this.emitFile({
- type: 'asset',
- fileName: `${prefix}${name}`,
- source: readFileSync(join(framework, name)),
- });
- },
- };
-}
diff --git a/apps/web/src/features/block-write/DocxBlock.tsx b/apps/web/src/features/block-write/DocxBlock.tsx
index 81786e7e6e..ca8a591c3c 100644
--- a/apps/web/src/features/block-write/DocxBlock.tsx
+++ b/apps/web/src/features/block-write/DocxBlock.tsx
@@ -32,14 +32,7 @@ import { downloadFile } from '@filesystem/download';
import IconShared from '@icon/share.svg';
import { useMessageRootsQuery } from '@queries/messages/document-messages';
import { Badge } from '@ui';
-import {
- createMemo,
- createSignal,
- Match,
- onMount,
- Show,
- Switch,
-} from 'solid-js';
+import { createMemo, Match, onMount, Show, Switch } from 'solid-js';
import type { DocxBlockData } from './definition';
import {
buildDocxSeed,
@@ -49,7 +42,6 @@ import {
initializeDocxSync,
} from './queries/docx-document';
import { createDocxSession } from './queries/docx-session';
-import { type DocxodusRuntime, loadDocxodus } from './queries/docxodus-runtime';
import { DocxCommentMargin, DocxDetachedComments } from './views/DocxComments';
import { DocxEditorView } from './views/DocxEditorView';
@@ -98,14 +90,6 @@ export default function DocxBlock(props: { share?: string }) {
const roots = useMessageRootsQuery(parent);
// Gated: reading a pending query's data would suspend and blank the editor.
const rootThreads = () => (roots.isSuccess ? (roots.data ?? []) : []);
- // A plain signal, not a resource: reading a pending resource would suspend
- // the block and blank it while the engine streams in.
- const [runtime, setRuntime] = createSignal<DocxodusRuntime>();
- const [runtimeError, setRuntimeError] = createSignal(false);
- loadDocxodus().then(setRuntime, (error: unknown) => {
- console.error('DOCX engine failed to load', error);
- setRuntimeError(true);
- });
const reportError = (error: unknown) => {
console.error('DOCX editor error', error);
toast.failure(
@@ -179,7 +163,7 @@ export default function DocxBlock(props: { share?: string }) {
);
return (
<Switch>
- <Match when={state().t === 'error' || runtimeError()}>
+ <Match when={state().t === 'error'}>
<div class="p-6 text-sm text-failure">
{(() => {
const current = state();
@@ -189,69 +173,63 @@ export default function DocxBlock(props: { share?: string }) {
})()}
</div>
</Match>
- <Match when={!runtime() || !target()}>
+ <Match when={!target()}>
<div class="p-6 text-sm text-ink-muted">
Opening document…
</div>
</Match>
- <Match when={runtime()}>
- {(engine) => (
- <Show when={target()} keyed>
- {({ doc, original }) => (
- <DocxEditorView
- runtime={engine()}
- doc={doc}
- original={original}
- canEdit={!!doc && canEdit()}
+ <Match when={target()} keyed>
+ {({ doc, original }) => (
+ <DocxEditorView
+ doc={doc}
+ original={original}
+ canEdit={!!doc && canEdit()}
+ canComment={() => !!doc && canComment()}
+ fileName={fileName()}
+ peers={session.peers}
+ displayName={displayName}
+ author={displayName(userId())}
+ documentId={documentId}
+ onSelection={session.setSelection}
+ commentRoots={doc ? rootThreads : undefined}
+ margin={(context) => (
+ <DocxCommentMargin
+ documentId={documentId}
+ comments={context.comments}
+ geometry={context.geometry}
+ selectionTop={context.selectionTop}
canComment={() => !!doc && canComment()}
- author={displayName(userId()) || 'Macro user'}
- fileName={fileName()}
- peers={session.peers}
- displayName={displayName}
- onSelection={session.setSelection}
- subscribeRemote={session.onRemoteChange}
- commentRoots={doc ? rootThreads : undefined}
- margin={(context) => (
- <DocxCommentMargin
- documentId={documentId}
- comments={context.comments}
- editorRoot={context.editorRoot}
- margin={context.margin}
- revision={context.revision}
- canComment={() => !!doc && canComment()}
- isOwner={isOwner}
- userId={userId}
- />
- )}
- footer={(comments) => (
- <>
- <DocxDetachedComments
- documentId={documentId}
- threads={comments.detached()}
- canComment={canComment}
- isOwner={isOwner}
- />
- <EntityDiscussion
- parent={parent()}
- canWrite={canComment()}
- canModerate={isOwner()}
- link={{ type: 'write', id: documentId }}
- label="Discussion"
- />
- </>
- )}
- onDownload={(bytes) =>
- downloadFile(
- new Blob([bytes.slice().buffer], {
- type: DOCX_MIME,
- }),
- fileName()
- )
- }
- onError={reportError}
+ isOwner={isOwner}
+ userId={userId}
/>
)}
- </Show>
+ footer={(comments) => (
+ <>
+ <DocxDetachedComments
+ documentId={documentId}
+ threads={comments.detached()}
+ canComment={canComment}
+ isOwner={isOwner}
+ />
+ <EntityDiscussion
+ parent={parent()}
+ canWrite={canComment()}
+ canModerate={isOwner()}
+ link={{ type: 'write', id: documentId }}
+ label="Discussion"
+ />
+ </>
+ )}
+ onDownload={(bytes) =>
+ downloadFile(
+ new Blob([bytes.slice().buffer], {
+ type: DOCX_MIME,
+ }),
+ fileName()
+ )
+ }
+ onError={reportError}
+ />
)}
</Match>
</Switch>
diff --git a/apps/web/src/features/block-write/browser-test/README.md b/apps/web/src/features/block-write/browser-test/README.md
index 808c523147..769bbff102 100644
--- a/apps/web/src/features/block-write/browser-test/README.md
+++ b/apps/web/src/features/block-write/browser-test/README.md
@@ -3,18 +3,35 @@
These tests run the production `DocxEditorView` in real Chromium against the
real sync service. They do not use the app shell. The compiled Rust sync
Worker runs in Miniflare (`sync-server.ts`), so they need no dev login,
-backend or Docker.
+backend or Docker. Pages are drawn by the native DOCX engine (Rust compiled
+to wasm, `crates/docx_engine`) in a worker; build it first.
- `fixture.tsx` mounts one editor per tab with `createDocxSession`. Its
comment threads are stored in a Loro map in place of the message service,
- and it exposes `window.docxFixture` for assertions.
+ and it exposes `window.docxFixture` for assertions: the engine's paragraph
+ texts, the shared document's blocks and parts, comment marks, and `place`
+ to put the caret in (or select) a paragraph by its first words.
- `collaboration.browser.e2e.ts` opens several people on one document and
tests:
- - live and concurrent edits, formatting and lists;
- - read-only viewers and header edits;
+ - live and concurrent typing (including at the same spot), Enter, peer
+ carets, bold and lists as shared marks and properties;
+ - comments with highlights, kept on their text through edits;
+ - the downloaded `.docx` and reloading the merged document;
+ - sixty random edits each from two people at once (typing, Enter,
+ deleting, bold), converging for both and for someone opening it after;
+ - undo and redo of one person's own edits;
+ - header and footer editing in place;
+ - footnote editing in place and a new footnote (Ctrl+Alt+F) in a memo
+ built by the test, shared and downloaded;
+ - Word comments in the file shown beside their text (a memo built by the
+ test);
+ - tracked changes recorded per author, then rejected for everyone;
+ - find and replace (one match, then all, undone in one step);
+ - toolbar formatting (highlight, color, line spacing) and table rows;
+ - touch input (swipe, tap, double tap, held press);
+ - read-only viewers following along;
- an offline merge;
- - comments, including table cells;
- - the downloaded `.docx`.
+ - comment cards leaving a narrow pane a legible page.
- `agent.browser.e2e.ts` runs the AI tools' `runDocxAgentRequest` as its own
sync peer, exactly as the editing worker does, and checks that reads see
the live document and that edits reach an open editor and survive a reopen.
@@ -22,10 +39,17 @@ backend or Docker.
```sh
(\cd services/sync-service && just worker-build) # once, builds build/worker/shim.mjs
\cd apps/web
+just ensure-docx-engine-wasm # builds the engine's wasm when sources changed
bunx playwright test -c src/features/block-write/browser-test/playwright.config.ts
```
Set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` when Playwright's bundled Chromium
-is not installed. The fixture serves on port 3018 and must be reached as
+is not installed. `DOCX_E2E_SHOTS=<dir>` saves screenshots and the downloaded
+file along the way. The fixture serves on port 3018 and must be reached as
`localhost`, because the sync Worker only accepts `http://localhost:3000-3999`
origins.
+
+Without the sync service, `http://localhost:3018/?local` opens the fixture
+document in one editor and `?local=pair` in two editors that exchange
+updates directly; add `&fixture=complex-msa.docx` for the document with a
+table, picture, header and footer.
diff --git a/apps/web/src/features/block-write/browser-test/agent.browser.e2e.ts b/apps/web/src/features/block-write/browser-test/agent.browser.e2e.ts
index 893ede9049..68d75d5a5a 100644
--- a/apps/web/src/features/block-write/browser-test/agent.browser.e2e.ts
+++ b/apps/web/src/features/block-write/browser-test/agent.browser.e2e.ts
@@ -34,6 +34,23 @@ const paragraphs = async (page: Page) =>
'\n'
);
+/** Whether `text` is bold in the shared paragraph starting with `prefix`. */
+const sharedBold = (page: Page, prefix: string) =>
+ page.evaluate(
+ (prefix) =>
+ (window.docxFixture?.sharedBlock(prefix)?.attrs ?? []).some((a) =>
+ Object.keys(a).some((key) => /^r:.*:b$/.test(key))
+ ),
+ prefix
+ );
+
+/** Caret at the end of the paragraph starting with `prefix`, input focused. */
+async function caretAtEnd(page: Page, prefix: string) {
+ expect(
+ await page.evaluate((p) => window.docxFixture?.place(p, 'end'), prefix)
+ ).toBe(true);
+}
+
/** What the AI tools do, run the way the editing worker runs it. */
const agent = (page: Page, request: DocxAgentRequest) =>
page.evaluate(
@@ -44,7 +61,7 @@ const agent = (page: Page, request: DocxAgentRequest) =>
/** The id ReadWordDocument shows for the paragraph whose text starts so. */
function paragraphId(description: string, text: string): string {
const escaped = text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
- const match = new RegExp(`paragraph (\\w{32})[^\\n]*\\n\\s+${escaped}`).exec(
+ const match = new RegExp(`paragraph (\\S+)[^\\n]*\\n\\s+${escaped}`).exec(
description
);
if (!match) throw new Error(`no paragraph starting "${text}"`);
@@ -72,7 +89,7 @@ test('AI tool edits reach an open editor live and survive a reopen', async ({
await open(worker, documentId, AGENT);
const read = await agent(worker, { action: 'read' });
- expect(read).toContain('Word document with 17 blocks.');
+ expect(read).toMatch(/Word document with \d+ blocks\./);
const term = paragraphId(read, 'This Agreement shall remain');
const heading = paragraphId(read, '3. Term');
const definition = paragraphId(read, '"Confidential Information" means');
@@ -110,21 +127,15 @@ test('AI tool edits reach an open editor live and survive a reopen', async ({
expect(text).toMatch(
/3\. Term\nThis section sets out how long the Agreement lasts\.\nThis Agreement shall remain/
);
- const bold = alice
- .locator('.docx-body-flow [data-anchor]')
- .filter({ hasText: '"Confidential Information" means' })
- .locator('span, b, strong')
- .filter({ hasText: /^Confidential Information$/ })
- .first();
- await expect(bold).toHaveCSS('font-weight', '700');
+ await expect
+ .poll(() => sharedBold(alice, '"Confidential Information" means'))
+ .toBe(true);
+ expect(await agent(worker, { action: 'read' })).toContain(
+ 'bold: "Confidential Information"'
+ );
// People keep editing alongside it.
- await alice
- .locator('.docx-body-flow [data-anchor][contenteditable="true"]')
- .filter({ hasText: 'This section sets out' })
- .first()
- .click();
- await alice.keyboard.press('End');
+ await caretAtEnd(alice, 'This section sets out');
await alice.keyboard.type(' [alice]');
await expect
.poll(() => paragraphs(worker))
@@ -162,7 +173,7 @@ test('AI tool edits inside table cells', async ({ browser }) => {
await open(alice, documentId, ALICE, { fixture: 'complex-msa.docx' });
await open(worker, documentId, AGENT, { fixture: 'complex-msa.docx' });
const read = await agent(worker, { action: 'read' });
- const cell = /row 2, cell 1:\n\s+paragraph (\w{32})/.exec(read)?.[1];
+ const cell = /row 2, cell 1:\n\s+paragraph (\S+)/.exec(read)?.[1];
expect(cell).toBeDefined();
await agent(worker, {
action: 'edit',
diff --git a/apps/web/src/features/block-write/browser-test/collaboration.browser.e2e.ts b/apps/web/src/features/block-write/browser-test/collaboration.browser.e2e.ts
index ee6f6a6e30..64641fa57c 100644
--- a/apps/web/src/features/block-write/browser-test/collaboration.browser.e2e.ts
+++ b/apps/web/src/features/block-write/browser-test/collaboration.browser.e2e.ts
@@ -1,6 +1,6 @@
import { readFile } from 'node:fs/promises';
import { expect, type Page, test } from '@playwright/test';
-import { strFromU8, unzipSync } from 'fflate';
+import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
import type { Miniflare } from 'miniflare';
import { fixtureUrl, startSyncServer } from './sync-server';
@@ -19,15 +19,15 @@ test.afterAll(async () => {
await server?.dispose();
});
-async function open(page: Page, documentId: string, user: string, extra = {}) {
- // Text painted by the comment highlights, for assertions.
- await page.addInitScript(() => {
- globalThis.highlightedText = () =>
- Array.from(CSS.highlights.values())
- .flatMap((highlight) => Array.from(highlight))
- .map((range) => range.toString())
- .join('\n');
+/** Echoes a collaborator's console errors into the test output. */
+function logErrors(page: Page, name: string) {
+ page.on('console', (message) => {
+ if (message.type() === 'error') console.log(`[${name}]`, message.text());
});
+ page.on('pageerror', (error) => console.log(`[${name}]`, error.message));
+}
+
+async function open(page: Page, documentId: string, user: string, extra = {}) {
await page.goto(fixtureUrl(BASE, serverUrl, documentId, user, extra));
await expect
.poll(() => page.evaluate(() => window.docxFixture?.ready() ?? false), {
@@ -37,63 +37,40 @@ async function open(page: Page, documentId: string, user: string, extra = {}) {
await expect
.poll(() => page.evaluate(() => window.docxFixture?.status()))
.toBe('connected');
- // The document's own stylesheet ("body { margin: 20px }") must stay inside
- // the editor; leaking it shifts the whole app.
- expect(
- await page.evaluate(() => getComputedStyle(document.body).margin)
- ).toBe('0px');
+ // Pages are drawn by the engine into canvases.
+ await expect(page.locator('[data-docx-page] canvas').first()).toBeVisible();
}
+/** Paragraph texts as a collaborator's engine has them. */
const paragraphs = (page: Page) =>
page.evaluate(() => window.docxFixture?.paragraphs() ?? []);
-/** The editable paragraph whose text starts with `prefix`. */
-const paragraph = (page: Page, prefix: string) =>
- page
- .locator('.docx-body-flow [data-anchor][contenteditable="true"]')
- .filter({ hasText: prefix })
- .first();
+const joined = async (page: Page) => (await paragraphs(page)).join('\n');
-/** Select a whole paragraph's text, as a user dragging across it would. */
-async function selectParagraph(page: Page, prefix: string) {
- await paragraph(page, prefix).click();
- await page.evaluate((text) => {
- const block = Array.from(
- document.querySelectorAll<HTMLElement>(
- '.docx-body-flow [data-anchor][contenteditable="true"]'
- )
- ).find((element) => element.textContent?.includes(text));
- if (!block) throw new Error(`no paragraph ${text}`);
- const range = document.createRange();
- range.selectNodeContents(block);
- const selection = window.getSelection()!;
- selection.removeAllRanges();
- selection.addRange(range);
- }, prefix);
+/** Caret at the end of the paragraph starting with `prefix`, input focused. */
+async function caretAtEnd(page: Page, prefix: string) {
+ expect(
+ await page.evaluate((p) => window.docxFixture?.place(p, 'end'), prefix)
+ ).toBe(true);
}
-/** Computed weight of the first text run in the paragraph containing `text`. */
-const fontWeightAt = (page: Page, text: string) =>
- page.evaluate((needle) => {
- const block = Array.from(
- document.querySelectorAll<HTMLElement>('.docx-body-flow [data-anchor]')
- ).find((element) => element.textContent?.includes(needle));
- const walker =
- block && document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
- const node = walker?.nextNode();
- return node?.parentElement
- ? getComputedStyle(node.parentElement).fontWeight
- : '';
- }, text);
-
-declare global {
- function highlightedText(): string;
+async function selectParagraph(page: Page, prefix: string) {
+ expect(
+ await page.evaluate((p) => window.docxFixture?.place(p, 'all'), prefix)
+ ).toBe(true);
}
-async function caretAtEnd(page: Page, prefix: string) {
- const target = paragraph(page, prefix);
- await target.click();
- await page.keyboard.press('End');
+const sharedBlock = (page: Page, prefix: string) =>
+ page.evaluate((p) => window.docxFixture?.sharedBlock(p) ?? null, prefix);
+
+/** Start tags of the elements wrapping a shared paragraph's text. */
+async function wrappers(page: Page, prefix: string) {
+ const attrs = (await sharedBlock(page, prefix))?.attrs ?? [];
+ return attrs
+ .flatMap((a) =>
+ a.wrap ? (JSON.parse(a.wrap) as [string, string][]).map(([o]) => o) : []
+ )
+ .join(' ');
}
test('two people edit the same DOCX live through the sync service', async ({
@@ -107,11 +84,8 @@ test('two people edit the same DOCX live through the sync service', async ({
const [alice, bob] = await Promise.all(
contexts.map((context) => context.newPage())
);
- for (const page of [alice, bob])
- page.on('console', (message) => {
- if (message.type() === 'error')
- console.log(`[${page === alice ? 'alice' : 'bob'}]`, message.text());
- });
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
try {
// Alice opens an unseen document: her client seeds it from the upload.
await open(alice, documentId, ALICE);
@@ -119,11 +93,11 @@ test('two people edit the same DOCX live through the sync service', async ({
expect(await paragraphs(bob)).toEqual(await paragraphs(alice));
if (SHOTS) await alice.screenshot({ path: `${SHOTS}/01-opened.png` });
- // Typing is committed while Alice pauses and reaches Bob without a blur.
+ // Typing reaches Bob as it happens.
await caretAtEnd(alice, 'This Agreement shall remain');
await alice.keyboard.type(' Renewal requires mutual written consent.');
await expect
- .poll(async () => (await paragraphs(bob)).join('\n'))
+ .poll(() => joined(bob))
.toContain('Renewal requires mutual written consent.');
// Concurrent edits to different paragraphs both survive.
@@ -131,15 +105,23 @@ test('two people edit the same DOCX live through the sync service', async ({
await alice.keyboard.type(' [alice]');
await caretAtEnd(bob, 'This Agreement shall be governed');
await bob.keyboard.type(' [bob]');
- await alice.locator('body').press('Escape');
for (const page of [alice, bob]) {
- await expect
- .poll(async () => (await paragraphs(page)).join('\n'))
- .toContain('[alice]');
- await expect
- .poll(async () => (await paragraphs(page)).join('\n'))
- .toContain('[bob]');
+ await expect.poll(() => joined(page)).toContain('[alice]');
+ await expect.poll(() => joined(page)).toContain('[bob]');
+ }
+
+ // Concurrent typing in the same paragraph merges character by character.
+ await caretAtEnd(alice, 'This Agreement shall remain');
+ await caretAtEnd(bob, 'This Agreement shall remain');
+ await Promise.all([
+ alice.keyboard.type(' [one]'),
+ bob.keyboard.type(' [two]'),
+ ]);
+ for (const page of [alice, bob]) {
+ await expect.poll(() => joined(page)).toContain('[one]');
+ await expect.poll(() => joined(page)).toContain('[two]');
}
+ await expect.poll(() => paragraphs(bob)).toEqual(await paragraphs(alice));
// Enter splits a paragraph for everyone.
const before = (await paragraphs(alice)).length;
@@ -150,7 +132,7 @@ test('two people edit the same DOCX live through the sync service', async ({
.poll(async () => (await paragraphs(alice)).length)
.toBe(before + 1);
await expect
- .poll(async () => (await paragraphs(alice)).join('\n'))
+ .poll(() => joined(alice))
.toContain('Signed by the parties below.');
// Each sees the other's caret.
@@ -159,29 +141,29 @@ test('two people edit the same DOCX live through the sync service', async ({
if (SHOTS)
await alice.screenshot({ path: `${SHOTS}/02-collaborating.png` });
- // Toolbar formatting propagates.
+ // Toolbar formatting is stored as text marks and reaches Bob.
await selectParagraph(alice, 'This Agreement shall be governed');
await alice.getByRole('button', { name: 'Bold' }).click();
await expect
- .poll(() => fontWeightAt(bob, 'This Agreement shall be governed'))
- .toBe('700');
+ .poll(async () =>
+ (
+ await sharedBlock(bob, 'This Agreement shall be governed')
+ )?.attrs.every((a) => 'r:w:b' in a)
+ )
+ .toBe(true);
- // A list toggle changes the numbering part: Bob's editor remounts on it.
- await paragraph(alice, '"Confidential Information" means').click();
+ // A list toggle adds numbering to the paragraph (and a definition).
+ await caretAtEnd(alice, '"Confidential Information" means');
await alice.getByRole('button', { name: 'Bulleted list' }).click();
await expect
- .poll(() =>
- bob.evaluate(
- () =>
- Array.from(
- document.querySelectorAll('.docx-body-flow [data-list-marker]')
- ).length
- )
+ .poll(
+ async () =>
+ (await sharedBlock(bob, '"Confidential Information" means'))?.props
)
- .toBeGreaterThan(3);
+ .toContain('numPr');
- // Comments: select any line, comment, and the thread appears beside it
- // for both collaborators, with the text highlighted.
+ // Comments: select a paragraph, comment, and the thread appears beside
+ // it for both collaborators, with the text highlighted.
await selectParagraph(alice, 'Each party shall use');
await alice.getByRole('button', { name: 'Comment on selection' }).click();
await alice
@@ -199,31 +181,14 @@ test('two people edit the same DOCX live through the sync service', async ({
await expect(page.locator('[data-docx-thread]')).toContainText(
'Limit this to the evaluation period?'
);
- await expect
- .poll(() => page.evaluate(() => highlightedText()))
- .toContain('Each party shall use the Confidential Information');
+ await expect(
+ page.locator('[data-docx-comment-highlight]').first()
+ ).toBeVisible();
}
- // The floating button comments on a selection inside a table cell too.
- await selectParagraph(bob, 'Retainer');
- await bob
- .locator(
- '[data-docx-comment-button] button, button[data-docx-comment-button]'
- )
- .first()
- .click();
- await bob
- .getByRole('textbox', { name: 'Comment text' })
- .fill('Confirm the retainer amount.');
- await bob.getByRole('button', { name: 'Comment', exact: true }).click();
- await expect(alice.locator('[data-docx-thread]')).toHaveCount(2);
// Edits to commented text keep the thread on it.
await caretAtEnd(alice, 'Each party shall use');
await alice.keyboard.type(' during the term');
- await expect
- .poll(() => bob.evaluate(() => highlightedText()), { timeout: 30_000 })
- .toContain(
- 'evaluating a potential business relationship between the parties.'
- );
+ await expect(bob.locator('[data-docx-thread]')).toHaveCount(1);
if (SHOTS) await bob.screenshot({ path: `${SHOTS}/03-comments.png` });
// Download produces a clean .docx carrying everyone's edits.
@@ -238,7 +203,7 @@ test('two people edit the same DOCX live through the sync service', async ({
const documentXml = strFromU8(files['word/document.xml']);
expect(documentXml).toContain('Renewal requires mutual written consent.');
expect(documentXml).toContain('Signed by the parties below.');
- expect(documentXml).not.toContain('Unid=');
+ expect(documentXml).toContain('<w:numPr>');
// Comments are Macro threads: the Word file itself carries no comments.
expect(files['word/comments.xml']).toBeUndefined();
@@ -257,9 +222,88 @@ test('two people edit the same DOCX live through the sync service', async ({
}
});
-test('undo and redo cover typing the editor has not committed yet', async ({
- browser,
-}) => {
+test('random concurrent edits converge for everyone', async ({ browser }) => {
+ const documentId = crypto.randomUUID();
+ const contexts = await Promise.all([
+ browser.newContext(),
+ browser.newContext(),
+ browser.newContext(),
+ ]);
+ const [alice, bob, carol] = await Promise.all(
+ contexts.map((context) => context.newPage())
+ );
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
+ try {
+ await open(alice, documentId, ALICE, { fixture: 'complex-msa.docx' });
+ await open(bob, documentId, BOB, { fixture: 'complex-msa.docx' });
+ /** Sixty edits at random places (typing, Enter, deleting, bold),
+ * some in quick succession, from a seeded generator. */
+ const randomEdits = (page: Page, seed: number) =>
+ page.evaluate(async (seed) => {
+ let state = seed;
+ const rand = (n: number) => {
+ state = (state * 1103515245 + 12345) % 2147483648;
+ return state % n;
+ };
+ const editor = window.docxFixture?.editor();
+ if (!editor) throw new Error('no editor');
+ for (let i = 0; i < 60; i++) {
+ const paras = (await editor.paragraphs()).filter((p) => p.text);
+ const p = paras[rand(paras.length)];
+ const offset = rand(p.text.length + 1);
+ const at = { block: p.id, offset };
+ const kind = rand(10);
+ if (kind < 5)
+ editor.run([
+ { op: 'select', anchor: at, focus: at },
+ { op: 'insertText', text: `<${seed}.${i}>` },
+ ]);
+ else if (kind < 6)
+ editor.run([
+ { op: 'select', anchor: at, focus: at },
+ { op: 'insertParagraph' },
+ ]);
+ else if (kind < 8)
+ editor.run([
+ { op: 'select', anchor: at, focus: at },
+ { op: 'delete', forward: rand(2) === 0 },
+ ]);
+ else {
+ const end = Math.min(p.text.length, offset + 1 + rand(8));
+ editor.run([
+ { op: 'select', anchor: at, focus: { block: p.id, offset: end } },
+ { op: 'toggleFormat', format: 'bold' },
+ ]);
+ }
+ if (rand(3) === 0)
+ await new Promise((resolve) => setTimeout(resolve, rand(40)));
+ }
+ await editor.idle();
+ }, seed);
+ await Promise.all([randomEdits(alice, 7), randomEdits(bob, 11)]);
+ // Both end with the same paragraphs, every insertion kept once.
+ await expect
+ .poll(
+ async () =>
+ JSON.stringify(await paragraphs(alice)) ===
+ JSON.stringify(await paragraphs(bob)),
+ { timeout: 30_000 }
+ )
+ .toBe(true);
+ const text = await joined(alice);
+ for (const seed of [7, 11])
+ for (const match of text.matchAll(new RegExp(`<${seed}\\.(\\d+)>`, 'g')))
+ expect(text.split(match[0]).length - 1, match[0]).toBe(1);
+ // Someone opening it now reads the same document.
+ await open(carol, documentId, BOB, { fixture: 'complex-msa.docx' });
+ expect(await paragraphs(carol)).toEqual(await paragraphs(alice));
+ } finally {
+ await Promise.all(contexts.map((context) => context.close()));
+ }
+});
+
+test('undo and redo cover this person’s own edits', async ({ browser }) => {
const documentId = crypto.randomUUID();
const contexts = await Promise.all([
browser.newContext(),
@@ -268,41 +312,682 @@ test('undo and redo cover typing the editor has not committed yet', async ({
const [alice, bob] = await Promise.all(
contexts.map((context) => context.newPage())
);
- const shared = async () => (await paragraphs(bob)).join('\n');
try {
await open(alice, documentId, ALICE);
await open(bob, documentId, BOB);
- // Undo straight after typing, before the idle commit, and keep going.
- const clause = paragraph(alice, 'This Agreement shall remain');
await caretAtEnd(alice, 'This Agreement shall remain');
await alice.keyboard.type(' [first]');
+ await expect.poll(() => joined(bob)).toContain('[first]');
+ // Bob's concurrent edit elsewhere is not Alice's to undo.
+ await caretAtEnd(bob, '"Representatives" means');
+ await bob.keyboard.type(' [bob]');
+ await expect.poll(() => joined(alice)).toContain('[bob]');
+
await alice.keyboard.press('ControlOrMeta+z');
- await expect(clause).not.toContainText('[first]');
+ await expect.poll(() => joined(alice)).not.toContain('[first]');
+ await expect.poll(() => joined(bob)).not.toContain('[first]');
+ expect(await joined(alice)).toContain('[bob]');
await alice.keyboard.press('ControlOrMeta+Shift+z');
- await expect(clause).toContainText('[first]');
- await expect.poll(shared).toContain('[first]');
- // The caret lands after the redone text, so typing continues there.
- await alice.keyboard.type(' [second]');
- await expect(clause).toContainText('[first] [second]');
- await alice.keyboard.press('ControlOrMeta+z');
- await alice.keyboard.press('ControlOrMeta+z');
- await expect(clause).not.toContainText('[first]');
- await expect.poll(shared).not.toContain('[first]');
- expect(await shared()).not.toContain('[second]');
+ await expect.poll(() => joined(alice)).toContain('[first]');
+ await expect.poll(() => joined(bob)).toContain('[first]');
- // The toolbar commits pending typing the same way.
- await alice.keyboard.type(' [third]');
+ // The toolbar does the same.
await alice.getByRole('button', { name: 'Undo' }).click();
- await expect(clause).not.toContainText('[third]');
+ await expect.poll(() => joined(bob)).not.toContain('[first]');
await alice.getByRole('button', { name: 'Redo' }).click();
- await expect(clause).toContainText('[third]');
- await expect.poll(shared).toContain('[third]');
+ await expect.poll(() => joined(bob)).toContain('[first]');
+ } finally {
+ await Promise.all(contexts.map((context) => context.close()));
+ }
+});
+
+test('headers and footers are edited in place and shared', async ({
+ browser,
+}) => {
+ const documentId = crypto.randomUUID();
+ const contexts = await Promise.all([
+ browser.newContext(),
+ browser.newContext(),
+ ]);
+ const [alice, bob] = await Promise.all(
+ contexts.map((context) => context.newPage())
+ );
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
+ const story = (page: Page) =>
+ page.evaluate(() => window.docxFixture?.editor()?.state()?.story.kind);
+ try {
+ await open(alice, documentId, ALICE, { fixture: 'complex-msa.docx' });
+ await open(bob, documentId, BOB, { fixture: 'complex-msa.docx' });
+
+ // Double-click the header of the first page.
+ const sheet = alice.locator('[data-docx-page="0"]');
+ const box = (await sheet.boundingBox())!;
+ const page = (await alice.evaluate(
+ () => window.docxFixture?.editor()?.pages()[0]
+ ))!;
+ const scale = box.width / page.width;
+ const headerY = ((page.header?.top ?? 0) + (page.header?.bottom ?? 0)) / 2;
+ await alice.mouse.dblclick(box.x + box.width / 2, box.y + headerY * scale);
+ await expect.poll(() => story(alice)).toBe('header');
+ await expect(alice.locator('[data-docx-story-label]')).toContainText(
+ 'Header'
+ );
+ await alice.keyboard.press('End');
+ await alice.keyboard.type(' (Draft 2)');
+ // The header part reaches Bob through the sync service.
+ await expect
+ .poll(() =>
+ bob.evaluate(() => window.docxFixture?.sharedPart('header1.xml'))
+ )
+ .toContain('(Draft 2)');
+ if (SHOTS) await alice.screenshot({ path: `${SHOTS}/05-header.png` });
+
+ // Escape returns to the body, where typing goes to the body again.
+ await alice.keyboard.press('Escape');
+ await expect.poll(() => story(alice)).toBe('body');
+ await caretAtEnd(alice, 'Either party may terminate');
+ await alice.keyboard.type(' [body]');
+ await expect.poll(() => joined(bob)).toContain('[body]');
+
+ // Bob's download carries the new header.
+ const [download] = await Promise.all([
+ bob.waitForEvent('download'),
+ bob.getByRole('button', { name: 'Download .docx' }).click(),
+ ]);
+ const files = unzipSync(
+ new Uint8Array(await readFile((await download.path())!))
+ );
+ expect(strFromU8(files['word/header1.xml'])).toContain('(Draft 2)');
+ } finally {
+ await Promise.all(contexts.map((context) => context.close()));
+ }
+});
+
+const W_NS =
+ 'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"';
+const XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>';
+const WORD_CT =
+ 'application/vnd.openxmlformats-officedocument.wordprocessingml';
+const REL =
+ 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+
+/** A run of text. */
+const run = (t: string) => `<w:r><w:t xml:space="preserve">${t}</w:t></w:r>`;
+
+/**
+ * A one-page DOCX built here rather than kept as a binary fixture, as a
+ * data URL the fixture page can fetch: `body` paragraphs plus parts, each
+ * with its relationship type (a full URI, or one under the office
+ * relationships), content type suffix and XML.
+ */
+function docxDataUrl(
+ body: string,
+ parts: Record<string, { rel: string; type: string; xml: string }> = {}
+) {
+ const sect =
+ '<w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720" w:gutter="0"/></w:sectPr>';
+ const entries = Object.entries(parts);
+ const overrides = entries
+ .map(
+ ([name, p]) =>
+ `<Override PartName="/word/${name}" ContentType="${WORD_CT}.${p.type}+xml"/>`
+ )
+ .join('');
+ const rels = entries
+ .map(
+ ([name, p], i) =>
+ `<Relationship Id="rIdP${i}" Type="${p.rel.includes('://') ? p.rel : `${REL}/${p.rel}`}" Target="${name}"/>`
+ )
+ .join('');
+ const files: Record<string, string> = {
+ '[Content_Types].xml': `${XML_DECL}<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="${WORD_CT}.document.main+xml"/>${overrides}</Types>`,
+ '_rels/.rels': `${XML_DECL}<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="${REL}/officeDocument" Target="word/document.xml"/></Relationships>`,
+ 'word/_rels/document.xml.rels': `${XML_DECL}<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">${rels}</Relationships>`,
+ 'word/document.xml': `${XML_DECL}<w:document ${W_NS}><w:body>${body}${sect}</w:body></w:document>`,
+ };
+ for (const [name, p] of entries) files[`word/${name}`] = p.xml;
+ const zip = zipSync(
+ Object.fromEntries(
+ Object.entries(files).map(([name, xml]) => [name, strToU8(xml)])
+ )
+ );
+ return `data:${WORD_CT}.document;base64,${Buffer.from(zip).toString('base64')}`;
+}
+
+/** A short memo with two footnotes. */
+function footnotedMemo() {
+ const superscript = '<w:rPr><w:vertAlign w:val="superscript"/></w:rPr>';
+ const ref = (id: number) =>
+ `<w:r>${superscript}<w:footnoteReference w:id="${id}"/></w:r>`;
+ const note = (id: number, t: string) =>
+ `<w:footnote w:id="${id}"><w:p><w:r>${superscript}<w:footnoteRef/></w:r><w:r><w:rPr><w:sz w:val="20"/></w:rPr><w:t xml:space="preserve"> ${t}</w:t></w:r></w:p></w:footnote>`;
+ return docxDataUrl(
+ [
+ `<w:p>${run('The Seller shall deliver the Shares at Closing.')}${ref(1)}${run(' The Purchase Price is payable in cash.')}${ref(2)}</w:p>`,
+ `<w:p>${run('Each party bears its own costs.')}</w:p>`,
+ ].join(''),
+ {
+ 'footnotes.xml': {
+ rel: 'footnotes',
+ type: 'footnotes',
+ xml: `${XML_DECL}<w:footnotes ${W_NS}><w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote><w:footnote w:type="continuationSeparator" w:id="0"><w:p><w:r><w:continuationSeparator/></w:r></w:p></w:footnote>${note(1, 'As defined in the Agreement.')}${note(2, 'In United States dollars.')}</w:footnotes>`,
+ },
+ }
+ );
+}
+
+/** A memo carrying Word comments: one with a reply, one resolved. */
+function commentedMemo() {
+ const comment = (id: number, author: string, text: string, para: string) =>
+ `<w:comment w:id="${id}" w:author="${author}" w:date="2026-09-30T10:00:00Z"><w:p w14:paraId="${para}"><w:r><w:t>${text}</w:t></w:r></w:p></w:comment>`;
+ const ranged = (id: number, t: string) =>
+ `<w:commentRangeStart w:id="${id}"/>${run(t)}<w:commentRangeEnd w:id="${id}"/><w:r><w:commentReference w:id="${id}"/></w:r>`;
+ return docxDataUrl(
+ [
+ `<w:p>${run('The ')}${ranged(0, 'Purchase Price')}<w:r><w:commentReference w:id="1"/></w:r>${run(' is payable at Closing.')}</w:p>`,
+ `<w:p>${run('Each party bears ')}${ranged(2, 'its own costs')}${run('.')}</w:p>`,
+ ].join(''),
+ {
+ 'comments.xml': {
+ rel: 'comments',
+ type: 'comments',
+ xml: `${XML_DECL}<w:comments ${W_NS}>${comment(0, 'Opposing Counsel', 'Should this include fees?', '0000000A')}${comment(1, 'Our Firm', 'No, fees are separate.', '0000000B')}${comment(2, 'Opposing Counsel', 'Agreed.', '0000000C')}</w:comments>`,
+ },
+ 'commentsExtended.xml': {
+ rel: 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended',
+ type: 'commentsExtended',
+ xml: `${XML_DECL}<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"><w15:commentEx w15:paraId="0000000A" w15:done="0"/><w15:commentEx w15:paraId="0000000B" w15:paraIdParent="0000000A" w15:done="0"/><w15:commentEx w15:paraId="0000000C" w15:done="1"/></w15:commentsEx>`,
+ },
+ }
+ );
+}
+
+test('comments in the file show beside their text', async ({ browser }) => {
+ const documentId = crypto.randomUUID();
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ logErrors(page, 'alice');
+ try {
+ await open(page, documentId, ALICE, { src: commentedMemo() });
+ // One card per comment, its reply inside it.
+ const first = page.locator('[data-docx-word-comment="0"]');
+ await expect(first).toContainText('Opposing Counsel');
+ await expect(first).toContainText('Should this include fees?');
+ await expect(first).toContainText('No, fees are separate.');
+ await expect(page.locator('[data-docx-word-comment="1"]')).toHaveCount(0);
+ await expect(page.locator('[data-docx-word-comment="2"]')).toContainText(
+ 'Resolved'
+ );
+ // The commented text is highlighted.
+ await expect(
+ page.locator('[data-docx-comment-highlight="word:0"]').first()
+ ).toBeVisible();
+ if (SHOTS) await page.screenshot({ path: `${SHOTS}/06-word-comments.png` });
+ // The comments stay in the downloaded file.
+ const [download] = await Promise.all([
+ page.waitForEvent('download'),
+ page.getByRole('button', { name: 'Download .docx' }).click(),
+ ]);
+ const files = unzipSync(
+ new Uint8Array(await readFile((await download.path())!))
+ );
+ expect(strFromU8(files['word/comments.xml'])).toContain(
+ 'Should this include fees?'
+ );
+ } finally {
+ await context.close();
+ }
+});
+
+test('footnotes are edited where they are and shared', async ({ browser }) => {
+ const documentId = crypto.randomUUID();
+ const contexts = await Promise.all([
+ browser.newContext(),
+ browser.newContext(),
+ ]);
+ const [alice, bob] = await Promise.all(
+ contexts.map((context) => context.newPage())
+ );
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
+ const story = (page: Page) =>
+ page.evaluate(() => window.docxFixture?.editor()?.state()?.story.kind);
+ const src = footnotedMemo();
+ try {
+ await open(alice, documentId, ALICE, { src });
+ await open(bob, documentId, BOB, { src });
+
+ // One click in the first footnote's text puts the caret there.
+ const sheet = alice.locator('[data-docx-page="0"]');
+ await sheet.evaluate((el) => el.scrollIntoView({ block: 'end' }));
+ let box = (await sheet.boundingBox())!;
+ const page = (await alice.evaluate(
+ () => window.docxFixture?.editor()?.pages()[0]
+ ))!;
+ expect(page.notes).toBeTruthy();
+ const scale = box.width / page.width;
+ const notes = page.notes!;
+ // The first note's line is the area's top line.
+ await alice.mouse.click(
+ box.x + box.width / 2,
+ box.y + (notes.top + 6) * scale
+ );
+ await expect.poll(() => story(alice)).toBe('footnote');
+ await alice.keyboard.press('End');
+ await alice.keyboard.type(' (as amended)');
+ // The notes part reaches Bob through the sync service.
+ await expect
+ .poll(() =>
+ bob.evaluate(() => window.docxFixture?.sharedPart('footnotes.xml'))
+ )
+ .toContain('As defined in the Agreement. (as amended)');
+ if (SHOTS) await alice.screenshot({ path: `${SHOTS}/05b-footnote.png` });
+
+ // A click on the body goes back to it.
+ await sheet.evaluate((el) => el.scrollIntoView({ block: 'start' }));
+ box = (await sheet.boundingBox())!;
+ await alice.mouse.click(box.x + box.width / 2, box.y + 76 * scale);
+ await expect.poll(() => story(alice)).toBe('body');
+ await caretAtEnd(alice, 'Each party bears');
+ await alice.keyboard.type(' [body]');
+ await expect.poll(() => joined(bob)).toContain('[body]');
+
+ // Ctrl+Alt+F adds a footnote at the caret and moves into it.
+ await alice.keyboard.press('Control+Alt+KeyF');
+ await expect.poll(() => story(alice)).toBe('footnote');
+ await alice.keyboard.type('Including counsel fees.');
+ await expect
+ .poll(() =>
+ bob.evaluate(() => window.docxFixture?.sharedPart('footnotes.xml'))
+ )
+ .toContain('Including counsel fees.');
+ if (SHOTS)
+ await alice.screenshot({ path: `${SHOTS}/05c-new-footnote.png` });
+ await alice.keyboard.press('Escape');
+ await expect.poll(() => story(alice)).toBe('body');
+
+ // Bob's download carries the edited note and keeps the separators.
+ const [download] = await Promise.all([
+ bob.waitForEvent('download'),
+ bob.getByRole('button', { name: 'Download .docx' }).click(),
+ ]);
+ const files = unzipSync(
+ new Uint8Array(await readFile((await download.path())!))
+ );
+ const saved = strFromU8(files['word/footnotes.xml']);
+ expect(saved).toContain('(as amended)');
+ expect(saved).toContain('w:type="separator"');
+ expect(saved).toContain('In United States dollars.');
+ expect(saved).toContain('Including counsel fees.');
+ expect(
+ strFromU8(files['word/document.xml']).match(/footnoteReference/g)
+ ).toHaveLength(3);
+ } finally {
+ await Promise.all(contexts.map((context) => context.close()));
+ }
+});
+
+test('tracked changes are recorded per author and resolved for everyone', async ({
+ browser,
+}) => {
+ const documentId = crypto.randomUUID();
+ const contexts = await Promise.all([
+ browser.newContext(),
+ browser.newContext(),
+ ]);
+ const [alice, bob] = await Promise.all(
+ contexts.map((context) => context.newPage())
+ );
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
+ const tracking = (page: Page) =>
+ page.evaluate(() => window.docxFixture?.editor()?.state()?.format.tracking);
+ try {
+ await open(alice, documentId, ALICE);
+ await open(bob, documentId, BOB);
+ const original = await paragraphs(alice);
+
+ // Alice turns tracking on for the document; Bob's editor follows.
+ await alice.getByRole('button', { name: 'Track changes' }).click();
+ await expect.poll(() => tracking(alice)).toBe(true);
+ await expect
+ .poll(() =>
+ bob.evaluate(() => window.docxFixture?.sharedPart('settings.xml'))
+ )
+ .toContain('trackRevisions');
+ // Bob's next edit refreshes his formatting state.
+ await caretAtEnd(bob, 'This Agreement shall remain');
+ await expect.poll(() => tracking(bob)).toBe(true);
+
+ // Bob's typing is his insertion, his deletion is marked, not removed.
+ await bob.keyboard.type(' Renewal requires mutual consent.');
+ await caretAtEnd(bob, 'This Agreement shall be governed');
+ for (let i = 0; i < 9; i++) await bob.keyboard.press('Backspace');
+ await expect
+ .poll(() => wrappers(alice, 'This Agreement shall remain'))
+ .toContain('w:author="Bob"');
+ await expect
+ .poll(() => wrappers(alice, 'This Agreement shall be governed'))
+ .toContain('<w:del ');
+ // The deleted text is still there, struck through.
+ expect(await joined(alice)).toContain('principles.');
+ if (SHOTS) await alice.screenshot({ path: `${SHOTS}/06-tracked.png` });
+
+ // Alice rejects everything: both see the original text again.
+ await alice.getByRole('button', { name: 'Reject all changes' }).click();
+ for (const page of [alice, bob])
+ await expect.poll(() => paragraphs(page)).toEqual(original);
+ } finally {
+ await Promise.all(contexts.map((context) => context.close()));
+ }
+});
+
+test('find and replace, shared with everyone', async ({ browser }) => {
+ const documentId = crypto.randomUUID();
+ const contexts = await Promise.all([
+ browser.newContext(),
+ browser.newContext(),
+ ]);
+ const [alice, bob] = await Promise.all(
+ contexts.map((context) => context.newPage())
+ );
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
+ const occurrences = async (page: Page, word: RegExp) =>
+ (await joined(page)).match(word)?.length ?? 0;
+ try {
+ await open(alice, documentId, ALICE);
+ await open(bob, documentId, BOB);
+ const count = await occurrences(alice, /agreement/gi);
+ expect(count).toBeGreaterThan(2);
+
+ // Mod+F in the document opens the find bar; matches are counted and
+ // highlighted on the pages.
+ await caretAtEnd(alice, 'This Agreement shall remain');
+ await alice.keyboard.press('Control+f');
+ const field = alice.locator('[data-docx-find-query]');
+ await expect(field).toBeFocused();
+ await field.fill('agreement');
+ const status = alice.locator('[data-docx-find-status]');
+ await expect(status).toHaveText(new RegExp(`^\\d+ of ${count}$`));
+ await expect(alice.locator('.docx-find-current')).toHaveCount(1);
+ await expect(alice.locator('[data-docx-find-match]')).not.toHaveCount(0);
+ // Enter moves on (wrapping), selecting the match in the document.
+ const first = await status.textContent();
+ await field.press('Enter');
+ await expect(status).not.toHaveText(first ?? '');
+ const selected = () =>
+ alice.evaluate(() => window.docxFixture?.editor()?.selectedText());
+ await expect.poll(selected).toMatch(/^agreement$/i);
+ if (SHOTS) await alice.screenshot({ path: `${SHOTS}/08-find.png` });
+
+ // Replace the current match, then the rest; Bob sees both.
+ await alice.locator('[data-docx-find-replace-toggle]').click();
+ await alice.locator('[data-docx-find-replacement]').fill('Contract');
+ await alice.locator('[data-docx-replace]').click();
+ await expect(status).toHaveText(new RegExp(`^\\d+ of ${count - 1}$`));
+ await expect.poll(() => occurrences(bob, /Contract/g)).toBe(1);
+ await alice.locator('[data-docx-replace-all]').click();
+ await expect(status).toHaveText(`Replaced ${count - 1}`);
+ for (const page of [alice, bob]) {
+ await expect.poll(() => occurrences(page, /agreement/gi)).toBe(0);
+ await expect.poll(() => occurrences(page, /Contract/g)).toBe(count);
+ }
+
+ // Escape closes the bar; one undo takes back the whole replace all.
+ await alice.locator('[data-docx-find-replacement]').press('Escape');
+ await expect(alice.locator('[data-docx-find]')).toHaveCount(0);
+ await expect(alice.locator('[data-docx-input]')).toBeFocused();
+ await alice.keyboard.press('Control+z');
+ for (const page of [alice, bob])
+ await expect.poll(() => occurrences(page, /agreement/gi)).toBe(count - 1);
+ } finally {
+ await Promise.all(contexts.map((context) => context.close()));
+ }
+});
+
+test('toolbar formatting and table commands reach collaborators', async ({
+ browser,
+}) => {
+ const documentId = crypto.randomUUID();
+ const contexts = await Promise.all([
+ browser.newContext(),
+ browser.newContext(),
+ ]);
+ const [alice, bob] = await Promise.all(
+ contexts.map((context) => context.newPage())
+ );
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
+ const rowCount = (page: Page) =>
+ page.evaluate(() => window.docxFixture?.sharedCount('tr') ?? 0);
+ const menu = async (page: Page, name: string, item: string) => {
+ await page.locator(`[data-docx-menu="${name}"]`).click();
+ await page.getByRole('menuitem', { name: item, exact: true }).click();
+ };
+ try {
+ await open(alice, documentId, ALICE, { fixture: 'complex-msa.docx' });
+ await open(bob, documentId, BOB, { fixture: 'complex-msa.docx' });
+
+ // Highlight, color and line spacing on a paragraph.
+ await selectParagraph(alice, 'Kickoff');
+ await menu(alice, 'highlight', 'Yellow');
+ await menu(alice, 'color', 'Red');
+ await expect
+ .poll(async () =>
+ JSON.stringify((await sharedBlock(bob, 'Kickoff'))?.attrs)
+ )
+ .toContain('w:highlight w:val=\\"yellow\\"');
+ await expect
+ .poll(async () =>
+ JSON.stringify((await sharedBlock(bob, 'Kickoff'))?.attrs)
+ )
+ .toContain('FF0000');
+ // The document keeps the caret: typing replaces the selection.
+ await expect(alice.locator('[data-docx-input]')).toBeFocused();
+ await expect
+ .poll(() =>
+ alice.evaluate(
+ () => window.docxFixture?.editor()?.state()?.format.highlight
+ )
+ )
+ .toBe('yellow');
+
+ // Rows added from the table menu, which shows inside tables only.
+ const before = await rowCount(bob);
+ await expect(alice.locator('[data-docx-menu="table"]')).toBeVisible();
+ await menu(alice, 'table', 'Insert row below');
+ await expect.poll(() => rowCount(bob)).toBe(before + 1);
+ await caretAtEnd(alice, 'Provider shall perform');
+ await expect(alice.locator('[data-docx-menu="table"]')).toHaveCount(0);
+ await menu(alice, 'line-spacing', '2.0');
+ await expect
+ .poll(
+ async () => (await sharedBlock(bob, 'Provider shall perform'))?.props
+ )
+ .toContain('w:line="480"');
+ if (SHOTS) await alice.screenshot({ path: `${SHOTS}/09-toolbar.png` });
+ } finally {
+ await Promise.all(contexts.map((context) => context.close()));
+ }
+});
+
+test('copy and paste keep formatting, from here and from other apps', async ({
+ browser,
+}) => {
+ const documentId = crypto.randomUUID();
+ const contexts = await Promise.all([
+ browser.newContext({ permissions: ['clipboard-read', 'clipboard-write'] }),
+ browser.newContext(),
+ ]);
+ const [alice, bob] = await Promise.all(
+ contexts.map((context) => context.newPage())
+ );
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
+ try {
+ await open(alice, documentId, ALICE);
+ await open(bob, documentId, BOB);
+ // The first paragraph has a bold defined term ("Agreement").
+ await selectParagraph(alice, 'This Mutual Non-Disclosure');
+ await alice.keyboard.press('ControlOrMeta+c');
+ await expect
+ .poll(() =>
+ alice.evaluate(async () => {
+ const [item] = await navigator.clipboard.read();
+ return item?.types ?? [];
+ })
+ )
+ .toContain('text/html');
+ await caretAtEnd(alice, 'IN WITNESS WHEREOF');
+ await alice.keyboard.press('Enter');
+ await alice.keyboard.press('ControlOrMeta+v');
+ await expect
+ .poll(async () =>
+ (await paragraphs(bob)).filter((p) =>
+ p.startsWith('This Mutual Non-Disclosure')
+ )
+ )
+ .toHaveLength(2);
+ const copies = await bob.evaluate(() => {
+ const fixture = window.docxFixture;
+ return fixture?.sharedBlock('This Mutual Non-Disclosure');
+ });
+ expect(JSON.stringify(copies?.attrs)).toContain('r:w:b');
+
+ // HTML from another application keeps bold text and becomes a list.
+ await caretAtEnd(alice, 'IN WITNESS WHEREOF');
+ await alice.keyboard.press('Enter');
+ await alice.evaluate(() => {
+ const data = new DataTransfer();
+ data.setData(
+ 'text/html',
+ '<b style="font-weight:normal" id="docs-internal-guid-1"><p><span style="font-weight:700">Notices.</span><span> All notices</span></p><ul><li><p>by email</p></li><li><p>by courier</p></li></ul></b>'
+ );
+ data.setData('text/plain', 'Notices. All notices\nby email\nby courier');
+ document.querySelector('[data-docx-input]')?.dispatchEvent(
+ new ClipboardEvent('paste', {
+ clipboardData: data,
+ bubbles: true,
+ cancelable: true,
+ })
+ );
+ });
+ await expect
+ .poll(async () => (await sharedBlock(bob, 'by courier'))?.props ?? '')
+ .toContain('numPr');
+ expect(
+ JSON.stringify((await sharedBlock(bob, 'Notices.'))?.attrs ?? [])
+ ).toContain('r:w:b');
} finally {
await Promise.all(contexts.map((context) => context.close()));
}
});
+test('on a touch screen, a swipe scrolls and taps place the caret', async ({
+ browser,
+}) => {
+ const documentId = crypto.randomUUID();
+ const context = await browser.newContext({
+ hasTouch: true,
+ viewport: { width: 420, height: 760 },
+ });
+ const page = await context.newPage();
+ logErrors(page, 'touch');
+ const cdp = await context.newCDPSession(page);
+ const touch = (
+ type: 'touchStart' | 'touchMove' | 'touchEnd',
+ x: number,
+ y: number
+ ) =>
+ cdp.send('Input.dispatchTouchEvent', {
+ type,
+ touchPoints: type === 'touchEnd' ? [] : [{ x, y }],
+ });
+ const selection = () =>
+ page.evaluate(() => window.docxFixture?.editor()?.state()?.selection);
+ const focused = () =>
+ page.evaluate(() =>
+ document.activeElement?.hasAttribute('data-docx-input')
+ );
+ try {
+ await open(page, documentId, ALICE);
+ const scroller = page.locator('[data-docx-scroller]');
+ const sheet = await page.locator('[data-docx-page="0"]').boundingBox();
+ if (!sheet) throw new Error('no page');
+ // A point on the first body line.
+ const caret = await page.evaluate(async () => {
+ const editor = window.docxFixture?.editor();
+ const first = (await editor?.paragraphs())?.find((p) => p.text.trim());
+ return first
+ ? editor?.caretAt({ block: first.id, offset: 2 })
+ : undefined;
+ });
+ if (!caret) throw new Error('no caret');
+ const scale =
+ sheet.width /
+ (await page.evaluate(
+ () => window.docxFixture?.editor()?.pages()[0]?.width ?? 1
+ ));
+ const x = sheet.x + caret.x * scale;
+ const y = sheet.y + (caret.y + caret.height / 2) * scale;
+
+ // A swipe scrolls the pages and leaves the keyboard closed.
+ await touch('touchStart', 200, 600);
+ for (let i = 1; i <= 8; i++) await touch('touchMove', 200, 600 - i * 40);
+ await touch('touchEnd', 0, 0);
+ await expect
+ .poll(() => scroller.evaluate((e) => e.scrollTop))
+ .toBeGreaterThan(30);
+ expect(await focused()).toBe(false);
+ await scroller.evaluate((e) => {
+ e.scrollTop = 0;
+ });
+
+ // A tap places the caret there and focuses the text input.
+ await page.touchscreen.tap(x, y);
+ await expect.poll(focused).toBe(true);
+ await expect
+ .poll(async () => {
+ const s = await selection();
+ return s && s.anchor.offset === s.focus.offset ? s.focus.offset : -1;
+ })
+ .toBeGreaterThanOrEqual(0);
+
+ // A double tap selects a word (after a pause: no double tap with the
+ // tap before).
+ await page.waitForTimeout(400);
+ await page.touchscreen.tap(x, y);
+ await page.touchscreen.tap(x, y);
+ await expect
+ .poll(async () => {
+ const s = await selection();
+ return s ? s.focus.offset - s.anchor.offset : 0;
+ })
+ .toBeGreaterThan(1);
+
+ // A long press selects a word too.
+ await page.evaluate(() =>
+ window.docxFixture
+ ?.editor()
+ ?.run([{ op: 'move', unit: 'document', forward: false, extend: false }])
+ );
+ await touch('touchStart', x, y);
+ await page.waitForTimeout(800);
+ await touch('touchEnd', 0, 0);
+ await expect
+ .poll(async () => {
+ const s = await selection();
+ return s ? s.focus.offset - s.anchor.offset : 0;
+ })
+ .toBeGreaterThan(1);
+ } finally {
+ await context.close();
+ }
+});
+
test('comment cards leave a narrow pane a legible page', async ({
browser,
}) => {
@@ -329,16 +1014,14 @@ test('comment cards leave a narrow pane a legible page', async ({
// The page keeps a legible width and the pane scrolls sideways to the card.
await expect
.poll(async () => (await layout()).page)
- .toBeGreaterThanOrEqual(480);
+ .toBeGreaterThanOrEqual(479);
expect((await layout()).scrolls).toBe(true);
} finally {
await context.close();
}
});
-test('viewers follow along read-only, and header edits reach them', async ({
- browser,
-}) => {
+test('viewers follow along read-only', async ({ browser }) => {
const documentId = crypto.randomUUID();
const contexts = await Promise.all([
browser.newContext(),
@@ -353,30 +1036,22 @@ test('viewers follow along read-only, and header edits reach them', async ({
readonly: '1',
fixture: 'complex-msa.docx',
});
- await expect(
- viewer.locator('.docx-body-flow [contenteditable="true"]')
- ).toHaveCount(0);
await expect(viewer.getByRole('button', { name: 'Bold' })).toHaveCount(0);
+ await expect(viewer.locator('[data-docx-input]')).toHaveAttribute(
+ 'readonly',
+ ''
+ );
// A body edit in a document with a table, image and content control.
await caretAtEnd(alice, 'Either party may terminate');
await alice.keyboard.type(' Termination notices must be in writing.');
await expect
- .poll(async () => (await paragraphs(viewer)).join('\n'))
+ .poll(() => joined(viewer))
.toContain('Termination notices must be in writing.');
-
- // Header text lives in its own package part.
- const header = alice
- .locator('[data-hf-band="header"] [contenteditable="true"]')
- .first();
- await header.click();
- await alice.keyboard.press('End');
- await alice.keyboard.type(' (DRAFT)');
- await alice.locator('.docx-body-flow [data-anchor]').first().click();
- // Viewers read the print layout: every page repeats the header.
- await expect(viewer.locator('.docx-editor-host')).toContainText(
- 'CONFIDENTIAL - Acme / Globex (DRAFT)'
- );
+ // Typing does nothing for the viewer.
+ await caretAtEnd(viewer, 'Either party may terminate');
+ await viewer.keyboard.type('zzz');
+ await expect.poll(() => joined(alice)).not.toContain('zzz');
} finally {
await Promise.all(contexts.map((context) => context.close()));
}
@@ -393,6 +1068,8 @@ test('edits made offline merge when the connection returns', async ({
const [alice, bob] = await Promise.all(
contexts.map((context) => context.newPage())
);
+ logErrors(alice, 'alice');
+ logErrors(bob, 'bob');
// Route Bob's sync socket through the test so the network can be cut.
let offline = false;
const sockets: Array<{ close: () => Promise<void> }> = [];
@@ -415,27 +1092,19 @@ test('edits made offline merge when the connection returns', async ({
await caretAtEnd(bob, 'This Agreement shall remain');
await bob.keyboard.type(' [written offline]');
- await caretAtEnd(alice, '"Representatives" means');
+ await caretAtEnd(alice, 'This Agreement shall remain');
await alice.keyboard.type(' [written online]');
- await expect
- .poll(async () => (await paragraphs(alice)).join('\n'))
- .toContain('[written online]');
+ await expect.poll(() => joined(alice)).toContain('[written online]');
// Bob keeps working locally while disconnected.
- await expect
- .poll(async () => (await paragraphs(bob)).join('\n'))
- .toContain('[written offline]');
+ await expect.poll(() => joined(bob)).toContain('[written offline]');
offline = false;
for (const page of [alice, bob]) {
await expect
- .poll(async () => (await paragraphs(page)).join('\n'), {
- timeout: 60_000,
- })
+ .poll(() => joined(page), { timeout: 60_000 })
.toContain('[written offline]');
await expect
- .poll(async () => (await paragraphs(page)).join('\n'), {
- timeout: 60_000,
- })
+ .poll(() => joined(page), { timeout: 60_000 })
.toContain('[written online]');
}
expect(await paragraphs(bob)).toEqual(await paragraphs(alice));
diff --git a/apps/web/src/features/block-write/browser-test/fixture.tsx b/apps/web/src/features/block-write/browser-test/fixture.tsx
index 9b2fe0e41a..3ffc7991cd 100644
--- a/apps/web/src/features/block-write/browser-test/fixture.tsx
+++ b/apps/web/src/features/block-write/browser-test/fixture.tsx
@@ -8,7 +8,6 @@ import {
type DocxAgentResult,
runDocxAgentRequest,
} from '@macro-inc/collaboration/docx/agent';
-import { readDocxState } from '@macro-inc/collaboration/docx/schema';
import { InitializeFromSnapshotRequest } from '@macro-inc/collaboration/sync-service/generated/schema';
import { createSyncSocket } from '@macro-inc/collaboration/sync-service/socket';
import {
@@ -18,41 +17,120 @@ import {
import { createWebsocketStateSignal } from '@macro-inc/collaboration/websocket/solid/state-signal';
import type { MessageListItem } from '@service-storage/messages';
import type { LoroDoc } from 'loro-crdt';
-import { createSignal, onCleanup, Show } from 'solid-js';
+import { createSignal, For, onCleanup, Show } from 'solid-js';
import { render } from 'solid-js/web';
import { readCommentMarks } from '../core/comment-marks';
+import { readCollabState, sharedParagraphTexts } from '../core/docx-loro';
import { buildSeedSnapshot } from '../core/docx-seed';
import ComplexMsa from '../core/fixtures/complex-msa.docx?url';
import MutualNda from '../core/fixtures/mutual-nda.docx?url';
-import { contentText } from '../core/text-offsets';
import type { LocatedThread } from '../primitives/create-docx-comments';
-import type { createDocxEditor } from '../primitives/create-docx-editor';
+import type { DocxEditor } from '../primitives/create-docx-editor';
import { createDocxSession } from '../queries/docx-session';
-import {
- type DocxodusRuntime,
- loadDocxodus,
-} from '../queries/docxodus-runtime';
import { DocxEditorView } from '../views/DocxEditorView';
import { DocxMarginLayout } from '../views/DocxMarginLayout';
-type Handle = ReturnType<typeof createDocxEditor>;
-
declare global {
interface Window {
docxFixture?: {
status: () => string;
ready: () => boolean;
- paragraphs: () => string[];
- sharedOrder: () => string[];
- sharedBlocks: () => Array<[string, string]>;
+ /** Paragraph texts as this editor's engine has them. */
+ paragraphs: () => Promise<string[]>;
+ /** Paragraph texts as the shared document has them. */
+ sharedParagraphs: () => string[];
/** Run an AI tool request as the editing worker does: its own peer. */
agent: (request: DocxAgentRequest) => Promise<DocxAgentResult>;
marks: () => Record<string, unknown>;
- handle: () => Handle | undefined;
+ editor: () => DocxEditor | undefined;
+ /** Puts the caret in (or selects) the paragraph starting with `prefix`. */
+ place: (
+ prefix: string,
+ where: 'start' | 'end' | 'all'
+ ) => Promise<boolean>;
+ /** Shared formatting of the paragraph starting with `prefix`. */
+ sharedBlock: (
+ prefix: string
+ ) => { props: string; attrs: Record<string, string>[] } | null;
+ /** XML of the shared part whose name ends with `suffix` (a notes part
+ * with its notes). */
+ sharedPart: (suffix: string) => string | null;
+ /** How many shared blocks there are of a kind (`p`, `tbl`, `tr`, `tc`...). */
+ sharedCount: (kind: string) => number;
};
}
}
+/** Fixture helpers that read the engine and the shared document. */
+function helpers(
+ editor: () => DocxEditor | undefined,
+ doc: () => LoroDoc | undefined
+) {
+ return {
+ place: async (prefix: string, where: 'start' | 'end' | 'all') => {
+ const current = editor();
+ if (!current) return false;
+ const found = (await current.paragraphs()).find((p) =>
+ p.text.replace(/\uFFFC/g, '').startsWith(prefix)
+ );
+ if (!found) return false;
+ const end = { block: found.id, offset: found.text.length };
+ const start = { block: found.id, offset: 0 };
+ current.run([
+ where === 'all'
+ ? { op: 'select', anchor: start, focus: end }
+ : {
+ op: 'select',
+ anchor: where === 'end' ? end : start,
+ focus: where === 'end' ? end : start,
+ },
+ ]);
+ await current.idle();
+ document.querySelector<HTMLTextAreaElement>('[data-docx-input]')?.focus();
+ return true;
+ },
+ sharedCount: (kind: string) => {
+ const shared = doc();
+ return shared
+ ? readCollabState(shared).blocks.filter((b) => b.k === kind).length
+ : 0;
+ },
+ sharedBlock: (prefix: string) => {
+ const shared = doc();
+ if (!shared) return null;
+ const block = readCollabState(shared).blocks.find(
+ (b) =>
+ b.k === 'p' &&
+ (b.t ?? [])
+ .map((op) => ('insert' in op ? op.insert : ''))
+ .join('')
+ .replace(/\uFFFC/g, '')
+ .startsWith(prefix)
+ );
+ if (!block) return null;
+ return {
+ props: block.x,
+ attrs: (block.t ?? []).map((op) =>
+ 'insert' in op ? (op.attributes ?? {}) : {}
+ ),
+ };
+ },
+ sharedPart: (suffix: string) => {
+ const shared = doc();
+ if (!shared) return null;
+ const parts = readCollabState(shared).parts;
+ const name = Object.keys(parts).find((key) => key.endsWith(suffix));
+ if (!name) return null;
+ // Footnotes and endnotes are shared note by note (`part|id`).
+ const notes = Object.keys(parts)
+ .filter((key) => key.startsWith(`${name}|`))
+ .map((key) => parts[key])
+ .join('');
+ return (parts[name] ?? '') + notes;
+ },
+ };
+}
+
const FIXTURES: Record<string, string> = {
'mutual-nda.docx': MutualNda,
'complex-msa.docx': ComplexMsa,
@@ -78,8 +156,11 @@ const socketUrl = params.get('socket') ?? '';
const token = params.get('token') ?? '';
const user = params.get('user') ?? 'macro|[email protected]';
const readonly = params.has('readonly');
+/** A bundled fixture by name, or any document URL (`src`). */
const fixture =
- FIXTURES[params.get('fixture') ?? 'mutual-nda.docx'] ?? MutualNda;
+ params.get('src') ??
+ FIXTURES[params.get('fixture') ?? 'mutual-nda.docx'] ??
+ MutualNda;
const shortName = (id: string | undefined) =>
(id ?? '')
@@ -229,10 +310,8 @@ function FixtureThreadCard(props: {
}
function Fixture() {
- const [runtime, setRuntime] = createSignal<DocxodusRuntime>();
- const [handle, setHandle] = createSignal<Handle>();
+ const [editor, setEditor] = createSignal<DocxEditor>();
const [roots, setRoots] = createSignal<MessageListItem[]>([]);
- void loadDocxodus().then(setRuntime);
const session = createDocxSession({
documentId,
@@ -247,11 +326,7 @@ function Fixture() {
).ok,
fetchOriginal: async () =>
new Uint8Array(await (await fetch(fixture)).arrayBuffer()),
- buildSeed: async (original) =>
- buildSeedSnapshot(
- (await loadDocxodus()).exports.DocxSessionBridge,
- original
- ),
+ buildSeed: buildSeedSnapshot,
initialize: async (snapshot) => {
const response = await fetch(
`${worker}document/${documentId}/initialize`,
@@ -285,22 +360,16 @@ function Fixture() {
window.docxFixture = {
status: session.status,
- ready: () => !!handle(),
- paragraphs: () =>
- Array.from(
- document.querySelectorAll<HTMLElement>('.docx-body-flow [data-anchor]')
- )
- .filter((element) => !element.querySelector('[data-anchor]'))
- .map(contentText),
- sharedOrder: () => {
- const state = session.state();
- return state.t === 'ready' ? readDocxState(state.doc).order : [];
- },
- sharedBlocks: () => {
+ ready: () => !!editor(),
+ paragraphs: async () =>
+ (await editor()?.paragraphs())?.map((p) =>
+ p.text.replace(/\uFFFC/g, '')
+ ) ?? [],
+ sharedParagraphs: () => {
const state = session.state();
- if (state.t !== 'ready') return [];
- const shared = readDocxState(state.doc);
- return shared.order.map((id) => [id, shared.blocks.get(id) ?? '']);
+ return state.t === 'ready'
+ ? sharedParagraphTexts(state.doc).map((t) => t.replace(/\uFFFC/g, ''))
+ : [];
},
agent: async (request) => {
const source = new SyncServiceSource(
@@ -319,7 +388,11 @@ function Fixture() {
? Object.fromEntries(readCommentMarks(state.doc))
: {};
},
- handle,
+ editor,
+ ...helpers(editor, () => {
+ const state = session.state();
+ return state.t === 'ready' ? state.doc : undefined;
+ }),
};
onCleanup(() => Reflect.deleteProperty(window, 'docxFixture'));
@@ -328,15 +401,15 @@ function Fixture() {
<Show
when={(() => {
const state = session.state();
- const engine = runtime();
- return engine && state.t === 'ready'
- ? { engine, doc: state.doc }
- : undefined;
+ return state.t === 'ready' ? { doc: state.doc } : undefined;
})()}
keyed
fallback={
<div class="p-6 text-sm text-ink-muted" data-fixture-state>
- {session.state().t}
+ {(() => {
+ const state = session.state();
+ return state.t === 'error' ? `error: ${state.message}` : state.t;
+ })()}
</div>
}
>
@@ -344,18 +417,17 @@ function Fixture() {
watchFixtureThreads(ready.doc, setRoots);
return (
<DocxEditorView
- runtime={ready.engine}
doc={ready.doc}
canEdit={!readonly}
canComment={() => true}
- author={shortName(user)}
fileName="fixture.docx"
peers={session.peers}
displayName={shortName}
+ author={shortName(user)}
+ documentId={documentId}
onSelection={session.setSelection}
- subscribeRemote={session.onRemoteChange}
commentRoots={roots}
- onReady={setHandle}
+ onReady={setEditor}
onDownload={(bytes) => {
const url = URL.createObjectURL(
new Blob([bytes.slice().buffer], {
@@ -372,9 +444,8 @@ function Fixture() {
margin={(context) => (
<DocxMarginLayout
comments={context.comments}
- editorRoot={context.editorRoot}
- margin={context.margin}
- revision={context.revision}
+ geometry={context.geometry}
+ selectionTop={context.selectionTop}
canComment={() => true}
renderCard={(thread, isActive) => (
<FixtureThreadCard
@@ -406,7 +477,83 @@ function Fixture() {
);
}
+/**
+ * Local mode (`?local`): no sync service. The fixture document is seeded into
+ * an in-page Loro document; `?local=pair` shows two editors whose documents
+ * exchange updates directly, for trying collaboration without a server.
+ */
+function LocalFixture() {
+ const pair = params.get('local') === 'pair';
+ const [docs, setDocs] = createSignal<LoroDoc[]>();
+ const [editor, setEditor] = createSignal<DocxEditor>();
+ void (async () => {
+ const original = new Uint8Array(await (await fetch(fixture)).arrayBuffer());
+ const snapshot = await buildSeedSnapshot(original);
+ const { LoroDoc } = await import('loro-crdt');
+ const a = new LoroDoc();
+ a.import(snapshot);
+ if (!pair) {
+ setDocs([a]);
+ return;
+ }
+ const b = new LoroDoc();
+ b.import(snapshot);
+ a.subscribeLocalUpdates((u) => queueMicrotask(() => b.import(u)));
+ b.subscribeLocalUpdates((u) => queueMicrotask(() => a.import(u)));
+ setDocs([a, b]);
+ })();
+ window.docxFixture = {
+ status: () => 'connected',
+ ready: () => !!editor(),
+ paragraphs: async () =>
+ (await editor()?.paragraphs())?.map((p) =>
+ p.text.replace(/\uFFFC/g, '')
+ ) ?? [],
+ sharedParagraphs: () => {
+ const doc = docs()?.[0];
+ return doc
+ ? sharedParagraphTexts(doc).map((t) => t.replace(/\uFFFC/g, ''))
+ : [];
+ },
+ agent: () => Promise.reject(new Error('no sync service in local mode')),
+ marks: () => {
+ const doc = docs()?.[0];
+ return doc ? Object.fromEntries(readCommentMarks(doc)) : {};
+ },
+ editor,
+ ...helpers(editor, () => docs()?.[0]),
+ };
+ return (
+ <main class="flex h-screen w-screen overflow-hidden bg-page font-sans text-ink">
+ <Show when={docs()} fallback={<div class="p-6">seeding…</div>}>
+ {(list) => (
+ <For each={list()}>
+ {(doc, index) => (
+ <div class="h-full min-w-0 flex-1 border-r border-edge">
+ <DocxEditorView
+ doc={doc}
+ canEdit={!readonly}
+ canComment={() => true}
+ fileName="fixture.docx"
+ peers={() => []}
+ displayName={shortName}
+ onReady={index() === 0 ? setEditor : undefined}
+ onDownload={() => {}}
+ onError={(error) => console.error('[docx-fixture]', error)}
+ />
+ </div>
+ )}
+ </For>
+ )}
+ </Show>
+ </main>
+ );
+}
+
const root = document.getElementById('root');
if (!root) throw new Error('DOCX fixture root is missing.');
-const dispose = render(() => <Fixture />, root);
+const dispose = render(
+ () => (params.has('local') ? <LocalFixture /> : <Fixture />),
+ root
+);
import.meta.hot?.dispose(dispose);
diff --git a/apps/web/src/features/block-write/browser-test/vite.config.ts b/apps/web/src/features/block-write/browser-test/vite.config.ts
index 53bccedf9e..85aa4ea6f4 100644
--- a/apps/web/src/features/block-write/browser-test/vite.config.ts
+++ b/apps/web/src/features/block-write/browser-test/vite.config.ts
@@ -5,7 +5,6 @@ import solidPlugin from 'vite-plugin-solid';
import solidSvg from 'vite-plugin-solid-svg';
import wasm from 'vite-plugin-wasm';
import tsconfigPaths from 'vite-tsconfig-paths';
-import { docxodusRuntime } from '../../../../scripts/docxodus-runtime';
const directory = fileURLToPath(new URL('.', import.meta.url));
const webDirectory = fileURLToPath(new URL('../../../../', import.meta.url));
@@ -22,10 +21,9 @@ export default defineConfig({
tsconfigPaths({ projects: [`${webDirectory}/tsconfig.json`] }),
tailwind(),
wasm(),
- docxodusRuntime(),
],
resolve: { dedupe: ['solid-js', 'loro-crdt'] },
- optimizeDeps: { include: ['fflate', 'docxodus'], exclude: ['loro-crdt'] },
+ optimizeDeps: { include: ['fflate'], exclude: ['loro-crdt'] },
server: {
host: '127.0.0.1',
port: 3018,
diff --git a/apps/web/src/features/block-write/components/DocxFindBar.tsx b/apps/web/src/features/block-write/components/DocxFindBar.tsx
new file mode 100644
index 0000000000..fa603c0b95
--- /dev/null
+++ b/apps/web/src/features/block-write/components/DocxFindBar.tsx
@@ -0,0 +1,215 @@
+import CaretDown from '@phosphor/caret-down.svg';
+import CaretUp from '@phosphor/caret-up.svg';
+import MagnifyingGlass from '@phosphor/magnifying-glass.svg';
+import Swap from '@phosphor/swap.svg';
+import TextAa from '@phosphor/text-aa.svg';
+import TextT from '@phosphor/text-t.svg';
+import X from '@phosphor/x.svg';
+import { InputGroup } from '@ui/components/InputGroup';
+import { Toolbar } from '@ui/components/Toolbar';
+import { createEffect, on, Show } from 'solid-js';
+
+export type DocxFindBarProps = {
+ query: string;
+ replacement: string;
+ matchCase: boolean;
+ wholeWord: boolean;
+ /** Matches found, and the one being looked at (0-based). */
+ count: number;
+ current: number | undefined;
+ /** More matches exist than were counted. */
+ truncated: boolean;
+ /** How many matches the last replace all changed. */
+ replaced: number | undefined;
+ /** The replace field is showing. */
+ replacing: boolean;
+ canEdit: boolean;
+ /** Bumps when the search field should take focus. */
+ focusRequest: number;
+ onQuery: (query: string) => void;
+ onReplacement: (replacement: string) => void;
+ onToggleMatchCase: () => void;
+ onToggleWholeWord: () => void;
+ onToggleReplace: () => void;
+ onNext: () => void;
+ onPrevious: () => void;
+ onReplace: () => void;
+ onReplaceAll: () => void;
+ onClose: () => void;
+};
+
+/** Whether a key press is the platform's find shortcut (Mod+F). */
+function isFindKey(event: KeyboardEvent) {
+ return (event.metaKey || event.ctrlKey) && event.code === 'KeyF';
+}
+
+/** Find and replace over the pages: a search field with the match count,
+ * case and whole-word options, and an optional replace field. */
+export function DocxFindBar(props: DocxFindBarProps) {
+ let search!: HTMLInputElement;
+
+ createEffect(
+ on(
+ () => props.focusRequest,
+ () => {
+ search.focus();
+ search.select();
+ }
+ )
+ );
+
+ const status = () => {
+ if (props.replaced !== undefined && props.count === 0)
+ return `Replaced ${props.replaced.toLocaleString()}`;
+ if (!props.query) return '';
+ if (!props.count) return 'No results';
+ const total = `${props.count.toLocaleString()}${props.truncated ? '+' : ''}`;
+ return props.current === undefined
+ ? total
+ : `${(props.current + 1).toLocaleString()} of ${total}`;
+ };
+
+ /** Keys shared by both fields. */
+ function onKeyDown(event: KeyboardEvent, enter: (shift: boolean) => void) {
+ if (event.key === 'Escape') {
+ event.preventDefault();
+ props.onClose();
+ } else if (event.key === 'Enter' && !event.isComposing) {
+ event.preventDefault();
+ enter(event.shiftKey);
+ } else if (isFindKey(event)) {
+ event.preventDefault();
+ search.focus();
+ search.select();
+ } else if ((event.metaKey || event.ctrlKey) && event.code === 'KeyG') {
+ event.preventDefault();
+ if (event.shiftKey) props.onPrevious();
+ else props.onNext();
+ }
+ }
+
+ return (
+ <Toolbar
+ size="icon-sm"
+ orientation="vertical"
+ aria-label="Find in document"
+ class="w-[min(26rem,calc(100vw-2rem))] shadow-md"
+ data-docx-find
+ >
+ <div class="flex items-center gap-1">
+ <InputGroup size="sm" class="flex-1">
+ <InputGroup.Addon>
+ <MagnifyingGlass />
+ </InputGroup.Addon>
+ <InputGroup.Input
+ ref={search}
+ type="text"
+ placeholder="Find in document"
+ aria-label="Find in document"
+ value={props.query}
+ spellcheck={false}
+ onInput={(event) => props.onQuery(event.currentTarget.value)}
+ onKeyDown={(event) =>
+ onKeyDown(event, (shift) =>
+ shift ? props.onPrevious() : props.onNext()
+ )
+ }
+ data-docx-find-query
+ />
+ <InputGroup.Addon align="inline-end">
+ <span
+ class="whitespace-nowrap text-xs text-ink-muted tabular-nums"
+ aria-live="polite"
+ data-docx-find-status
+ >
+ {status()}
+ </span>
+ </InputGroup.Addon>
+ </InputGroup>
+ <Toolbar.Button
+ label="Match case"
+ aria-pressed={props.matchCase}
+ onClick={() => props.onToggleMatchCase()}
+ >
+ <TextAa />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label="Whole words only"
+ aria-pressed={props.wholeWord}
+ onClick={() => props.onToggleWholeWord()}
+ >
+ <TextT />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label="Previous match"
+ shortcut="Shift+Enter"
+ disabled={!props.count}
+ onClick={() => props.onPrevious()}
+ >
+ <CaretUp />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label="Next match"
+ shortcut="Enter"
+ disabled={!props.count}
+ onClick={() => props.onNext()}
+ >
+ <CaretDown />
+ </Toolbar.Button>
+ <Show when={props.canEdit}>
+ <Toolbar.Button
+ label={props.replacing ? 'Hide replace' : 'Replace'}
+ aria-pressed={props.replacing}
+ onClick={() => props.onToggleReplace()}
+ data-docx-find-replace-toggle
+ >
+ <Swap />
+ </Toolbar.Button>
+ </Show>
+ <Toolbar.Button
+ label="Close"
+ shortcut="Escape"
+ onClick={() => props.onClose()}
+ >
+ <X />
+ </Toolbar.Button>
+ </div>
+ <Show when={props.canEdit && props.replacing}>
+ <div class="flex items-center gap-1">
+ <InputGroup size="sm" class="flex-1">
+ <InputGroup.Input
+ type="text"
+ placeholder="Replace with"
+ aria-label="Replace with"
+ value={props.replacement}
+ spellcheck={false}
+ onInput={(event) =>
+ props.onReplacement(event.currentTarget.value)
+ }
+ onKeyDown={(event) => onKeyDown(event, () => props.onReplace())}
+ data-docx-find-replacement
+ />
+ </InputGroup>
+ <Toolbar.Button
+ size="sm"
+ variant="outline"
+ disabled={props.current === undefined}
+ onClick={() => props.onReplace()}
+ data-docx-replace
+ >
+ Replace
+ </Toolbar.Button>
+ <Toolbar.Button
+ size="sm"
+ variant="outline"
+ disabled={!props.count}
+ onClick={() => props.onReplaceAll()}
+ data-docx-replace-all
+ >
+ Replace all
+ </Toolbar.Button>
+ </div>
+ </Show>
+ </Toolbar>
+ );
+}
diff --git a/apps/web/src/features/block-write/components/DocxToolbar.tsx b/apps/web/src/features/block-write/components/DocxToolbar.tsx
index 071da63676..3c4e793ea1 100644
--- a/apps/web/src/features/block-write/components/DocxToolbar.tsx
+++ b/apps/web/src/features/block-write/components/DocxToolbar.tsx
@@ -1,42 +1,179 @@
import ArrowClockwise from '@phosphor/arrow-clockwise.svg';
import ArrowCounterClockwise from '@phosphor/arrow-counter-clockwise.svg';
+import ArrowsDownUp from '@phosphor/arrows-down-up.svg';
+import AsteriskSimple from '@phosphor/asterisk-simple.svg';
import ChatCircleText from '@phosphor/chat-circle-text.svg';
+import Check from '@phosphor/check.svg';
+import Checks from '@phosphor/checks.svg';
import DownloadSimple from '@phosphor/download-simple.svg';
+import Eye from '@phosphor/eye.svg';
+import EyeSlash from '@phosphor/eye-slash.svg';
+import GitDiff from '@phosphor/git-diff.svg';
+import Highlighter from '@phosphor/highlighter.svg';
import ListBullets from '@phosphor/list-bullets.svg';
import ListNumbers from '@phosphor/list-numbers.svg';
-import PencilSimpleLine from '@phosphor/pencil-simple-line.svg';
+import MagnifyingGlass from '@phosphor/magnifying-glass.svg';
+import RowsPlusBottom from '@phosphor/rows-plus-bottom.svg';
import Table from '@phosphor/table.svg';
+import TextAUnderline from '@phosphor/text-a-underline.svg';
import TextAlignCenter from '@phosphor/text-align-center.svg';
import TextAlignJustify from '@phosphor/text-align-justify.svg';
import TextAlignLeft from '@phosphor/text-align-left.svg';
import TextAlignRight from '@phosphor/text-align-right.svg';
import TextB from '@phosphor/text-b.svg';
+import TextIndent from '@phosphor/text-indent.svg';
import TextItalic from '@phosphor/text-italic.svg';
+import TextOutdent from '@phosphor/text-outdent.svg';
import TextStrikethrough from '@phosphor/text-strikethrough.svg';
+import TextSubscript from '@phosphor/text-subscript.svg';
+import TextSuperscript from '@phosphor/text-superscript.svg';
+import TextTSlash from '@phosphor/text-t-slash.svg';
import TextUnderline from '@phosphor/text-underline.svg';
+import X from '@phosphor/x.svg';
+import XCircle from '@phosphor/x-circle.svg';
+import { Dropdown } from '@ui/components/Dropdown';
import { Toolbar } from '@ui/components/Toolbar';
import { For, type JSX, Show } from 'solid-js';
-export type DocxInlineFormat = 'bold' | 'italic' | 'underline' | 'strike';
+export type DocxInlineFormat =
+ | 'bold'
+ | 'italic'
+ | 'underline'
+ | 'strike'
+ | 'superscript'
+ | 'subscript';
+/** Table row and column commands. */
+export type DocxTableOp =
+ | 'rowAbove'
+ | 'rowBelow'
+ | 'columnLeft'
+ | 'columnRight'
+ | 'deleteRow'
+ | 'deleteColumn'
+ | 'deleteTable';
export type DocxAlignment = 'left' | 'center' | 'right' | 'justify';
export type DocxParagraphStyle = { id: string; name: string };
+/** Font sizes offered in the size picker (points). */
+const FONT_SIZES = [8, 9, 10, 10.5, 11, 12, 14, 16, 18, 20, 24, 28, 36, 48, 72];
+
+/** Font families offered in the font picker. */
+const FONT_FAMILIES = [
+ 'Arial',
+ 'Calibri',
+ 'Cambria',
+ 'Courier New',
+ 'Garamond',
+ 'Georgia',
+ 'Segoe UI',
+ 'Tahoma',
+ 'Times New Roman',
+ 'Verdana',
+];
+
+/** Word's standard text colors (`RRGGBB`). */
+const TEXT_COLORS: Array<{ name: string; hex: string }> = [
+ { name: 'Black', hex: '000000' },
+ { name: 'Dark red', hex: 'C00000' },
+ { name: 'Red', hex: 'FF0000' },
+ { name: 'Orange', hex: 'FFC000' },
+ { name: 'Yellow', hex: 'FFFF00' },
+ { name: 'Light green', hex: '92D050' },
+ { name: 'Green', hex: '00B050' },
+ { name: 'Light blue', hex: '00B0F0' },
+ { name: 'Blue', hex: '0070C0' },
+ { name: 'Dark blue', hex: '002060' },
+ { name: 'Purple', hex: '7030A0' },
+];
+
+/** Word's highlight colors: name in the file, label, swatch. */
+const HIGHLIGHTS: Array<{ value: string; name: string; hex: string }> = [
+ { value: 'yellow', name: 'Yellow', hex: 'FFFF00' },
+ { value: 'green', name: 'Bright green', hex: '00FF00' },
+ { value: 'cyan', name: 'Turquoise', hex: '00FFFF' },
+ { value: 'magenta', name: 'Pink', hex: 'FF00FF' },
+ { value: 'blue', name: 'Blue', hex: '0000FF' },
+ { value: 'red', name: 'Red', hex: 'FF0000' },
+ { value: 'darkBlue', name: 'Dark blue', hex: '000080' },
+ { value: 'darkCyan', name: 'Teal', hex: '008080' },
+ { value: 'darkGreen', name: 'Green', hex: '008000' },
+ { value: 'darkMagenta', name: 'Violet', hex: '800080' },
+ { value: 'darkRed', name: 'Dark red', hex: '800000' },
+ { value: 'darkYellow', name: 'Dark yellow', hex: '808000' },
+ { value: 'darkGray', name: 'Gray 50%', hex: '808080' },
+ { value: 'lightGray', name: 'Gray 25%', hex: 'C0C0C0' },
+];
+
+/** Line spacing multiples offered. */
+const LINE_SPACINGS = [1, 1.15, 1.5, 2, 2.5, 3];
+
+const TABLE_OPS: Array<{ op: DocxTableOp; label: string }> = [
+ { op: 'rowAbove', label: 'Insert row above' },
+ { op: 'rowBelow', label: 'Insert row below' },
+ { op: 'columnLeft', label: 'Insert column left' },
+ { op: 'columnRight', label: 'Insert column right' },
+ { op: 'deleteRow', label: 'Delete row' },
+ { op: 'deleteColumn', label: 'Delete column' },
+ { op: 'deleteTable', label: 'Delete table' },
+];
+
export type DocxToolbarProps = {
canEdit: boolean;
canComment: boolean;
format: Partial<Record<DocxInlineFormat, boolean>>;
+ /** Font size at the selection (points). */
+ fontSize: number | null;
+ /** Font family at the selection. */
+ fontFamily: string | null;
+ /** Text color at the selection (`RRGGBB`, null for automatic). */
+ color: string | null;
+ /** Highlight at the selection (a Word highlight name). */
+ highlight: string | null;
+ /** Line spacing of the paragraph as a multiple, when it is one. */
+ lineSpacing: number | null;
+ /** The caret is in a table. */
+ inTable: boolean;
paragraphStyle: string | null;
paragraphStyles: DocxParagraphStyle[];
- trackChanges: boolean;
+ /** Tracked changes shown inline (else the document as if accepted). */
+ showMarkup: boolean;
+ /** The document records everyone's edits as tracked changes. */
+ tracking: boolean;
+ /** The selection (or the caret) is on a tracked change. */
+ onRevision: boolean;
onFormat: (format: DocxInlineFormat) => void;
+ onFontSize: (size: number) => void;
+ onFontFamily: (family: string) => void;
+ /** Set the text color (`RRGGBB`), or null for automatic. */
+ onColor: (color: string | null) => void;
+ /** Set the highlight (a Word highlight name), or null to remove it. */
+ onHighlight: (highlight: string | null) => void;
+ onClearFormat: () => void;
+ /** Indent (or outdent) the paragraphs. */
+ onIndent: (forward: boolean) => void;
+ onLineSpacing: (multiple: number) => void;
+ onTable: (op: DocxTableOp) => void;
+ /** Put focus back in the document (after a menu closes). */
+ onRefocus?: () => void;
onParagraphStyle: (styleId: string) => void;
- onList: (kind: 'bullet' | 'decimal') => void;
+ onList: (kind: 'bullet' | 'number') => void;
onAlign: (alignment: DocxAlignment) => void;
onUndo: () => void;
onRedo: () => void;
onInsertTable: () => void;
- onToggleTrackChanges: () => void;
+ /** Insert a footnote (or endnote) at the caret. */
+ onInsertNote: (endnote: boolean) => void;
+ /** The selection is in the body (notes are inserted from there). */
+ inBody: boolean;
+ onToggleMarkup: () => void;
+ onToggleTracking: () => void;
+ /** Accept the change at the selection, or every change. */
+ onAccept: (all: boolean) => void;
+ /** Reject the change at the selection, or every change. */
+ onReject: (all: boolean) => void;
onComment: () => void;
+ /** Open find (and replace). */
+ onFind: () => void;
onDownload: () => void;
};
@@ -64,8 +201,63 @@ const INLINE: Array<{
label: 'Strikethrough',
icon: () => <TextStrikethrough />,
},
+ {
+ format: 'superscript',
+ label: 'Superscript',
+ icon: () => <TextSuperscript />,
+ shortcut: 'Mod+Shift+=',
+ },
+ {
+ format: 'subscript',
+ label: 'Subscript',
+ icon: () => <TextSubscript />,
+ shortcut: 'Mod+=',
+ },
];
+/** A square of a document color. */
+function Swatch(props: { hex: string | null }) {
+ return (
+ <span
+ class="inline-block size-3.5 shrink-0 rounded-[3px] border border-edge-muted"
+ style={{ background: props.hex ? `#${props.hex}` : 'transparent' }}
+ />
+ );
+}
+
+/** A toolbar button opening a menu; closing it hands focus back to the
+ * document through `onClose`. */
+function ToolbarMenu(props: {
+ label: string;
+ icon: JSX.Element;
+ children: JSX.Element;
+ testId?: string;
+ onClose?: () => void;
+}) {
+ return (
+ <Dropdown placement="bottom-start" modal={false}>
+ <Dropdown.Trigger
+ variant="ghost"
+ size="icon-sm"
+ label={props.label}
+ data-docx-menu={props.testId}
+ >
+ {props.icon}
+ </Dropdown.Trigger>
+ <Dropdown.Content
+ class="min-w-44"
+ onCloseAutoFocus={(event: Event) => {
+ if (!props.onClose) return;
+ event.preventDefault();
+ props.onClose();
+ }}
+ >
+ {props.children}
+ </Dropdown.Content>
+ </Dropdown>
+ );
+}
+
const ALIGNMENTS: Array<{
alignment: DocxAlignment;
label: string;
@@ -140,7 +332,59 @@ export function DocxToolbar(props: DocxToolbarProps) {
</option>
</Show>
<For each={props.paragraphStyles}>
- {(style) => <option value={style.id}>{style.name}</option>}
+ {(style) => (
+ <option
+ value={style.id}
+ selected={style.id === props.paragraphStyle}
+ >
+ {style.name}
+ </option>
+ )}
+ </For>
+ </select>
+ <select
+ aria-label="Font"
+ class="h-6 max-w-32 rounded-md border border-edge-muted bg-input px-1.5 text-xs text-ink"
+ value={props.fontFamily ?? ''}
+ onChange={(event) => props.onFontFamily(event.currentTarget.value)}
+ >
+ <Show
+ when={
+ props.fontFamily !== null &&
+ !FONT_FAMILIES.includes(props.fontFamily)
+ }
+ >
+ <option value={props.fontFamily ?? ''}>{props.fontFamily}</option>
+ </Show>
+ <For each={FONT_FAMILIES}>
+ {(family) => (
+ <option value={family} selected={family === props.fontFamily}>
+ {family}
+ </option>
+ )}
+ </For>
+ </select>
+ <select
+ aria-label="Font size"
+ class="h-6 w-14 rounded-md border border-edge-muted bg-input px-1 text-xs text-ink"
+ value={props.fontSize ?? ''}
+ onChange={(event) =>
+ props.onFontSize(Number(event.currentTarget.value))
+ }
+ >
+ <Show
+ when={
+ props.fontSize !== null && !FONT_SIZES.includes(props.fontSize)
+ }
+ >
+ <option value={props.fontSize ?? ''}>{props.fontSize}</option>
+ </Show>
+ <For each={FONT_SIZES}>
+ {(size) => (
+ <option value={size} selected={size === props.fontSize}>
+ {size}
+ </option>
+ )}
</For>
</select>
<Toolbar.Divider />
@@ -157,6 +401,56 @@ export function DocxToolbar(props: DocxToolbarProps) {
</Toolbar.Button>
)}
</For>
+ <ToolbarMenu
+ label="Text color"
+ icon={<TextAUnderline />}
+ testId="color"
+ onClose={props.onRefocus}
+ >
+ <Dropdown.Item onSelect={() => props.onColor(null)}>
+ <Swatch hex={null} />
+ <span>Automatic</span>
+ </Dropdown.Item>
+ <For each={TEXT_COLORS}>
+ {(c) => (
+ <Dropdown.Item onSelect={() => props.onColor(c.hex)}>
+ <Swatch hex={c.hex} />
+ <span>{c.name}</span>
+ <Show when={props.color === c.hex}>
+ <Check class="ml-auto size-3.5" />
+ </Show>
+ </Dropdown.Item>
+ )}
+ </For>
+ </ToolbarMenu>
+ <ToolbarMenu
+ label="Highlight"
+ icon={<Highlighter />}
+ testId="highlight"
+ onClose={props.onRefocus}
+ >
+ <Dropdown.Item onSelect={() => props.onHighlight(null)}>
+ <Swatch hex={null} />
+ <span>No highlight</span>
+ </Dropdown.Item>
+ <For each={HIGHLIGHTS}>
+ {(h) => (
+ <Dropdown.Item onSelect={() => props.onHighlight(h.value)}>
+ <Swatch hex={h.hex} />
+ <span>{h.name}</span>
+ <Show when={props.highlight === h.value}>
+ <Check class="ml-auto size-3.5" />
+ </Show>
+ </Dropdown.Item>
+ )}
+ </For>
+ </ToolbarMenu>
+ <Toolbar.Button
+ label="Clear formatting"
+ onClick={() => props.onClearFormat()}
+ >
+ <TextTSlash />
+ </Toolbar.Button>
</Toolbar.Group>
<Toolbar.Divider />
<Toolbar.Group>
@@ -168,7 +462,7 @@ export function DocxToolbar(props: DocxToolbarProps) {
</Toolbar.Button>
<Toolbar.Button
label="Numbered list"
- onClick={() => props.onList('decimal')}
+ onClick={() => props.onList('number')}
>
<ListNumbers />
</Toolbar.Button>
@@ -185,6 +479,41 @@ export function DocxToolbar(props: DocxToolbarProps) {
</Toolbar.Button>
)}
</For>
+ <Toolbar.Button
+ label="Decrease indent"
+ shortcut="Shift+Tab"
+ onClick={() => props.onIndent(false)}
+ >
+ <TextOutdent />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label="Increase indent"
+ onClick={() => props.onIndent(true)}
+ >
+ <TextIndent />
+ </Toolbar.Button>
+ <ToolbarMenu
+ label="Line spacing"
+ icon={<ArrowsDownUp />}
+ testId="line-spacing"
+ onClose={props.onRefocus}
+ >
+ <For each={LINE_SPACINGS}>
+ {(m) => (
+ <Dropdown.Item onSelect={() => props.onLineSpacing(m)}>
+ <span>{m.toFixed(m === 1.15 ? 2 : 1)}</span>
+ <Show
+ when={
+ props.lineSpacing !== null &&
+ Math.abs(props.lineSpacing - m) < 0.01
+ }
+ >
+ <Check class="ml-auto size-3.5" />
+ </Show>
+ </Dropdown.Item>
+ )}
+ </For>
+ </ToolbarMenu>
</Toolbar.Group>
<Toolbar.Divider />
<Toolbar.Button
@@ -193,15 +522,89 @@ export function DocxToolbar(props: DocxToolbarProps) {
>
<Table />
</Toolbar.Button>
- <Toolbar.Button
- label={
- props.trackChanges ? 'Stop tracking changes' : 'Track changes'
- }
- aria-pressed={props.trackChanges}
- onClick={() => props.onToggleTrackChanges()}
- >
- <PencilSimpleLine />
- </Toolbar.Button>
+ <Show when={props.inBody}>
+ <ToolbarMenu
+ label="Insert footnote or endnote"
+ icon={<AsteriskSimple />}
+ testId="notes"
+ onClose={props.onRefocus}
+ >
+ <Dropdown.Item onSelect={() => props.onInsertNote(false)}>
+ <span>Footnote</span>
+ </Dropdown.Item>
+ <Dropdown.Item onSelect={() => props.onInsertNote(true)}>
+ <span>Endnote</span>
+ </Dropdown.Item>
+ </ToolbarMenu>
+ </Show>
+ <Show when={props.inTable}>
+ <ToolbarMenu
+ label="Table rows and columns"
+ icon={<RowsPlusBottom />}
+ testId="table"
+ onClose={props.onRefocus}
+ >
+ <For each={TABLE_OPS}>
+ {(item) => (
+ <Dropdown.Item onSelect={() => props.onTable(item.op)}>
+ <span>{item.label}</span>
+ </Dropdown.Item>
+ )}
+ </For>
+ </ToolbarMenu>
+ </Show>
+ <Toolbar.Divider />
+ <Toolbar.Group>
+ <Toolbar.Button
+ label={props.tracking ? 'Stop tracking changes' : 'Track changes'}
+ aria-pressed={props.tracking}
+ data-docx-track-changes
+ onClick={() => props.onToggleTracking()}
+ >
+ <GitDiff />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label={
+ props.showMarkup
+ ? 'Hide tracked changes'
+ : 'Show tracked changes'
+ }
+ aria-pressed={props.showMarkup}
+ onClick={() => props.onToggleMarkup()}
+ >
+ <Show when={props.showMarkup} fallback={<EyeSlash />}>
+ <Eye />
+ </Show>
+ </Toolbar.Button>
+ <Show when={props.tracking || props.onRevision}>
+ <Toolbar.Button
+ label="Accept change"
+ disabled={!props.onRevision}
+ onClick={() => props.onAccept(false)}
+ >
+ <Check />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label="Reject change"
+ disabled={!props.onRevision}
+ onClick={() => props.onReject(false)}
+ >
+ <X />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label="Accept all changes"
+ onClick={() => props.onAccept(true)}
+ >
+ <Checks />
+ </Toolbar.Button>
+ <Toolbar.Button
+ label="Reject all changes"
+ onClick={() => props.onReject(true)}
+ >
+ <XCircle />
+ </Toolbar.Button>
+ </Show>
+ </Toolbar.Group>
<Toolbar.Divider />
</Show>
<Show when={props.canComment}>
@@ -213,6 +616,13 @@ export function DocxToolbar(props: DocxToolbarProps) {
<ChatCircleText />
</Toolbar.Button>
</Show>
+ <Toolbar.Button
+ label="Find and replace"
+ shortcut="Mod+F"
+ onClick={() => props.onFind()}
+ >
+ <MagnifyingGlass />
+ </Toolbar.Button>
<Toolbar.Button
label="Download .docx"
onClick={() => props.onDownload()}
diff --git a/apps/web/src/features/block-write/core/clipboard.test.ts b/apps/web/src/features/block-write/core/clipboard.test.ts
new file mode 100644
index 0000000000..f096a886cf
--- /dev/null
+++ b/apps/web/src/features/block-write/core/clipboard.test.ts
@@ -0,0 +1,108 @@
+import type { Clip } from '@core/docx-engine/types';
+import { describe, expect, it } from 'vitest';
+import {
+ clipboardHtml,
+ htmlToParagraphs,
+ readClipboardHtml,
+} from './clipboard';
+
+const read = (html: string) => readClipboardHtml(html, 'doc-1').paragraphs;
+
+describe('clipboard', () => {
+ it('round-trips its own paragraphs and tells documents apart', () => {
+ const clip: Clip = {
+ paragraphs: [
+ {
+ runs: [{ text: 'Héllo “world”', attrs: { 'r:w:b': '<w:b/>' } }],
+ props: '<w:pPr><w:pStyle w:val="Heading1"/></w:pPr>',
+ },
+ ],
+ html: '<meta charset="utf-8"><h1>Héllo</h1>',
+ text: 'Héllo “world”',
+ };
+ const html = clipboardHtml(clip, 'doc-1');
+ expect(html).toContain('<h1>Héllo</h1>');
+ expect(readClipboardHtml(html, 'doc-1')).toEqual({
+ paragraphs: clip.paragraphs,
+ sameDocument: true,
+ });
+ expect(readClipboardHtml(html, 'doc-2').sameDocument).toBe(false);
+ });
+
+ it('reads a native payload it did not write as ordinary HTML', () => {
+ const forged = btoa(
+ JSON.stringify({
+ v: 1,
+ doc: 'doc-1',
+ key: 'guessed',
+ paragraphs: [
+ { runs: [{ text: 'x', attrs: { 'r:w:b': '</w:rPr><w:evil/>' } }] },
+ ],
+ })
+ );
+ const html = `<div data-macro-docx="${forged}"><p><b>Shown</b></p></div>`;
+ expect(readClipboardHtml(html, 'doc-1')).toEqual({
+ paragraphs: [{ runs: [{ text: 'Shown', bold: true }] }],
+ sameDocument: false,
+ });
+ });
+
+ it('reads Google Docs HTML', () => {
+ const html =
+ '<meta charset="utf-8"><b style="font-weight:normal;" id="docs-internal-guid-1"><p dir="ltr"><span style="font-weight:700;">Bold</span><span style="font-weight:400;font-style:italic;"> and italic</span></p><ul><li dir="ltr"><p dir="ltr"><span>One</span></p></li><li><p><span>Two</span></p><ol><li><p><span>Nested</span></p></li></ol></li></ul><h2 dir="ltr"><span>Title</span></h2><br><p><span style="text-decoration:underline;">Under</span></p></b>';
+ expect(read(html)).toEqual([
+ {
+ runs: [
+ { text: 'Bold', bold: true },
+ { text: ' and italic', italic: true },
+ ],
+ },
+ { runs: [{ text: 'One' }], list: 'bullet', level: 0 },
+ { runs: [{ text: 'Two' }], list: 'bullet', level: 0 },
+ { runs: [{ text: 'Nested' }], list: 'number', level: 1 },
+ { runs: [{ text: 'Title' }], heading: 2 },
+ { runs: [] },
+ { runs: [{ text: 'Under', underline: true }] },
+ // The last paragraph's mark.
+ { runs: [] },
+ ]);
+ });
+
+ it('reads Word HTML lists without their labels', () => {
+ const html = `<html><body><!--StartFragment--><p class=MsoListParagraphCxSpFirst style='text-indent:-.25in;mso-list:l0 level1 lfo1'><span style='font-family:Symbol'><span style='mso-list:Ignore'>·<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; </span></span></span>Item one<o:p></o:p></p><p class=MsoListParagraphCxSpLast style='text-indent:-.25in;mso-list:l1 level2 lfo2'><span style='mso-list:Ignore'>(a)<span>&nbsp; </span></span>Sub <b>item</b><o:p></o:p></p><!--EndFragment--></body></html>`;
+ expect(read(html)).toEqual([
+ { runs: [{ text: 'Item one' }], list: 'bullet', level: 0 },
+ {
+ runs: [{ text: 'Sub ' }, { text: 'item', bold: true }],
+ list: 'number',
+ level: 1,
+ },
+ { runs: [] },
+ ]);
+ });
+
+ it('collapses whitespace, keeps line breaks and joins table cells', () => {
+ const doc = new DOMParser().parseFromString(
+ '<p> Hello\n world </p><p>line<br>break</p><table><tr><td>A</td><td><b>B</b></td></tr></table><pre>a b</pre>',
+ 'text/html'
+ );
+ expect(htmlToParagraphs(doc.body)).toEqual([
+ { runs: [{ text: 'Hello world' }] },
+ { runs: [{ text: 'line\nbreak' }] },
+ { runs: [{ text: 'A\t' }, { text: 'B', bold: true }] },
+ { runs: [{ text: 'a b' }] },
+ { runs: [] },
+ ]);
+ // One paragraph, or text after the last block, pastes inline.
+ expect(
+ htmlToParagraphs(
+ new DOMParser().parseFromString('<p>Only</p>', 'text/html').body
+ )
+ ).toEqual([{ runs: [{ text: 'Only' }] }]);
+ expect(
+ htmlToParagraphs(
+ new DOMParser().parseFromString('<p>One</p>two', 'text/html').body
+ )
+ ).toEqual([{ runs: [{ text: 'One' }] }, { runs: [{ text: 'two' }] }]);
+ });
+});
diff --git a/apps/web/src/features/block-write/core/clipboard.ts b/apps/web/src/features/block-write/core/clipboard.ts
new file mode 100644
index 0000000000..beadbf0a0b
--- /dev/null
+++ b/apps/web/src/features/block-write/core/clipboard.ts
@@ -0,0 +1,378 @@
+import type {
+ Clip,
+ ClipParagraph,
+ ClipRun,
+ ListKind,
+} from '@core/docx-engine/types';
+
+/**
+ * The clipboard for DOCX documents. A copy goes out as plain text and as
+ * HTML that carries Macro's own form of the paragraphs in an attribute, so
+ * pasting back into a DOCX keeps every run's formatting while other
+ * applications read ordinary HTML. Pasted HTML from elsewhere (Word, Google
+ * Docs, web pages) becomes paragraphs with headings, lists and basic
+ * character formatting.
+ */
+
+const NATIVE = 'data-macro-docx';
+
+/**
+ * A copy carries this browser's clipboard key, so a paste trusts only
+ * paragraphs this app copied: a web page can put the same attribute in its
+ * HTML, and its runs' raw markup must not reach the document. The key is
+ * shared by this origin's tabs (so copies between documents keep their
+ * formatting) and unreadable to other sites.
+ */
+type Native = {
+ v: 1;
+ doc: string;
+ key: string;
+ paragraphs: ClipParagraph[];
+};
+
+const KEY_STORAGE = 'macro-docx-clipboard-key';
+let sessionKey: string | undefined;
+
+function clipboardKey(): string {
+ if (sessionKey) return sessionKey;
+ try {
+ const stored = localStorage.getItem(KEY_STORAGE);
+ if (stored) {
+ sessionKey = stored;
+ return stored;
+ }
+ } catch {
+ // Storage blocked: the key lasts as long as this page.
+ }
+ const bytes = crypto.getRandomValues(new Uint8Array(16));
+ sessionKey = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join(
+ ''
+ );
+ try {
+ localStorage.setItem(KEY_STORAGE, sessionKey);
+ } catch {
+ // As above.
+ }
+ return sessionKey;
+}
+
+function toBase64(text: string): string {
+ const bytes = new TextEncoder().encode(text);
+ let binary = '';
+ for (let i = 0; i < bytes.length; i += 0x8000)
+ binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+ return btoa(binary);
+}
+
+function fromBase64(data: string): string {
+ const binary = atob(data);
+ const bytes = new Uint8Array(binary.length);
+ for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+ return new TextDecoder().decode(bytes);
+}
+
+/** The HTML a copy puts on the clipboard. */
+export function clipboardHtml(clip: Clip, documentId: string): string {
+ const native: Native = {
+ v: 1,
+ doc: documentId,
+ key: clipboardKey(),
+ paragraphs: clip.paragraphs,
+ };
+ const body = clip.html.replace(/^<meta[^>]*>/, '');
+ return `<meta charset="utf-8"><div ${NATIVE}="${toBase64(JSON.stringify(native))}">${body}</div>`;
+}
+
+type Format = {
+ bold: boolean;
+ italic: boolean;
+ underline: boolean;
+ strike: boolean;
+ superscript: boolean;
+ subscript: boolean;
+ /** Whitespace is kept as it is (`pre`, `pre-wrap`). */
+ pre: boolean;
+};
+
+const PLAIN: Format = {
+ bold: false,
+ italic: false,
+ underline: false,
+ strike: false,
+ superscript: false,
+ subscript: false,
+ pre: false,
+};
+
+const SKIPPED = new Set([
+ 'SCRIPT',
+ 'STYLE',
+ 'HEAD',
+ 'TITLE',
+ 'META',
+ 'LINK',
+ 'TEMPLATE',
+ 'NOSCRIPT',
+ 'SVG',
+ 'IMG',
+ 'OBJECT',
+ 'IFRAME',
+ 'BUTTON',
+ 'SELECT',
+ 'INPUT',
+ 'TEXTAREA',
+]);
+
+const BLOCKS = new Set([
+ 'P',
+ 'DIV',
+ 'H1',
+ 'H2',
+ 'H3',
+ 'H4',
+ 'H5',
+ 'H6',
+ 'LI',
+ 'BLOCKQUOTE',
+ 'PRE',
+ 'TR',
+ 'DT',
+ 'DD',
+ 'SECTION',
+ 'ARTICLE',
+ 'HEADER',
+ 'FOOTER',
+ 'ADDRESS',
+ 'FIGURE',
+ 'FIGCAPTION',
+ 'CENTER',
+ 'UL',
+ 'OL',
+ 'TABLE',
+ 'HR',
+]);
+
+/** Character formatting an element adds (or, through its style, removes). */
+function formatOf(element: HTMLElement, outer: Format): Format {
+ const f = { ...outer };
+ switch (element.tagName) {
+ case 'B':
+ case 'STRONG':
+ f.bold = true;
+ break;
+ case 'I':
+ case 'EM':
+ case 'CITE':
+ case 'VAR':
+ f.italic = true;
+ break;
+ case 'U':
+ case 'INS':
+ f.underline = true;
+ break;
+ case 'S':
+ case 'STRIKE':
+ case 'DEL':
+ f.strike = true;
+ break;
+ case 'SUP':
+ f.superscript = true;
+ break;
+ case 'SUB':
+ f.subscript = true;
+ break;
+ case 'PRE':
+ f.pre = true;
+ break;
+ }
+ const style = element.style;
+ const weight = style.fontWeight;
+ if (weight) {
+ const n = Number(weight);
+ f.bold = Number.isFinite(n) ? n >= 600 : /bold/.test(weight);
+ }
+ if (style.fontStyle) f.italic = /italic|oblique/.test(style.fontStyle);
+ const decoration = style.textDecorationLine || style.textDecoration;
+ if (decoration) {
+ f.underline = decoration.includes('underline');
+ f.strike = decoration.includes('line-through');
+ }
+ const vertical = style.verticalAlign;
+ if (vertical === 'super') f.superscript = true;
+ if (vertical === 'sub') f.subscript = true;
+ if (vertical === 'baseline') f.superscript = f.subscript = false;
+ const space = style.whiteSpace;
+ if (space) f.pre = /pre/.test(space);
+ return f;
+}
+
+/** Word's list markup: `mso-list: l0 level2 lfo1` on a paragraph. */
+function wordListLevel(element: HTMLElement): number | undefined {
+ const match = /mso-list:\s*l\d+\s+level(\d+)/i.exec(
+ element.getAttribute('style') ?? ''
+ );
+ return match ? Number(match[1]) - 1 : undefined;
+}
+
+function isWordListLabel(element: HTMLElement): boolean {
+ return /mso-list:\s*ignore/i.test(element.getAttribute('style') ?? '');
+}
+
+/** Paragraphs from HTML that did not come from this editor. */
+export function htmlToParagraphs(root: ParentNode): ClipParagraph[] {
+ const out: ClipParagraph[] = [];
+ let current: ClipParagraph = { runs: [] };
+ /** Whether the paragraph so far ends in whitespace (for collapsing). */
+ let trailingSpace = true;
+
+ /**
+ * Ends the paragraph being collected. An empty one is dropped but keeps
+ * its heading or list settings for the block nested in it (a `<p>` inside
+ * an `<li>`), unless `reset`.
+ */
+ const flush = (keepEmpty = false, reset = false) => {
+ const runs = current.runs;
+ const last = runs[runs.length - 1];
+ if (last) last.text = last.text.replace(/[ \t]+$/, '');
+ const filtered = runs.filter((r) => r.text.length > 0);
+ if (filtered.length || keepEmpty) {
+ out.push({ ...current, runs: filtered });
+ current = { runs: [] };
+ } else {
+ current = reset ? { runs: [] } : { ...current, runs: [] };
+ }
+ trailingSpace = true;
+ };
+
+ const push = (text: string, f: Format) => {
+ let t = text;
+ if (!f.pre) {
+ t = t.replace(/[\t\n\r ]+/g, ' ');
+ if (trailingSpace) t = t.replace(/^ /, '');
+ }
+ if (!t) return;
+ trailingSpace = /[ \t\n]$/.test(t);
+ const run: ClipRun = { text: t };
+ for (const key of [
+ 'bold',
+ 'italic',
+ 'underline',
+ 'strike',
+ 'superscript',
+ 'subscript',
+ ] as const)
+ if (f[key]) run[key] = true;
+ const last = current.runs[current.runs.length - 1];
+ const same =
+ last &&
+ [
+ 'bold',
+ 'italic',
+ 'underline',
+ 'strike',
+ 'superscript',
+ 'subscript',
+ ].every((k) => !!last[k as keyof ClipRun] === !!run[k as keyof ClipRun]);
+ if (same && last) last.text += t;
+ else current.runs.push(run);
+ };
+
+ const walk = (
+ node: Node,
+ f: Format,
+ list: { kind: ListKind; depth: number } | undefined,
+ cells: { count: number }
+ ) => {
+ if (node.nodeType === Node.TEXT_NODE) {
+ push(node.textContent ?? '', f);
+ return;
+ }
+ if (node.nodeType !== Node.ELEMENT_NODE) return;
+ const element = node as HTMLElement;
+ const tag = element.tagName.toUpperCase();
+ if (SKIPPED.has(tag) || isWordListLabel(element)) return;
+ if (tag === 'BR') {
+ if (current.runs.length) push('\n', { ...f, pre: true });
+ else flush(true);
+ trailingSpace = true;
+ return;
+ }
+ const format = formatOf(element, f);
+ if (tag === 'TD' || tag === 'TH') {
+ if (cells.count++ > 0) push('\t', { ...format, pre: true });
+ for (const child of element.childNodes)
+ walk(child, format, list, { count: 0 });
+ return;
+ }
+ if (!BLOCKS.has(tag)) {
+ for (const child of element.childNodes) walk(child, format, list, cells);
+ return;
+ }
+ flush();
+ let inner = list;
+ if (tag === 'UL' || tag === 'OL') {
+ inner = {
+ kind: tag === 'UL' ? 'bullet' : 'number',
+ depth: list ? list.depth + 1 : 0,
+ };
+ }
+ if (/^H[1-6]$/.test(tag)) current.heading = Number(tag[1]);
+ if (tag === 'LI' && list) {
+ current.list = list.kind;
+ current.level = list.depth;
+ }
+ const wordLevel = wordListLevel(element);
+ if (wordLevel !== undefined) {
+ const label = element.querySelector('[style*="mso-list"]');
+ const text = (label?.textContent ?? '').trim();
+ current.list = /^\(?[0-9a-zA-Z]{1,6}[.):]?$/.test(text)
+ ? 'number'
+ : 'bullet';
+ current.level = wordLevel;
+ }
+ const rowCells = { count: 0 };
+ for (const child of element.childNodes)
+ walk(child, format, inner, tag === 'TR' ? rowCells : cells);
+ flush(false, true);
+ };
+
+ for (const child of root.childNodes)
+ walk(child, PLAIN, undefined, { count: 0 });
+ // Text after the last block is an unfinished paragraph.
+ const unfinished = current.runs.some((r) => r.text.trim());
+ flush();
+ // Several whole paragraphs end with their paragraph mark: what follows
+ // the caret stays a paragraph of its own.
+ if (out.length > 1 && !unfinished) out.push({ runs: [] });
+ return out;
+}
+
+/**
+ * What pasted HTML holds: this editor's own paragraphs (and whether they
+ * came from the same document), or paragraphs read from foreign HTML.
+ */
+export function readClipboardHtml(
+ html: string,
+ documentId: string
+): { paragraphs: ClipParagraph[]; sameDocument: boolean } {
+ const parsed = new DOMParser().parseFromString(html, 'text/html');
+ const marked = parsed.querySelector(`[${NATIVE}]`);
+ const data = marked?.getAttribute(NATIVE);
+ if (data) {
+ try {
+ const native = JSON.parse(fromBase64(data)) as Native;
+ if (
+ native.v === 1 &&
+ native.key === clipboardKey() &&
+ Array.isArray(native.paragraphs)
+ )
+ return {
+ paragraphs: native.paragraphs,
+ sameDocument: native.doc === documentId,
+ };
+ } catch {
+ // Not ours after all: read it as HTML.
+ }
+ }
+ return { paragraphs: htmlToParagraphs(parsed.body), sameDocument: false };
+}
diff --git a/apps/web/src/features/block-write/core/comment-marks.ts b/apps/web/src/features/block-write/core/comment-marks.ts
index 96e9bba6b5..6425f9b7d4 100644
--- a/apps/web/src/features/block-write/core/comment-marks.ts
+++ b/apps/web/src/features/block-write/core/comment-marks.ts
@@ -1,5 +1,5 @@
-import { DOCX_LORO_CONTAINERS } from '@macro-inc/collaboration/docx/schema';
import type { LoroDoc } from 'loro-crdt';
+import { DOCX_LORO_CONTAINERS } from './docx-loro';
/**
* Where a comment thread is anchored in a DOCX: a span of one paragraph's
diff --git a/apps/web/src/features/block-write/core/delta.test.ts b/apps/web/src/features/block-write/core/delta.test.ts
new file mode 100644
index 0000000000..26e03075cb
--- /dev/null
+++ b/apps/web/src/features/block-write/core/delta.test.ts
@@ -0,0 +1,88 @@
+import type { DeltaOp } from '@core/docx-engine/types';
+import { describe, expect, it } from 'vitest';
+import { applyToText, transform } from './delta';
+
+/** Both orders of applying two concurrent edits give the same text. */
+function converges(text: string, a: DeltaOp[], b: DeltaOp[]) {
+ const ab = applyToText(applyToText(text, a), transform(a, b));
+ return ab;
+}
+
+describe('transform', () => {
+ it('shifts an insert past text inserted before it', () => {
+ const remote: DeltaOp[] = [{ insert: 'abc' }];
+ const local: DeltaOp[] = [{ retain: 5 }, { insert: 'X' }];
+ expect(transform(remote, local)).toEqual([{ retain: 8 }, { insert: 'X' }]);
+ expect(converges('Hello world', remote, local)).toBe('abcHelloX world');
+ });
+
+ it('puts the earlier side first at the same position', () => {
+ const remote: DeltaOp[] = [{ retain: 2 }, { insert: 'R' }];
+ const local: DeltaOp[] = [{ retain: 2 }, { insert: 'L' }];
+ expect(converges('abcd', remote, local)).toBe('abRLcd');
+ });
+
+ it('drops a delete of text already deleted', () => {
+ const remote: DeltaOp[] = [{ retain: 1 }, { delete: 3 }];
+ const local: DeltaOp[] = [{ retain: 2 }, { delete: 3 }];
+ expect(converges('abcdefg', remote, local)).toBe('afg');
+ });
+
+ it('keeps an insert inside a range the other side deleted', () => {
+ const remote: DeltaOp[] = [{ retain: 1 }, { delete: 4 }];
+ const local: DeltaOp[] = [{ retain: 3 }, { insert: 'X' }];
+ expect(converges('abcdefg', remote, local)).toBe('aXfg');
+ });
+
+ it('carries attribute changes over shifted text', () => {
+ const remote: DeltaOp[] = [{ insert: '>> ' }];
+ const local: DeltaOp[] = [{ retain: 2, attributes: { 'r:w:b': '<w:b/>' } }];
+ expect(transform(remote, local)).toEqual([
+ { retain: 3 },
+ { retain: 2, attributes: { 'r:w:b': '<w:b/>' } },
+ ]);
+ });
+
+ it('converges on random edits', () => {
+ let seed = 7;
+ const rand = (n: number) => {
+ seed = (seed * 1103515245 + 12345) % 2147483648;
+ return seed % n;
+ };
+ const edit = (len: number): DeltaOp[] => {
+ const at = rand(len + 1);
+ const ops: DeltaOp[] = at ? [{ retain: at }] : [];
+ if (rand(2) === 0) ops.push({ insert: 'xyz'.slice(0, 1 + rand(3)) });
+ else if (at < len) ops.push({ delete: 1 + rand(len - at) });
+ return ops;
+ };
+ for (let i = 0; i < 500; i++) {
+ const text = 'the quick brown fox'.slice(0, 1 + rand(19));
+ const a = edit(text.length);
+ const b = edit(text.length);
+ const viaA = applyToText(applyToText(text, a), transform(a, b));
+ const viaB = applyToText(applyToText(text, b), transform(b, a));
+ // Inserts at one spot order differently by side, so compare lengths
+ // and, without competing inserts, the exact text.
+ expect(viaA.length).toBe(viaB.length);
+ // With the same side first at ties both ways, the texts agree.
+ expect(applyToText(applyToText(text, a), transform(a, b, true))).toBe(
+ viaB
+ );
+ }
+ });
+
+ it('can put the second side first at the same position', () => {
+ const local: DeltaOp[] = [{ retain: 2 }, { insert: 'L' }];
+ const remote: DeltaOp[] = [{ retain: 2 }, { insert: 'R' }];
+ // The engine has the local edit; the shared text put the remote first.
+ expect(transform(local, remote, true)).toEqual([
+ { retain: 2 },
+ { insert: 'R' },
+ ]);
+ expect(applyToText('abcd', [...local])).toBe('abLcd');
+ expect(applyToText('abLcd', transform(local, remote, true))).toBe(
+ applyToText(applyToText('abcd', remote), transform(remote, local))
+ );
+ });
+});
diff --git a/apps/web/src/features/block-write/core/delta.ts b/apps/web/src/features/block-write/core/delta.ts
new file mode 100644
index 0000000000..83d2922d17
--- /dev/null
+++ b/apps/web/src/features/block-write/core/delta.ts
@@ -0,0 +1,167 @@
+import type { DeltaOp } from '@core/docx-engine/types';
+
+/**
+ * Rich-text deltas (Quill's format, as Loro and the DOCX engine exchange
+ * them): operational transformation of one paragraph's concurrent edits.
+ *
+ * The engine computes each local edit against the text it last knew; when
+ * another peer's change reached the shared document meanwhile, the local
+ * delta is transformed past it before it is applied.
+ */
+
+type Attributes = Record<string, string | null>;
+
+function length(op: DeltaOp): number {
+ if ('delete' in op) return op.delete;
+ if ('retain' in op) return op.retain;
+ return op.insert.length;
+}
+
+/** Walks a delta op by op, splitting ops on demand. */
+class Cursor {
+ private index = 0;
+ private offset = 0;
+
+ constructor(private readonly ops: readonly DeltaOp[]) {}
+
+ hasNext(): boolean {
+ return this.index < this.ops.length;
+ }
+
+ peekType(): 'insert' | 'delete' | 'retain' {
+ const op = this.ops[this.index];
+ if (!op) return 'retain';
+ if ('insert' in op) return 'insert';
+ if ('delete' in op) return 'delete';
+ return 'retain';
+ }
+
+ peekLength(): number {
+ const op = this.ops[this.index];
+ return op ? length(op) - this.offset : Number.POSITIVE_INFINITY;
+ }
+
+ /** The next op, or its first `max` units. Past the end: a plain retain. */
+ next(max = Number.POSITIVE_INFINITY): DeltaOp {
+ const op = this.ops[this.index];
+ if (!op) return { retain: max };
+ const rest = length(op) - this.offset;
+ const take = Math.min(rest, max);
+ const start = this.offset;
+ if (take === rest) {
+ this.index++;
+ this.offset = 0;
+ } else {
+ this.offset += take;
+ }
+ if ('delete' in op) return { delete: take };
+ if ('retain' in op)
+ return op.attributes
+ ? { retain: take, attributes: op.attributes }
+ : { retain: take };
+ const insert = op.insert.slice(start, start + take);
+ return op.attributes ? { insert, attributes: op.attributes } : { insert };
+ }
+}
+
+function sameAttributes(a?: Attributes, b?: Attributes): boolean {
+ const ka = a ? Object.keys(a) : [];
+ const kb = b ? Object.keys(b) : [];
+ if (ka.length !== kb.length) return false;
+ return ka.every((k) => b?.[k] === a?.[k]);
+}
+
+/** Appends an op, merging it with the last one when they combine. */
+function push(out: DeltaOp[], op: DeltaOp) {
+ if (length(op) === 0) return;
+ const last = out[out.length - 1];
+ if (last) {
+ if ('delete' in op && 'delete' in last) {
+ last.delete += op.delete;
+ return;
+ }
+ if (
+ 'retain' in op &&
+ 'retain' in last &&
+ sameAttributes(op.attributes, last.attributes)
+ ) {
+ last.retain += op.retain;
+ return;
+ }
+ if (
+ 'insert' in op &&
+ 'insert' in last &&
+ sameAttributes(op.attributes, last.attributes)
+ ) {
+ last.insert += op.insert;
+ return;
+ }
+ }
+ out.push({ ...op } as DeltaOp);
+}
+
+/** Drops a trailing plain retain. */
+function chop(ops: DeltaOp[]): DeltaOp[] {
+ const last = ops[ops.length - 1];
+ if (last && 'retain' in last && !last.attributes) ops.pop();
+ return ops;
+}
+
+/**
+ * `b` rewritten to apply after `a`, where both were made against the same
+ * text and `a` is already applied. At the same position `a`'s insertion
+ * comes first (`b`'s with `bFirst`); when both change the same attribute,
+ * `b`'s value wins.
+ */
+export function transform(
+ a: readonly DeltaOp[],
+ b: readonly DeltaOp[],
+ bFirst = false
+): DeltaOp[] {
+ const ai = new Cursor(a);
+ const bi = new Cursor(b);
+ const out: DeltaOp[] = [];
+ while (ai.hasNext() || bi.hasNext()) {
+ const bInserts = bi.peekType() === 'insert' && bi.hasNext();
+ if (ai.peekType() === 'insert' && ai.hasNext() && !(bFirst && bInserts)) {
+ // Text the other side inserted: step over it.
+ push(out, { retain: length(ai.next()) });
+ continue;
+ }
+ if (bi.peekType() === 'insert' && bi.hasNext()) {
+ push(out, bi.next());
+ continue;
+ }
+ if (!bi.hasNext()) break;
+ const n = Math.min(ai.peekLength(), bi.peekLength());
+ const aop = ai.next(n);
+ const bop = bi.next(n);
+ if ('delete' in aop) {
+ // Already gone: whatever b did to it no longer applies.
+ continue;
+ }
+ if ('delete' in bop) {
+ push(out, bop);
+ continue;
+ }
+ // Both kept the text: b's attribute changes still apply.
+ const attributes = 'retain' in bop ? bop.attributes : undefined;
+ push(out, attributes ? { retain: n, attributes } : { retain: n });
+ }
+ return chop(out);
+}
+
+/** Applies a delta to plain text (attributes ignored), for tests and checks. */
+export function applyToText(text: string, delta: readonly DeltaOp[]): string {
+ let out = '';
+ let at = 0;
+ for (const op of delta) {
+ if ('insert' in op) out += op.insert;
+ else if ('delete' in op) at += op.delete;
+ else {
+ out += text.slice(at, at + op.retain);
+ at += op.retain;
+ }
+ }
+ return out + text.slice(at);
+}
diff --git a/apps/web/src/features/block-write/core/docx-collab.test.ts b/apps/web/src/features/block-write/core/docx-collab.test.ts
new file mode 100644
index 0000000000..b09df125d9
--- /dev/null
+++ b/apps/web/src/features/block-write/core/docx-collab.test.ts
@@ -0,0 +1,391 @@
+import type {
+ CollabState,
+ DeltaOp,
+ EditOp,
+ EditResult,
+ RemoteChange,
+} from '@core/docx-engine/types';
+import { LoroDoc, LoroText } from 'loro-crdt';
+import { describe, expect, it } from 'vitest';
+import { applyToText } from './delta';
+import { DocxCollab, type DocxEngine } from './docx-collab';
+import {
+ DOCX_LORO_CONTAINERS,
+ readBlock,
+ readCollabState,
+ writeCollabState,
+} from './docx-loro';
+
+const deltaText = (delta: DeltaOp[] = []) =>
+ delta.map((op) => ('insert' in op ? op.insert : '')).join('');
+
+const RESULT_BASE: Omit<EditResult, 'changes' | 'changed'> = {
+ selection: {
+ anchor: { block: '', offset: 0 },
+ focus: { block: '', offset: 0 },
+ },
+ range: {
+ from: { block: '', offset: 0 },
+ to: { block: '', offset: 0 },
+ },
+ caret: null,
+ rects: [],
+ story: { kind: 'body' },
+ format: {
+ bold: false,
+ italic: false,
+ underline: false,
+ strike: false,
+ superscript: false,
+ subscript: false,
+ font: null,
+ size: null,
+ color: null,
+ highlight: null,
+ style: null,
+ styleName: null,
+ align: null,
+ list: false,
+ lineSpacing: null,
+ table: false,
+ tracking: false,
+ revision: false,
+ canUndo: false,
+ canRedo: false,
+ },
+};
+
+/**
+ * A stand-in for the engine: paragraphs as plain text, typing at a
+ * selected position, and a gate that holds an edit in flight.
+ */
+class FakeEngine implements DocxEngine {
+ texts = new Map<string, string>();
+ private caret = { block: '', offset: 0 };
+ gate: Promise<void> | null = null;
+ /** Holds each batch of remote changes in flight until released. */
+ holdRemote = false;
+ private held: Array<() => void> = [];
+
+ constructor(state: CollabState) {
+ for (const b of state.blocks)
+ if (b.k === 'p') this.texts.set(b.id, deltaText(b.t));
+ }
+
+ async apply(ops: EditOp[]): Promise<EditResult | null> {
+ if (this.gate) await this.gate;
+ const changes: EditResult['changes'] = [];
+ for (const op of ops) {
+ if (op.op === 'select') this.caret = { ...op.focus };
+ if (op.op === 'insertText') {
+ const { block, offset } = this.caret;
+ const text = this.texts.get(block) ?? '';
+ this.texts.set(
+ block,
+ text.slice(0, offset) + op.text + text.slice(offset)
+ );
+ const delta: DeltaOp[] = offset
+ ? [{ retain: offset }, { insert: op.text }]
+ : [{ insert: op.text }];
+ changes.push({ t: 'text', id: block, delta });
+ this.caret = { block, offset: offset + op.text.length };
+ }
+ }
+ return { ...RESULT_BASE, changed: changes.length > 0, changes };
+ }
+
+ async applyRemote(changes: RemoteChange[]): Promise<EditResult | null> {
+ if (this.holdRemote)
+ await new Promise<void>((resolve) => this.held.push(resolve));
+ for (const c of changes) {
+ if (c.t === 'block' && c.block.k === 'p') {
+ const text = deltaText(c.block.t);
+ if (c.block.id === this.caret.block) {
+ // Like the engine: follow the changes when they fit the text.
+ let old = this.texts.get(c.block.id) ?? '';
+ let offset = this.caret.offset;
+ for (const d of c.deltas ?? []) {
+ old = applyToText(old, d);
+ offset = mapThrough(offset, d);
+ }
+ if (c.deltas?.length && old === text) this.caret.offset = offset;
+ }
+ this.texts.set(c.block.id, text);
+ }
+ if (c.t === 'remove') this.texts.delete(c.id);
+ }
+ return { ...RESULT_BASE, changed: false, changes: [] };
+ }
+}
+
+/** Lets the oldest held batch of remote changes through. */
+function releaseRemote(engine: FakeEngine) {
+ (engine as unknown as { held: Array<() => void> }).held.shift()?.();
+}
+
+/** The engine's caret mapping: text inserted at the caret goes after it. */
+function mapThrough(offset: number, delta: DeltaOp[]) {
+ let index = offset;
+ let at = 0;
+ for (const op of delta) {
+ if (at > index) break;
+ if ('delete' in op) index -= Math.min(op.delete, index - at);
+ else if ('retain' in op) at += op.retain;
+ else {
+ if (at < index) index += op.insert.length;
+ at += op.insert.length;
+ }
+ }
+ return index;
+}
+
+const STATE: CollabState = {
+ parts: { '/word/document.xml': '<w:document/>' },
+ types: {},
+ rels: {},
+ blocks: [
+ {
+ id: 'p1',
+ k: 'p',
+ p: '',
+ o: 'a0',
+ a: '',
+ x: '',
+ t: [{ insert: 'Hello world' }],
+ },
+ ],
+};
+
+function connect(a: LoroDoc, b: LoroDoc) {
+ // Deliver each side's commits to the other, as the sync service would.
+ a.subscribeLocalUpdates((update) => b.import(update));
+ b.subscribeLocalUpdates((update) => a.import(update));
+}
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+function paragraph(doc: LoroDoc, id: string): string {
+ const map = doc.getMap(DOCX_LORO_CONTAINERS.blocks).get(id);
+ return deltaText(readBlock(doc, id)?.t) + (map ? '' : '<missing>');
+}
+
+describe('DocxCollab', () => {
+ it('keeps the typist in place when both type at one spot', async () => {
+ const a = new LoroDoc();
+ writeCollabState(a, STATE);
+ const b = new LoroDoc();
+ b.import(a.export({ mode: 'snapshot' }));
+ connect(a, b);
+ const ea = new FakeEngine(readCollabState(a));
+ const eb = new FakeEngine(readCollabState(b));
+ const ca = new DocxCollab(a, ea);
+ const cb = new DocxCollab(b, eb);
+ const end = { block: 'p1', offset: 11 };
+ let release!: () => void;
+ ea.gate = new Promise((resolve) => {
+ release = resolve;
+ });
+ // A types a space at the end, held in flight while B types " x" there.
+ const pendingA = ca.apply([
+ { op: 'select', anchor: end, focus: end },
+ { op: 'insertText', text: ' ' },
+ ]);
+ await cb.apply([
+ { op: 'select', anchor: end, focus: end },
+ { op: 'insertText', text: ' x' },
+ ]);
+ await settle();
+ release();
+ await pendingA;
+ ea.gate = null;
+ await settle();
+ await ca.idle();
+ // A's space goes first: right after what A typed before.
+ expect(paragraph(a, 'p1')).toBe('Hello world x');
+ // A keeps typing after the space A typed, not inside B's text.
+ await ca.apply([{ op: 'insertText', text: 'y' }]);
+ await settle();
+ await cb.idle();
+ expect(paragraph(b, 'p1')).toBe('Hello world y x');
+ expect(eb.texts.get('p1')).toBe('Hello world y x');
+ ca.dispose();
+ cb.dispose();
+ });
+
+ it('applies changes that arrive while others are applied before a local edit', async () => {
+ const a = new LoroDoc();
+ writeCollabState(a, STATE);
+ const b = new LoroDoc();
+ b.import(a.export({ mode: 'snapshot' }));
+ connect(a, b);
+ const ea = new FakeEngine(readCollabState(a));
+ const eb = new FakeEngine(readCollabState(b));
+ const ca = new DocxCollab(a, ea);
+ const cb = new DocxCollab(b, eb);
+ const at = (offset: number): EditOp => ({
+ op: 'select',
+ anchor: { block: 'p1', offset },
+ focus: { block: 'p1', offset },
+ });
+ await ca.apply([at(11)]);
+ ea.holdRemote = true;
+ // B's first edit reaches A, which starts applying it (held there).
+ await cb.apply([at(0), { op: 'insertText', text: 'X' }]);
+ await settle();
+ // A types at the end; B's second edit arrives before A's turn.
+ const typed = ca.apply([{ op: 'insertText', text: '!' }]);
+ await cb.apply([{ op: 'insertText', text: 'Y' }]);
+ await settle();
+ // A's turn starts by applying that edit (held), and a third arrives.
+ releaseRemote(ea);
+ await settle();
+ await cb.apply([{ op: 'insertText', text: 'Z' }]);
+ await settle();
+ ea.holdRemote = false;
+ releaseRemote(ea);
+ await typed;
+ await settle();
+ await ca.idle();
+ await cb.idle();
+ // A's text went where A typed it, at the end.
+ expect(paragraph(a, 'p1')).toBe('XYZHello world!');
+ expect(paragraph(b, 'p1')).toBe('XYZHello world!');
+ expect(ea.texts.get('p1')).toBe('XYZHello world!');
+ ca.dispose();
+ cb.dispose();
+ });
+
+ it('seeds and reads back the shared state', () => {
+ const doc = new LoroDoc();
+ writeCollabState(doc, STATE);
+ expect(readCollabState(doc)).toEqual(STATE);
+ const text = doc
+ .getMap(DOCX_LORO_CONTAINERS.blocks)
+ .get('p1') as unknown as { get: (k: string) => unknown };
+ expect(text.get('t')).toBeInstanceOf(LoroText);
+ });
+
+ it('publishes local edits and applies remote ones', async () => {
+ const a = new LoroDoc();
+ writeCollabState(a, STATE);
+ const b = new LoroDoc();
+ b.import(a.export({ mode: 'snapshot' }));
+ connect(a, b);
+ const ea = new FakeEngine(readCollabState(a));
+ const eb = new FakeEngine(readCollabState(b));
+ const ca = new DocxCollab(a, ea);
+ const cb = new DocxCollab(b, eb);
+ await ca.apply([
+ {
+ op: 'select',
+ anchor: { block: 'p1', offset: 5 },
+ focus: { block: 'p1', offset: 5 },
+ },
+ { op: 'insertText', text: ',' },
+ ]);
+ await settle();
+ await cb.idle();
+ expect(paragraph(b, 'p1')).toBe('Hello, world');
+ expect(eb.texts.get('p1')).toBe('Hello, world');
+ ca.dispose();
+ cb.dispose();
+ });
+
+ it('converges when both peers type in one paragraph at once', async () => {
+ const a = new LoroDoc();
+ writeCollabState(a, STATE);
+ const b = new LoroDoc();
+ b.import(a.export({ mode: 'snapshot' }));
+ connect(a, b);
+ const ea = new FakeEngine(readCollabState(a));
+ const eb = new FakeEngine(readCollabState(b));
+ const ca = new DocxCollab(a, ea);
+ const cb = new DocxCollab(b, eb);
+ // A's edit is held in flight while B's lands in both documents.
+ let release!: () => void;
+ ea.gate = new Promise((resolve) => {
+ release = resolve;
+ });
+ const pendingA = ca.apply([
+ {
+ op: 'select',
+ anchor: { block: 'p1', offset: 11 },
+ focus: { block: 'p1', offset: 11 },
+ },
+ { op: 'insertText', text: '!' },
+ ]);
+ await cb.apply([
+ {
+ op: 'select',
+ anchor: { block: 'p1', offset: 0 },
+ focus: { block: 'p1', offset: 0 },
+ },
+ { op: 'insertText', text: '>> ' },
+ ]);
+ await settle();
+ release();
+ ea.gate = null;
+ await pendingA;
+ await settle();
+ await ca.idle();
+ await cb.idle();
+ expect(paragraph(a, 'p1')).toBe('>> Hello world!');
+ expect(paragraph(b, 'p1')).toBe('>> Hello world!');
+ // Both engines end up with what the shared document holds.
+ expect(ea.texts.get('p1')).toBe('>> Hello world!');
+ expect(eb.texts.get('p1')).toBe('>> Hello world!');
+ ca.dispose();
+ cb.dispose();
+ });
+
+ it('typing merges into one undo step; other edits are steps of their own', async () => {
+ const doc = new LoroDoc();
+ writeCollabState(doc, STATE);
+ const engine = new FakeEngine(readCollabState(doc));
+ const collab = new DocxCollab(doc, engine);
+ const at = (offset: number): EditOp => ({
+ op: 'select',
+ anchor: { block: 'p1', offset },
+ focus: { block: 'p1', offset },
+ });
+ // A command (no group), then typing in two batches, then a command.
+ await collab.apply([at(0), { op: 'insertText', text: '1' }]);
+ await collab.apply([at(1), { op: 'insertText', text: 'a' }], 'typing');
+ await collab.apply([{ op: 'insertText', text: 'b' }], 'typing');
+ await collab.apply([at(14), { op: 'insertText', text: '!' }]);
+ expect(paragraph(doc, 'p1')).toBe('1abHello world!');
+ const steps: string[] = [];
+ while (collab.undo()) {
+ await settle();
+ await collab.idle();
+ steps.push(paragraph(doc, 'p1'));
+ }
+ expect(steps).toEqual(['1abHello world', '1Hello world', 'Hello world']);
+ collab.dispose();
+ });
+
+ it('undo reverts this peer’s step and tells the engine', async () => {
+ const doc = new LoroDoc();
+ writeCollabState(doc, STATE);
+ const engine = new FakeEngine(readCollabState(doc));
+ const collab = new DocxCollab(doc, engine);
+ await collab.apply([
+ {
+ op: 'select',
+ anchor: { block: 'p1', offset: 0 },
+ focus: { block: 'p1', offset: 0 },
+ },
+ { op: 'insertText', text: 'Well, ' },
+ ]);
+ expect(collab.canUndo()).toBe(true);
+ expect(collab.undo()).toBe(true);
+ await settle();
+ await collab.idle();
+ expect(paragraph(doc, 'p1')).toBe('Hello world');
+ expect(engine.texts.get('p1')).toBe('Hello world');
+ expect(applyToText('Hello world', [{ retain: 5 }, { delete: 6 }])).toBe(
+ 'Hello'
+ );
+ collab.dispose();
+ });
+});
diff --git a/apps/web/src/features/block-write/core/docx-collab.ts b/apps/web/src/features/block-write/core/docx-collab.ts
new file mode 100644
index 0000000000..14e86d5719
--- /dev/null
+++ b/apps/web/src/features/block-write/core/docx-collab.ts
@@ -0,0 +1,279 @@
+import type {
+ DeltaOp,
+ EditOp,
+ EditResult,
+ RemoteChange,
+ Selection,
+} from '@core/docx-engine/types';
+import { type LoroDoc, type LoroEventBatch, UndoManager } from 'loro-crdt';
+import { transform } from './delta';
+import {
+ collectTouched,
+ configureDocxText,
+ DOCX_ORIGINS,
+ emptyTouched,
+ remoteChanges,
+ type Touched,
+ writeChanges,
+} from './docx-loro';
+
+/** Typing within this many milliseconds is one undo step. */
+const MERGE_INTERVAL = 800;
+
+/** The engine as the collaboration bridge drives it. */
+export interface DocxEngine {
+ apply(ops: EditOp[], group?: string): Promise<EditResult | null>;
+ applyRemote(changes: RemoteChange[]): Promise<EditResult | null>;
+}
+
+export type DocxCollabOptions = {
+ /**
+ * Whether this peer keeps an undo history of its own edits (default true;
+ * viewers only follow along).
+ */
+ undo?: boolean;
+ /** The selection to store with an undo step. */
+ selection?: () => Selection | undefined;
+ /** Called with the engine's result after changes from elsewhere applied. */
+ onRemote?: (result: EditResult, restored?: Selection) => void;
+ /** Called when an engine call fails. */
+ onError?: (error: unknown) => void;
+};
+
+function merge(into: Touched, from: Touched) {
+ for (const id of from.blocks) into.blocks.add(id);
+ for (const entry of from.entries) into.entries.add(entry);
+}
+
+function isSelection(value: unknown): value is Selection {
+ return (
+ typeof value === 'object' &&
+ value !== null &&
+ 'anchor' in value &&
+ 'focus' in value
+ );
+}
+
+/**
+ * Keeps one engine session and one collaborative Loro document in step.
+ *
+ * Local edits run in the engine first; their changes (text deltas, block
+ * fields, new and removed blocks) are written to the Loro document in one
+ * commit. Changes from other peers, and from undo and redo of the shared
+ * history, are read from Loro events and handed to the engine as whole
+ * blocks. Calls are serialized, so the engine never computes an edit
+ * against a document that changed under it, except for remote changes that
+ * arrive while an edit is in flight: those are recorded, the edit's text
+ * deltas are transformed past them, and the affected blocks are sent to the
+ * engine again so both sides converge.
+ */
+export class DocxCollab {
+ private chain: Promise<unknown> = Promise.resolve();
+ /** Remote changes the engine has not seen yet. */
+ private pending: Touched = emptyTouched();
+ /** Remote changes seen while a local edit is in flight. */
+ private inflight: Touched | null = null;
+ /**
+ * Per paragraph, the text changes that take the engine's copy to the
+ * shared one (in the engine's coordinates), so carets follow them
+ * exactly instead of being guessed from the texts.
+ */
+ private drift = new Map<string, DeltaOp[][]>();
+ private flushing = false;
+ private restored: Selection | undefined;
+ private readonly undoManager: UndoManager | undefined;
+ /** The group of the last local edit (typing merges into one step). */
+ private lastGroup: string | undefined;
+ private readonly unsubscribe: () => void;
+
+ constructor(
+ private readonly doc: LoroDoc,
+ private readonly engine: DocxEngine,
+ private readonly options: DocxCollabOptions = {}
+ ) {
+ configureDocxText(doc);
+ this.unsubscribe = doc.subscribe((batch) => this.onEvents(batch));
+ if (options.undo === false) return;
+ this.undoManager = new UndoManager(doc, {
+ mergeInterval: MERGE_INTERVAL,
+ maxUndoSteps: 300,
+ excludeOriginPrefixes: [
+ DOCX_ORIGINS.seed,
+ DOCX_ORIGINS.migrate,
+ DOCX_ORIGINS.comment,
+ ],
+ onPush: () => ({
+ value: (options.selection?.() ?? null) as never,
+ cursors: [],
+ }),
+ onPop: (_isUndo, meta) => {
+ const value = meta?.value as unknown;
+ this.restored = isSelection(value) ? value : undefined;
+ },
+ });
+ }
+
+ /** Stops listening; the Loro document and engine stay as they are. */
+ dispose() {
+ this.unsubscribe();
+ this.undoManager?.free();
+ }
+
+ private serial<T>(run: () => Promise<T>): Promise<T> {
+ const next = this.chain.then(run, run);
+ this.chain = next.catch(() => {});
+ return next;
+ }
+
+ private onEvents(batch: LoroEventBatch) {
+ if (batch.origin === DOCX_ORIGINS.local) return;
+ if (
+ batch.origin === DOCX_ORIGINS.seed ||
+ batch.origin === DOCX_ORIGINS.migrate ||
+ batch.origin === DOCX_ORIGINS.comment
+ )
+ return;
+ const touched = emptyTouched();
+ collectTouched(batch.events, touched);
+ merge(this.pending, touched);
+ if (this.inflight) {
+ // Where these land relative to the engine's copy is known once the
+ // local edit is done (see `apply`).
+ merge(this.inflight, touched);
+ for (const [id, list] of touched.text)
+ this.inflight.text.set(id, [
+ ...(this.inflight.text.get(id) ?? []),
+ ...list,
+ ]);
+ } else {
+ for (const [id, list] of touched.text)
+ for (const delta of list) this.addDrift(id, delta);
+ }
+ this.flushSoon();
+ }
+
+ private addDrift(id: string, delta: DeltaOp[]) {
+ const list = this.drift.get(id) ?? [];
+ list.push(delta);
+ this.drift.set(id, list);
+ }
+
+ /** Runs operations in the engine and publishes their changes. */
+ apply(ops: EditOp[], group?: string): Promise<EditResult | null> {
+ const run = this.serial(async () => {
+ // Changes that arrived since the last flush first, and any arriving
+ // while those are applied: the edit must be made against the shared
+ // text as it is. From the last check on, nothing runs in between
+ // until changes are caught as in flight.
+ do await this.flushPending();
+ while (this.pending.blocks.size || this.pending.entries.size);
+ this.inflight = emptyTouched();
+ let result: EditResult | null;
+ let seen: Touched;
+ try {
+ result = await this.engine.apply(ops, group);
+ } catch (error) {
+ // The engine's copy is as it was: the changes apply to it as made.
+ for (const [id, list] of this.inflight?.text ?? [])
+ for (const delta of list) this.addDrift(id, delta);
+ this.inflight = null;
+ throw error;
+ }
+ seen = this.inflight ?? emptyTouched();
+ this.inflight = null;
+ const local = new Map<string, DeltaOp[]>();
+ if (result?.changes.length) {
+ writeChanges(this.doc, result.changes, (id, delta) => {
+ local.set(id, delta);
+ const remote = seen.text.get(id);
+ if (!remote?.length) return delta;
+ // The engine's copy of this paragraph missed those changes. Where
+ // both inserted at one spot this person's text goes first, right
+ // after what they typed before, so each person's typing stays in
+ // one piece.
+ this.pending.blocks.add(id);
+ return remote.reduce((l, r) => transform(r, l, true), delta);
+ });
+ // Typing (or deleting) merges into one undo step while it goes on;
+ // every other edit is a step of its own.
+ this.undoManager?.setMergeInterval(
+ group !== undefined && group === this.lastGroup ? MERGE_INTERVAL : 0
+ );
+ this.lastGroup = group;
+ this.doc.commit({ origin: DOCX_ORIGINS.local });
+ }
+ // Remote changes made during the edit, as the engine (which has the
+ // local edit) must apply them: past the local change, and after it
+ // where both inserted at one spot, as the shared text has them.
+ for (const [id, remote] of seen.text) {
+ let mine = local.get(id) ?? [];
+ for (const r of remote) {
+ this.addDrift(id, transform(mine, r));
+ mine = transform(r, mine, true);
+ }
+ }
+ return result;
+ });
+ void run.then(
+ () => this.flushSoon(),
+ () => this.flushSoon()
+ );
+ return run;
+ }
+
+ /** Hands remote changes to the engine once nothing else is running. */
+ private flushSoon() {
+ if (this.flushing) return;
+ if (this.pending.blocks.size === 0 && this.pending.entries.size === 0)
+ return;
+ this.flushing = true;
+ void this.serial(async () => {
+ this.flushing = false;
+ await this.flushPending();
+ }).catch((error: unknown) => {
+ this.flushing = false;
+ this.options.onError?.(error);
+ });
+ }
+
+ /** Hands the engine every remote change it has not seen (serialized). */
+ private async flushPending() {
+ const touched = this.pending;
+ this.pending = emptyTouched();
+ const drift = this.drift;
+ this.drift = new Map();
+ const changes = remoteChanges(this.doc, touched).map((change) => {
+ if (change.t !== 'block') return change;
+ const deltas = drift.get(change.block.id);
+ return deltas?.length ? { ...change, deltas } : change;
+ });
+ if (!changes.length) return;
+ const result = await this.engine.applyRemote(changes);
+ const restored = this.restored;
+ this.restored = undefined;
+ if (result) this.options.onRemote?.(result, restored);
+ }
+
+ /** Resolves once every queued engine call has finished. */
+ idle(): Promise<void> {
+ return this.chain.then(() => undefined);
+ }
+
+ /** Undoes this peer's last step in the shared document. */
+ undo(): boolean {
+ return this.undoManager?.undo() ?? false;
+ }
+
+ /** Redoes this peer's last undone step. */
+ redo(): boolean {
+ return this.undoManager?.redo() ?? false;
+ }
+
+ canUndo(): boolean {
+ return this.undoManager?.canUndo() ?? false;
+ }
+
+ canRedo(): boolean {
+ return this.undoManager?.canRedo() ?? false;
+ }
+}
diff --git a/apps/web/src/features/block-write/core/docx-engine.ts b/apps/web/src/features/block-write/core/docx-engine.ts
deleted file mode 100644
index a7bd67941f..0000000000
--- a/apps/web/src/features/block-write/core/docx-engine.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-import type { DocxPackageState } from '@macro-inc/collaboration/docx/schema';
-import { splitPackage } from './docx-package';
-
-/** The Docxodus session bridge calls the collaboration layer uses. */
-export type DocxSyncBridge = {
- SaveWithAnchorIds?: (handle: number) => Uint8Array;
- ListAnchors?: (handle: number) => string;
- RawReplaceXml?: (handle: number, anchor: string, xml: string) => string;
- RawInsertXml?: (
- handle: number,
- anchor: string,
- position: string,
- xml: string
- ) => string;
- DeleteBlock: (handle: number, anchor: string) => string;
- MoveBlock?: (
- handle: number,
- source: string,
- target: string,
- position: string
- ) => string;
-};
-
-export type BlockPosition = 'before' | 'after';
-
-/** Engine operations over one live document session. */
-export type DocxEngine = {
- /** The session's current document, split the way collaboration stores it. */
- snapshot(): DocxPackageState;
- /** Body block id → the engine anchor that addresses it. */
- bodyAnchors(): Map<string, string>;
- replaceBlock(anchor: string, xml: string): boolean;
- insertBlock(anchor: string, position: BlockPosition, xml: string): boolean;
- deleteBlock(anchor: string): boolean;
- moveBlock(source: string, target: string, position: BlockPosition): boolean;
-};
-
-export class DocxEngineUnsupportedError extends Error {}
-
-function succeeded(result: string | undefined): boolean {
- if (!result) return false;
- try {
- const parsed: unknown = JSON.parse(result);
- return (
- typeof parsed === 'object' &&
- parsed !== null &&
- 'success' in parsed &&
- parsed.success === true
- );
- } catch {
- return false;
- }
-}
-
-function require<T>(value: T | undefined, name: string): T {
- if (value === undefined)
- throw new DocxEngineUnsupportedError(
- `This Docxodus build lacks ${name}, which collaboration requires.`
- );
- return value;
-}
-
-type AnchorIndex = Record<string, { unid?: string; scope?: string }>;
-
-export function bridgeEngine(
- bridge: DocxSyncBridge,
- handle: () => number
-): DocxEngine {
- const save = require(bridge.SaveWithAnchorIds, 'SaveWithAnchorIds');
- const listAnchors = require(bridge.ListAnchors, 'ListAnchors');
- const replace = require(bridge.RawReplaceXml, 'RawReplaceXml');
- const insert = require(bridge.RawInsertXml, 'RawInsertXml');
- return {
- snapshot: () => splitPackage(save(handle())),
- bodyAnchors() {
- const parsed = JSON.parse(listAnchors(handle())) as {
- anchorIndex?: AnchorIndex;
- };
- const anchors = new Map<string, string>();
- for (const [anchor, info] of Object.entries(parsed.anchorIndex ?? {})) {
- if (info.scope === 'body' && info.unid) anchors.set(info.unid, anchor);
- }
- return anchors;
- },
- replaceBlock: (anchor, xml) => succeeded(replace(handle(), anchor, xml)),
- insertBlock: (anchor, position, xml) =>
- succeeded(insert(handle(), anchor, position, xml)),
- deleteBlock: (anchor) => succeeded(bridge.DeleteBlock(handle(), anchor)),
- moveBlock: (source, target, position) =>
- bridge.MoveBlock
- ? succeeded(bridge.MoveBlock(handle(), source, target, position))
- : false,
- };
-}
diff --git a/apps/web/src/features/block-write/core/docx-loro-schema.ts b/apps/web/src/features/block-write/core/docx-loro-schema.ts
index f325b6e92e..622e351fea 100644
--- a/apps/web/src/features/block-write/core/docx-loro-schema.ts
+++ b/apps/web/src/features/block-write/core/docx-loro-schema.ts
@@ -1,16 +1,13 @@
import { schema } from '@loro-mirror/core';
-import { DOCX_LORO_CONTAINERS } from '@macro-inc/collaboration/docx/schema';
+import { DOCX_LORO_CONTAINERS } from './docx-loro';
-const strings = () =>
- schema.LoroMap({} as Record<string, ReturnType<typeof schema.String>>);
-
-/** Mirror schema for the collaborative DOCX roots (see `DOCX_LORO_CONTAINERS`). */
+/**
+ * Schema handed to the sync stack's Loro manager. The DOCX editor reads and
+ * writes the Loro document directly (see `docx-loro.ts`) and turns the
+ * manager's JSON mirror off, so only the format metadata is declared.
+ */
export const DOCX_LORO_SCHEMA = schema({
[DOCX_LORO_CONTAINERS.meta]: schema.LoroMap(
{} as Record<string, ReturnType<typeof schema.Number>>
),
- [DOCX_LORO_CONTAINERS.blocks]: strings(),
- [DOCX_LORO_CONTAINERS.order]: strings(),
- [DOCX_LORO_CONTAINERS.parts]: strings(),
- [DOCX_LORO_CONTAINERS.marks]: strings(),
});
diff --git a/apps/web/src/features/block-write/core/docx-loro.ts b/apps/web/src/features/block-write/core/docx-loro.ts
new file mode 100644
index 0000000000..de0f2c38d6
--- /dev/null
+++ b/apps/web/src/features/block-write/core/docx-loro.ts
@@ -0,0 +1,338 @@
+import type {
+ BlockRecord,
+ Change,
+ CollabState,
+ DeltaOp,
+ RemoteChange,
+ V1State,
+} from '@core/docx-engine/types';
+import { type LoroDoc, type LoroEvent, LoroMap, LoroText } from 'loro-crdt';
+
+/**
+ * Root containers of a collaborative DOCX (see `crates/docx_engine` `collab`).
+ *
+ * Parts, relationships and content types are flat maps of strings. Each
+ * block is a map (`k` kind, `p` parent, `o` position key, `a` attributes,
+ * `x` properties) and each paragraph's text is a rich-text container whose
+ * marks are its formatting, so concurrent typing in one paragraph merges
+ * character by character. Comment marks keep their own map.
+ */
+export const DOCX_LORO_CONTAINERS = {
+ meta: 'docxMeta',
+ marks: 'docxMarks',
+ parts: 'wordParts',
+ types: 'wordTypes',
+ rels: 'wordRels',
+ blocks: 'wordBlocks',
+} as const;
+
+/** Containers of the first format, read once to migrate. */
+export const LEGACY_CONTAINERS = {
+ blocks: 'docxBlocks',
+ order: 'docxOrder',
+ parts: 'docxParts',
+} as const;
+
+export const DOCX_FORMAT_VERSION = 2;
+
+/** Commit origins of writes that do not come from the editing engine. */
+export const DOCX_ORIGINS = {
+ /** Edits made by this peer's engine (already applied there). */
+ local: 'docx-local',
+ seed: 'docx-seed',
+ migrate: 'docx-migrate',
+ comment: 'docx-comment',
+} as const;
+
+const FLAT = [
+ DOCX_LORO_CONTAINERS.parts,
+ DOCX_LORO_CONTAINERS.types,
+ DOCX_LORO_CONTAINERS.rels,
+] as const;
+
+/**
+ * Every peer must read and write paragraph marks the same way: a mark never
+ * grows over text typed next to it, because the engine states the full
+ * formatting of every insertion.
+ */
+export function configureDocxText(doc: LoroDoc) {
+ doc.configDefaultTextStyle({ expand: 'none' });
+}
+
+export function docxFormatVersion(doc: LoroDoc): number | undefined {
+ const value = doc.getMap(DOCX_LORO_CONTAINERS.meta).get('formatVersion');
+ return typeof value === 'number' ? value : undefined;
+}
+
+/** True once a peer has seeded the document. */
+export function isDocxSeeded(doc: LoroDoc): boolean {
+ return docxFormatVersion(doc) !== undefined;
+}
+
+function stringEntries(map: LoroMap): Record<string, string> {
+ const out: Record<string, string> = {};
+ for (const key of map.keys()) {
+ const value = map.get(key);
+ if (typeof value === 'string') out[key] = value;
+ }
+ return out;
+}
+
+function field(map: LoroMap, key: string): string {
+ const value = map.get(key);
+ return typeof value === 'string' ? value : '';
+}
+
+/** One block as stored, or null when it is not (or no longer) a block. */
+export function readBlock(doc: LoroDoc, id: string): BlockRecord | null {
+ const value = doc.getMap(DOCX_LORO_CONTAINERS.blocks).get(id);
+ if (!(value instanceof LoroMap)) return null;
+ const k = field(value, 'k');
+ if (!k) return null;
+ const record: BlockRecord = {
+ id,
+ k,
+ p: field(value, 'p'),
+ o: field(value, 'o'),
+ a: field(value, 'a'),
+ x: field(value, 'x'),
+ };
+ const text = value.get('t');
+ if (text instanceof LoroText) record.t = text.toDelta() as DeltaOp[];
+ else if (k === 'p') record.t = [];
+ return record;
+}
+
+/** The whole shared state, for opening the document in the engine. */
+export function readCollabState(doc: LoroDoc): CollabState {
+ const blocks: BlockRecord[] = [];
+ const map = doc.getMap(DOCX_LORO_CONTAINERS.blocks);
+ for (const id of map.keys()) {
+ const record = readBlock(doc, id);
+ if (record) blocks.push(record);
+ }
+ return {
+ parts: stringEntries(doc.getMap(DOCX_LORO_CONTAINERS.parts)),
+ types: stringEntries(doc.getMap(DOCX_LORO_CONTAINERS.types)),
+ rels: stringEntries(doc.getMap(DOCX_LORO_CONTAINERS.rels)),
+ blocks,
+ };
+}
+
+function writeBlock(doc: LoroDoc, record: BlockRecord) {
+ const map = doc
+ .getMap(DOCX_LORO_CONTAINERS.blocks)
+ .setContainer(record.id, new LoroMap());
+ map.set('k', record.k);
+ map.set('p', record.p);
+ map.set('o', record.o);
+ map.set('a', record.a);
+ map.set('x', record.x);
+ if (record.t) {
+ const text = map.setContainer('t', new LoroText());
+ if (record.t.length) text.applyDelta(record.t);
+ }
+}
+
+/** Writes a document's whole state (seeding or migrating) in one commit. */
+export function writeCollabState(
+ doc: LoroDoc,
+ state: CollabState,
+ origin: string = DOCX_ORIGINS.seed
+) {
+ configureDocxText(doc);
+ for (const [container, entries] of [
+ [DOCX_LORO_CONTAINERS.parts, state.parts],
+ [DOCX_LORO_CONTAINERS.types, state.types],
+ [DOCX_LORO_CONTAINERS.rels, state.rels],
+ ] as const) {
+ const map = doc.getMap(container);
+ for (const [key, value] of Object.entries(entries)) map.set(key, value);
+ }
+ for (const record of state.blocks) writeBlock(doc, record);
+ doc
+ .getMap(DOCX_LORO_CONTAINERS.meta)
+ .set('formatVersion', DOCX_FORMAT_VERSION);
+ doc.commit({ origin });
+}
+
+/** The first format's state, for migrating it. */
+export function readV1State(doc: LoroDoc): V1State {
+ const blocks = stringEntries(doc.getMap(LEGACY_CONTAINERS.blocks));
+ const keys = stringEntries(doc.getMap(LEGACY_CONTAINERS.order));
+ const order = Object.entries(keys)
+ .filter(([id]) => id in blocks)
+ .sort(([ia, ka], [ib, kb]) =>
+ ka < kb ? -1 : ka > kb ? 1 : ia < ib ? -1 : ia > ib ? 1 : 0
+ )
+ .map(([id]) => id);
+ return {
+ order,
+ blocks,
+ parts: stringEntries(doc.getMap(LEGACY_CONTAINERS.parts)),
+ };
+}
+
+/** Empties the first format's containers once their content moved. */
+export function clearV1(doc: LoroDoc) {
+ for (const name of Object.values(LEGACY_CONTAINERS)) {
+ const map = doc.getMap(name);
+ for (const key of map.keys()) map.delete(key);
+ }
+}
+
+/**
+ * Writes the engine's changes into the shared containers (not committed).
+ * `adjust` rewrites a text delta made against an older version of the text.
+ */
+export function writeChanges(
+ doc: LoroDoc,
+ changes: readonly Change[],
+ adjust: (id: string, delta: DeltaOp[]) => DeltaOp[] = (_, d) => d
+) {
+ const blocks = doc.getMap(DOCX_LORO_CONTAINERS.blocks);
+ for (const change of changes) {
+ switch (change.t) {
+ case 'block':
+ writeBlock(doc, change.block);
+ break;
+ case 'fields': {
+ const map = blocks.get(change.id);
+ if (!(map instanceof LoroMap)) break;
+ for (const [key, value] of Object.entries(change.fields))
+ map.set(key, value);
+ break;
+ }
+ case 'text': {
+ const map = blocks.get(change.id);
+ if (!(map instanceof LoroMap)) break;
+ let text = map.get('t');
+ if (!(text instanceof LoroText))
+ text = map.setContainer('t', new LoroText());
+ const delta = adjust(change.id, change.delta);
+ if (delta.length) (text as LoroText).applyDelta(delta);
+ break;
+ }
+ case 'remove':
+ blocks.delete(change.id);
+ break;
+ case 'entry': {
+ const map = doc.getMap(change.container);
+ if (change.value === null) map.delete(change.key);
+ else map.set(change.key, change.value);
+ break;
+ }
+ }
+ }
+}
+
+/** What other peers (or the shared undo history) changed, by event path. */
+export type Touched = {
+ blocks: Set<string>;
+ /** `container\u0000key` of flat-map entries. */
+ entries: Set<string>;
+ /** Text deltas per block, in order. */
+ text: Map<string, DeltaOp[][]>;
+};
+
+export function emptyTouched(): Touched {
+ return { blocks: new Set(), entries: new Set(), text: new Map() };
+}
+
+const SEPARATOR = '\u0000';
+
+/** Notes the blocks and entries a batch of events changed. */
+export function collectTouched(
+ events: ReadonlyArray<Pick<LoroEvent, 'path' | 'diff'>>,
+ into: Touched
+) {
+ for (const event of events) {
+ const [root, id, sub] = event.path;
+ const diff = event.diff;
+ if (root === DOCX_LORO_CONTAINERS.blocks) {
+ if (id === undefined) {
+ // Blocks added or removed.
+ if (diff.type === 'map')
+ for (const key of Object.keys(diff.updated)) into.blocks.add(key);
+ continue;
+ }
+ into.blocks.add(String(id));
+ if (sub === 't' && diff.type === 'text') {
+ const list = into.text.get(String(id)) ?? [];
+ list.push(diff.diff as DeltaOp[]);
+ into.text.set(String(id), list);
+ }
+ continue;
+ }
+ if (
+ typeof root === 'string' &&
+ (FLAT as readonly string[]).includes(root) &&
+ diff.type === 'map'
+ ) {
+ for (const key of Object.keys(diff.updated))
+ into.entries.add(`${root}${SEPARATOR}${key}`);
+ }
+ }
+}
+
+/** The engine's view of what was touched: whole blocks and entries as they now are. */
+export function remoteChanges(doc: LoroDoc, touched: Touched): RemoteChange[] {
+ const out: RemoteChange[] = [];
+ // Parents before children, so a new table's rows find it.
+ const records: BlockRecord[] = [];
+ for (const id of touched.blocks) {
+ const record = readBlock(doc, id);
+ if (record) records.push(record);
+ else out.push({ t: 'remove', id });
+ }
+ const byId = new Map(records.map((r) => [r.id, r]));
+ const depth = (r: BlockRecord) => {
+ let d = 0;
+ let parent = byId.get(r.p);
+ while (parent && d < 64) {
+ d++;
+ parent = byId.get(parent.p);
+ }
+ return d;
+ };
+ records.sort((a, b) => depth(a) - depth(b));
+ for (const block of records) out.push({ t: 'block', block });
+ for (const entry of touched.entries) {
+ const [container, key] = entry.split(SEPARATOR);
+ const value = doc.getMap(container).get(key);
+ out.push({
+ t: 'entry',
+ container,
+ key,
+ value: typeof value === 'string' ? value : null,
+ });
+ }
+ return out;
+}
+
+/** Paragraph texts of the shared document in document order (tests, checks). */
+export function sharedParagraphTexts(doc: LoroDoc): string[] {
+ const { blocks } = readCollabState(doc);
+ const children = new Map<string, BlockRecord[]>();
+ for (const b of blocks) {
+ const list = children.get(b.p) ?? [];
+ list.push(b);
+ children.set(b.p, list);
+ }
+ for (const list of children.values())
+ list.sort((a, b) =>
+ a.o < b.o ? -1 : a.o > b.o ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+ );
+ const out: string[] = [];
+ const walk = (parent: string) => {
+ for (const b of children.get(parent) ?? []) {
+ if (b.k === 'p')
+ out.push(
+ (b.t ?? []).map((op) => ('insert' in op ? op.insert : '')).join('')
+ );
+ walk(b.id);
+ }
+ };
+ walk('');
+ return out;
+}
diff --git a/apps/web/src/features/block-write/core/docx-package.test.ts b/apps/web/src/features/block-write/core/docx-package.test.ts
deleted file mode 100644
index 5dc08cf4c1..0000000000
--- a/apps/web/src/features/block-write/core/docx-package.test.ts
+++ /dev/null
@@ -1,156 +0,0 @@
-// @vitest-environment node
-import { strFromU8, unzipSync } from 'fflate';
-import { beforeAll, describe, expect, it } from 'vitest';
-import {
- bridge,
- fixture,
- loadEngine,
- SYNC_SESSION_SETTINGS,
- xmlText,
-} from '../tests/docx-test-peer';
-import {
- assembleDocumentXml,
- assemblePackage,
- BLOCKS_PLACEHOLDER,
- DOCUMENT_PART,
- decodePart,
- encodePart,
- splitDocumentXml,
- splitPackage,
-} from './docx-package';
-
-beforeAll(loadEngine, 60_000);
-
-const W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
-const PT = 'http://powertools.codeplex.com/2011';
-
-function documentXml(body: string) {
- return `<?xml version="1.0" encoding="utf-8"?><w:document xmlns:w="${W}" xmlns:r="urn:r"><w:body xmlns:p18="${PT}">${body}</w:body></w:document>`;
-}
-
-describe('splitDocumentXml', () => {
- it('extracts top-level blocks with their ids and keeps the final section in the shell', () => {
- const split = splitDocumentXml(
- documentXml(
- '<w:p p18:Unid="a1"><w:r><w:t>One &gt; two</w:t></w:r></w:p>' +
- '<!-- note --><w:tbl p18:Unid="b2"><w:tr><w:tc><w:p p18:Unid="c3"/></w:tc></w:tr></w:tbl>' +
- '<w:p p18:Unid="d4" w:rsidR="x>y"/>' +
- '<w:sectPr p18:Unid="e5"><w:pgSz w:w="12240"/></w:sectPr>'
- )
- );
- expect(split.order).toEqual(['a1', 'b2', 'd4']);
- expect(split.shell).toContain(`${BLOCKS_PLACEHOLDER}<w:sectPr`);
- expect(split.shell).not.toContain('a1');
- // Blocks declare the prefixes their ancestors declared.
- const first = split.blocks.get('a1')!;
- expect(first).toContain(`xmlns:p18="${PT}"`);
- expect(first).toContain(`xmlns:w="${W}"`);
- expect(first).not.toContain('xmlns:r=');
- expect(split.blocks.get('d4')).toContain('w:rsidR="x>y"');
- });
-
- it('round-trips through assembly', () => {
- const xml = documentXml(
- '<w:p p18:Unid="a1"><w:r><w:t>Hello</w:t></w:r></w:p><w:p p18:Unid="b2"/>'
- );
- const split = splitDocumentXml(xml);
- const assembled = assembleDocumentXml({
- order: split.order,
- blocks: split.blocks,
- parts: new Map([[DOCUMENT_PART, split.shell]]),
- });
- expect(splitDocumentXml(assembled).order).toEqual(['a1', 'b2']);
- expect(xmlText(assembled)).toBe('Hello');
- });
-
- it('gives elements without ids a deterministic content address', () => {
- const xml = documentXml('<w:p/><w:p/><w:p><w:r><w:t>x</w:t></w:r></w:p>');
- const first = splitDocumentXml(xml);
- expect(new Set(first.order).size).toBe(3);
- expect(splitDocumentXml(xml).order).toEqual(first.order);
- });
-
- it('handles an empty body', () => {
- const split = splitDocumentXml(documentXml(''));
- expect(split.order).toEqual([]);
- expect(split.shell).toContain(BLOCKS_PLACEHOLDER);
- });
-
- it('rejects documents that are not WordprocessingML', () => {
- expect(() => splitDocumentXml('<root><body/></root>')).toThrow();
- });
-});
-
-describe('package parts', () => {
- it('encodes binary parts as base64 and text parts verbatim', () => {
- const binary = new Uint8Array([0, 255, 128, 10]);
- const encoded = encodePart('word/media/image1.png', binary);
- expect(encoded.startsWith('b64:')).toBe(true);
- expect(decodePart(encoded)).toEqual(binary);
- expect(
- encodePart('word/styles.xml', new TextEncoder().encode('<a/>'))
- ).toBe('<a/>');
- });
-});
-
-describe.each(['mutual-nda.docx', 'complex-msa.docx'])(
- 'engine snapshots of %s',
- (name) => {
- it('split into blocks that reopen to the same document', () => {
- const engine = bridge();
- const handle = engine.OpenSession(fixture(name), SYNC_SESSION_SETTINGS);
- try {
- const state = splitPackage(engine.SaveWithAnchorIds(handle));
- expect(state.order.length).toBeGreaterThan(5);
- expect(state.parts.has('word/styles.xml')).toBe(true);
- const reopened = engine.OpenSession(
- assemblePackage(state),
- SYNC_SESSION_SETTINGS
- );
- try {
- const again = splitPackage(engine.SaveWithAnchorIds(reopened));
- expect(again.order).toEqual(state.order);
- for (const id of state.order)
- expect(xmlText(again.blocks.get(id)!)).toBe(
- xmlText(state.blocks.get(id)!)
- );
- // User-facing saves strip the engine's anchor ids.
- const clean = unzipSync(engine.Save(reopened));
- expect(strFromU8(clean[DOCUMENT_PART])).not.toContain('Unid=');
- } finally {
- engine.CloseSession(reopened);
- }
- } finally {
- engine.CloseSession(handle);
- }
- });
-
- it('produce blocks every raw engine operation accepts', () => {
- const engine = bridge();
- const handle = engine.OpenSession(fixture(name), SYNC_SESSION_SETTINGS);
- try {
- const state = splitPackage(engine.SaveWithAnchorIds(handle));
- const anchors = JSON.parse(engine.ListAnchors!(handle))
- .anchorIndex as Record<string, { unid: string; scope: string }>;
- const byId = new Map(
- Object.entries(anchors)
- .filter(([, info]) => info.scope === 'body')
- .map(([anchor, info]) => [info.unid, anchor])
- );
- const paragraph = state.order.find((id) =>
- byId.get(id)?.startsWith('p:')
- )!;
- const result = JSON.parse(
- engine.RawReplaceXml(
- handle,
- byId.get(paragraph)!,
- state.blocks.get(paragraph)!
- )
- );
- expect(result.success).toBe(true);
- } finally {
- engine.CloseSession(handle);
- }
- });
- }
-);
diff --git a/apps/web/src/features/block-write/core/docx-package.ts b/apps/web/src/features/block-write/core/docx-package.ts
deleted file mode 100644
index a3011b8477..0000000000
--- a/apps/web/src/features/block-write/core/docx-package.ts
+++ /dev/null
@@ -1,375 +0,0 @@
-import type { DocxPackageState } from '@macro-inc/collaboration/docx/schema';
-import { strFromU8, strToU8, unzipSync, type Zippable, zipSync } from 'fflate';
-
-export const DOCUMENT_PART = 'word/document.xml';
-const CONTENT_TYPES_PART = '[Content_Types].xml';
-/** Where the shell's body content goes when the package is assembled. */
-export const BLOCKS_PLACEHOLDER = '<!--macro-docx-blocks-->';
-const WORDML_NS =
- 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
-const POWERTOOLS_NS = 'http://powertools.codeplex.com/2011';
-const MARKUP_COMPATIBILITY_NS =
- 'http://schemas.openxmlformats.org/markup-compatibility/2006';
-const BINARY_PREFIX = 'b64:';
-
-export class DocxPackageError extends Error {}
-
-function isTextPart(name: string): boolean {
- return name === CONTENT_TYPES_PART || /\.(xml|rels)$/i.test(name);
-}
-
-function bytesToBase64(bytes: Uint8Array): string {
- let binary = '';
- const chunk = 0x8000;
- for (let i = 0; i < bytes.length; i += chunk)
- binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
- return btoa(binary);
-}
-
-function base64ToBytes(value: string): Uint8Array {
- const binary = atob(value);
- const bytes = new Uint8Array(binary.length);
- for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
- return bytes;
-}
-
-export function encodePart(name: string, bytes: Uint8Array): string {
- return isTextPart(name)
- ? strFromU8(bytes)
- : BINARY_PREFIX + bytesToBase64(bytes);
-}
-
-export function decodePart(value: string): Uint8Array {
- return value.startsWith(BINARY_PREFIX)
- ? base64ToBytes(value.slice(BINARY_PREFIX.length))
- : strToU8(value);
-}
-
-type StartTag = {
- /** Qualified element name. */
- name: string;
- /** Offset of `<`. */
- start: number;
- /** Offset just past `>`. */
- end: number;
- selfClosing: boolean;
-};
-
-/** Offset just past the tag that opens at `start`, honouring quoted attribute values. */
-function tagEnd(xml: string, start: number): number {
- let quote: string | null = null;
- for (let i = start + 1; i < xml.length; i++) {
- const char = xml[i];
- if (quote) {
- if (char === quote) quote = null;
- } else if (char === '"' || char === "'") {
- quote = char;
- } else if (char === '>') {
- return i + 1;
- }
- }
- throw new DocxPackageError('unterminated XML tag');
-}
-
-function skipSpecial(xml: string, start: number): number | null {
- if (xml.startsWith('<!--', start)) {
- const end = xml.indexOf('-->', start + 4);
- if (end < 0) throw new DocxPackageError('unterminated XML comment');
- return end + 3;
- }
- if (xml.startsWith('<![CDATA[', start)) {
- const end = xml.indexOf(']]>', start + 9);
- if (end < 0) throw new DocxPackageError('unterminated CDATA section');
- return end + 3;
- }
- if (xml.startsWith('<?', start)) {
- const end = xml.indexOf('?>', start + 2);
- if (end < 0)
- throw new DocxPackageError('unterminated processing instruction');
- return end + 2;
- }
- return null;
-}
-
-function readStartTag(xml: string, start: number): StartTag {
- const end = tagEnd(xml, start);
- const match = /^<([^\s/>]+)/.exec(
- xml.slice(start, Math.min(end, start + 256))
- );
- if (!match) throw new DocxPackageError('malformed XML start tag');
- return {
- name: match[1],
- start,
- end,
- selfClosing: xml[end - 2] === '/',
- };
-}
-
-/** Offset just past the element whose start tag is `tag`. */
-function elementEnd(xml: string, tag: StartTag): number {
- if (tag.selfClosing) return tag.end;
- let depth = 1;
- let i = tag.end;
- while (i < xml.length) {
- const lt = xml.indexOf('<', i);
- if (lt < 0) break;
- const special = skipSpecial(xml, lt);
- if (special !== null) {
- i = special;
- continue;
- }
- const end = tagEnd(xml, lt);
- if (xml[lt + 1] === '/') {
- depth--;
- if (depth === 0) return end;
- } else if (xml[end - 2] !== '/') {
- depth++;
- }
- i = end;
- }
- throw new DocxPackageError(`unterminated <${tag.name}> element`);
-}
-
-/** Namespace declarations made by one start tag (prefix → uri; '' is the default namespace). */
-function declarations(startTag: string): Map<string, string> {
- const found = new Map<string, string>();
- for (const match of startTag.matchAll(
- /\sxmlns(?::([\w.-]+))?\s*=\s*"([^"]*)"/g
- ))
- found.set(match[1] ?? '', match[2]);
- return found;
-}
-
-function attribute(startTag: string, qualifiedName: string): string | null {
- const escaped = qualifiedName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
- const match = new RegExp(`\\s${escaped}\\s*=\\s*"([^"]*)"`).exec(startTag);
- return match ? match[1] : null;
-}
-
-function prefixFor(scope: Map<string, string>, uri: string): string | null {
- for (const [prefix, value] of scope)
- if (value === uri && prefix) return prefix;
- return null;
-}
-
-/** Prefixes an element's markup uses, including those named by mc:Ignorable-style attributes. */
-function usedPrefixes(xml: string, mcPrefix: string | null): Set<string> {
- const used = new Set<string>();
- for (const match of xml.matchAll(/<\/?([A-Za-z_][\w.-]*):/g))
- used.add(match[1]);
- for (const match of xml.matchAll(
- /\s([A-Za-z_][\w.-]*):[A-Za-z_][\w.-]*\s*=/g
- ))
- used.add(match[1]);
- if (mcPrefix) {
- const listed = new RegExp(
- `\\s${mcPrefix}:(?:Ignorable|ProcessContent|MustUnderstand|PreserveElements|PreserveAttributes)\\s*=\\s*"([^"]*)"`,
- 'g'
- );
- for (const match of xml.matchAll(listed))
- for (const token of match[1].split(/\s+/)) {
- const prefix = token.split(':')[0];
- if (prefix) used.add(prefix);
- }
- }
- used.delete('xmlns');
- used.delete('xml');
- return used;
-}
-
-/**
- * Make an element extracted from its document self-describing: declare every
- * namespace prefix it uses that an ancestor declared. Raw engine operations
- * parse a block on its own, outside the document it came from.
- */
-function standalone(
- xml: string,
- tag: StartTag,
- scope: Map<string, string>,
- mcPrefix: string | null
-): string {
- const startTag = xml.slice(0, tag.end - tag.start);
- const own = declarations(startTag);
- const missing: string[] = [];
- for (const prefix of usedPrefixes(xml, mcPrefix)) {
- if (own.has(prefix)) continue;
- const uri = scope.get(prefix);
- if (uri !== undefined) missing.push(` xmlns:${prefix}="${uri}"`);
- }
- if (missing.length === 0) return xml;
- const insertAt = tag.name.length + 1;
- return xml.slice(0, insertAt) + missing.sort().join('') + xml.slice(insertAt);
-}
-
-export type SplitDocument = {
- shell: string;
- order: string[];
- blocks: Map<string, string>;
-};
-
-/**
- * Split `word/document.xml` into its top-level body elements and a shell that
- * keeps everything else (root, namespaces, final section properties).
- */
-export function splitDocumentXml(xml: string): SplitDocument {
- let i = 0;
- let root: StartTag | null = null;
- while (i < xml.length) {
- const lt = xml.indexOf('<', i);
- if (lt < 0) break;
- const special = skipSpecial(xml, lt);
- if (special !== null) {
- i = special;
- continue;
- }
- root = readStartTag(xml, lt);
- break;
- }
- if (!root) throw new DocxPackageError('document part has no root element');
- const scope = declarations(xml.slice(root.start, root.end));
- const w = prefixFor(scope, WORDML_NS);
- if (!w) throw new DocxPackageError('document part is not WordprocessingML');
-
- const bodyName = `${w}:body`;
- let body: StartTag | null = null;
- i = root.end;
- while (i < xml.length) {
- const lt = xml.indexOf('<', i);
- if (lt < 0) break;
- const special = skipSpecial(xml, lt);
- if (special !== null) {
- i = special;
- continue;
- }
- if (xml[lt + 1] === '/') break;
- const tag = readStartTag(xml, lt);
- if (tag.name === bodyName) {
- body = tag;
- break;
- }
- i = elementEnd(xml, tag);
- }
- if (!body) throw new DocxPackageError('document part has no body');
- if (body.selfClosing) {
- return {
- shell:
- xml.slice(0, body.end - 2) +
- `>${BLOCKS_PLACEHOLDER}</${bodyName}>` +
- xml.slice(body.end),
- order: [],
- blocks: new Map(),
- };
- }
- for (const [prefix, uri] of declarations(xml.slice(body.start, body.end)))
- scope.set(prefix, uri);
- const unidPrefix = prefixFor(scope, POWERTOOLS_NS);
- const mcPrefix = prefixFor(scope, MARKUP_COMPATIBILITY_NS);
-
- type Child = { tag: StartTag; end: number };
- const children: Child[] = [];
- let bodyClose = -1;
- i = body.end;
- while (i < xml.length) {
- const lt = xml.indexOf('<', i);
- if (lt < 0) break;
- const special = skipSpecial(xml, lt);
- if (special !== null) {
- i = special;
- continue;
- }
- if (xml[lt + 1] === '/') {
- bodyClose = lt;
- break;
- }
- const tag = readStartTag(xml, lt);
- const end = elementEnd(xml, tag);
- children.push({ tag, end });
- i = end;
- }
- if (bodyClose < 0) throw new DocxPackageError('unterminated document body');
-
- // The body's final sectPr describes the last section; it belongs to the shell.
- const last = children.at(-1);
- const finalSection =
- last && last.tag.name === `${w}:sectPr` ? children.pop() : undefined;
-
- const order: string[] = [];
- const blocks = new Map<string, string>();
- const seen = new Map<string, number>();
- for (const child of children) {
- const element = xml.slice(child.tag.start, child.end);
- const startTag = xml.slice(child.tag.start, child.tag.end);
- let id = unidPrefix ? attribute(startTag, `${unidPrefix}:Unid`) : null;
- if (!id) {
- // Every element the engine saves carries an id; fall back to a content
- // address so a foreign package still splits deterministically.
- const base = `x${fnv1a(element)}`;
- const count = seen.get(base) ?? 0;
- seen.set(base, count + 1);
- id = count ? `${base}-${count}` : base;
- }
- if (blocks.has(id))
- throw new DocxPackageError(`duplicate block id ${id} in document body`);
- order.push(id);
- blocks.set(id, standalone(element, child.tag, scope, mcPrefix));
- }
-
- const tail = finalSection
- ? xml.slice(finalSection.tag.start, finalSection.end)
- : '';
- const shell =
- xml.slice(0, body.end) + BLOCKS_PLACEHOLDER + tail + xml.slice(bodyClose);
- return { shell, order, blocks };
-}
-
-function fnv1a(value: string): string {
- let hash = 0x811c9dc5;
- for (let i = 0; i < value.length; i++) {
- hash ^= value.charCodeAt(i);
- hash = Math.imul(hash, 0x01000193);
- }
- return (hash >>> 0).toString(16).padStart(8, '0');
-}
-
-/** Read an engine snapshot (saved with anchor ids) into collaboration state. */
-export function splitPackage(bytes: Uint8Array): DocxPackageState {
- const files = unzipSync(bytes);
- const document = files[DOCUMENT_PART];
- if (!document) throw new DocxPackageError('package has no word/document.xml');
- const split = splitDocumentXml(strFromU8(document));
- const parts = new Map<string, string>();
- for (const [name, content] of Object.entries(files)) {
- if (name.endsWith('/')) continue;
- parts.set(
- name,
- name === DOCUMENT_PART ? split.shell : encodePart(name, content)
- );
- }
- return { order: split.order, blocks: split.blocks, parts };
-}
-
-/** The document part for `state`: its shell with the ordered blocks in the body. */
-export function assembleDocumentXml(state: DocxPackageState): string {
- const shell = state.parts.get(DOCUMENT_PART);
- if (shell === undefined || !shell.includes(BLOCKS_PLACEHOLDER))
- throw new DocxPackageError('collaboration state has no document shell');
- const body = state.order.map((id) => state.blocks.get(id) ?? '').join('');
- return shell.replace(BLOCKS_PLACEHOLDER, () => body);
-}
-
-/** Build an openable package from collaboration state. */
-export function assemblePackage(state: DocxPackageState): Uint8Array {
- const files: Zippable = {};
- const contentTypes = state.parts.get(CONTENT_TYPES_PART);
- if (contentTypes !== undefined)
- files[CONTENT_TYPES_PART] = strToU8(contentTypes);
- for (const [name, value] of state.parts) {
- if (name === CONTENT_TYPES_PART) continue;
- files[name] =
- name === DOCUMENT_PART
- ? strToU8(assembleDocumentXml(state))
- : decodePart(value);
- }
- // Stored, not deflated: the package is opened in-process immediately.
- return zipSync(files, { level: 0 });
-}
diff --git a/apps/web/src/features/block-write/core/docx-seed.ts b/apps/web/src/features/block-write/core/docx-seed.ts
index 518cfd4973..4f0f216657 100644
--- a/apps/web/src/features/block-write/core/docx-seed.ts
+++ b/apps/web/src/features/block-write/core/docx-seed.ts
@@ -1,38 +1,30 @@
-import { seedDocxState } from '@macro-inc/collaboration/docx/schema';
+import {
+ closeDocument,
+ collabState,
+ openDocument,
+} from '@core/docx-engine/client';
import { LoroDoc } from 'loro-crdt';
-import { bridgeEngine, type DocxSyncBridge } from './docx-engine';
+import { writeCollabState } from './docx-loro';
-/** Settings every session in a collaborative editor is opened with. */
-export const DOCX_SYNC_SESSION_SETTINGS = {
- // The editor re-renders from HTML; markdown patches are wasted work.
- emitMarkdownPatch: false,
- // Raw operations only ever carry XML the engine itself serialized.
- validateRawOps: false,
-};
-
-type SeedBridge = DocxSyncBridge & {
- OpenSession: (bytes: Uint8Array, settingsJson: string) => number;
- CloseSession: (handle: number) => void;
-};
+let seeds = 0;
/**
- * The first collaborative snapshot of an uploaded DOCX: open it once, split
- * the engine's save into blocks and parts, and write them to a new Loro
- * document. Every peer that opens the same upload derives the same block ids.
+ * The first collaborative snapshot of an uploaded DOCX: the engine opens it
+ * once and its shared state goes into a new Loro document. Block ids are
+ * assigned in document order, so every peer that seeds the same upload
+ * derives the same ids (only one seed is ever stored).
*/
-export function buildSeedSnapshot(
- bridge: SeedBridge,
+export async function buildSeedSnapshot(
bytes: Uint8Array
-): Uint8Array {
- const handle = bridge.OpenSession(
- bytes,
- JSON.stringify(DOCX_SYNC_SESSION_SETTINGS)
- );
+): Promise<Uint8Array> {
+ const key = `docx-seed-${++seeds}`;
+ await openDocument(key, bytes.slice().buffer);
try {
+ const state = await collabState(key);
const doc = new LoroDoc();
- seedDocxState(doc, bridgeEngine(bridge, () => handle).snapshot());
+ writeCollabState(doc, state);
return doc.export({ mode: 'snapshot' });
} finally {
- bridge.CloseSession(handle);
+ await closeDocument(key).catch(() => {});
}
}
diff --git a/apps/web/src/features/block-write/core/docx-sync.test.ts b/apps/web/src/features/block-write/core/docx-sync.test.ts
deleted file mode 100644
index 0dc13a59e7..0000000000
--- a/apps/web/src/features/block-write/core/docx-sync.test.ts
+++ /dev/null
@@ -1,287 +0,0 @@
-// @vitest-environment node
-
-import { readDocxState } from '@macro-inc/collaboration/docx/schema';
-import { afterEach, beforeAll, describe, expect, it } from 'vitest';
-import { bridge, fixture, loadEngine, TestPeer } from '../tests/docx-test-peer';
-
-beforeAll(loadEngine, 60_000);
-
-const peers: TestPeer[] = [];
-afterEach(() => {
- for (const peer of peers.splice(0)) peer.close();
-});
-
-/** A seeding peer plus `count - 1` peers joined from its snapshot. */
-function room(count: number, name = 'mutual-nda.docx'): TestPeer[] {
- const bytes = fixture(name);
- const first = new TestPeer(bytes);
- const seed = first.doc.export({ mode: 'snapshot' });
- const all = [first];
- for (let i = 1; i < count; i++) all.push(new TestPeer(bytes, seed));
- peers.push(...all);
- return all;
-}
-
-function exchange(all: TestPeer[]) {
- for (let round = 0; round < 2; round++)
- for (const peer of all)
- peer.deliver(...all.filter((other) => other !== peer));
-}
-
-function expectConverged(all: TestPeer[]) {
- const [first, ...rest] = all;
- const shared = readDocxState(first.doc);
- for (const peer of rest) {
- expect(peer.text()).toEqual(first.text());
- expect(readDocxState(peer.doc).order).toEqual(shared.order);
- }
- // The engine sessions agree with the shared document they converged on.
- for (const peer of all)
- expect(peer.sync.sharedState.order).toEqual(shared.order);
-}
-
-function anchor(peer: TestPeer, index: number) {
- return peer.bodyIds()[index];
-}
-
-function edit(peer: TestPeer, index: number, text: string) {
- const result = JSON.parse(
- bridge().ReplaceTextAtSpan(peer.handle, anchor(peer, index), 0, 0, text)
- );
- expect(result.success).toBe(true);
- peer.sync.publishLocal();
-}
-
-describe('DocxSyncController', () => {
- it('opens joining peers on the seeded document', () => {
- const [alice, bob] = room(2);
- expect(bob.bodyIds()).toEqual(alice.bodyIds());
- expect(bob.text()).toEqual(alice.text());
- });
-
- it('propagates a text edit by patching only that block', () => {
- const [alice, bob] = room(2);
- edit(alice, 1, 'AMENDED: ');
- alice.deliver(bob);
- expect(bob.text()[1].startsWith('AMENDED: ')).toBe(true);
- expect(bob.rebuilds).toBe(0);
- expectConverged([alice, bob]);
- });
-
- it('merges concurrent edits to different paragraphs', () => {
- const [alice, bob, carol] = room(3);
- edit(alice, 1, '[alice] ');
- edit(bob, 3, '[bob] ');
- edit(carol, 4, '[carol] ');
- exchange([alice, bob, carol]);
- expectConverged([alice, bob, carol]);
- const text = alice.text();
- expect(text[1].startsWith('[alice] ')).toBe(true);
- expect(text[3].startsWith('[bob] ')).toBe(true);
- expect(text[4].startsWith('[carol] ')).toBe(true);
- });
-
- it('converges when two peers edit the same paragraph at once', () => {
- const [alice, bob] = room(2);
- edit(alice, 1, '[alice] ');
- edit(bob, 1, '[bob] ');
- exchange([alice, bob]);
- expectConverged([alice, bob]);
- expect(
- ['[alice] ', '[bob] '].some((p) => alice.text()[1].startsWith(p))
- ).toBe(true);
- });
-
- it('propagates paragraph splits, merges, deletes and moves', () => {
- const [alice, bob] = room(2);
- const engine = bridge();
- expect(
- JSON.parse(engine.SplitParagraph(alice.handle, anchor(alice, 1), 20))
- .success
- ).toBe(true);
- alice.sync.publishLocal();
- alice.deliver(bob);
- expectConverged([alice, bob]);
- expect(bob.bodyIds()).toEqual(alice.bodyIds());
-
- expect(
- JSON.parse(
- engine.MergeParagraphs(alice.handle, anchor(alice, 1), anchor(alice, 2))
- ).success
- ).toBe(true);
- alice.sync.publishLocal();
- alice.deliver(bob);
- expectConverged([alice, bob]);
-
- expect(
- JSON.parse(engine.DeleteBlock(bob.handle, anchor(bob, 3))).success
- ).toBe(true);
- bob.sync.publishLocal();
- bob.deliver(alice);
- expectConverged([alice, bob]);
-
- expect(
- JSON.parse(
- engine.MoveBlock(
- alice.handle,
- anchor(alice, 5),
- anchor(alice, 1),
- 'before'
- )
- ).success
- ).toBe(true);
- alice.sync.publishLocal();
- alice.deliver(bob);
- expectConverged([alice, bob]);
- expect(alice.rebuilds + bob.rebuilds).toBe(0);
- });
-
- it('keeps concurrent inserts from both peers', () => {
- const [alice, bob] = room(2);
- const engine = bridge();
- engine.SplitParagraph(alice.handle, anchor(alice, 1), 10);
- alice.sync.publishLocal();
- engine.SplitParagraph(bob.handle, anchor(bob, 1), 30);
- bob.sync.publishLocal();
- const before = alice.bodyIds().length;
- exchange([alice, bob]);
- expectConverged([alice, bob]);
- expect(alice.bodyIds().length).toBe(before + 1);
- });
-
- it('replicates undo as an ordinary change', () => {
- const [alice, bob] = room(2);
- const original = alice.text()[1];
- edit(alice, 1, 'Typo ');
- alice.deliver(bob);
- expect(bridge().Undo(alice.handle)).toBe(true);
- alice.sync.publishLocal();
- alice.deliver(bob);
- expect(bob.text()[1]).toBe(original);
- expectConverged([alice, bob]);
- });
-
- it('rebuilds peers when an edit changes a package part', () => {
- const [alice, bob] = room(2);
- const result = JSON.parse(
- bridge().ApplyListFormat(alice.handle, anchor(alice, 1), 'bullet')
- );
- expect(result.success).toBe(true);
- alice.sync.publishLocal();
- alice.deliver(bob);
- expectConverged([alice, bob]);
- expect(bob.rebuilds).toBe(1);
- });
-
- it('opens a late joiner on the merged document', () => {
- const [alice, bob] = room(2);
- edit(alice, 1, '[alice] ');
- edit(bob, 4, '[bob] ');
- exchange([alice, bob]);
- const late = new TestPeer(
- fixture('mutual-nda.docx'),
- alice.doc.export({ mode: 'snapshot' })
- );
- peers.push(late);
- expectConverged([alice, bob, late]);
- });
-
- it('defers a remote change to a block the user is still typing in', () => {
- const [alice, bob] = room(2);
- const busy = anchor(bob, 1).split(':')[2];
- const host = (
- bob.sync as unknown as { host: { isBusy?: (id: string) => boolean } }
- ).host;
- host.isBusy = (id) => id === busy;
- edit(alice, 1, '[alice] ');
- alice.deliver(bob);
- expect(bob.text()[1].startsWith('[alice] ')).toBe(false);
- // Once the typing commits, this peer's version wins and both converge.
- host.isBusy = () => false;
- edit(bob, 1, '[bob] ');
- bob.deliver(alice);
- expectConverged([alice, bob]);
- expect(alice.text()[1].startsWith('[bob] ')).toBe(true);
- });
-
- it('handles documents with tables, content controls and headers', () => {
- const [alice, bob] = room(2, 'complex-msa.docx');
- const ids = alice.bodyIds();
- const table = ids.findIndex((id) => id.startsWith('tbl:'));
- expect(table).toBeGreaterThan(0);
- edit(alice, 2, 'Edited: ');
- expect(
- JSON.parse(
- bridge().InsertTableRow(alice.handle, cellAnchor(alice), 'below')
- ).success
- ).toBe(true);
- alice.sync.publishLocal();
- alice.deliver(bob);
- expectConverged([alice, bob]);
- });
-});
-
-describe('randomized collaboration', () => {
- it.each([11, 29, 47])(
- 'converges after random concurrent edits (seed %i)',
- (seed) => {
- let state = seed;
- const random = () => {
- state = (state * 16807) % 2147483647;
- return state / 2147483647;
- };
- const pick = <T>(items: readonly T[]) =>
- items[Math.floor(random() * items.length)];
- const all = room(3);
- const engine = bridge();
- for (let step = 0; step < 40; step++) {
- const peer = pick(all);
- const paragraphs = peer
- .bodyIds()
- .filter((id) => id.startsWith('p:') || id.startsWith('h:'));
- const target = pick(paragraphs);
- const length = peer.blockText(target).length;
- const operation = Math.floor(random() * 5);
- if (operation === 0 || operation === 1) {
- engine.ReplaceTextAtSpan(
- peer.handle,
- target,
- Math.floor(random() * (length + 1)),
- 0,
- `<${step}>`
- );
- } else if (operation === 2 && length > 2) {
- engine.SplitParagraph(
- peer.handle,
- target,
- 1 + Math.floor(random() * (length - 1))
- );
- } else if (operation === 3 && paragraphs.length > 6) {
- engine.DeleteBlock(peer.handle, target);
- } else if (operation === 4) {
- const other = pick(paragraphs);
- if (other !== target)
- engine.MoveBlock(
- peer.handle,
- target,
- other,
- pick(['before', 'after'])
- );
- }
- peer.sync.publishLocal();
- if (random() < 0.4) peer.deliver(...all.filter((p) => p !== peer));
- }
- exchange(all);
- expectConverged(all);
- },
- 60_000
- );
-});
-
-function cellAnchor(peer: TestPeer): string {
- const anchors = JSON.parse(bridge().ListAnchors!(peer.handle))
- .anchorIndex as Record<string, unknown>;
- const cell = Object.keys(anchors).find((id) => id.startsWith('tc:'));
- if (!cell) throw new Error('fixture has no table cell');
- return cell;
-}
diff --git a/apps/web/src/features/block-write/core/docx-sync.ts b/apps/web/src/features/block-write/core/docx-sync.ts
deleted file mode 100644
index fff0165c64..0000000000
--- a/apps/web/src/features/block-write/core/docx-sync.ts
+++ /dev/null
@@ -1,222 +0,0 @@
-import {
- type DocxChanges,
- type DocxPackageState,
- diffDocxStates,
- hasChanges,
- readDocxState,
- writeDocxChanges,
-} from '@macro-inc/collaboration/docx/schema';
-import type { LoroDoc } from 'loro-crdt';
-import type { DocxEngine } from './docx-engine';
-import { assemblePackage } from './docx-package';
-
-/** What the sync controller needs from the editor that owns the session. */
-export type DocxSyncHost = {
- /** The engine for the session currently on screen. */
- engine(): DocxEngine;
- /** Repaint after the session was changed outside the editor's own commands. */
- refresh(): void;
- /** Replace the session with a package and remount the editor. */
- rebuild(bytes: Uint8Array): void;
- /** True while a block holds typing the editor has not committed yet. */
- isBusy?(blockId: string): boolean;
-};
-
-export type RemoteOutcome = 'unchanged' | 'patched' | 'rebuilt';
-
-/** More block operations than this remount instead of patching one by one. */
-const MAX_PATCH_OPERATIONS = 64;
-
-function applyChanges(
- state: DocxPackageState,
- changes: DocxChanges,
- order: readonly string[]
-): DocxPackageState {
- const blocks = new Map(state.blocks);
- for (const [id, xml] of changes.upserts) blocks.set(id, xml);
- for (const id of changes.removed) blocks.delete(id);
- const parts = new Map(state.parts);
- for (const [name, value] of changes.parts) {
- if (value === null) parts.delete(name);
- else parts.set(name, value);
- }
- return { order: [...order], blocks, parts };
-}
-
-/** Indices of `sequence` that form a longest common subsequence with `target`. */
-function stableIds(
- sequence: readonly string[],
- target: readonly string[]
-): Set<string> {
- const position = new Map(target.map((id, index) => [id, index]));
- const ranks = sequence.map((id) => position.get(id) ?? -1);
- const tails: number[] = [];
- const previous = new Array<number>(ranks.length).fill(-1);
- ranks.forEach((rank, index) => {
- if (rank < 0) return;
- let low = 0;
- let high = tails.length;
- while (low < high) {
- const mid = (low + high) >> 1;
- if (ranks[tails[mid]] < rank) low = mid + 1;
- else high = mid;
- }
- if (low > 0) previous[index] = tails[low - 1];
- tails[low] = index;
- });
- const stable = new Set<string>();
- let cursor = tails.length ? tails[tails.length - 1] : -1;
- while (cursor >= 0) {
- stable.add(sequence[cursor]);
- cursor = previous[cursor];
- }
- return stable;
-}
-
-/**
- * Keeps one live Docxodus session and one collaborative Loro document in step.
- *
- * Two baselines make the exchange echo-free: `session` is what the engine held
- * when the two last agreed, and `shared` is what the Loro document held. Local
- * publishing diffs the engine against `session`; remote application diffs Loro
- * against `shared`. Re-serialization differences between the two never show up
- * as edits on either side.
- */
-export class DocxSyncController {
- private session: DocxPackageState;
- private shared: DocxPackageState;
-
- constructor(
- private readonly doc: LoroDoc,
- private readonly host: DocxSyncHost
- ) {
- this.session = host.engine().snapshot();
- this.shared = readDocxState(doc);
- }
-
- /** The collaborative document as last applied to the session. */
- get sharedState(): DocxPackageState {
- return this.shared;
- }
-
- /** Publish edits made in the session since the last exchange. */
- publishLocal(): boolean {
- const current = this.host.engine().snapshot();
- const changes = diffDocxStates(this.session, current);
- this.session = current;
- if (!hasChanges(changes)) return false;
- writeDocxChanges(this.doc, changes);
- this.shared = applyChanges(this.shared, changes, current.order);
- return true;
- }
-
- /** Bring the session up to date with the collaborative document. */
- applyRemote(): RemoteOutcome {
- // Never let a remote patch overwrite committed-but-unpublished edits.
- this.publishLocal();
- const next = readDocxState(this.doc);
- const changes = diffDocxStates(this.shared, next);
- if (!hasChanges(changes)) {
- this.shared = next;
- return 'unchanged';
- }
- const deferred = new Map<string, string>();
- if (changes.parts.size === 0 && this.patch(next, changes, deferred)) {
- this.host.refresh();
- this.session = this.host.engine().snapshot();
- const blocks = new Map(next.blocks);
- for (const [id, xml] of deferred) blocks.set(id, xml);
- this.shared = { ...next, blocks };
- return 'patched';
- }
- this.rebuild(next);
- return 'rebuilt';
- }
-
- /** Replace the session wholesale with the collaborative document. */
- rebuild(next: DocxPackageState = readDocxState(this.doc)) {
- this.host.rebuild(assemblePackage(next));
- this.session = this.host.engine().snapshot();
- this.shared = next;
- }
-
- /**
- * Translate block changes into raw engine operations. Returns false when the
- * session cannot be patched in place, leaving the caller to rebuild.
- * `deferred` collects blocks skipped because the user is typing in them,
- * mapped to the shared content they last agreed on.
- */
- private patch(
- next: DocxPackageState,
- changes: DocxChanges,
- deferred: Map<string, string>
- ): boolean {
- const engine = this.host.engine();
- const target = next.order;
- const removed = new Set(changes.removed);
- const sessionOrder = this.session.order.filter((id) => !removed.has(id));
- const inSession = new Set(sessionOrder);
- // Blocks the session has that the shared document neither has nor removed
- // mean the two diverged in a way a patch cannot reason about.
- const wanted = new Set(target);
- if (sessionOrder.some((id) => !wanted.has(id))) return false;
-
- const stable = stableIds(sessionOrder, target);
- const operations =
- changes.removed.length +
- target.filter((id) => !stable.has(id)).length +
- changes.upserts.size;
- if (operations > MAX_PATCH_OPERATIONS) return false;
-
- let anchors = engine.bodyAnchors();
- const anchorOf = (id: string): string | undefined => {
- const known = anchors.get(id);
- if (known) return known;
- anchors = engine.bodyAnchors();
- return anchors.get(id);
- };
-
- for (const id of changes.removed) {
- if (!this.session.blocks.has(id)) continue;
- const anchor = anchorOf(id);
- if (!anchor || !engine.deleteBlock(anchor)) return false;
- }
-
- const inserted = new Set<string>();
- const firstStable = target.find((id) => stable.has(id));
- let previous: string | null = null;
- for (const id of target) {
- if (!stable.has(id)) {
- const neighbour =
- previous ?? firstStable ?? sessionOrder.find((other) => other !== id);
- const position = previous ? 'after' : 'before';
- const neighbourAnchor = neighbour ? anchorOf(neighbour) : undefined;
- if (!neighbourAnchor) return false;
- if (inSession.has(id)) {
- const anchor = anchorOf(id);
- if (!anchor || !engine.moveBlock(anchor, neighbourAnchor, position))
- return false;
- } else {
- const xml = next.blocks.get(id);
- if (xml === undefined) return false;
- if (!engine.insertBlock(neighbourAnchor, position, xml)) return false;
- inserted.add(id);
- inSession.add(id);
- }
- }
- previous = id;
- }
-
- for (const [id, xml] of changes.upserts) {
- if (inserted.has(id)) continue;
- if (this.host.isBusy?.(id)) {
- const agreed = this.shared.blocks.get(id);
- if (agreed !== undefined) deferred.set(id, agreed);
- continue;
- }
- const anchor = anchorOf(id);
- if (!anchor || !engine.replaceBlock(anchor, xml)) return false;
- }
- return true;
- }
-}
diff --git a/apps/web/src/features/block-write/core/editor-bridge.ts b/apps/web/src/features/block-write/core/editor-bridge.ts
deleted file mode 100644
index e35b1eccfd..0000000000
--- a/apps/web/src/features/block-write/core/editor-bridge.ts
+++ /dev/null
@@ -1,211 +0,0 @@
-import type { DocxEditorExports } from 'docxodus';
-
-/**
- * Bridge calls that read the session without changing it. Everything else is
- * treated as a mutation, so a Docxodus release that adds an editing command is
- * published conservatively instead of silently dropped.
- */
-const READ_ONLY_CALLS = new Set([
- 'CloseSession',
- 'CreateBlankDocx',
- 'GetDiff',
- 'GetEditSummary',
- 'GetFormatting',
- 'GetImageCapabilities',
- 'GetListMembership',
- 'GetSectionInfo',
- 'GetVersion',
- 'Grep',
- 'GrepCrossBlock',
- 'ListAnchors',
- 'ListBlocks',
- 'ListBookmarks',
- 'ListComments',
- 'ListContentControls',
- 'ListHyperlinks',
- 'ListImages',
- 'ListInlineSpans',
- 'ListNotes',
- 'ListRenderedBlocks',
- 'ListRevisions',
- 'ListStyles',
- 'OpenSession',
- 'Project',
- 'RawGetXml',
- 'RemainingPlaceholders',
- 'Save',
- 'SaveWithAnchorIds',
- 'ValidMoveTargets',
-]);
-
-const isRead = (name: string) =>
- READ_ONLY_CALLS.has(name) ||
- name.startsWith('Render') ||
- name.startsWith('Find');
-
-/** Whole-document renders whose stylesheet must be scoped to the editor. */
-const DOCUMENT_RENDERS = [
- 'RenderHtml',
- 'RenderHtmlForReview',
- 'RenderEditorHtml',
- // The windowed mount injects this document's <style> into the page.
- 'RenderEditorChromeHtml',
-] as const;
-
-/** A whole HTML document, as opposed to JSON or a fragment. */
-const isHtmlDocument = (value: unknown): value is string =>
- typeof value === 'string' && /^\s*<(?:!doctype|html)/i.test(value);
-
-export type EditorBridgeOptions = {
- /** Selector of the editor's mount; document CSS is confined to it. */
- rootSelector: string;
- /** Settings merged into every session the editor opens. */
- sessionSettings: Record<string, unknown>;
- /** Called after every bridge call that may have changed the session. */
- onMutation: (call: string) => void;
-};
-
-type AnyFunction = (...args: never[]) => unknown;
-
-/**
- * The editor's view of the engine: every session is opened with the sync
- * settings, document styles are scoped so the converter's `body`/`span` rules
- * cannot restyle the app, and mutations are reported for publishing.
- */
-export function editorBridge(
- exports: DocxEditorExports,
- options: EditorBridgeOptions
-): DocxEditorExports {
- const source = exports.DocxSessionBridge as unknown as Record<
- string,
- unknown
- >;
- const bridge: Record<string, unknown> = {};
- for (const [name, value] of Object.entries(source)) {
- if (typeof value !== 'function') {
- bridge[name] = value;
- continue;
- }
- const call = value as AnyFunction;
- if (name === 'OpenSession') {
- bridge[name] = (bytes: Uint8Array, settingsJson: string) => {
- const requested = settingsJson
- ? (JSON.parse(settingsJson) as object)
- : {};
- return (call as (b: Uint8Array, s: string) => number)(
- bytes,
- JSON.stringify({ ...requested, ...options.sessionSettings })
- );
- };
- } else if ((DOCUMENT_RENDERS as readonly string[]).includes(name)) {
- bridge[name] = (...args: never[]) =>
- scopeDocumentStyles(call(...args) as string, options.rootSelector);
- } else if (isRead(name)) {
- // A render added in a later release must not leak its stylesheet either.
- bridge[name] = (...args: never[]) => {
- const result = call(...args);
- return isHtmlDocument(result)
- ? scopeDocumentStyles(result, options.rootSelector)
- : result;
- };
- } else {
- bridge[name] = (...args: never[]) => {
- const result = call(...args);
- options.onMutation(name);
- return result;
- };
- }
- }
- const convert = exports.DocumentConverter.ConvertDocxToHtmlComplete;
- return {
- DocxSessionBridge: bridge as DocxEditorExports['DocxSessionBridge'],
- DocumentConverter: {
- ConvertDocxToHtmlComplete: (...args: unknown[]) =>
- scopeDocumentStyles(convert(...args), options.rootSelector),
- },
- };
-}
-
-const SCOPED_ATTRIBUTE = 'data-macro-docx-scoped';
-
-function splitSelectors(selectorText: string): string[] {
- const selectors: string[] = [];
- let depth = 0;
- let start = 0;
- for (let i = 0; i < selectorText.length; i++) {
- const char = selectorText[i];
- if (char === '(' || char === '[') depth++;
- else if (char === ')' || char === ']') depth--;
- else if (char === ',' && depth === 0) {
- selectors.push(selectorText.slice(start, i).trim());
- start = i + 1;
- }
- }
- selectors.push(selectorText.slice(start).trim());
- return selectors.filter(Boolean);
-}
-
-/** Re-root one selector: the document's `html`/`body`/`:root` become the mount. */
-export function scopeSelector(selector: string, root: string): string {
- let rest = selector.trim();
- let consumed = false;
- let separated = false;
- for (;;) {
- const match = /^(?:html|body|:root)(?=$|[\s>+~.#[:])/.exec(rest);
- if (!match) break;
- consumed = true;
- rest = rest.slice(match[0].length);
- const space = /^\s+/.exec(rest);
- separated = !!space;
- if (!space) break;
- rest = rest.slice(space[0].length);
- }
- if (!consumed) return `${root} ${rest}`;
- if (!rest) return root;
- if (separated || /^[>+~]/.test(rest)) return `${root} ${rest}`;
- return `${root}${rest}`;
-}
-
-function scopeRules(container: CSSStyleSheet | CSSGroupingRule, root: string) {
- for (let i = container.cssRules.length - 1; i >= 0; i--) {
- const rule = container.cssRules[i];
- // @page and @import cannot be confined to an element; drop them.
- if (rule instanceof CSSPageRule || rule instanceof CSSImportRule) {
- container.deleteRule(i);
- } else if (rule instanceof CSSStyleRule) {
- rule.selectorText = splitSelectors(rule.selectorText)
- .map((selector) => scopeSelector(selector, root))
- .join(', ');
- } else if ('cssRules' in rule) {
- scopeRules(rule as CSSGroupingRule, root);
- }
- }
-}
-
-function scopeStyle(style: HTMLStyleElement, root: string) {
- if (style.hasAttribute(SCOPED_ATTRIBUTE)) return;
- // Parse with the browser's CSSOM in an inert sheet, then write it back.
- const parser = document.createElement('style');
- parser.media = 'not all';
- parser.textContent = style.textContent ?? '';
- document.head.appendChild(parser);
- try {
- const sheet = parser.sheet;
- if (!sheet) return;
- scopeRules(sheet, root);
- style.textContent = Array.from(sheet.cssRules, (rule) => rule.cssText).join(
- '\n'
- );
- style.setAttribute(SCOPED_ATTRIBUTE, '');
- } finally {
- parser.remove();
- }
-}
-
-function scopeDocumentStyles(html: string, root: string): string {
- if (!html || html.charCodeAt(0) === 0x7b /* error object */) return html;
- const parsed = new DOMParser().parseFromString(html, 'text/html');
- for (const style of Array.from(parsed.querySelectorAll('style')))
- scopeStyle(style, root);
- return `<!doctype html>\n${parsed.documentElement.outerHTML}`;
-}
diff --git a/apps/web/src/features/block-write/core/keymap.test.ts b/apps/web/src/features/block-write/core/keymap.test.ts
new file mode 100644
index 0000000000..ec5dace791
--- /dev/null
+++ b/apps/web/src/features/block-write/core/keymap.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest';
+import { keyAction } from './keymap';
+
+const key = (
+ key: string,
+ mods: Partial<{
+ shiftKey: boolean;
+ altKey: boolean;
+ ctrlKey: boolean;
+ metaKey: boolean;
+ }> = {},
+ code = key.length === 1 ? `Key${key.toUpperCase()}` : key
+) => ({
+ key,
+ code,
+ shiftKey: false,
+ altKey: false,
+ ctrlKey: false,
+ metaKey: false,
+ ...mods,
+});
+
+describe('keyAction', () => {
+ it('moves by platform word and line conventions', () => {
+ // Left and right arrows move on the page (visually).
+ expect(keyAction(key('ArrowLeft', { altKey: true }), true)).toEqual({
+ kind: 'ops',
+ ops: [
+ {
+ op: 'move',
+ unit: 'word',
+ forward: false,
+ extend: false,
+ visual: true,
+ },
+ ],
+ });
+ expect(keyAction(key('ArrowRight', { ctrlKey: true }), false)).toEqual({
+ kind: 'ops',
+ ops: [
+ {
+ op: 'move',
+ unit: 'word',
+ forward: true,
+ extend: false,
+ visual: true,
+ },
+ ],
+ });
+ expect(
+ keyAction(key('ArrowRight', { metaKey: true, shiftKey: true }), true)
+ ).toEqual({
+ kind: 'ops',
+ ops: [
+ {
+ op: 'move',
+ unit: 'lineBoundary',
+ forward: true,
+ extend: true,
+ visual: true,
+ },
+ ],
+ });
+ expect(keyAction(key('End', { ctrlKey: true }), false)).toEqual({
+ kind: 'ops',
+ ops: [{ op: 'move', unit: 'document', forward: true, extend: false }],
+ });
+ });
+
+ it('maps editing keys', () => {
+ expect(keyAction(key('Enter'), false)).toEqual({
+ kind: 'ops',
+ ops: [{ op: 'insertParagraph' }],
+ });
+ expect(keyAction(key('Enter', { shiftKey: true }), false)).toEqual({
+ kind: 'ops',
+ ops: [{ op: 'insertBreak', kind: 'line' }],
+ });
+ expect(keyAction(key('Backspace', { altKey: true }), true)).toEqual({
+ kind: 'ops',
+ ops: [{ op: 'delete', forward: false, unit: 'word' }],
+ group: 'delete',
+ });
+ expect(keyAction(key('Tab', { shiftKey: true }), false)).toEqual({
+ kind: 'tab',
+ forward: false,
+ });
+ });
+
+ it('maps formatting and history shortcuts', () => {
+ expect(keyAction(key('b', { metaKey: true }), true)).toEqual({
+ kind: 'ops',
+ ops: [{ op: 'toggleFormat', format: 'bold' }],
+ });
+ expect(
+ keyAction(key('z', { ctrlKey: true, shiftKey: true }), false)
+ ).toEqual({ kind: 'redo' });
+ expect(keyAction(key('y', { ctrlKey: true }), false)).toEqual({
+ kind: 'redo',
+ });
+ expect(keyAction(key('m', { metaKey: true, altKey: true }), true)).toEqual({
+ kind: 'comment',
+ });
+ });
+
+ it('inserts footnotes and endnotes with Word’s shortcuts', () => {
+ const footnote = {
+ kind: 'ops',
+ ops: [{ op: 'insertNote', endnote: false }],
+ };
+ const endnote = { kind: 'ops', ops: [{ op: 'insertNote', endnote: true }] };
+ expect(keyAction(key('f', { ctrlKey: true, altKey: true }), false)).toEqual(
+ footnote
+ );
+ expect(keyAction(key('d', { ctrlKey: true, altKey: true }), false)).toEqual(
+ endnote
+ );
+ expect(keyAction(key('f', { metaKey: true, altKey: true }), true)).toEqual(
+ footnote
+ );
+ expect(keyAction(key('e', { metaKey: true, altKey: true }), true)).toEqual(
+ endnote
+ );
+ // Plain Mod+F still finds.
+ expect(keyAction(key('f', { ctrlKey: true }), false)).toEqual({
+ kind: 'find',
+ replace: false,
+ });
+ });
+
+ it('opens find and replace', () => {
+ expect(keyAction(key('f', { ctrlKey: true }), false)).toEqual({
+ kind: 'find',
+ replace: false,
+ });
+ expect(keyAction(key('h', { ctrlKey: true }), false)).toEqual({
+ kind: 'find',
+ replace: true,
+ });
+ // Cmd+H hides the app on macOS.
+ expect(keyAction(key('h', { metaKey: true }), true)).toBeNull();
+ expect(
+ keyAction(key('h', { metaKey: true, shiftKey: true }), true)
+ ).toEqual({ kind: 'find', replace: true });
+ expect(
+ keyAction(key('g', { metaKey: true, shiftKey: true }), true)
+ ).toEqual({ kind: 'findNext', forward: false });
+ });
+
+ it('leaves typing and clipboard keys to the browser', () => {
+ expect(keyAction(key('a'), false)).toBeNull();
+ expect(keyAction(key('c', { ctrlKey: true }), false)).toBeNull();
+ expect(keyAction(key('v', { metaKey: true }), true)).toBeNull();
+ });
+});
diff --git a/apps/web/src/features/block-write/core/keymap.ts b/apps/web/src/features/block-write/core/keymap.ts
new file mode 100644
index 0000000000..166afa387f
--- /dev/null
+++ b/apps/web/src/features/block-write/core/keymap.ts
@@ -0,0 +1,143 @@
+import type { EditOp, Unit } from '@core/docx-engine/types';
+
+/** What a key press does in the DOCX editor. */
+export type KeyAction =
+ | { kind: 'ops'; ops: EditOp[]; group?: string }
+ | { kind: 'undo' }
+ | { kind: 'redo' }
+ | { kind: 'comment' }
+ | { kind: 'page'; forward: boolean; extend: boolean }
+ /** Tab: indents list items at their start, else types a tab. */
+ | { kind: 'tab'; forward: boolean }
+ /** Opens the find bar, with the replace field. */
+ | { kind: 'find'; replace: boolean }
+ /** The next (or previous) match of the search. */
+ | { kind: 'findNext'; forward: boolean };
+
+type Key = Pick<
+ KeyboardEvent,
+ 'key' | 'code' | 'shiftKey' | 'altKey' | 'ctrlKey' | 'metaKey'
+>;
+
+/**
+ * The editing action for a key press, or null to let the browser handle it
+ * (typed characters arrive as input events; clipboard keys as clipboard
+ * events). `mac` selects the platform's modifier conventions.
+ */
+export function keyAction(event: Key, mac: boolean): KeyAction | null {
+ const mod = mac ? event.metaKey : event.ctrlKey;
+ const word = mac ? event.altKey : event.ctrlKey;
+ const extend = event.shiftKey;
+ const move = (unit: Unit, forward: boolean, visual = false): KeyAction => ({
+ kind: 'ops',
+ ops: [
+ visual
+ ? { op: 'move', unit, forward, extend, visual }
+ : { op: 'move', unit, forward, extend },
+ ],
+ });
+ switch (event.key) {
+ case 'ArrowLeft':
+ case 'ArrowRight': {
+ // Left and right on the page (reversed in right-to-left text).
+ const forward = event.key === 'ArrowRight';
+ if (mac && event.metaKey) return move('lineBoundary', forward, true);
+ return move(word ? 'word' : 'char', forward, true);
+ }
+ case 'ArrowUp':
+ case 'ArrowDown': {
+ const forward = event.key === 'ArrowDown';
+ if (mac && event.metaKey) return move('document', forward);
+ if (word) return move('paragraph', forward);
+ return move('line', forward);
+ }
+ case 'Home':
+ case 'End': {
+ const forward = event.key === 'End';
+ return move(mod ? 'document' : 'lineBoundary', forward);
+ }
+ case 'PageUp':
+ case 'PageDown':
+ return { kind: 'page', forward: event.key === 'PageDown', extend };
+ case 'Backspace':
+ case 'Delete': {
+ const forward = event.key === 'Delete';
+ const unit: Unit =
+ mac && event.metaKey ? 'lineBoundary' : word ? 'word' : 'char';
+ return {
+ kind: 'ops',
+ ops: [{ op: 'delete', forward, unit }],
+ group: 'delete',
+ };
+ }
+ case 'Enter': {
+ if (mod)
+ return { kind: 'ops', ops: [{ op: 'insertBreak', kind: 'page' }] };
+ if (event.shiftKey)
+ return { kind: 'ops', ops: [{ op: 'insertBreak', kind: 'line' }] };
+ return { kind: 'ops', ops: [{ op: 'insertParagraph' }] };
+ }
+ case 'Tab':
+ if (mod || event.altKey) return null;
+ return { kind: 'tab', forward: !event.shiftKey };
+ default:
+ break;
+ }
+ if (!mod) return null;
+ const letter = event.code.startsWith('Key') ? event.code.slice(3) : '';
+ if (event.altKey) {
+ if (letter === 'M') return { kind: 'comment' };
+ // Word's note shortcuts: Ctrl+Alt+F and Ctrl+Alt+D, or Cmd+Option+F
+ // and Cmd+Option+E on a Mac.
+ if (letter === 'F')
+ return { kind: 'ops', ops: [{ op: 'insertNote', endnote: false }] };
+ if (letter === (mac ? 'E' : 'D'))
+ return { kind: 'ops', ops: [{ op: 'insertNote', endnote: true }] };
+ return null;
+ }
+ switch (letter) {
+ case 'Z':
+ return event.shiftKey ? { kind: 'redo' } : { kind: 'undo' };
+ case 'Y':
+ return mac ? null : { kind: 'redo' };
+ case 'A':
+ return { kind: 'ops', ops: [{ op: 'selectAll' }] };
+ case 'F':
+ return { kind: 'find', replace: false };
+ case 'G':
+ return { kind: 'findNext', forward: !event.shiftKey };
+ case 'H':
+ // Cmd+H hides the app on macOS, so replace is Cmd+Shift+H there.
+ if (mac && !event.shiftKey) return null;
+ return { kind: 'find', replace: true };
+ case 'B':
+ return { kind: 'ops', ops: [{ op: 'toggleFormat', format: 'bold' }] };
+ case 'I':
+ return { kind: 'ops', ops: [{ op: 'toggleFormat', format: 'italic' }] };
+ case 'U':
+ return {
+ kind: 'ops',
+ ops: [{ op: 'toggleFormat', format: 'underline' }],
+ };
+ case 'E':
+ return { kind: 'ops', ops: [{ op: 'setParagraph', align: 'center' }] };
+ case 'L':
+ return event.shiftKey
+ ? { kind: 'ops', ops: [{ op: 'toggleList', kind: 'bullet' }] }
+ : { kind: 'ops', ops: [{ op: 'setParagraph', align: 'left' }] };
+ case 'R':
+ return { kind: 'ops', ops: [{ op: 'setParagraph', align: 'right' }] };
+ case 'J':
+ return { kind: 'ops', ops: [{ op: 'setParagraph', align: 'justify' }] };
+ default:
+ break;
+ }
+ if (event.key === '=' && event.shiftKey)
+ return {
+ kind: 'ops',
+ ops: [{ op: 'toggleFormat', format: 'superscript' }],
+ };
+ if (event.key === '=')
+ return { kind: 'ops', ops: [{ op: 'toggleFormat', format: 'subscript' }] };
+ return null;
+}
diff --git a/apps/web/src/features/block-write/core/text-offsets.test.ts b/apps/web/src/features/block-write/core/text-offsets.test.ts
deleted file mode 100644
index bd30f5fdf5..0000000000
--- a/apps/web/src/features/block-write/core/text-offsets.test.ts
+++ /dev/null
@@ -1,83 +0,0 @@
-import { beforeEach, describe, expect, it } from 'vitest';
-import {
- blockOf,
- blockSpanOfRange,
- changedTextEnd,
- contentOffset,
- contentRange,
- contentText,
-} from './text-offsets';
-
-let root: HTMLElement;
-
-beforeEach(() => {
- document.body.innerHTML = `
- <div id="root">
- <p data-anchor="p1"><span data-list-marker="">1.</span><span>‎Hello </span><b>bold</b><span> world</span></p>
- <p data-anchor="p2">Page <span data-field="" data-field-cached="7">12</span> end</p>
- </div>`;
- root = document.getElementById('root')!;
-});
-
-const block = (id: string) =>
- root.querySelector<HTMLElement>(`[data-anchor="${id}"]`)!;
-
-describe('content offsets', () => {
- it('excludes list markers and bidi marks from the text', () => {
- expect(contentText(block('p1'))).toBe('Hello bold world');
- });
-
- it('counts a field as its cached result', () => {
- expect(contentText(block('p2'))).toBe('Page 7 end');
- });
-
- it('maps DOM positions to content offsets', () => {
- const bold = block('p1').querySelector('b')!.firstChild!;
- expect(contentOffset(block('p1'), bold, 2)).toBe(8);
- });
-
- it('builds ranges that cover exactly the requested text', () => {
- const range = contentRange(block('p1'), 6, 7)!;
- expect(range.toString()).toBe('bold wo');
- expect(contentRange(block('p1'), 0, 5)!.toString()).toBe('Hello');
- expect(contentRange(block('p1'), 40, 2)).toBeNull();
- });
-
- it('round-trips a selection into a block span', () => {
- const range = contentRange(block('p1'), 6, 4)!;
- expect(blockSpanOfRange(range, root)).toMatchObject({
- block: block('p1'),
- start: 6,
- length: 4,
- });
- });
-
- it('clamps a selection that continues into the next block', () => {
- const range = document.createRange();
- const start = contentRange(block('p1'), 11, 1)!;
- range.setStart(start.startContainer, start.startOffset);
- range.setEnd(block('p2').firstChild!, 2);
- expect(blockSpanOfRange(range, root)).toMatchObject({
- start: 11,
- length: 5,
- });
- });
-
- it('finds the block that owns a node', () => {
- expect(blockOf(block('p2').firstChild, root)).toBe(block('p2'));
- expect(blockOf(root, root)).toBeNull();
- });
-});
-
-describe('changed text end', () => {
- it('lands after reinserted text and where removed text was', () => {
- expect(changedTextEnd('notice.', 'notice. More.')).toBe(13);
- expect(changedTextEnd('notice. More.', 'notice.')).toBe(7);
- });
-
- it('handles a change in the middle and repeated characters', () => {
- expect(changedTextEnd('abcdef', 'abcXYZdef')).toBe(6);
- expect(changedTextEnd('aaa', 'aaaa')).toBe(4);
- expect(changedTextEnd('same', 'same')).toBe(4);
- });
-});
diff --git a/apps/web/src/features/block-write/core/text-offsets.ts b/apps/web/src/features/block-write/core/text-offsets.ts
deleted file mode 100644
index aec8015c6c..0000000000
--- a/apps/web/src/features/block-write/core/text-offsets.ts
+++ /dev/null
@@ -1,222 +0,0 @@
-/**
- * Content offsets inside a rendered DOCX block, in the same space the
- * Docxodus editor uses for its own selection spans: generated chrome (list
- * numbers, note references) and injected bidi marks do not count, and a field
- * counts as its cached result.
- */
-
-const GENERATED_CHROME =
- '[data-list-marker], a.footnote-ref, a.endnote-ref, a[class$="-backref"], a.comment-marker';
-const BIDI_MARKS = /[‎‏؜‪-‮⁦-⁩]/;
-const BIDI_MARKS_GLOBAL = new RegExp(BIDI_MARKS.source, 'g');
-
-function stripBidi(text: string): string {
- return text.replace(BIDI_MARKS_GLOBAL, '');
-}
-
-function isElement(node: Node): node is Element {
- return node.nodeType === Node.ELEMENT_NODE;
-}
-
-function isChrome(node: Node, block: Element): boolean {
- let element: Element | null = isElement(node) ? node : node.parentElement;
- while (element && element !== block) {
- if (element.matches(GENERATED_CHROME)) return true;
- element = element.parentElement;
- }
- return false;
-}
-
-function isField(node: Node): node is HTMLElement {
- return isElement(node) && node.hasAttribute('data-field');
-}
-
-function fieldText(field: HTMLElement): string {
- return stripBidi(field.dataset.fieldCached ?? field.textContent ?? '');
-}
-
-/** The block (rendered paragraph) a node belongs to, inside `root`. */
-export function blockOf(node: Node | null, root: Element): HTMLElement | null {
- let element: Element | null =
- node && isElement(node) ? node : (node?.parentElement ?? null);
- while (element && element !== root) {
- if (element.hasAttribute('data-anchor') && element instanceof HTMLElement)
- return element;
- element = element.parentElement;
- }
- return null;
-}
-
-/** The block's text in content-offset space. */
-export function contentText(block: Element): string {
- let out = '';
- const walk = (node: Node) => {
- if (isField(node)) out += fieldText(node);
- else if (node.nodeType === Node.TEXT_NODE) {
- if (!isChrome(node, block)) out += stripBidi(node.textContent ?? '');
- } else node.childNodes.forEach(walk);
- };
- walk(block);
- return out;
-}
-
-/** Content offset of a DOM position (container + offset) inside `block`. */
-export function contentOffset(
- block: Element,
- container: Node,
- offset: number
-): number {
- let count = 0;
- let done = false;
- const walk = (node: Node) => {
- if (done) return;
- if (isField(node)) {
- const inside = node === container || node.contains(container);
- if (!inside || offset > 0 || node !== container)
- count += fieldText(node).length;
- if (inside) done = true;
- return;
- }
- if (node.nodeType === Node.TEXT_NODE) {
- const chrome = isChrome(node, block);
- if (node === container) {
- if (!chrome)
- count += stripBidi((node.textContent ?? '').slice(0, offset)).length;
- done = true;
- return;
- }
- if (!chrome) count += stripBidi(node.textContent ?? '').length;
- return;
- }
- if (node === container) {
- const children = Array.from(node.childNodes);
- for (let i = 0; i < offset && i < children.length; i++) walk(children[i]);
- done = true;
- return;
- }
- node.childNodes.forEach(walk);
- };
- walk(block);
- return count;
-}
-
-type Point = { node: Node; offset: number };
-
-/** The DOM position at content offset `target`, or null past the end. */
-function pointAt(
- block: Element,
- target: number,
- preferEnd: boolean
-): Point | null {
- let count = 0;
- let found: Point | null = null;
- const walk = (node: Node): boolean => {
- if (isField(node)) {
- const length = fieldText(node).length;
- if (
- target <= count + length &&
- (preferEnd ? target > count : target < count + length)
- ) {
- const parent = node.parentNode;
- if (!parent) return false;
- const index = Array.prototype.indexOf.call(parent.childNodes, node);
- found = { node: parent, offset: preferEnd ? index + 1 : index };
- return true;
- }
- count += length;
- return false;
- }
- if (node.nodeType === Node.TEXT_NODE) {
- if (isChrome(node, block)) return false;
- const raw = node.textContent ?? '';
- const length = stripBidi(raw).length;
- const hit = preferEnd
- ? target > count && target <= count + length
- : target >= count && target < count + length;
- if (hit) {
- let content = count;
- for (let i = 0; i <= raw.length; i++) {
- if (
- content === target &&
- (i === raw.length || !BIDI_MARKS.test(raw[i]))
- ) {
- found = { node, offset: i };
- return true;
- }
- if (i < raw.length && !BIDI_MARKS.test(raw[i])) content++;
- }
- }
- count += length;
- return false;
- }
- for (const child of Array.from(node.childNodes))
- if (walk(child)) return true;
- return false;
- };
- walk(block);
- return found;
-}
-
-/** A DOM range covering content offsets [start, start + length) of `block`. */
-export function contentRange(
- block: Element,
- start: number,
- length: number
-): Range | null {
- if (length <= 0) return null;
- const from = pointAt(block, start, false);
- const to = pointAt(block, start + length, true);
- if (!from || !to) return null;
- const range = document.createRange();
- range.setStart(from.node, from.offset);
- range.setEnd(to.node, to.offset);
- return range.collapsed ? null : range;
-}
-
-/** A collapsed range at content offset `offset` of `block` (clamped to its end). */
-export function caretRange(block: Element, offset: number): Range | null {
- const length = contentText(block).length;
- const target = Math.max(0, Math.min(offset, length));
- const point =
- target > 0 ? pointAt(block, target, true) : pointAt(block, 0, false);
- const range = document.createRange();
- if (point) range.setStart(point.node, point.offset);
- else range.selectNodeContents(block);
- range.collapse(true);
- return range;
-}
-
-/**
- * The part of `range` that falls inside one block: the block where the range
- * starts, clamped to that block's end when the range continues past it.
- */
-export function blockSpanOfRange(
- range: Range,
- root: Element
-): { block: HTMLElement; start: number; length: number } | null {
- const block = blockOf(range.startContainer, root);
- if (!block) return null;
- const start = contentOffset(block, range.startContainer, range.startOffset);
- const end = block.contains(range.endContainer)
- ? contentOffset(block, range.endContainer, range.endOffset)
- : contentText(block).length;
- if (end <= start) return null;
- return { block, start, length: end - start };
-}
-
-/**
- * Where the caret belongs after `before` became `after`, as undo and redo
- * place it: the end of the text that changed, in `after`'s offsets.
- */
-export function changedTextEnd(before: string, after: string): number {
- const limit = Math.min(before.length, after.length);
- let start = 0;
- while (start < limit && before[start] === after[start]) start++;
- let end = 0;
- while (
- end < limit - start &&
- before[before.length - 1 - end] === after[after.length - 1 - end]
- )
- end++;
- return after.length - end;
-}
diff --git a/apps/web/src/features/block-write/primitives/create-comment-highlights.ts b/apps/web/src/features/block-write/primitives/create-comment-highlights.ts
deleted file mode 100644
index c48004a062..0000000000
--- a/apps/web/src/features/block-write/primitives/create-comment-highlights.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { type Accessor, createEffect, onCleanup } from 'solid-js';
-import type { DocxComments } from './create-docx-comments';
-
-let instances = 0;
-
-/**
- * Paint comment highlights with the CSS Custom Highlight API, which styles
- * ranges without touching the editor's DOM, so commenting never interferes
- * with editing. Returns the stylesheet text for the per-instance names.
- */
-export function createCommentHighlights(
- comments: DocxComments,
- enabled: Accessor<boolean>
-): string {
- const id = ++instances;
- const base = `docx-comment-${id}`;
- const active = `docx-comment-active-${id}`;
- const supported = () => typeof CSS !== 'undefined' && 'highlights' in CSS;
- createEffect(() => {
- if (!supported()) return;
- const threads = enabled() ? comments.located() : [];
- const selected = comments.active();
- CSS.highlights.set(
- base,
- new Highlight(
- ...threads
- .filter((thread) => !thread.resolved && thread.id !== selected)
- .map((thread) => thread.range)
- )
- );
- CSS.highlights.set(
- active,
- new Highlight(
- ...threads
- .filter((thread) => thread.id === selected)
- .map((thread) => thread.range)
- )
- );
- });
- onCleanup(() => {
- if (!supported()) return;
- CSS.highlights.delete(base);
- CSS.highlights.delete(active);
- });
- return `::highlight(${base}) { background-color: oklch(from var(--color-yellow) l c h / 0.28); text-decoration: underline 2px oklch(from var(--color-yellow) l c h / 0.7); }
-::highlight(${active}) { background-color: oklch(from var(--color-yellow) l c h / 0.55); text-decoration: underline 2px oklch(from var(--color-yellow) l c h / 0.9); }`;
-}
diff --git a/apps/web/src/features/block-write/primitives/create-docx-comments.ts b/apps/web/src/features/block-write/primitives/create-docx-comments.ts
index 24da3644f2..beaec6c4b0 100644
--- a/apps/web/src/features/block-write/primitives/create-docx-comments.ts
+++ b/apps/web/src/features/block-write/primitives/create-docx-comments.ts
@@ -1,4 +1,9 @@
-import { DOCX_LORO_CONTAINERS } from '@macro-inc/collaboration/docx/schema';
+import type {
+ DocComment,
+ PageRect,
+ ParagraphText,
+ Pos,
+} from '@core/docx-engine/types';
import type { MessageListItem } from '@service-storage/messages';
import type { LoroDoc } from 'loro-crdt';
import {
@@ -6,6 +11,7 @@ import {
createEffect,
createMemo,
createSignal,
+ on,
onCleanup,
untrack,
} from 'solid-js';
@@ -18,25 +24,31 @@ import {
resolveMark,
writeCommentMark,
} from '../core/comment-marks';
-import {
- blockSpanOfRange,
- contentRange,
- contentText,
-} from '../core/text-offsets';
+import { DOCX_LORO_CONTAINERS } from '../core/docx-loro';
export type DocxCommentDraft = { markId: string; mark: CommentMark };
export type LocatedThread = {
- /** Thread root id, or the draft's mark id. */
+ /** Thread root id, the draft's mark id, or `word:` + a document comment's id. */
id: string;
markId: string;
root: MessageListItem | null;
resolved: boolean;
- block: HTMLElement;
- range: Range;
+ /** Where the commented text is, as found in the current document. */
+ mark: CommentMark;
+ /** Its highlight rectangles on the pages. */
+ rects: PageRect[];
+ /** A comment the document itself carries (Word's), with its replies. */
+ word?: { comment: DocComment; replies: DocComment[] };
};
-type Paragraph = { id: string; text: string; element: HTMLElement };
+/** The highlighted range of a document comment: a comment on a point
+ * (no range) highlights the character before it. */
+function wordRange(comment: DocComment): { from: Pos; to: Pos } {
+ const { from, to } = comment;
+ if (from.block !== to.block || from.offset !== to.offset) return { from, to };
+ return { from: { ...from, offset: Math.max(0, from.offset - 1) }, to };
+}
/** A placeholder mark for a thread known only by its quoted text. */
function quotedMark(root: MessageListItem): CommentMark | null {
@@ -52,18 +64,26 @@ export function threadMarkId(root: MessageListItem): string | null {
return anchor && anchor.type === 'markdown' ? anchor.mark_id : null;
}
+/** What comment placement needs from the editor. */
+export type CommentGeometry = {
+ revision: Accessor<number>;
+ paragraphs: () => Promise<ParagraphText[]>;
+ /** The comments the document itself carries (Word's). */
+ documentComments: () => Promise<DocComment[]>;
+ rangeRects: (from: Pos, to: Pos) => Promise<PageRect[]>;
+ /** The current selection, in document order. */
+ selection: () => { from: Pos; to: Pos } | undefined;
+};
+
/**
- * Comment anchoring for a rendered DOCX: marks live in the collaborative
- * document, threads come from the shared message store, and both are joined
- * to the paragraphs currently on screen.
+ * Comment anchoring for a DOCX: marks live in the collaborative document,
+ * threads come from the shared message store, and both are joined to the
+ * text the engine currently lays out.
*/
export function createDocxComments(options: {
doc: LoroDoc | null;
roots: Accessor<MessageListItem[]>;
- /** The element the editor renders the document body into. */
- root: Accessor<HTMLElement | undefined>;
- /** Bumps whenever the rendered document may have changed. */
- revision: Accessor<number>;
+ geometry: CommentGeometry;
canEdit: Accessor<boolean>;
}) {
const [marks, setMarks] = createSignal<Map<string, CommentMark>>(
@@ -71,6 +91,9 @@ export function createDocxComments(options: {
);
const [draft, setDraft] = createSignal<DocxCommentDraft>();
const [active, setActive] = createSignal<string | null>(null);
+ const [paragraphs, setParagraphs] = createSignal<ParagraphText[]>([]);
+ const [wordComments, setWordComments] = createSignal<DocComment[]>([]);
+ const [located, setLocated] = createSignal<LocatedThread[]>([]);
if (options.doc) {
const doc = options.doc;
@@ -80,27 +103,34 @@ export function createDocxComments(options: {
onCleanup(unsubscribe);
}
- const paragraphs = createMemo<Paragraph[]>(() => {
- options.revision();
- const root = options.root();
- if (!root) return [];
- const body = root.querySelector<HTMLElement>('.docx-body-flow') ?? root;
- return Array.from(body.querySelectorAll<HTMLElement>('[data-anchor]'))
- .filter((element) => !element.querySelector('[data-anchor]'))
- .map((element) => ({
- id: element.getAttribute('data-anchor')!,
- text: contentText(element),
- element,
- }));
- });
-
const live = (root: MessageListItem) => !root.state.deleted_at;
+ // The engine's text: refreshed shortly after the document changes.
+ let textTimer: ReturnType<typeof setTimeout> | undefined;
+ createEffect(
+ on(options.geometry.revision, () => {
+ clearTimeout(textTimer);
+ textTimer = setTimeout(() => {
+ options.geometry
+ .paragraphs()
+ .then(setParagraphs)
+ .catch(() => {});
+ options.geometry
+ .documentComments()
+ .then(setWordComments)
+ .catch(() => {});
+ }, 120);
+ })
+ );
+ onCleanup(() => clearTimeout(textTimer));
+
+ /** Marks resolved against the current text. */
const placement = createMemo(() => {
const blocks = paragraphs();
const all = marks();
- const out: LocatedThread[] = [];
+ const out: Array<Omit<LocatedThread, 'rects'>> = [];
const relocations: Array<[string, CommentMark]> = [];
+ if (!blocks.length) return { threads: out, relocations };
const place = (
id: string,
markId: string,
@@ -108,30 +138,21 @@ export function createDocxComments(options: {
root: MessageListItem | null
) => {
const found = resolveMark(mark, blocks);
- if (!found) return false;
- const block = blocks.find((paragraph) => paragraph.id === found.block);
- const range =
- block && contentRange(block.element, found.start, found.length);
- if (!block || !range) return false;
- if (found.relocated && root)
- relocations.push([
- markId,
- {
- block: found.block,
- start: found.start,
- length: found.length,
- text: found.text,
- },
- ]);
+ if (!found) return;
+ const placed: CommentMark = {
+ block: found.block,
+ start: found.start,
+ length: found.length,
+ text: found.text,
+ };
+ if (found.relocated && root) relocations.push([markId, placed]);
out.push({
id,
markId,
root,
resolved: !!root?.state.resolved,
- block: block.element,
- range,
+ mark: placed,
});
- return true;
};
for (const root of options.roots()) {
if (!live(root)) continue;
@@ -145,9 +166,61 @@ export function createDocxComments(options: {
}
const pending = draft();
if (pending) place(pending.markId, pending.markId, pending.mark, null);
+ // The document's own comments, replies under the comment they answer.
+ const documentComments = wordComments();
+ const known = new Set(documentComments.map((c) => c.id));
+ for (const comment of documentComments) {
+ if (comment.parent && known.has(comment.parent)) continue;
+ const { from, to } = wordRange(comment);
+ const id = `word:${comment.id}`;
+ out.push({
+ id,
+ markId: id,
+ root: null,
+ resolved: comment.done,
+ mark: {
+ block: from.block,
+ start: from.offset,
+ length: from.block === to.block ? to.offset - from.offset : 0,
+ text: '',
+ },
+ word: {
+ comment,
+ replies: documentComments.filter((c) => c.parent === comment.id),
+ },
+ });
+ }
return { threads: out, relocations };
});
- const located = () => placement().threads;
+
+ // Highlight geometry comes from the engine (asynchronously).
+ let generation = 0;
+ createEffect(
+ on([placement, options.geometry.revision], ([{ threads }]) => {
+ const current = ++generation;
+ Promise.all(
+ threads.map(async (thread) => {
+ const range = thread.word
+ ? wordRange(thread.word.comment)
+ : {
+ from: { block: thread.mark.block, offset: thread.mark.start },
+ to: {
+ block: thread.mark.block,
+ offset: thread.mark.start + thread.mark.length,
+ },
+ };
+ return {
+ ...thread,
+ rects: await options.geometry.rangeRects(range.from, range.to),
+ };
+ })
+ )
+ .then((next) => {
+ if (current === generation) setLocated(next);
+ })
+ .catch(() => {});
+ })
+ );
// Keep stored offsets close to the text so later edits relocate cheaply.
// Writing a relocated mark re-resolves it in place, so this settles; marks
@@ -174,7 +247,9 @@ export function createDocxComments(options: {
/** Threads that cannot be shown beside the text: legacy anchors or removed text. */
const detached = createMemo(() => {
- const shown = new Set(located().map((thread) => thread.id));
+ // Until the text is known every thread would look detached.
+ if (!paragraphs().length) return [];
+ const shown = new Set(placement().threads.map((thread) => thread.id));
return options
.roots()
.filter((root) => live(root) && root.state.anchor && !shown.has(root.id));
@@ -182,23 +257,22 @@ export function createDocxComments(options: {
/** Start a comment on the current selection. False when nothing usable is selected. */
function beginDraft(): boolean {
- const root = options.root();
- const selection = window.getSelection();
- if (
- !root ||
- !selection ||
- selection.rangeCount === 0 ||
- selection.isCollapsed
- )
- return false;
- const span = blockSpanOfRange(selection.getRangeAt(0), root);
- if (!span) return false;
- const id = span.block.getAttribute('data-anchor');
- const length = Math.min(span.length, MAX_MARK_TEXT);
- const text = contentText(span.block).slice(span.start, span.start + length);
- if (!id || !text.trim()) return false;
+ const selection = options.geometry.selection();
+ if (!selection) return false;
+ const { from, to } = selection;
+ if (from.block === to.block && from.offset === to.offset) return false;
+ const paragraph = paragraphs().find((p) => p.id === from.block);
+ if (!paragraph) return false;
+ // A selection over several paragraphs anchors on the first one's part.
+ const end = to.block === from.block ? to.offset : paragraph.text.length;
+ const length = Math.min(end - from.offset, MAX_MARK_TEXT);
+ const text = paragraph.text.slice(from.offset, from.offset + length);
+ if (!text.trim()) return false;
const markId = uuidv7();
- setDraft({ markId, mark: { block: id, start: span.start, length, text } });
+ setDraft({
+ markId,
+ mark: { block: from.block, start: from.offset, length, text },
+ });
setActive(markId);
return true;
}
@@ -228,13 +302,15 @@ export function createDocxComments(options: {
}
}
- /** The thread whose highlight contains a caret position. */
- function threadAt(node: Node, offset: number): string | null {
+ /** The thread whose text contains a position. */
+ function threadAt(pos: Pos): string | null {
for (const thread of located()) {
if (thread.resolved && active() !== thread.id) continue;
+ const { block, start, length } = thread.mark;
if (
- thread.range.comparePoint(node, offset) === 0 &&
- thread.block.contains(node)
+ block === pos.block &&
+ pos.offset >= start &&
+ pos.offset <= start + length
)
return thread.id;
}
diff --git a/apps/web/src/features/block-write/primitives/create-docx-editor.ts b/apps/web/src/features/block-write/primitives/create-docx-editor.ts
index 3e3ef4f022..49edfa33eb 100644
--- a/apps/web/src/features/block-write/primitives/create-docx-editor.ts
+++ b/apps/web/src/features/block-write/primitives/create-docx-editor.ts
@@ -1,350 +1,317 @@
-import { readDocxState } from '@macro-inc/collaboration/docx/schema';
-import type { DocxEditor } from 'docxodus';
+import * as engine from '@core/docx-engine/client';
+import type {
+ EditOp,
+ EditResult,
+ FindOptions,
+ PageInfo,
+ Pos,
+ Selection,
+ StyleInfo,
+} from '@core/docx-engine/types';
import type { LoroDoc } from 'loro-crdt';
-import { type Accessor, createSignal, onCleanup } from 'solid-js';
-import { bridgeEngine, type DocxEngine } from '../core/docx-engine';
-import { assemblePackage } from '../core/docx-package';
-import { DOCX_SYNC_SESSION_SETTINGS } from '../core/docx-seed';
-import { DocxSyncController } from '../core/docx-sync';
-import { editorBridge } from '../core/editor-bridge';
+import { createSignal, onCleanup } from 'solid-js';
+import { DocxCollab } from '../core/docx-collab';
import {
- caretRange,
- changedTextEnd,
- contentOffset,
- contentText,
-} from '../core/text-offsets';
-import type { DocxodusRuntime } from '../queries/docxodus-runtime';
+ clearV1,
+ configureDocxText,
+ DOCX_FORMAT_VERSION,
+ DOCX_ORIGINS,
+ docxFormatVersion,
+ readCollabState,
+ readV1State,
+ writeCollabState,
+} from '../core/docx-loro';
+import { createPageRenderer } from './create-page-renderer';
-/** Commit typing this long after the last keystroke so peers see it live. */
-const IDLE_COMMIT_MS = 1_200;
-/** Coalesce bursts of engine mutations into one publish. */
-const PUBLISH_DELAY_MS = 80;
-/** A rendered block the user can type in. */
-const EDITABLE_BLOCK = '[data-anchor][contenteditable="true"]';
+let instances = 0;
+
+/** Points to CSS pixels at 100% zoom. */
+export const PX_PER_PT = 96 / 72;
export type DocxEditorOptions = {
- runtime: DocxodusRuntime;
- /** The collaborative document; null opens `original` read-only, unsynced. */
+ /** Collaborative document, or null for a read-only original. */
doc: LoroDoc | null;
+ /** The uploaded file, shown read-only when there is no shared document. */
original?: Uint8Array;
+ /** Whether this user may change the document. */
editable: boolean;
- author: string;
- /** The scrolling element around the document, kept in place on remounts. */
- scroller?: () => HTMLElement | undefined;
- /** Called after remote changes land (`subscribe` receives the trigger). */
- subscribeRemote?: (listener: () => void) => () => void;
+ /** The name this person's tracked changes are recorded under. */
+ author?: string;
+ /** Called with this user's selection when it changes. */
+ onSelection?: (selection: Selection | undefined) => void;
onError?: (error: unknown) => void;
};
-export type DocxEditorHandle = {
- editor: Accessor<DocxEditor | undefined>;
- /** Bumps whenever the rendered document changes (local or remote). */
- revision: Accessor<number>;
- /** Mount the editor into `element`. */
- mount: (element: HTMLElement) => Promise<void>;
- /** Publish committed local edits now (e.g. before leaving). */
- flush: () => void;
- /** Undo the last edit, including typing not yet committed. */
- undo: () => void;
- /** Redo the last undone edit. */
- redo: () => void;
- /** The editor's live document bytes, without engine bookkeeping. */
- save: () => Uint8Array | undefined;
-};
-
-let mountCounter = 0;
-
/**
- * Own one Docxodus editor and keep it in step with the collaborative
- * document: local engine mutations are published, remote changes are patched
- * into the live session, and typing is committed while the user pauses.
+ * One open document: the engine session in the worker, its link to the
+ * shared document, the page renderer, and the editing state the view shows.
*/
-export function createDocxEditor(options: DocxEditorOptions): DocxEditorHandle {
- const [editor, setEditor] = createSignal<DocxEditor>();
+export function createDocxEditor(options: DocxEditorOptions) {
+ const docKey = `docx-${++instances}-${Math.random().toString(36).slice(2)}`;
+ const [pages, setPages] = createSignal<PageInfo[]>([]);
+ const [state, setState] = createSignal<EditResult>();
+ const [ready, setReady] = createSignal(false);
+ /** Bumps whenever the document's content changes. */
const [revision, setRevision] = createSignal(0);
- const bump = () => setRevision((value) => value + 1);
- let container: HTMLElement | undefined;
- let controller: DocxSyncController | undefined;
- let publishTimer: ReturnType<typeof setTimeout> | undefined;
- let idleTimer: ReturnType<typeof setTimeout> | undefined;
+ const [zoom, setZoom] = createSignal(1);
+ const [styles, setStyles] = createSignal<StyleInfo[]>([]);
+ const [markup, setMarkupSignal] = createSignal(true);
+ let collab: DocxCollab | undefined;
let disposed = false;
- let applying = false;
- let unsubscribeRemote: (() => void) | undefined;
- const rootId = `docx-editor-${++mountCounter}`;
- const rootSelector = `[data-docx-editor="${rootId}"]`;
-
- const publish = () => {
- clearTimeout(publishTimer);
- publishTimer = undefined;
- if (!controller || applying || disposed) return;
- try {
- if (controller.publishLocal()) bump();
- } catch (error) {
- options.onError?.(error);
- }
- };
- const schedulePublish = () => {
- if (applying || !options.doc) return;
- clearTimeout(publishTimer);
- publishTimer = setTimeout(publish, PUBLISH_DELAY_MS);
- };
- const exports = editorBridge(options.runtime.exports, {
- rootSelector,
- sessionSettings: DOCX_SYNC_SESSION_SETTINGS,
- onMutation: () => {
- schedulePublish();
- bump();
- },
+ const renderer = createPageRenderer({
+ docKey,
+ scale: () => zoom() * PX_PER_PT,
+ onError: options.onError,
});
- const engine: DocxEngine = bridgeEngine(
- options.runtime.exports.DocxSessionBridge,
- () => {
- const current = editor();
- if (!current) throw new Error('DOCX editor is not mounted');
- return current.sessionHandle;
+ function take(result: EditResult | null | undefined) {
+ if (!result || disposed) return;
+ setState(result);
+ if (result.pages) {
+ setPages(result.pages);
+ renderer.update(result.pages, result.bands ?? []);
}
- );
-
- const editorOptions = () => ({
- editable: options.editable,
- comments: false,
- // Docxodus renders header/footer stories as editing bands only; readers
- // get the print layout, where every page carries its header and footer.
- headerFooter: options.editable,
- paginated: !options.editable,
- blockDrag: options.editable,
- revisionAuthor: options.author,
- commentAuthor: options.author,
- });
-
- /** A fresh child for each editor instance; the scoped root stays stable. */
- const freshHost = () => {
- const host = document.createElement('div');
- host.className = 'docx-editor-host';
- container!.replaceChildren(host);
- return host;
- };
-
- const activeBlock = (): HTMLElement | null => {
- const active = document.activeElement;
- if (!(active instanceof HTMLElement) || !container?.contains(active))
- return null;
- return active.closest<HTMLElement>(EDITABLE_BLOCK);
- };
- const isDirty = (block: HTMLElement) =>
- block.dataset.committedText !== undefined &&
- contentText(block) !== block.dataset.committedText;
+ if (result.changed || result.pages) setRevision((r) => r + 1);
+ options.onSelection?.(result.selection);
+ }
- /** True while a block (or a paragraph inside it) holds uncommitted typing. */
- const isBusy = (blockId: string) => {
- const block = activeBlock();
- if (!block || !isDirty(block)) return false;
- if (block.getAttribute('data-anchor') === blockId) return true;
- const owner = container?.querySelector(
- `[data-anchor="${CSS.escape(blockId)}"]`
+ /** Opens the shared document, migrating the first format if needed. */
+ async function openShared(doc: LoroDoc) {
+ configureDocxText(doc);
+ const version = docxFormatVersion(doc);
+ if (version !== undefined && version < DOCX_FORMAT_VERSION) {
+ if (!options.editable) {
+ return engine.openV1Document(docKey, readV1State(doc));
+ }
+ // Rewrite the first format once; every editor derives the same
+ // blocks from it, so concurrent migrations agree.
+ await engine.openV1Document(docKey, readV1State(doc));
+ const migrated = await engine.collabState(docKey);
+ clearV1(doc);
+ writeCollabState(doc, migrated, DOCX_ORIGINS.migrate);
+ }
+ return engine.openCollabDocument(
+ docKey,
+ readCollabState(doc),
+ Math.floor(Math.random() * 2 ** 48)
);
- return !!owner?.contains(block);
- };
-
- const editableBlocks = () =>
- Array.from(container?.querySelectorAll<HTMLElement>(EDITABLE_BLOCK) ?? []);
-
- const scrollTop = () => options.scroller?.()?.scrollTop;
+ }
- /** Focus `block` with the caret at a content offset and the scroll at `top`. */
- const placeCaret = (block: HTMLElement, offset: number, top?: number) => {
- block.focus({ preventScroll: true });
- const caret = caretRange(block, offset);
- const selection = window.getSelection();
- if (caret && selection) {
- selection.removeAllRanges();
- selection.addRange(caret);
- }
- const scrollParent = options.scroller?.();
- if (scrollParent && top !== undefined) scrollParent.scrollTop = top;
- };
+ /** Keeps the engine in step with the shared document from now on. */
+ function follow(doc: LoroDoc) {
+ collab = new DocxCollab(doc, adapter, {
+ undo: options.editable,
+ selection: () => state()?.selection,
+ onRemote: (result, restored) => {
+ take(result);
+ if (restored)
+ run([
+ {
+ op: 'select',
+ anchor: restored.anchor,
+ focus: restored.focus,
+ },
+ ]);
+ },
+ onError: options.onError,
+ });
+ }
- /** The focused block and the content offset of the selection's focus end. */
- const caretPosition = () => {
- const block = activeBlock();
- if (!block) return null;
- const selection = window.getSelection();
- const node = selection?.focusNode;
- const inside = !!node && block.contains(node);
- return {
- block,
- collapsed: inside && selection!.isCollapsed,
- offset: inside ? contentOffset(block, node, selection!.focusOffset) : 0,
- };
- };
+ let stopMigrationWatch: (() => void) | undefined;
/**
- * Commit the block the user is typing in without moving their caret: the
- * editor commits on blur, so blur and restore focus at the same offset. The
- * idle commit leaves a selection in progress alone; `force` commits anyway.
+ * A viewer of a first-format document shows it as it is until an editor
+ * migrates it, then reopens from the shared blocks and follows along.
*/
- const commitTyping = (force = false) => {
- clearTimeout(idleTimer);
- idleTimer = undefined;
- const position = caretPosition();
- if (!position || !isDirty(position.block)) return;
- if (!force && !position.collapsed) return;
- const id = position.block.getAttribute('data-anchor');
- const top = scrollTop();
- position.block.blur();
- const fresh =
- (id &&
- container?.querySelector<HTMLElement>(
- `[data-anchor="${CSS.escape(id)}"][contenteditable="true"]`
- )) ||
- null;
- if (fresh) placeCaret(fresh, position.offset, top);
- };
+ function awaitMigration(doc: LoroDoc) {
+ if (disposed) return;
+ const unsubscribe = doc.subscribe(() => {
+ if (docxFormatVersion(doc) !== DOCX_FORMAT_VERSION) return;
+ unsubscribe();
+ stopMigrationWatch = undefined;
+ void (async () => {
+ if (disposed) return;
+ const reopened = await engine.openCollabDocument(
+ docKey,
+ readCollabState(doc),
+ Math.floor(Math.random() * 2 ** 48)
+ );
+ if (disposed) return;
+ follow(doc);
+ show(reopened);
+ renderer.invalidate();
+ })().catch((error: unknown) => options.onError?.(error));
+ });
+ // Runs after an await, outside the owner: the editor's own cleanup
+ // stops it.
+ stopMigrationWatch = unsubscribe;
+ }
- /**
- * Step through the session's history. Typing reaches the session only when
- * committed, so commit it first; otherwise undo skips past it.
- */
- const step = (direction: 'undo' | 'redo') => {
- const current = editor();
- if (!current || !options.editable) return;
- commitTyping(true);
- const position = caretPosition();
- const index = position ? editableBlocks().indexOf(position.block) : -1;
- const before = editableBlocks().map(contentText);
- const top = scrollTop();
- current[direction]();
- // Repainting drops the caret. Put it at the end of the change, as word
- // processors do, so typing continues there and the next shortcut lands.
- const blocks = editableBlocks();
- const changed = blocks.findIndex(
- (block, i) => contentText(block) !== before[i]
- );
- if (changed >= 0) {
- const block = blocks[changed];
- placeCaret(
- block,
- changedTextEnd(before[changed] ?? '', contentText(block)),
- top
- );
- block.scrollIntoView({ block: 'nearest' });
- return;
+ function show(opened: { pages: PageInfo[]; state: EditResult }) {
+ setPages(opened.pages);
+ renderer.update(opened.pages);
+ take(opened.state);
+ }
+
+ async function open() {
+ const doc = options.doc;
+ const opened = doc
+ ? await openShared(doc)
+ : await engine.openDocument(
+ docKey,
+ (options.original ?? new Uint8Array()).slice().buffer
+ );
+ if (disposed) return;
+ if (options.author) await engine.setAuthor(docKey, options.author);
+ if (doc) {
+ if (options.editable) await engine.setExternalUndo(docKey, true);
+ if (docxFormatVersion(doc) === DOCX_FORMAT_VERSION) follow(doc);
+ else awaitMigration(doc);
}
- if (!position || container?.contains(document.activeElement)) return;
- const block = blocks[Math.min(index, blocks.length - 1)];
- if (block) placeCaret(block, position.offset, top);
- };
+ show(opened);
+ setStyles(await engine.styles(docKey));
+ setReady(true);
+ }
- /** Own the history shortcuts so they commit pending typing first. */
- const onKeyDown = (event: KeyboardEvent) => {
- if (!options.editable || event.isComposing || event.altKey) return;
- if (!(event.metaKey || event.ctrlKey)) return;
- const key = event.key.toLowerCase();
- if (key !== 'z' && key !== 'y') return;
- if (
- !(event.target instanceof Element) ||
- !event.target.closest(EDITABLE_BLOCK)
- )
- return;
- event.preventDefault();
- event.stopPropagation();
- step(key === 'z' && !event.shiftKey ? 'undo' : 'redo');
+ const adapter = {
+ apply: (ops: EditOp[], group?: string) =>
+ engine.applyOps(docKey, ops, group),
+ applyRemote: (changes: Parameters<typeof engine.applyRemote>[1]) =>
+ engine.applyRemote(docKey, changes),
};
- const onInput = (event: Event) => {
- if ((event as InputEvent).isComposing) return;
- clearTimeout(idleTimer);
- idleTimer = setTimeout(() => commitTyping(), IDLE_COMMIT_MS);
- };
+ // Operations queue up while one is in flight; queued typing merges.
+ type Queued = { ops: EditOp[]; group?: string };
+ const queue: Queued[] = [];
+ let pumping = false;
- const rebuild = (bytes: Uint8Array) => {
- const previous = editor();
- const scrollParent = options.scroller?.();
- const scrollTop = scrollParent?.scrollTop ?? 0;
- previous?.close();
- const next = options.runtime.module.DocxEditor.open(
- freshHost(),
- bytes,
- exports,
- editorOptions()
- );
- setEditor(next);
- if (scrollParent) scrollParent.scrollTop = scrollTop;
- };
+ function coalesce(): Queued | undefined {
+ const first = queue.shift();
+ if (!first) return undefined;
+ const typing = (q: Queued) =>
+ q.group === 'typing' &&
+ q.ops.length === 1 &&
+ q.ops[0].op === 'insertText';
+ if (!typing(first)) return first;
+ let text = (first.ops[0] as { text: string }).text;
+ while (queue.length && typing(queue[0])) {
+ text += (queue.shift()!.ops[0] as { text: string }).text;
+ }
+ return { ops: [{ op: 'insertText', text }], group: 'typing' };
+ }
- const applyRemote = () => {
- if (!controller || disposed) return;
- applying = true;
+ async function pump() {
+ if (pumping) return;
+ pumping = true;
try {
- controller.applyRemote();
- } catch (error) {
- options.onError?.(error);
+ for (let next = coalesce(); next; next = coalesce()) {
+ if (disposed) return;
+ try {
+ const result = collab
+ ? await collab.apply(next.ops, next.group)
+ : await engine.applyOps(docKey, next.ops, next.group);
+ take(result);
+ } catch (error) {
+ options.onError?.(error);
+ }
+ }
} finally {
- applying = false;
+ pumping = false;
}
- bump();
- };
+ }
- async function mount(element: HTMLElement) {
- container = element;
- container.setAttribute('data-docx-editor', rootId);
- container.addEventListener('input', onInput);
- // Capture, so this runs before the block's own shortcut handling.
- container.addEventListener('keydown', onKeyDown, true);
- const bytes = options.doc
- ? assemblePackage(readDocxState(options.doc))
- : options.original;
- if (!bytes) throw new Error('No document to open');
- const opened = await options.runtime.module.DocxEditor.openAsync(
- freshHost(),
- bytes,
- exports,
- editorOptions()
+ /** Runs operations after any already queued. */
+ function run(ops: EditOp[], group?: string) {
+ if (!ready() && ops.some((op) => op.op !== 'select')) return;
+ const editing = ops.some(
+ (op) =>
+ ![
+ 'select',
+ 'move',
+ 'selectAll',
+ 'selectWord',
+ 'selectParagraph',
+ ].includes(op.op)
);
- if (disposed) {
- opened.close();
+ if (editing && !options.editable) return;
+ queue.push({ ops, group });
+ void pump();
+ }
+
+ async function undo() {
+ if (collab) {
+ collab.undo();
return;
}
- setEditor(opened);
- if (options.doc) {
- controller = new DocxSyncController(options.doc, {
- engine: () => engine,
- refresh: () => editor()?.refresh(),
- rebuild,
- isBusy,
- });
- unsubscribeRemote = options.subscribeRemote?.(applyRemote);
- // Changes that arrived while the editor was mounting.
- applyRemote();
+ take(await engine.undo(docKey));
+ }
+
+ async function redo() {
+ if (collab) {
+ collab.redo();
+ return;
}
- bump();
+ take(await engine.redo(docKey));
}
- const onHide = () => {
- if (document.visibilityState === 'hidden') publish();
- };
- document.addEventListener('visibilitychange', onHide);
+ async function setMarkup(next: boolean) {
+ setMarkupSignal(next);
+ take(await engine.setMarkup(docKey, next));
+ }
+
+ open().catch((error: unknown) => options.onError?.(error));
onCleanup(() => {
- publish();
disposed = true;
- unsubscribeRemote?.();
- clearTimeout(idleTimer);
- document.removeEventListener('visibilitychange', onHide);
- container?.removeEventListener('input', onInput);
- container?.removeEventListener('keydown', onKeyDown, true);
- editor()?.close();
+ stopMigrationWatch?.();
+ collab?.dispose();
+ renderer.dispose();
+ void engine.closeDocument(docKey).catch(() => {});
});
return {
- editor,
+ docKey,
+ ready,
+ pages,
+ state,
revision,
- mount,
- flush: publish,
- undo: () => step('undo'),
- redo: () => step('redo'),
- save: () => editor()?.save(),
+ styles,
+ zoom,
+ setZoom(next: number) {
+ if (Math.abs(next - zoom()) < 0.001) return;
+ setZoom(next);
+ renderer.invalidate();
+ },
+ markup,
+ setMarkup,
+ renderer,
+ run,
+ undo,
+ redo,
+ canUndo: () => (collab ? collab.canUndo() : !!state()?.format.canUndo),
+ canRedo: () => (collab ? collab.canRedo() : !!state()?.format.canRedo),
+ hitTest: (page: number, x: number, y: number) =>
+ engine.hitTest(docKey, page, x, y),
+ caretAt: (pos: Pos) => engine.caretAt(docKey, pos),
+ rangeRects: (from: Pos, to: Pos) => engine.rangeRects(docKey, from, to),
+ paragraphs: () => engine.paragraphs(docKey),
+ /** The comments stored in the document (Word's). */
+ documentComments: () => engine.documentComments(docKey),
+ selectedText: () => engine.selectedText(docKey),
+ /** The matches of a search in the body, with their highlights. */
+ find: (query: string, findOptions: FindOptions) =>
+ engine.find(docKey, query, findOptions),
+ /** The selection for the clipboard (paragraphs, HTML and text). */
+ copySelection: () => engine.copySelection(docKey),
+ save: () => engine.saveDocument(docKey),
+ /** Waits until queued operations and remote changes are applied. */
+ async idle() {
+ while (pumping || queue.length)
+ await new Promise((r) => setTimeout(r, 5));
+ await collab?.idle();
+ },
};
}
+
+export type DocxEditor = ReturnType<typeof createDocxEditor>;
diff --git a/apps/web/src/features/block-write/primitives/create-docx-find.ts b/apps/web/src/features/block-write/primitives/create-docx-find.ts
new file mode 100644
index 0000000000..b87fca15c5
--- /dev/null
+++ b/apps/web/src/features/block-write/primitives/create-docx-find.ts
@@ -0,0 +1,234 @@
+import type {
+ EditOp,
+ FindMatch,
+ FindOptions,
+ FindResult,
+ Pos,
+} from '@core/docx-engine/types';
+import {
+ type Accessor,
+ batch,
+ createEffect,
+ createSignal,
+ on,
+ onCleanup,
+} from 'solid-js';
+
+export type DocxFindDeps = {
+ /** Searches the document. */
+ search: (query: string, options: FindOptions) => Promise<FindResult>;
+ /** The selected text, to search for when the bar opens. */
+ selectedText: () => Promise<string>;
+ /** Bumps whenever the document's content changes. */
+ revision: Accessor<number>;
+ /** Runs edit operations in the document. */
+ run: (ops: EditOp[]) => void;
+ /** Scrolls a match into view. */
+ reveal: (match: FindMatch) => void;
+};
+
+const samePlace = (a: Pos, b: Pos) =>
+ a.block === b.block && a.offset === b.offset;
+
+/**
+ * Find and replace for a DOCX editor: the query and options, the matches
+ * the engine found (searched again whenever the document changes) and the
+ * current one. Moving between matches selects them in the document, so
+ * the editor's selection is where a replace happens and where editing
+ * continues once the bar closes.
+ */
+export function createDocxFind(deps: DocxFindDeps) {
+ const [open, setOpen] = createSignal(false);
+ const [replacing, setReplacing] = createSignal(false);
+ const [query, setQuerySignal] = createSignal('');
+ const [replacement, setReplacement] = createSignal('');
+ const [matchCase, setMatchCase] = createSignal(false);
+ const [wholeWord, setWholeWord] = createSignal(false);
+ const [result, setResult] = createSignal<FindResult>({ matches: [] });
+ const [current, setCurrent] = createSignal<number>();
+ /** What the last replace all did, until the query changes. */
+ const [replaced, setReplaced] = createSignal<number>();
+ /** Bumps to ask the bar to focus (and select) its search field. */
+ const [focusRequest, setFocusRequest] = createSignal(0);
+
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ let token = 0;
+ /** The next result takes its current match from the selection. */
+ let followSelection = false;
+ onCleanup(() => clearTimeout(timer));
+
+ const options = (): FindOptions => ({
+ matchCase: matchCase(),
+ wholeWord: wholeWord(),
+ });
+
+ const matches = () => result().matches;
+ const currentMatch = () => {
+ const index = current();
+ return index === undefined ? undefined : matches()[index];
+ };
+
+ /** Searches after `delay` ms; `reveal` scrolls to the current match. */
+ function search(delay: number, reveal: boolean) {
+ clearTimeout(timer);
+ const mine = ++token;
+ if (!open() || !query()) {
+ batch(() => {
+ setResult({ matches: [] });
+ setCurrent(undefined);
+ });
+ return;
+ }
+ timer = setTimeout(() => {
+ const previous = currentMatch();
+ deps
+ .search(query(), options())
+ .then((next) => {
+ if (mine !== token) return;
+ // Stay on the match being looked at while the document changes,
+ // unless a replace moved the selection on.
+ const kept =
+ previous && !followSelection
+ ? next.matches.findIndex((m) => samePlace(m.from, previous.from))
+ : -1;
+ followSelection = false;
+ const index = kept >= 0 ? kept : next.current;
+ batch(() => {
+ setResult(next);
+ setCurrent(index);
+ });
+ const match = index === undefined ? undefined : next.matches[index];
+ if (reveal && match) deps.reveal(match);
+ })
+ .catch(() => {});
+ }, delay);
+ }
+
+ // The engine holds the text: search it again after every change, from
+ // this editor or from others.
+ createEffect(
+ on(
+ deps.revision,
+ () => {
+ if (open() && query()) search(200, false);
+ },
+ { defer: true }
+ )
+ );
+
+ /** Moves to a match and selects it in the document. */
+ function go(index: number) {
+ const match = matches()[index];
+ if (!match) return;
+ setCurrent(index);
+ deps.run([{ op: 'select', anchor: match.from, focus: match.to }]);
+ deps.reveal(match);
+ }
+
+ return {
+ open,
+ replacing,
+ query,
+ replacement,
+ matchCase,
+ wholeWord,
+ matches,
+ current,
+ currentMatch,
+ truncated: () => !!result().truncated,
+ replaced,
+ focusRequest,
+ /** Opens the bar (with the replace field), searching for the selected
+ * text when it is a short single line. */
+ show(withReplace: boolean) {
+ const wasOpen = open();
+ batch(() => {
+ setOpen(true);
+ if (withReplace) setReplacing(true);
+ setFocusRequest((n) => n + 1);
+ });
+ deps
+ .selectedText()
+ .then((text) => {
+ if (text && text.length <= 200 && !/[\n\r]/.test(text)) {
+ setReplaced(undefined);
+ setQuerySignal(text);
+ search(0, true);
+ } else if (!wasOpen) search(0, true);
+ })
+ .catch(() => {});
+ },
+ /** Closes the bar; the current match stays selected. */
+ close() {
+ clearTimeout(timer);
+ token++;
+ batch(() => {
+ setOpen(false);
+ setReplacing(false);
+ setResult({ matches: [] });
+ setCurrent(undefined);
+ setReplaced(undefined);
+ });
+ },
+ setReplacing,
+ setQuery(next: string) {
+ setReplaced(undefined);
+ setQuerySignal(next);
+ search(120, true);
+ },
+ setReplacement,
+ toggleMatchCase() {
+ setMatchCase((v) => !v);
+ search(0, true);
+ },
+ toggleWholeWord() {
+ setWholeWord((v) => !v);
+ search(0, true);
+ },
+ next() {
+ const n = matches().length;
+ if (!n) return;
+ const index = current();
+ go(index === undefined ? 0 : (index + 1) % n);
+ },
+ previous() {
+ const n = matches().length;
+ if (!n) return;
+ const index = current();
+ go(index === undefined ? n - 1 : (index - 1 + n) % n);
+ },
+ /** Replaces the current match and moves to the next one. */
+ replace(editable: boolean) {
+ const match = currentMatch();
+ if (!editable || !match) return;
+ followSelection = true;
+ deps.run([
+ { op: 'select', anchor: match.from, focus: match.to },
+ {
+ op: 'replace',
+ query: query(),
+ options: options(),
+ with: replacement(),
+ },
+ ]);
+ },
+ /** Replaces every match. */
+ replaceAll(editable: boolean) {
+ const count = matches().length;
+ if (!editable || !count) return;
+ followSelection = true;
+ setReplaced(count);
+ deps.run([
+ {
+ op: 'replace',
+ query: query(),
+ options: options(),
+ with: replacement(),
+ all: true,
+ },
+ ]);
+ },
+ };
+}
+
+export type DocxFind = ReturnType<typeof createDocxFind>;
diff --git a/apps/web/src/features/block-write/primitives/create-page-renderer.test.ts b/apps/web/src/features/block-write/primitives/create-page-renderer.test.ts
new file mode 100644
index 0000000000..0cf16b4aca
--- /dev/null
+++ b/apps/web/src/features/block-write/primitives/create-page-renderer.test.ts
@@ -0,0 +1,99 @@
+import type { Band, PageInfo } from '@core/docx-engine/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+type Call = {
+ kind: 'page' | 'band';
+ resolve: () => void;
+};
+const calls: Call[] = [];
+
+function bitmap() {
+ return { width: 10, height: 10, close: () => {} };
+}
+
+vi.mock('@core/docx-engine/client', () => ({
+ renderPage: () =>
+ new Promise((resolve) => {
+ calls.push({
+ kind: 'page',
+ resolve: () => resolve({ bitmap: bitmap() }),
+ });
+ }),
+ renderBand: () =>
+ new Promise((resolve) => {
+ calls.push({
+ kind: 'band',
+ resolve: () => resolve({ bitmap: bitmap() }),
+ });
+ }),
+}));
+
+const { createPageRenderer } = await import('./create-page-renderer');
+
+const page = (fingerprint: string) =>
+ ({ width: 600, height: 800, fingerprint }) as PageInfo;
+const band = (top: number): Band => ({ page: 0, top, bottom: top + 10 });
+
+function canvas() {
+ return {
+ width: 0,
+ height: 0,
+ getContext: () => ({ drawImage: () => {} }),
+ } as unknown as HTMLCanvasElement;
+}
+
+/** Lets the renderer's promise chain run. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('createPageRenderer', () => {
+ beforeEach(() => {
+ calls.length = 0;
+ });
+
+ it('draws strips that arrive while a strip render is in flight', async () => {
+ const renderer = createPageRenderer({ docKey: 'd', scale: () => 1 });
+ renderer.update([page('a')]);
+ renderer.attach(0, canvas());
+ renderer.setVisible(0, true);
+ calls.shift()?.resolve();
+ await settle();
+
+ renderer.update([page('b')], [band(0)]);
+ expect(calls.map((c) => c.kind)).toEqual(['band']);
+ // Typing goes on while that strip is drawn.
+ renderer.update([page('c')], [band(20)]);
+ calls.shift()?.resolve();
+ await settle();
+ // The later strip is drawn next, not dropped.
+ expect(calls.map((c) => c.kind)).toEqual(['band']);
+ calls.shift()?.resolve();
+ await settle();
+ expect(calls).toEqual([]);
+ });
+
+ it('redraws when the page is invalidated during a render', async () => {
+ const renderer = createPageRenderer({ docKey: 'd', scale: () => 1 });
+ renderer.update([page('a')]);
+ renderer.attach(0, canvas());
+ renderer.setVisible(0, true);
+ renderer.invalidate();
+ calls.shift()?.resolve();
+ await settle();
+ // The first render is stale, so the page is drawn again.
+ expect(calls.map((c) => c.kind)).toEqual(['page']);
+ calls.shift()?.resolve();
+ await settle();
+ expect(calls).toEqual([]);
+ });
+
+ it('redraws a page that changed size while it was being drawn', async () => {
+ const renderer = createPageRenderer({ docKey: 'd', scale: () => 1 });
+ renderer.update([page('a')]);
+ renderer.attach(0, canvas());
+ renderer.setVisible(0, true);
+ renderer.update([{ ...page('b'), height: 900 }]);
+ calls.shift()?.resolve();
+ await settle();
+ expect(calls.map((c) => c.kind)).toEqual(['page']);
+ });
+});
diff --git a/apps/web/src/features/block-write/primitives/create-page-renderer.ts b/apps/web/src/features/block-write/primitives/create-page-renderer.ts
new file mode 100644
index 0000000000..cd5091f35a
--- /dev/null
+++ b/apps/web/src/features/block-write/primitives/create-page-renderer.ts
@@ -0,0 +1,214 @@
+import {
+ type Rendered,
+ renderBand,
+ renderPage,
+} from '@core/docx-engine/client';
+import type { Band, PageInfo } from '@core/docx-engine/types';
+
+/** The most pixels per CSS pixel a page is drawn with. */
+const MAX_DPR = 2;
+
+type PageState = {
+ canvas?: HTMLCanvasElement;
+ visible: boolean;
+ /** Fingerprint of what the canvas shows (`undefined` = nothing yet). */
+ shown?: string;
+ /** Canvas pixel width it was drawn at. */
+ width?: number;
+ /** Strips to redraw to reach the latest fingerprint. */
+ bands: Band[];
+ /** Fingerprint of a render in flight; strips that arrive meanwhile go
+ * on top of it. */
+ drawing?: string;
+ /** Bumps whenever the drawn content is thrown away, so a render in
+ * flight does not mark a stale result as shown. */
+ stamp: number;
+};
+
+/**
+ * Draws pages into canvases on demand: visible pages first, one engine
+ * render at a time so edits and hit tests never wait behind a burst of
+ * renders, and only the changed strips of a page after an edit.
+ */
+export function createPageRenderer(options: {
+ docKey: string;
+ /** CSS pixels per point. */
+ scale: () => number;
+ onError?: (error: unknown) => void;
+}) {
+ const states = new Map<number, PageState>();
+ let pages: PageInfo[] = [];
+ let busy = false;
+ let disposed = false;
+
+ const state = (index: number): PageState => {
+ let s = states.get(index);
+ if (!s) {
+ s = { visible: false, bands: [], stamp: 0 };
+ states.set(index, s);
+ }
+ return s;
+ };
+
+ const dpr = () =>
+ Math.min(
+ MAX_DPR,
+ typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1
+ );
+
+ /** Canvas size in pixels for a page at the current zoom. */
+ const pixelWidth = (page: PageInfo) =>
+ Math.max(16, Math.round(page.width * options.scale() * dpr()));
+ const pixelHeight = (page: PageInfo) =>
+ Math.max(16, Math.round(page.height * options.scale() * dpr()));
+
+ /** Whether a page needs a full redraw. */
+ const stale = (index: number) => {
+ const s = states.get(index);
+ const page = pages[index];
+ if (!s?.canvas || !page) return false;
+ return s.shown === undefined || s.width !== pixelWidth(page);
+ };
+
+ function nextJob(): { index: number; band?: Band[] } | undefined {
+ const candidates = [...states.entries()]
+ .filter(([, s]) => s.visible && s.canvas)
+ .map(([index]) => index)
+ .sort((a, b) => a - b);
+ for (const index of candidates) if (stale(index)) return { index };
+ for (const index of candidates) {
+ const s = states.get(index);
+ if (s?.bands.length) return { index, band: s.bands };
+ }
+ return undefined;
+ }
+
+ async function draw(index: number, bands?: Band[]) {
+ const s = state(index);
+ const page = pages[index];
+ const canvas = s.canvas;
+ if (!page || !canvas) return;
+ const width = pixelWidth(page);
+ const target = page.fingerprint;
+ const stamp = s.stamp;
+ s.drawing = target;
+ s.bands = [];
+ try {
+ if (!bands) {
+ const out: Rendered = await renderPage(options.docKey, index, width);
+ if (disposed || s.canvas !== canvas || s.stamp !== stamp)
+ return out.bitmap.close();
+ canvas.width = out.bitmap.width;
+ canvas.height = out.bitmap.height;
+ canvas.getContext('2d')?.drawImage(out.bitmap, 0, 0);
+ out.bitmap.close();
+ s.width = width;
+ } else {
+ // One strip covering every changed band of the page.
+ const top = Math.min(...bands.map((b) => b.top));
+ const bottom = Math.max(...bands.map((b) => b.bottom));
+ const out = await renderBand(options.docKey, index, width, top, bottom);
+ if (disposed || s.canvas !== canvas || s.stamp !== stamp)
+ return out.bitmap.close();
+ const perPoint = width / page.width;
+ canvas
+ .getContext('2d')
+ ?.drawImage(out.bitmap, 0, Math.round(top * perPoint));
+ out.bitmap.close();
+ }
+ // Strips that arrived meanwhile (in `s.bands`) take it the rest of
+ // the way.
+ s.shown = target;
+ } finally {
+ s.drawing = undefined;
+ }
+ }
+
+ /** Throws away what a page shows, so it is drawn afresh. */
+ function discard(s: PageState) {
+ s.shown = undefined;
+ s.bands = [];
+ s.stamp++;
+ }
+
+ async function pump() {
+ if (busy || disposed) return;
+ const job = nextJob();
+ if (!job) return;
+ busy = true;
+ try {
+ await draw(job.index, job.band);
+ } catch (error) {
+ options.onError?.(error);
+ const s = states.get(job.index);
+ if (s) discard(s);
+ } finally {
+ busy = false;
+ }
+ void pump();
+ }
+
+ return {
+ /** The size a page's canvas element should take (CSS pixels). */
+ cssSize(page: PageInfo) {
+ return {
+ width: page.width * options.scale(),
+ height: page.height * options.scale(),
+ };
+ },
+ /** New page list (and the strips that changed since the last one). */
+ update(next: PageInfo[], bands: Band[] = []) {
+ const previous = pages;
+ pages = next;
+ for (const [index, s] of states) {
+ const page = next[index];
+ if (!page) {
+ discard(s);
+ continue;
+ }
+ const before = previous[index];
+ // What the canvas shows, or will once the render in flight lands.
+ const base = s.drawing ?? s.shown;
+ if (base === undefined || page.fingerprint === base) continue;
+ const sameSize =
+ before &&
+ before.width === page.width &&
+ before.height === page.height;
+ const strips = bands.filter((b) => b.page === index);
+ if (sameSize && strips.length && base === before?.fingerprint) {
+ s.bands.push(...strips);
+ } else if (sameSize && strips.length && s.bands.length) {
+ // Already behind by some strips: these go with them.
+ s.bands.push(...strips);
+ } else {
+ discard(s);
+ }
+ }
+ void pump();
+ },
+ /** Gives a page its canvas (or takes it away when it scrolls off). */
+ attach(index: number, canvas: HTMLCanvasElement | undefined) {
+ const s = state(index);
+ s.canvas = canvas;
+ if (!canvas) discard(s);
+ void pump();
+ },
+ setVisible(index: number, visible: boolean) {
+ state(index).visible = visible;
+ if (visible) void pump();
+ },
+ /** Redraws everything (after a zoom change). */
+ invalidate() {
+ for (const s of states.values()) discard(s);
+ void pump();
+ },
+ pixelWidth,
+ pixelHeight,
+ dispose() {
+ disposed = true;
+ states.clear();
+ },
+ };
+}
+
+export type PageRenderer = ReturnType<typeof createPageRenderer>;
diff --git a/apps/web/src/features/block-write/queries/docx-document.ts b/apps/web/src/features/block-write/queries/docx-document.ts
index a5c0a145ca..5b32ca99cd 100644
--- a/apps/web/src/features/block-write/queries/docx-document.ts
+++ b/apps/web/src/features/block-write/queries/docx-document.ts
@@ -5,7 +5,6 @@ import { createSyncServiceSource } from '@service-sync/source';
import type { DocumentSyncAuthorization } from '@service-sync/source/authorization';
import { buildSeedSnapshot } from '../core/docx-seed';
import type { DocxConnection } from './docx-session';
-import { loadDocxodus } from './docxodus-runtime';
const docxKeys = {
original: (documentId: string) => ['docx', 'original', documentId] as const,
@@ -39,9 +38,8 @@ export async function initializeDocxSync(
if (result.isErr()) throw new Error('Unable to initialize collaboration.');
}
-export async function buildDocxSeed(original: Uint8Array): Promise<Uint8Array> {
- const runtime = await loadDocxodus();
- return buildSeedSnapshot(runtime.exports.DocxSessionBridge, original);
+export function buildDocxSeed(original: Uint8Array): Promise<Uint8Array> {
+ return buildSeedSnapshot(original);
}
export function connectDocxSync(
diff --git a/apps/web/src/features/block-write/queries/docx-session.ts b/apps/web/src/features/block-write/queries/docx-session.ts
index e7a8e0dd57..b26de24962 100644
--- a/apps/web/src/features/block-write/queries/docx-session.ts
+++ b/apps/web/src/features/block-write/queries/docx-session.ts
@@ -1,7 +1,10 @@
import { createAwareness } from '@macro-inc/collaboration/collab/awareness';
import type { Chatter } from '@macro-inc/collaboration/collab/chatter';
import { createSyncEngine } from '@macro-inc/collaboration/collab/engine';
-import { LoroManager } from '@macro-inc/collaboration/collab/manager';
+import {
+ LoroManager,
+ LoroManagerError,
+} from '@macro-inc/collaboration/collab/manager';
import {
IDBSnapshotStore,
LORO_SNAPSHOT_DB_NAME,
@@ -21,15 +24,15 @@ import {
type WALStore,
WALSyncer,
} from '@macro-inc/collaboration/collab/wal';
-import {
- DOCX_FORMAT_VERSION,
- docxFormatVersion,
- isDocxSeeded,
-} from '@macro-inc/collaboration/docx/schema';
import type { LoroDoc } from 'loro-crdt';
import { errAsync, type ResultAsync } from 'neverthrow';
import { type Accessor, createSignal, onCleanup } from 'solid-js';
import { match } from 'ts-pattern';
+import {
+ DOCX_FORMAT_VERSION,
+ docxFormatVersion,
+ isDocxSeeded,
+} from '../core/docx-loro';
import { DOCX_LORO_SCHEMA } from '../core/docx-loro-schema';
/** Where a collaborator's caret is: a paragraph and an offset in its text. */
@@ -104,6 +107,9 @@ function isSelection(value: unknown): value is DocxSelection {
export function createDocxSession(options: DocxSessionOptions): DocxSession {
const manager = new LoroManager(DOCX_LORO_SCHEMA, {
documentId: options.documentId,
+ // The editor reads the document directly; a JSON mirror of it would be
+ // rebuilt on every keystroke.
+ mirror: false,
});
const snapshots =
options.persistence?.snapshots ??
@@ -228,7 +234,18 @@ export function createDocxSession(options: DocxSessionOptions): DocxSession {
? manager.importUpdate(initial.snapshot)
: await manager.initializeFromSnapshot(initial.snapshot);
if (disposed) return;
- if (result.isErr()) {
+ // Changes that arrive ahead of their history wait in the document until
+ // the sync engine's catch-up request brings the rest; only a copy with
+ // nothing to show yet cannot go on without them.
+ const failed = result.isErr()
+ ? result.error.filter(
+ (error) =>
+ !manager.initialized ||
+ error.code !== LoroManagerError.ImportPending
+ )
+ : [];
+ if (failed.length) {
+ console.error('DOCX snapshot import failed', failed);
setState({ t: 'error', message: 'This document could not be opened.' });
return;
}
diff --git a/apps/web/src/features/block-write/queries/docxodus-runtime.ts b/apps/web/src/features/block-write/queries/docxodus-runtime.ts
deleted file mode 100644
index f6561fa3b6..0000000000
--- a/apps/web/src/features/block-write/queries/docxodus-runtime.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import type { DocxEditorExports } from 'docxodus';
-
-type DocxodusModule = typeof import('docxodus');
-
-export type DocxodusRuntime = {
- module: DocxodusModule;
- /** Raw engine exports, shared by every editor on the page. */
- exports: ReturnType<DocxodusModule['getWasmExports']>;
-};
-
-let loading: Promise<DocxodusRuntime> | undefined;
-
-/** Where the build serves the runtime (see `scripts/docxodus-runtime.ts`). */
-export function docxodusRuntimeBase(): string {
- const version = import.meta.env.DOCXODUS_VERSION;
- if (!version) throw new Error('This build does not serve the DOCX engine.');
- return `${import.meta.env.BASE_URL.replace(/\/?$/, '/')}docxodus/${version}/`;
-}
-
-/**
- * Load the Docxodus editor and its WebAssembly engine once per page.
- * Assemblies stream in and compile off the main thread; nothing is fetched
- * until a DOCX is opened.
- */
-export function loadDocxodus(): Promise<DocxodusRuntime> {
- loading ??= (async () => {
- const module = await import('docxodus');
- await module.initialize(docxodusRuntimeBase());
- return { module, exports: module.getWasmExports() };
- })().catch((error: unknown) => {
- loading = undefined;
- throw error;
- });
- return loading;
-}
-
-export type { DocxEditorExports };
diff --git a/apps/web/src/features/block-write/tests/docx-test-peer.ts b/apps/web/src/features/block-write/tests/docx-test-peer.ts
deleted file mode 100644
index 61fbd9b33e..0000000000
--- a/apps/web/src/features/block-write/tests/docx-test-peer.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-import { readFileSync } from 'node:fs';
-import {
- readDocxState,
- seedDocxState,
-} from '@macro-inc/collaboration/docx/schema';
-import { getWasmExports, initialize } from 'docxodus/core';
-import { LoroDoc } from 'loro-crdt';
-import { bridgeEngine, type DocxEngine } from '../core/docx-engine';
-import { assemblePackage } from '../core/docx-package';
-import { DocxSyncController } from '../core/docx-sync';
-
-/** Session settings the collaborative editor opens every session with. */
-export const SYNC_SESSION_SETTINGS = JSON.stringify({
- emitMarkdownPatch: false,
- validateRawOps: false,
-});
-
-export function fixture(name: string): Uint8Array {
- return new Uint8Array(
- readFileSync(new URL(`../core/fixtures/${name}`, import.meta.url))
- );
-}
-
-let ready: Promise<void> | undefined;
-/** Boot the Node build of the Docxodus engine once per test file. */
-export function loadEngine() {
- ready ??= initialize();
- return ready;
-}
-
-type Bridge = ReturnType<typeof getWasmExports>['DocxSessionBridge'];
-
-export function bridge(): Bridge {
- return getWasmExports().DocxSessionBridge;
-}
-
-/**
- * One collaborator: a live engine session and a Loro replica. Updates are
- * queued rather than delivered so tests choose when peers see each other.
- */
-export class TestPeer {
- readonly doc = new LoroDoc();
- handle: number;
- readonly engine: DocxEngine;
- readonly sync: DocxSyncController;
- rebuilds = 0;
- private readonly outbox: Uint8Array[] = [];
-
- constructor(bytes: Uint8Array, seed?: Uint8Array) {
- if (seed) this.doc.import(seed);
- this.doc.subscribeLocalUpdates((update) => this.outbox.push(update));
- const opening = seed ? assemblePackage(readDocxState(this.doc)) : bytes;
- this.handle = bridge().OpenSession(opening, SYNC_SESSION_SETTINGS);
- this.engine = bridgeEngine(bridge(), () => this.handle);
- if (!seed) seedDocxState(this.doc, this.engine.snapshot());
- this.sync = new DocxSyncController(this.doc, {
- engine: () => this.engine,
- refresh: () => {},
- rebuild: (next) => {
- this.rebuilds++;
- bridge().CloseSession(this.handle);
- this.handle = bridge().OpenSession(next, SYNC_SESSION_SETTINGS);
- },
- });
- }
-
- /** Hand every queued update to `others` and apply them there. */
- deliver(...others: TestPeer[]) {
- const updates = this.outbox.splice(0);
- for (const other of others) {
- for (const update of updates) other.doc.import(update);
- other.sync.applyRemote();
- }
- }
-
- bodyIds(): string[] {
- return (
- JSON.parse(bridge().ListBlocks!(this.handle)) as {
- body: Array<{ id: string }>;
- }
- ).body.map((unit) => unit.id);
- }
-
- /** The run text of every body block, in order. */
- text(): string[] {
- return this.bodyIds().map((id) => this.blockText(id));
- }
-
- blockText(anchor: string): string {
- return xmlText(bridge().RawGetXml(this.handle, anchor));
- }
-
- close() {
- bridge().CloseSession(this.handle);
- }
-}
-
-/** Concatenated `w:t` text of an element. */
-export function xmlText(xml: string): string {
- return [...xml.matchAll(/<w:t(?:\s[^>]*)?>([^<]*)<\/w:t>/g)]
- .map((match) =>
- match[1]
- .replaceAll('&lt;', '<')
- .replaceAll('&gt;', '>')
- .replaceAll('&quot;', '"')
- .replaceAll('&apos;', "'")
- .replaceAll('&amp;', '&')
- )
- .join('');
-}
diff --git a/apps/web/src/features/block-write/views/DocxCollaborators.tsx b/apps/web/src/features/block-write/views/DocxCollaborators.tsx
index 4cdff67a3f..bc7ed5674b 100644
--- a/apps/web/src/features/block-write/views/DocxCollaborators.tsx
+++ b/apps/web/src/features/block-write/views/DocxCollaborators.tsx
@@ -1,80 +1,93 @@
-import { type Accessor, createMemo, For, Show } from 'solid-js';
-import { caretRange } from '../core/text-offsets';
+import type { CaretRect, Pos } from '@core/docx-engine/types';
+import {
+ type Accessor,
+ createEffect,
+ createSignal,
+ For,
+ on,
+ Show,
+} from 'solid-js';
import type { DocxPeer } from '../queries/docx-session';
+import { type PageGeometry, toColumn } from './DocxPages';
-type Caret = {
- peer: DocxPeer;
- name: string;
- top: number;
- left: number;
- height: number;
-};
+type Caret = { peer: DocxPeer; name: string; caret: CaretRect };
-/** Where each collaborator's caret is, drawn over the document. */
+/** Where each collaborator's caret is, drawn over the pages. */
export function DocxCollaboratorCarets(props: {
peers: DocxPeer[];
- editorRoot: HTMLElement | undefined;
- /** Positioning parent of the overlay. */
- overlay: HTMLElement | undefined;
+ geometry: Accessor<PageGeometry>;
+ /** Bumps when the document changed (carets move with the text). */
revision: Accessor<number>;
+ caretAt: (pos: Pos) => Promise<CaretRect | null>;
displayName: (userId: string | undefined) => string;
}) {
- const carets = createMemo<Caret[]>(() => {
- props.revision();
- const root = props.editorRoot;
- const overlay = props.overlay;
- if (!root || !overlay) return [];
- const origin = overlay.getBoundingClientRect();
- return props.peers.flatMap((peer) => {
- const block = root.querySelector<HTMLElement>(
- `[data-anchor="${CSS.escape(peer.selection.block)}"]`
- );
- if (!block) return [];
- const range = caretRange(block, peer.selection.offset);
- const rect =
- range?.getClientRects()[0] ??
- range?.getBoundingClientRect() ??
- block.getBoundingClientRect();
- const fallback = block.getBoundingClientRect();
- const height = rect.height || Math.min(fallback.height, 20);
- return [
- {
- peer,
- name: props.displayName(peer.userId),
- top: (rect.height ? rect.top : fallback.top) - origin.top,
- left: (rect.height ? rect.left : fallback.left) - origin.left,
- height,
- },
- ];
- });
- });
+ const [carets, setCarets] = createSignal<Caret[]>([]);
+ let generation = 0;
+ // Caret geometry comes from the engine in the worker.
+ createEffect(
+ on([() => props.peers, props.revision], ([peers]) => {
+ const current = ++generation;
+ Promise.all(
+ peers.map(async (peer) => {
+ const caret = await props.caretAt({
+ block: peer.selection.block,
+ offset: peer.selection.offset,
+ });
+ return caret
+ ? [{ peer, name: props.displayName(peer.userId), caret }]
+ : [];
+ })
+ )
+ .then((found) => {
+ if (current === generation) setCarets(found.flat());
+ })
+ .catch(() => {});
+ })
+ );
return (
<For each={carets()}>
- {(caret) => (
- <div
- class="pointer-events-none absolute z-10"
- data-docx-peer={caret.peer.peerId}
- style={{
- top: `${caret.top}px`,
- left: `${caret.left}px`,
- height: `${caret.height}px`,
- }}
- >
- <div
- class="h-full w-0.5"
- style={{ 'background-color': caret.peer.color }}
- />
- <Show when={caret.name}>
- <div
- class="absolute bottom-full left-0 whitespace-nowrap rounded-sm px-1 py-px text-[10px] font-medium leading-tight"
- style={{ 'background-color': caret.peer.color, color: '#fff' }}
- >
- {caret.name}
- </div>
+ {(entry) => {
+ const box = () =>
+ toColumn(props.geometry(), {
+ page: entry.caret.page,
+ x: entry.caret.x,
+ y: entry.caret.y,
+ w: 0,
+ h: entry.caret.height,
+ });
+ return (
+ <Show when={box()}>
+ {(b) => (
+ <div
+ class="pointer-events-none absolute z-10"
+ data-docx-peer={entry.peer.peerId}
+ style={{
+ top: `${b().top}px`,
+ left: `${b().left}px`,
+ height: `${b().height}px`,
+ }}
+ >
+ <div
+ class="h-full w-0.5"
+ style={{ 'background-color': entry.peer.color }}
+ />
+ <Show when={entry.name}>
+ <div
+ class="absolute bottom-full left-0 whitespace-nowrap rounded-sm px-1 py-px text-[10px] font-medium leading-tight"
+ style={{
+ 'background-color': entry.peer.color,
+ color: '#fff',
+ }}
+ >
+ {entry.name}
+ </div>
+ </Show>
+ </div>
+ )}
</Show>
- </div>
- )}
+ );
+ }}
</For>
);
}
diff --git a/apps/web/src/features/block-write/views/DocxComments.tsx b/apps/web/src/features/block-write/views/DocxComments.tsx
index 03e92e0397..c9ca7f5482 100644
--- a/apps/web/src/features/block-write/views/DocxComments.tsx
+++ b/apps/web/src/features/block-write/views/DocxComments.tsx
@@ -20,6 +20,7 @@ import type {
LocatedThread,
} from '../primitives/create-docx-comments';
import { DocxMarginLayout } from './DocxMarginLayout';
+import type { PageGeometry } from './DocxPages';
function toRoot(item: MessageListItem, anchorId: string): Root {
return {
@@ -57,11 +58,10 @@ function draftRoot(markId: string, userId: string): Root {
export function DocxCommentMargin(props: {
documentId: string;
comments: DocxComments;
- /** The editor element; selection and clicks are read from it. */
- editorRoot: HTMLElement | undefined;
- /** Positioning parent: the margin scrolls with the document. */
- margin: HTMLElement | undefined;
- revision: Accessor<number>;
+ /** Page geometry of the pages column the margin sits beside. */
+ geometry: Accessor<PageGeometry>;
+ /** Top of the selected text, when there is a selection to comment on. */
+ selectionTop: Accessor<number | null>;
canComment: Accessor<boolean>;
isOwner: Accessor<boolean>;
userId: Accessor<string | undefined>;
@@ -128,9 +128,8 @@ export function DocxCommentMargin(props: {
<CommentsContext.Provider value={context}>
<DocxMarginLayout
comments={props.comments}
- editorRoot={props.editorRoot}
- margin={props.margin}
- revision={props.revision}
+ geometry={props.geometry}
+ selectionTop={props.selectionTop}
canComment={props.canComment}
renderCard={(thread, isActive) => (
<ThreadCard comment={rootFor(thread)} isActive={isActive()} />
diff --git a/apps/web/src/features/block-write/views/DocxEditorView.tsx b/apps/web/src/features/block-write/views/DocxEditorView.tsx
index 9ea846c1ea..e9cf6f54cb 100644
--- a/apps/web/src/features/block-write/views/DocxEditorView.tsx
+++ b/apps/web/src/features/block-write/views/DocxEditorView.tsx
@@ -1,3 +1,4 @@
+import type { EditOp, PageRect, Pos } from '@core/docx-engine/types';
import type { MessageListItem } from '@service-storage/messages';
import type { LoroDoc } from 'loro-crdt';
import {
@@ -5,66 +6,66 @@ import {
createEffect,
createMemo,
createSignal,
+ For,
type JSX,
onCleanup,
- onMount,
Show,
} from 'solid-js';
+import { match } from 'ts-pattern';
+import { DocxFindBar } from '../components/DocxFindBar';
import {
type DocxAlignment,
- type DocxInlineFormat,
type DocxParagraphStyle,
+ type DocxTableOp,
DocxToolbar,
} from '../components/DocxToolbar';
-import { blockOf, contentOffset } from '../core/text-offsets';
-import { createCommentHighlights } from '../primitives/create-comment-highlights';
import {
createDocxComments,
type DocxComments,
} from '../primitives/create-docx-comments';
-import { createDocxEditor } from '../primitives/create-docx-editor';
+import {
+ createDocxEditor,
+ type DocxEditor,
+ PX_PER_PT,
+} from '../primitives/create-docx-editor';
+import { createDocxFind } from '../primitives/create-docx-find';
import type { DocxPeer, DocxSelection } from '../queries/docx-session';
-import type { DocxodusRuntime } from '../queries/docxodus-runtime';
import { DocxCollaboratorCarets } from './DocxCollaborators';
+import {
+ DocxPages,
+ type PageGeometry,
+ pageGeometry,
+ toColumn,
+} from './DocxPages';
-/** A US Letter sheet at 96 dpi. */
-const PAGE_WIDTH = 816;
/** Room for a comment card (280px) and its inset beside the page. */
const MARGIN_WIDTH = 296;
-/** The narrowest the page gets beside comment cards: about 60% scale. */
+/** Horizontal padding around the pages. */
+const SIDE_PADDING = 32;
+/** The narrowest the page gets beside comment cards; narrower panes scroll. */
const PAGE_MIN_WIDTH = 480;
-/** Paragraph styles offered in the toolbar, when the document defines them. */
-const PREFERRED_STYLES = [
- 'Normal',
- 'Title',
- 'Subtitle',
- 'Heading 1',
- 'Heading 2',
- 'Heading 3',
- 'Quote',
-];
-
export type DocxMarginContext = {
comments: DocxComments;
- editorRoot: HTMLElement | undefined;
- margin: HTMLElement | undefined;
- revision: Accessor<number>;
+ geometry: Accessor<PageGeometry>;
+ /** Top of the selected text, when there is a selection to comment on. */
+ selectionTop: Accessor<number | null>;
};
export type DocxEditorViewProps = {
- runtime: DocxodusRuntime;
/** Collaborative document, or null for a read-only original. */
doc: LoroDoc | null;
original?: Uint8Array;
canEdit: boolean;
canComment: Accessor<boolean>;
- author: string;
fileName: string;
peers: Accessor<DocxPeer[]>;
displayName: (userId: string | undefined) => string;
+ /** The name this person's tracked changes are recorded under. */
+ author?: string;
+ /** The document's id (for pasting copied content back losslessly). */
+ documentId?: string;
onSelection?: (selection: DocxSelection | undefined) => void;
- subscribeRemote?: (listener: () => void) => () => void;
/** Comment roots for this document; omit to disable commenting. */
commentRoots?: Accessor<MessageListItem[]>;
/** Margin content (comment threads) laid out beside the page. */
@@ -73,129 +74,139 @@ export type DocxEditorViewProps = {
footer?: (comments: DocxComments) => JSX.Element;
onDownload: (bytes: Uint8Array) => void;
onError?: (error: unknown) => void;
- /** Test hook: the mounted editor handle. */
- onReady?: (handle: ReturnType<typeof createDocxEditor>) => void;
+ /** Test hook: the mounted editor. */
+ onReady?: (editor: DocxEditor) => void;
};
-/** The collaborative DOCX editor: toolbar, page, collaborators and comments. */
+/** The collaborative DOCX editor: toolbar, pages, collaborators and comments. */
export function DocxEditorView(props: DocxEditorViewProps) {
- let scroller!: HTMLDivElement;
- let page!: HTMLDivElement;
- const [editorRoot, setEditorRoot] = createSignal<HTMLDivElement>();
- const [margin, setMargin] = createSignal<HTMLDivElement>();
- const [loading, setLoading] = createSignal(true);
- const [format, setFormat] = createSignal<
- Partial<Record<DocxInlineFormat, boolean>>
- >({});
- const [paragraphStyle, setParagraphStyle] = createSignal<string | null>(null);
- const [trackChanges, setTrackChanges] = createSignal(false);
+ const [scroller, setScroller] = createSignal<HTMLDivElement>();
+ let input: HTMLTextAreaElement | undefined;
+ let selectionTimer: ReturnType<typeof setTimeout> | undefined;
- const handle = createDocxEditor({
- runtime: props.runtime,
+ const editor = createDocxEditor({
doc: props.doc,
original: props.original,
editable: props.canEdit,
author: props.author,
- scroller: () => scroller,
- subscribeRemote: props.subscribeRemote,
onError: props.onError,
+ onSelection: (selection) => {
+ // Presence updates are throttled; the caret moves with every key.
+ clearTimeout(selectionTimer);
+ selectionTimer = setTimeout(
+ () =>
+ props.onSelection?.(
+ selection
+ ? {
+ block: selection.focus.block,
+ offset: selection.focus.offset,
+ }
+ : undefined
+ ),
+ 80
+ );
+ },
+ });
+ onCleanup(() => clearTimeout(selectionTimer));
+
+ createEffect(() => {
+ if (editor.ready()) props.onReady?.(editor);
});
- const editor = handle.editor;
+
+ const geometry = pageGeometry(editor);
const comments = createDocxComments({
doc: props.doc,
roots: () => props.commentRoots?.() ?? [],
- root: editorRoot,
- revision: handle.revision,
+ geometry: {
+ revision: editor.revision,
+ paragraphs: editor.paragraphs,
+ documentComments: editor.documentComments,
+ rangeRects: editor.rangeRects,
+ selection: () => editor.state()?.range,
+ },
canEdit: () => props.canEdit,
});
- // The right gutter holds the comment margin. With cards or a draft showing
- // it keeps their width and the page gives way, down to a legible width
- // (narrower panes scroll sideways); otherwise it only needs room for the
- // comment button beside a selection, so the page stays centered.
- const pageColumns = () => {
- const cards =
- !!props.margin && (comments.located().length > 0 || !!comments.draft());
- const gutter = cards ? MARGIN_WIDTH : props.margin ? 48 : 0;
- const pageMin = cards ? PAGE_MIN_WIDTH : 0;
- return `minmax(0, 1fr) minmax(${pageMin}px, ${PAGE_WIDTH}px) minmax(${gutter}px, 1fr)`;
- };
- const highlightStyles = createCommentHighlights(
- comments,
- () => !!props.commentRoots
- );
-
- onMount(() => {
- const root = editorRoot();
- if (!root) return;
- handle
- .mount(root)
- .then(() => {
- setLoading(false);
- props.onReady?.(handle);
- })
- .catch((error: unknown) => {
- setLoading(false);
- props.onError?.(error);
- });
- });
+ /** Scrolls a page rectangle into view (a third of the way down). */
+ function reveal(rect: PageRect | undefined) {
+ const element = scroller();
+ const column = element?.querySelector<HTMLElement>('[data-docx-pages]');
+ const box = rect && toColumn(geometry(), rect);
+ if (!element || !column || !box) return;
+ const top =
+ column.getBoundingClientRect().top -
+ element.getBoundingClientRect().top +
+ element.scrollTop +
+ box.top;
+ const margin = 96;
+ if (
+ top < element.scrollTop + margin ||
+ top + box.height > element.scrollTop + element.clientHeight - margin
+ )
+ element.scrollTop = Math.max(0, top - element.clientHeight / 3);
+ }
- const paragraphStyles = createMemo<DocxParagraphStyle[]>(() => {
- handle.revision();
- const current = editor();
- if (!current) return [];
- const byName = new Map(
- current
- .styles()
- .filter((style) => style.type === 'paragraph')
- .map((style) => [style.name.toLowerCase(), style])
- );
- return PREFERRED_STYLES.flatMap((name) => {
- const style = byName.get(name.toLowerCase());
- return style ? [{ id: style.id, name }] : [];
- });
+ const find = createDocxFind({
+ search: (query, options) => editor.find(query, options),
+ selectedText: () => editor.selectedText(),
+ revision: editor.revision,
+ run: (ops) => editor.run(ops),
+ reveal: (match) => reveal(match.rects[0]),
});
- const refreshFormat = () => {
- const current = editor();
- if (!current) return;
- try {
- setFormat(current.queryFormatState());
- setParagraphStyle(current.styleAtCaret());
- } catch {
- // The caret is outside an editable block.
- }
+ const closeFind = () => {
+ find.close();
+ input?.focus();
};
- // Publish this user's caret and keep the toolbar state current.
+ // The right gutter holds the comment margin: with cards or a draft showing
+ // it keeps their width, otherwise only room for the comment button.
+ const showsCards = () =>
+ !!props.margin && (comments.located().length > 0 || !!comments.draft());
+ const gutter = () => (showsCards() ? MARGIN_WIDTH : 48);
+
+ // Fit the pages to the width available, never above 100%. Beside comment
+ // cards the page keeps a legible width and the pane scrolls sideways.
createEffect(() => {
- const root = editorRoot();
- if (!root) return;
- let timer: ReturnType<typeof setTimeout> | undefined;
- const onSelectionChange = () => {
- clearTimeout(timer);
- timer = setTimeout(() => {
- refreshFormat();
- const selection = window.getSelection();
- const node = selection?.focusNode;
- const block = node ? blockOf(node, root) : null;
- const id = block?.getAttribute('data-anchor');
- props.onSelection?.(
- block && id && node
- ? {
- block: id,
- offset: contentOffset(block, node, selection!.focusOffset),
- }
- : undefined
- );
- }, 80);
+ const element = scroller();
+ if (!element) return;
+ const floor = showsCards() ? PAGE_MIN_WIDTH : 0;
+ const right = gutter();
+ const fit = () => {
+ const pages = editor.pages();
+ if (!pages.length) return;
+ const widest = Math.max(...pages.map((p) => p.width)) * PX_PER_PT;
+ const available = Math.max(
+ floor,
+ element.clientWidth - SIDE_PADDING * 2 - right
+ );
+ editor.setZoom(Math.min(1, Math.max(0.3, available / widest)));
};
- document.addEventListener('selectionchange', onSelectionChange);
- onCleanup(() => {
- clearTimeout(timer);
- document.removeEventListener('selectionchange', onSelectionChange);
- });
+ const observer = new ResizeObserver(fit);
+ observer.observe(element);
+ fit();
+ onCleanup(() => observer.disconnect());
+ });
+
+ // Comments anchor in the body, not in headers, footers or notes.
+ const selectionTop = createMemo<number | null>(() => {
+ const state = editor.state();
+ const first = state?.rects[0];
+ if (!first || state.story.kind !== 'body') return null;
+ return toColumn(geometry(), first)?.top ?? null;
+ });
+
+ const paragraphStyles = createMemo<DocxParagraphStyle[]>(() => {
+ const all = editor.styles();
+ const quick = all.filter((s) => s.quick);
+ const current = editor.state()?.format.style;
+ const shown = quick.length ? quick : all.slice(0, 12);
+ const list = shown.map((s) => ({ id: s.id, name: s.name }));
+ const extra = current && all.find((s) => s.id === current);
+ if (extra && !list.some((s) => s.id === extra.id))
+ list.push({ id: extra.id, name: extra.name });
+ return list;
});
const beginComment = () => {
@@ -203,137 +214,293 @@ export function DocxEditorView(props: DocxEditorViewProps) {
props.onError?.(new Error('Select text to comment on.'));
};
- createEffect(() => {
- const root = editorRoot();
- if (!root || !props.commentRoots) return;
- const onKeyDown = (event: KeyboardEvent) => {
- if (
- (event.metaKey || event.ctrlKey) &&
- event.altKey &&
- event.code === 'KeyM'
- ) {
- event.preventDefault();
- beginComment();
- }
- };
- root.addEventListener('keydown', onKeyDown);
- onCleanup(() => root.removeEventListener('keydown', onKeyDown));
- });
+ const onTextClick = (pos: Pos) => {
+ if (!props.commentRoots) return;
+ const hit = comments.threadAt(pos);
+ if (hit) comments.setActive(hit);
+ else if (!comments.draft()) comments.setActive(null);
+ };
- const run = (
- command: (instance: NonNullable<ReturnType<typeof editor>>) => void
- ) => {
- const current = editor();
- if (!current) return;
- try {
- command(current);
- } catch (error) {
- props.onError?.(error);
- }
- refreshFormat();
+ const format = () => editor.state()?.format;
+
+ /** Runs a toolbar command and returns focus to the document. */
+ const command = (ops: EditOp[]) => {
+ editor.run(ops);
+ input?.focus();
};
+ const tableOp = (op: DocxTableOp): EditOp =>
+ match(op)
+ .with('rowAbove', (): EditOp => ({ op: 'insertRow', below: false }))
+ .with('rowBelow', (): EditOp => ({ op: 'insertRow', below: true }))
+ .with('columnLeft', (): EditOp => ({ op: 'insertColumn', right: false }))
+ .with('columnRight', (): EditOp => ({ op: 'insertColumn', right: true }))
+ .with('deleteRow', (): EditOp => ({ op: 'deleteRow' }))
+ .with('deleteColumn', (): EditOp => ({ op: 'deleteColumn' }))
+ .with('deleteTable', (): EditOp => ({ op: 'deleteTable' }))
+ .exhaustive();
+
+ /** At most this many matches are highlighted (the count shows them all). */
+ const HIGHLIGHTED = 5000;
+
+ const findHighlights = (g: Accessor<PageGeometry>) => (
+ <Show when={find.open()}>
+ <For each={find.matches().slice(0, HIGHLIGHTED)}>
+ {(match, index) => (
+ <For each={match.rects}>
+ {(rect) => {
+ const box = () => toColumn(g(), rect);
+ return (
+ <Show when={box()}>
+ {(b) => (
+ <div
+ class="absolute"
+ classList={{
+ 'docx-find': index() !== find.current(),
+ 'docx-find-current': index() === find.current(),
+ }}
+ data-docx-find-match={index()}
+ style={{
+ left: `${b().left}px`,
+ top: `${b().top}px`,
+ width: `${b().width}px`,
+ height: `${b().height}px`,
+ }}
+ />
+ )}
+ </Show>
+ );
+ }}
+ </For>
+ )}
+ </For>
+ </Show>
+ );
+
+ const commentHighlights = (g: Accessor<PageGeometry>) => (
+ <Show when={props.commentRoots}>
+ <For each={comments.located()}>
+ {(thread) => (
+ <For each={thread.rects}>
+ {(rect) => {
+ const box = () => toColumn(g(), rect);
+ return (
+ <Show when={box()}>
+ {(b) => (
+ <div
+ class="absolute"
+ classList={{
+ 'docx-comment': comments.active() !== thread.id,
+ 'docx-comment-active': comments.active() === thread.id,
+ hidden:
+ thread.resolved && comments.active() !== thread.id,
+ }}
+ data-docx-comment-highlight={thread.id}
+ style={{
+ left: `${b().left}px`,
+ top: `${b().top}px`,
+ width: `${b().width}px`,
+ height: `${b().height}px`,
+ }}
+ />
+ )}
+ </Show>
+ );
+ }}
+ </For>
+ )}
+ </For>
+ </Show>
+ );
+
return (
<div class="flex size-full min-h-0 min-w-0 flex-col">
- {/* A DOCX is authored for paper: its runs carry their own colours, so
- the sheet stays white whatever the app theme is. */}
- <style>{`.docx-paper { background: #fff; color: #000; }
-.docx-paper .docx-hf-band { padding: 10px 1in; }
-.docx-paper .docx-hf-band[data-hf-band='header'] { border-bottom: 1px dashed #e5e7eb; }
-.docx-paper .docx-hf-band[data-hf-band='footer'] { border-top: 1px dashed #e5e7eb; }
-.docx-paper .docx-hf-placeholder { font: 12px/1.5 var(--font-sans, sans-serif); color: #9ca3af; }
-.docx-paper .docx-hf-tag { margin-bottom: 2px; font: 500 10px/1.4 var(--font-sans, sans-serif); letter-spacing: 0.06em; text-transform: uppercase; color: #9ca3af; }
-${highlightStyles}`}</style>
+ {/* A DOCX is authored for paper: the engine draws white sheets with the
+ document's own colours whatever the app theme is. */}
+ <style>{`.docx-sheet { background: #fff; }
+.docx-selection { background-color: oklch(from var(--color-accent, #3b82f6) l c h / 0.28); }
+.docx-caret { background-color: #000; animation: docx-blink 1.06s steps(1) infinite; }
+@keyframes docx-blink { 50% { opacity: 0; } }
+.docx-composition { background: #fff; color: #000; text-decoration: underline; }
+.docx-comment { background-color: oklch(from var(--color-yellow) l c h / 0.28); border-bottom: 2px solid oklch(from var(--color-yellow) l c h / 0.7); }
+.docx-comment-active { background-color: oklch(from var(--color-yellow) l c h / 0.55); border-bottom: 2px solid oklch(from var(--color-yellow) l c h / 0.9); }
+.docx-find { background-color: oklch(from var(--color-orange) l c h / 0.3); }
+.docx-find-current { background-color: oklch(from var(--color-orange) l c h / 0.6); box-shadow: 0 0 0 1px oklch(from var(--color-orange) l c h / 0.9); }
+.docx-veil { background: rgb(255 255 255 / 0.55); }
+.docx-story-edge { border-color: oklch(from var(--color-accent, #3b82f6) l c h / 0.8); }`}</style>
<DocxToolbar
canEdit={props.canEdit}
- canComment={!!props.commentRoots && props.canComment()}
- format={format()}
- paragraphStyle={paragraphStyle()}
- paragraphStyles={paragraphStyles()}
- trackChanges={trackChanges()}
- onFormat={(key) => run((instance) => instance.format(key))}
- onParagraphStyle={(id) =>
- run((instance) => instance.setParagraphStyle(id))
+ canComment={
+ !!props.commentRoots &&
+ props.canComment() &&
+ editor.state()?.story.kind === 'body'
}
- onList={(kind) => run((instance) => instance.toggleList(kind))}
- onAlign={(alignment: DocxAlignment) =>
- run((instance) => instance.setAlignment(alignment))
+ format={{
+ bold: format()?.bold,
+ italic: format()?.italic,
+ underline: format()?.underline,
+ strike: format()?.strike,
+ superscript: format()?.superscript,
+ subscript: format()?.subscript,
+ }}
+ fontSize={format()?.size ?? null}
+ fontFamily={format()?.font ?? null}
+ color={format()?.color ?? null}
+ highlight={format()?.highlight ?? null}
+ lineSpacing={format()?.lineSpacing ?? null}
+ inTable={!!format()?.table}
+ paragraphStyle={format()?.style ?? null}
+ paragraphStyles={paragraphStyles()}
+ showMarkup={editor.markup()}
+ tracking={!!format()?.tracking}
+ onRevision={!!format()?.revision}
+ onFormat={(key) => {
+ editor.run([{ op: 'toggleFormat', format: key }]);
+ input?.focus();
+ }}
+ onFontSize={(size) => {
+ editor.run([{ op: 'setFormat', size }]);
+ input?.focus();
+ }}
+ onFontFamily={(font) => command([{ op: 'setFormat', font }])}
+ onColor={(color) => command([{ op: 'setFormat', color }])}
+ onHighlight={(highlight) => command([{ op: 'setFormat', highlight }])}
+ onClearFormat={() => command([{ op: 'clearFormat' }])}
+ onIndent={(forward) => command([{ op: 'indent', forward }])}
+ onLineSpacing={(value) =>
+ command([
+ { op: 'setParagraph', lineSpacing: { rule: 'auto', value } },
+ ])
}
- onUndo={() => run(() => handle.undo())}
- onRedo={() => run(() => handle.redo())}
- onInsertTable={() => run((instance) => instance.insertTable(3, 3))}
- onToggleTrackChanges={() =>
- run((instance) => {
- const next = !trackChanges();
- instance.setTrackedChanges(
- next
- ? props.runtime.module.TrackedChangeMode.RenderInline
- : props.runtime.module.TrackedChangeMode.Accept
- );
- setTrackChanges(next);
- })
+ onTable={(op) => command([tableOp(op)])}
+ onRefocus={() => input?.focus()}
+ onParagraphStyle={(id) => {
+ if (id) editor.run([{ op: 'setStyle', style: id }]);
+ input?.focus();
+ }}
+ onList={(kind) => {
+ editor.run([{ op: 'toggleList', kind }]);
+ input?.focus();
+ }}
+ onAlign={(alignment: DocxAlignment) => {
+ editor.run([{ op: 'setParagraph', align: alignment }]);
+ input?.focus();
+ }}
+ onUndo={() => void editor.undo()}
+ onRedo={() => void editor.redo()}
+ onInsertTable={() => {
+ editor.run([{ op: 'insertTable', rows: 3, cols: 3 }]);
+ input?.focus();
+ }}
+ onInsertNote={(endnote) => command([{ op: 'insertNote', endnote }])}
+ inBody={editor.state()?.story.kind === 'body'}
+ onToggleMarkup={() => void editor.setMarkup(!editor.markup())}
+ onToggleTracking={() =>
+ editor.run([{ op: 'setTracking', on: !format()?.tracking }])
}
+ onAccept={(all) => editor.run([{ op: 'acceptChanges', all }])}
+ onReject={(all) => editor.run([{ op: 'rejectChanges', all }])}
onComment={beginComment}
+ onFind={() => find.show(false)}
onDownload={() => {
- handle.flush();
- const bytes = handle.save();
- if (bytes) props.onDownload(bytes);
+ editor
+ .idle()
+ .then(() => editor.save())
+ .then(props.onDownload)
+ .catch((error: unknown) => props.onError?.(error));
}}
/>
- <div
- ref={scroller}
- class="relative min-h-0 flex-1 overflow-auto bg-panel"
- data-docx-scroller
- >
- {/* The page sits centered between equal gutters. The page column
- shrinks so Docxodus zooms the sheet to fit a narrow split instead
- of scrolling it sideways, unless comment cards need the room. */}
+ <div class="relative flex min-h-0 flex-1 flex-col">
<div
- class="relative grid gap-x-2 px-4 pt-6 pb-24"
- style={{ 'grid-template-columns': pageColumns() }}
+ ref={setScroller}
+ class="relative min-h-0 flex-1 overflow-auto bg-panel"
+ data-docx-scroller
>
- <div ref={page} class="relative col-start-2 min-w-0" data-docx-page>
- <div ref={setEditorRoot} class="docx-paper rounded-sm shadow-md" />
- <DocxCollaboratorCarets
- peers={props.peers()}
- editorRoot={editorRoot()}
- overlay={page}
- revision={handle.revision}
- displayName={props.displayName}
- />
- <Show when={loading()}>
- <div class="absolute inset-0 flex items-start justify-center pt-24 text-sm text-ink-muted">
- Opening document…
- </div>
+ <div
+ class="relative grid gap-x-2 pt-6 pb-24"
+ style={{
+ 'grid-template-columns': `minmax(${SIDE_PADDING}px, 1fr) ${geometry().width}px minmax(${gutter()}px, 1fr)`,
+ }}
+ >
+ <div class="relative col-start-2 min-w-0">
+ <DocxPages
+ editor={editor}
+ scroller={scroller()}
+ editable={props.canEdit}
+ documentId={props.documentId}
+ onTextClick={onTextClick}
+ onComment={props.commentRoots ? beginComment : undefined}
+ onFind={(replace) => find.show(replace && props.canEdit)}
+ onFindNext={(forward) => {
+ if (!find.open()) return;
+ if (forward) find.next();
+ else find.previous();
+ }}
+ inputRef={(el) => {
+ input = el;
+ }}
+ overlay={(g) => (
+ <>
+ {findHighlights(g)}
+ {commentHighlights(g)}
+ <DocxCollaboratorCarets
+ peers={props.peers()}
+ geometry={g}
+ revision={editor.revision}
+ caretAt={editor.caretAt}
+ displayName={props.displayName}
+ />
+ </>
+ )}
+ />
+ <Show when={!editor.ready()}>
+ <div class="absolute inset-x-0 top-24 flex justify-center text-sm text-ink-muted">
+ Opening document…
+ </div>
+ </Show>
+ </div>
+ <Show when={props.margin}>
+ {(renderMargin) => (
+ <div class="relative col-start-3 min-w-0" data-docx-margin>
+ {renderMargin()({ comments, geometry, selectionTop })}
+ </div>
+ )}
</Show>
</div>
- <Show when={props.margin}>
- {(renderMargin) => (
- <div
- ref={setMargin}
- class="relative col-start-3 min-w-0"
- data-docx-margin
- >
- {renderMargin()({
- comments,
- get editorRoot() {
- return editorRoot();
- },
- get margin() {
- return margin();
- },
- revision: handle.revision,
- })}
+ <Show when={props.footer}>
+ {(renderFooter) => (
+ <div class="mx-auto flex max-w-3xl flex-col gap-6 px-4 pb-16">
+ {renderFooter()(comments)}
</div>
)}
</Show>
</div>
- <Show when={props.footer}>
- {(renderFooter) => (
- <div class="mx-auto flex max-w-3xl flex-col gap-6 px-4 pb-16">
- {renderFooter()(comments)}
- </div>
- )}
+ <Show when={find.open()}>
+ <div class="absolute top-2 right-4 z-10">
+ <DocxFindBar
+ query={find.query()}
+ replacement={find.replacement()}
+ matchCase={find.matchCase()}
+ wholeWord={find.wholeWord()}
+ count={find.matches().length}
+ current={find.current()}
+ truncated={find.truncated()}
+ replaced={find.replaced()}
+ replacing={find.replacing()}
+ canEdit={props.canEdit}
+ focusRequest={find.focusRequest()}
+ onQuery={find.setQuery}
+ onReplacement={find.setReplacement}
+ onToggleMatchCase={find.toggleMatchCase}
+ onToggleWholeWord={find.toggleWholeWord}
+ onToggleReplace={() => find.setReplacing((v) => !v)}
+ onNext={find.next}
+ onPrevious={find.previous}
+ onReplace={() => find.replace(props.canEdit)}
+ onReplaceAll={() => find.replaceAll(props.canEdit)}
+ onClose={closeFind}
+ />
+ </div>
</Show>
</div>
</div>
diff --git a/apps/web/src/features/block-write/views/DocxMarginLayout.tsx b/apps/web/src/features/block-write/views/DocxMarginLayout.tsx
index be0d475c04..286ff7bbad 100644
--- a/apps/web/src/features/block-write/views/DocxMarginLayout.tsx
+++ b/apps/web/src/features/block-write/views/DocxMarginLayout.tsx
@@ -4,7 +4,6 @@ import {
type Accessor,
createEffect,
createMemo,
- createSignal,
For,
type JSX,
onCleanup,
@@ -12,63 +11,45 @@ import {
} from 'solid-js';
import { createStore } from 'solid-js/store';
import { layoutMarginCards } from '../core/comment-layout';
-import { blockOf } from '../core/text-offsets';
import type {
DocxComments,
LocatedThread,
} from '../primitives/create-docx-comments';
+import { type PageGeometry, toColumn } from './DocxPages';
+import { DocxWordCommentCard } from './DocxWordComment';
const CARD_WIDTH = 280;
/**
* The comment margin beside a DOCX: one card per placed thread, stacked next
- * to its text, a floating comment button beside any selection, and clicks on
- * highlighted text open their thread. The card itself is supplied.
+ * to its text, and a floating comment button beside any selection. The card
+ * itself is supplied. The margin shares its top edge with the pages column,
+ * so anchors are page geometry in column coordinates.
*/
export function DocxMarginLayout(props: {
comments: DocxComments;
- /** The editor element; selection and clicks are read from it. */
- editorRoot: HTMLElement | undefined;
- /** Positioning parent: the margin scrolls with the document. */
- margin: HTMLElement | undefined;
- revision: Accessor<number>;
+ geometry: Accessor<PageGeometry>;
+ /** Top of the selected text, when there is a selection to comment on. */
+ selectionTop: Accessor<number | null>;
canComment: Accessor<boolean>;
+ /** The card of a Macro thread (the document's own comments have theirs). */
renderCard: (
thread: LocatedThread,
isActive: Accessor<boolean>
) => JSX.Element;
}) {
const [heights, setHeights] = createStore<Record<string, number>>({});
- const [layoutTick, setLayoutTick] = createSignal(0);
- const relayout = () => setLayoutTick((tick) => tick + 1);
- createEffect(() => {
- const margin = props.margin;
- const root = props.editorRoot;
- if (!margin || !root) return;
- const observer = new ResizeObserver(relayout);
- observer.observe(margin);
- observer.observe(root);
- onCleanup(() => observer.disconnect());
- });
-
- const anchorTop = (thread: LocatedThread, marginTop: number) => {
- const rects = thread.range.getClientRects();
- const first = rects.length
- ? rects[0]
- : thread.range.getBoundingClientRect();
- return first.top - marginTop;
+ const anchorTop = (thread: LocatedThread) => {
+ const first = thread.rects[0];
+ const box = first ? toColumn(props.geometry(), first) : undefined;
+ return box?.top ?? 0;
};
const positions = createMemo(() => {
- layoutTick();
- props.revision();
- const margin = props.margin;
- if (!margin) return new Map<string, number>();
- const marginTop = margin.getBoundingClientRect().top;
const items = props.comments
.located()
- .map((thread) => ({ id: thread.id, top: anchorTop(thread, marginTop) }));
+ .map((thread) => ({ id: thread.id, top: anchorTop(thread) }));
return layoutMarginCards(
items,
new Map(Object.entries(heights)),
@@ -76,64 +57,25 @@ export function DocxMarginLayout(props: {
);
});
- // Clicking highlighted text opens its thread.
- createEffect(() => {
- const root = props.editorRoot;
- if (!root) return;
- const onClick = () => {
- const selection = window.getSelection();
- if (!selection?.isCollapsed || !selection.anchorNode) return;
- if (!blockOf(selection.anchorNode, root)) return;
- const hit = props.comments.threadAt(
- selection.anchorNode,
- selection.anchorOffset
- );
- if (hit) props.comments.setActive(hit);
- else if (!props.comments.draft()) props.comments.setActive(null);
- };
- root.addEventListener('click', onClick);
- onCleanup(() => root.removeEventListener('click', onClick));
- });
-
- // A floating "comment" affordance beside any selected text.
- const [selectionTop, setSelectionTop] = createSignal<number | null>(null);
- createEffect(() => {
- const root = props.editorRoot;
- const margin = props.margin;
- if (!root || !margin) return;
- const update = () => {
- const selection = window.getSelection();
- if (
- !props.canComment() ||
- !selection ||
- selection.isCollapsed ||
- selection.rangeCount === 0 ||
- !blockOf(selection.getRangeAt(0).startContainer, root)
- ) {
- setSelectionTop(null);
- return;
- }
- const rect = selection.getRangeAt(0).getClientRects()[0];
- setSelectionTop(
- rect ? rect.top - margin.getBoundingClientRect().top : null
- );
- };
- document.addEventListener('selectionchange', update);
- onCleanup(() => document.removeEventListener('selectionchange', update));
- });
-
return (
<>
- <Show when={selectionTop() !== null && !props.comments.draft()}>
+ <Show
+ when={
+ props.canComment() &&
+ props.selectionTop() !== null &&
+ !props.comments.draft()
+ }
+ >
<div
class="absolute left-2 z-10"
- style={{ top: `${selectionTop()}px` }}
+ style={{ top: `${props.selectionTop()}px` }}
>
<Button
size="icon-md"
variant="cta"
label="Comment"
data-docx-comment-button
+ onPointerDown={(event: PointerEvent) => event.preventDefault()}
onMouseDown={(event: MouseEvent) => event.preventDefault()}
onClick={() => props.comments.beginDraft()}
>
@@ -165,7 +107,17 @@ export function DocxMarginLayout(props: {
style={{ top: `${top()}px`, width: `${CARD_WIDTH}px` }}
onClick={() => props.comments.setActive(thread.id)}
>
- {props.renderCard(thread, isActive)}
+ <Show
+ when={thread.word}
+ fallback={props.renderCard(thread, isActive)}
+ >
+ {(word) => (
+ <DocxWordCommentCard
+ comment={word().comment}
+ replies={word().replies}
+ />
+ )}
+ </Show>
</div>
);
}}
diff --git a/apps/web/src/features/block-write/views/DocxPages.tsx b/apps/web/src/features/block-write/views/DocxPages.tsx
new file mode 100644
index 0000000000..6f6c854622
--- /dev/null
+++ b/apps/web/src/features/block-write/views/DocxPages.tsx
@@ -0,0 +1,867 @@
+import type {
+ CaretRect,
+ Clip,
+ EditOp,
+ PageRect,
+ Pos,
+} from '@core/docx-engine/types';
+import {
+ type Accessor,
+ createEffect,
+ createMemo,
+ createSignal,
+ For,
+ Index,
+ type JSX,
+ onCleanup,
+ onMount,
+ Show,
+} from 'solid-js';
+import { clipboardHtml, readClipboardHtml } from '../core/clipboard';
+import { keyAction } from '../core/keymap';
+import { type DocxEditor, PX_PER_PT } from '../primitives/create-docx-editor';
+
+/** Space between pages (CSS pixels). */
+export const PAGE_GAP = 16;
+
+const isMac =
+ typeof navigator !== 'undefined' &&
+ /Mac|iPhone|iPad/.test(navigator.platform);
+
+/** Where pages sit in the column (CSS pixels at the current zoom). */
+export function pageGeometry(editor: DocxEditor) {
+ return createMemo(() => {
+ const scale = editor.zoom() * PX_PER_PT;
+ const pages = editor.pages();
+ const width = Math.max(1, ...pages.map((p) => p.width * scale));
+ let top = 0;
+ const boxes = pages.map((p) => {
+ const box = {
+ left: (width - p.width * scale) / 2,
+ top,
+ width: p.width * scale,
+ height: p.height * scale,
+ };
+ top += box.height + PAGE_GAP;
+ return box;
+ });
+ return { scale, width, height: Math.max(0, top - PAGE_GAP), boxes };
+ });
+}
+
+export type PageGeometry = ReturnType<ReturnType<typeof pageGeometry>>;
+
+/** A page rectangle in column coordinates. */
+export function toColumn(geometry: PageGeometry, r: PageRect) {
+ const box = geometry.boxes[r.page];
+ if (!box) return undefined;
+ return {
+ left: box.left + r.x * geometry.scale,
+ top: box.top + r.y * geometry.scale,
+ width: r.w * geometry.scale,
+ height: r.h * geometry.scale,
+ };
+}
+
+function caretBox(geometry: PageGeometry, c: CaretRect) {
+ return toColumn(geometry, {
+ page: c.page,
+ x: c.x,
+ y: c.y,
+ w: 0,
+ h: c.height,
+ });
+}
+
+function Page(props: {
+ editor: DocxEditor;
+ index: number;
+ box: { left: number; top: number; width: number; height: number };
+ root: HTMLElement | undefined;
+}) {
+ let element!: HTMLDivElement;
+ const [near, setNear] = createSignal(false);
+ // Only pages near the viewport hold a canvas (a page bitmap is megabytes).
+ createEffect(() => {
+ const root = props.root;
+ if (!root) return;
+ const observer = new IntersectionObserver(
+ ([entry]) => {
+ setNear(entry.isIntersecting);
+ props.editor.renderer.setVisible(props.index, entry.isIntersecting);
+ },
+ { root, rootMargin: '100% 0px' }
+ );
+ observer.observe(element);
+ onCleanup(() => {
+ observer.disconnect();
+ props.editor.renderer.setVisible(props.index, false);
+ });
+ });
+ return (
+ <div
+ ref={element}
+ class="docx-sheet absolute overflow-hidden rounded-[2px] shadow-md"
+ data-docx-page={props.index}
+ style={{
+ left: `${props.box.left}px`,
+ top: `${props.box.top}px`,
+ width: `${props.box.width}px`,
+ height: `${props.box.height}px`,
+ }}
+ >
+ <Show when={near()}>
+ <canvas
+ ref={(canvas) => {
+ props.editor.renderer.attach(props.index, canvas);
+ onCleanup(() =>
+ props.editor.renderer.attach(props.index, undefined)
+ );
+ }}
+ class="block size-full"
+ />
+ </Show>
+ </div>
+ );
+}
+
+/**
+ * While a header or footer is being edited: the body dimmed on every page,
+ * a dashed edge around the header or footer area, and a label with a way
+ * back to the body on the page being edited.
+ */
+function StoryChrome(props: {
+ editor: DocxEditor;
+ geometry: PageGeometry;
+ onClose: () => void;
+}) {
+ const story = () => props.editor.state()?.story;
+ const kind = () => {
+ const k = story()?.kind;
+ return k === 'header' || k === 'footer' ? k : undefined;
+ };
+ return (
+ <Show when={kind()}>
+ {(k) => (
+ <Index each={props.editor.pages()}>
+ {(page, index) => {
+ const box = () => props.geometry.boxes[index];
+ const scale = () => props.geometry.scale;
+ const top = () => page().header?.bottom ?? 0;
+ const bottom = () => page().footer?.top ?? page().height;
+ const edge = () =>
+ k() === 'header' ? top() * scale() : bottom() * scale();
+ return (
+ <Show when={box()}>
+ {(b) => (
+ <>
+ <div
+ class="docx-veil absolute"
+ style={{
+ left: `${b().left}px`,
+ top: `${b().top + top() * scale()}px`,
+ width: `${b().width}px`,
+ height: `${Math.max(0, (bottom() - top()) * scale())}px`,
+ }}
+ />
+ <div
+ class="docx-story-edge absolute border-t border-dashed"
+ style={{
+ left: `${b().left}px`,
+ top: `${b().top + edge()}px`,
+ width: `${b().width}px`,
+ }}
+ />
+ <Show when={story()?.page === index}>
+ <div
+ class="pointer-events-auto absolute flex items-center gap-1 rounded-sm bg-accent px-1.5 py-0.5 text-[11px] text-accent-contrast"
+ data-docx-story-label
+ style={{
+ left: `${b().left + 8}px`,
+ top:
+ k() === 'header'
+ ? `${b().top + edge() + 2}px`
+ : `${b().top + edge() - 20}px`,
+ }}
+ onPointerDown={(event) => {
+ event.stopPropagation();
+ event.preventDefault();
+ }}
+ onMouseDown={(event) => event.preventDefault()}
+ >
+ <span>{k() === 'header' ? 'Header' : 'Footer'}</span>
+ <button
+ type="button"
+ class="rounded-sm px-1 underline-offset-2 hover:underline"
+ onClick={() => props.onClose()}
+ >
+ Close
+ </button>
+ </div>
+ </Show>
+ </>
+ )}
+ </Show>
+ );
+ }}
+ </Index>
+ )}
+ </Show>
+ );
+}
+
+/** How far (points) outside the notes' lines a click still edits a note. */
+const NOTE_SLOP = 4;
+
+export type DocxPagesProps = {
+ editor: DocxEditor;
+ /** The scrolling element (for page visibility and caret scrolling). */
+ scroller: HTMLElement | undefined;
+ editable: boolean;
+ /** Extra overlays drawn above the pages (comment highlights, peers). */
+ overlay?: (geometry: Accessor<PageGeometry>) => JSX.Element;
+ /** A click on the text (after the caret moved there). */
+ onTextClick?: (pos: Pos) => void;
+ /** Start a comment (keyboard shortcut). */
+ onComment?: () => void;
+ /** Open the find bar (keyboard shortcut), with the replace field. */
+ onFind?: (replace: boolean) => void;
+ /** Go to the next (or previous) match of the search. */
+ onFindNext?: (forward: boolean) => void;
+ /** Called with the input element once mounted (focus management). */
+ inputRef?: (input: HTMLTextAreaElement) => void;
+ /**
+ * The document's id: content copied from the same document pastes back
+ * with its pictures, links and list numbering.
+ */
+ documentId?: string;
+};
+
+/**
+ * The pages of a document drawn by the engine, with the selection, caret
+ * and an invisible text input that receives typing, IME composition and
+ * clipboard events.
+ */
+export function DocxPages(props: DocxPagesProps) {
+ const editor = props.editor;
+ const geometry = pageGeometry(editor);
+ let column!: HTMLDivElement;
+ let input!: HTMLTextAreaElement;
+ const [focused, setFocused] = createSignal(false);
+ const [composing, setComposing] = createSignal<string | null>(null);
+ /**
+ * The selection's clipboard content, fetched once the selection settles,
+ * so a copy can fill the clipboard synchronously.
+ */
+ let clipboard: { key: string; clip: Clip } | undefined;
+ let clipTimer: ReturnType<typeof setTimeout> | undefined;
+ onCleanup(() => clearTimeout(clipTimer));
+ const selectionKey = () =>
+ JSON.stringify([editor.state()?.selection, editor.revision()]);
+ const documentId = () => props.documentId ?? editor.docKey;
+
+ const caret = createMemo(() => {
+ const c = editor.state()?.caret;
+ return c ? caretBox(geometry(), c) : undefined;
+ });
+
+ const rects = createMemo(() =>
+ (editor.state()?.rects ?? [])
+ .map((r) => toColumn(geometry(), r))
+ .filter((r) => r !== undefined)
+ );
+
+ // Prefetch the clipboard content of a selection (an engine round trip).
+ createEffect(() => {
+ const selection = editor.state()?.selection;
+ const key = selectionKey();
+ clearTimeout(clipTimer);
+ if (
+ !selection ||
+ (selection.anchor.block === selection.focus.block &&
+ selection.anchor.offset === selection.focus.offset)
+ ) {
+ clipboard = undefined;
+ return;
+ }
+ clipTimer = setTimeout(() => {
+ editor
+ .copySelection()
+ .then((clip) => {
+ if (selectionKey() === key) clipboard = { key, clip };
+ })
+ .catch(() => {});
+ }, 120);
+ });
+
+ // Keep the caret in view after keyboard edits and moves.
+ let followCaret = false;
+ createEffect(() => {
+ const c = caret();
+ const scroller = props.scroller;
+ if (!c || !scroller || !followCaret) return;
+ followCaret = false;
+ const columnTop =
+ column.getBoundingClientRect().top -
+ scroller.getBoundingClientRect().top +
+ scroller.scrollTop;
+ const top = columnTop + c.top;
+ const bottom = top + c.height;
+ const margin = 40;
+ if (top < scroller.scrollTop + margin)
+ scroller.scrollTop = Math.max(0, top - margin);
+ else if (bottom > scroller.scrollTop + scroller.clientHeight - margin)
+ scroller.scrollTop = bottom - scroller.clientHeight + margin;
+ });
+
+ const run = (ops: EditOp[], group?: string) => {
+ followCaret = true;
+ editor.run(ops, group);
+ };
+
+ /** The page and point (in points) under a client position. */
+ function pointAt(clientX: number, clientY: number) {
+ const bounds = column.getBoundingClientRect();
+ const x = clientX - bounds.left;
+ const y = clientY - bounds.top;
+ const g = geometry();
+ let index = g.boxes.findIndex((b) => y < b.top + b.height + PAGE_GAP / 2);
+ if (index < 0) index = g.boxes.length - 1;
+ const box = g.boxes[index];
+ if (!box) return undefined;
+ return {
+ page: index,
+ x: (x - box.left) / g.scale,
+ y: Math.min(Math.max(0, (y - box.top) / g.scale), box.height / g.scale),
+ };
+ }
+
+ let dragAnchor: Pos | undefined;
+ let dragFrame = 0;
+
+ // Pointer events carry no click count (`detail` is 0), so double and
+ // triple clicks are counted here: quick presses close together.
+ let lastPress = { time: 0, x: 0, y: 0, count: 0 };
+ function clickCount(event: PointerEvent) {
+ const near =
+ Math.abs(event.clientX - lastPress.x) < 5 &&
+ Math.abs(event.clientY - lastPress.y) < 5;
+ const count =
+ near && event.timeStamp - lastPress.time < 500 ? lastPress.count + 1 : 1;
+ lastPress = {
+ time: event.timeStamp,
+ x: event.clientX,
+ y: event.clientY,
+ count,
+ };
+ return count;
+ }
+
+ /** The header, footer or notes area under a point (points), if any. */
+ function areaAt(point: { page: number; y: number }) {
+ const page = editor.pages()[point.page];
+ if (page?.header && point.y < page.header.bottom)
+ return { kind: 'header' as const, editable: page.header.editable };
+ if (page?.footer && point.y >= page.footer.top)
+ return { kind: 'footer' as const, editable: page.footer.editable };
+ const notes = page?.notes;
+ if (
+ notes &&
+ point.y >= notes.top - NOTE_SLOP &&
+ point.y <= notes.bottom + NOTE_SLOP
+ )
+ return { kind: 'note' as const, editable: notes.editable };
+ return undefined;
+ }
+
+ /**
+ * A click in a footnote or endnote edits it, as in Word. Double-clicking
+ * a header or footer edits it; while one is open, a click on another
+ * page's header or footer moves there and a click on the body goes back
+ * to it. Returns whether the click was fully handled.
+ */
+ async function switchStory(
+ point: { page: number; x: number; y: number },
+ clicks: number
+ ) {
+ if (!props.editable) return false;
+ const story = editor.state()?.story;
+ const area = areaAt(point);
+ if (area?.kind === 'note') {
+ // The engine enters the note under the point (keeping the selection
+ // when it is already there); the press goes on to place the caret.
+ run([{ op: 'enterStory', ...point }]);
+ await editor.idle();
+ return false;
+ }
+ if (!story || (story.kind !== 'header' && story.kind !== 'footer')) {
+ if (clicks === 2 && area?.editable) {
+ run([{ op: 'enterStory', ...point }]);
+ return true;
+ }
+ if (story && story.kind !== 'body') {
+ // Out of a note, back to the body.
+ editor.run([{ op: 'exitStory' }]);
+ await editor.idle();
+ }
+ return false;
+ }
+ if (area?.kind === story.kind && point.page === story.page) return false;
+ if (area?.editable) {
+ run([{ op: 'enterStory', ...point }]);
+ return true;
+ }
+ editor.run([{ op: 'exitStory' }]);
+ await editor.idle();
+ return false;
+ }
+
+ /** Presses are handled one after another, each after the last one's
+ * hit test, so a quick second click never overtakes the first. */
+ let presses: Promise<void> = Promise.resolve();
+ /** Whether the button is still down (a drag extends the selection). */
+ let held = false;
+
+ /**
+ * A finger on the page: it scrolls natively, a tap places the caret (and
+ * opens the keyboard), a double tap selects a word, and a press held
+ * still selects a word and then extends the selection as it moves.
+ */
+ let touch:
+ | {
+ id: number;
+ x: number;
+ y: number;
+ time: number;
+ timer: ReturnType<typeof setTimeout>;
+ }
+ | undefined;
+ /** A held press is selecting: the finger extends the selection. */
+ let touchSelecting = false;
+ let lastTap = { time: 0, x: 0, y: 0 };
+ onCleanup(() => clearTimeout(touch?.timer));
+
+ /** Movement (CSS pixels) after which a touch is a scroll, not a tap. */
+ const TAP_SLOP = 10;
+ const LONG_PRESS = 500;
+
+ function touchDown(event: PointerEvent) {
+ clearTimeout(touch?.timer);
+ const { clientX, clientY } = event;
+ touch = {
+ id: event.pointerId,
+ x: clientX,
+ y: clientY,
+ time: event.timeStamp,
+ timer: setTimeout(() => longPress(clientX, clientY), LONG_PRESS),
+ };
+ }
+
+ function longPress(clientX: number, clientY: number) {
+ touch = undefined;
+ const point = pointAt(clientX, clientY);
+ if (!point) return;
+ touchSelecting = true;
+ held = true;
+ input.focus({ preventScroll: true });
+ presses = presses
+ .then(async () => {
+ const pos = await editor.hitTest(point.page, point.x, point.y);
+ if (!pos) return;
+ editor.run([{ op: 'selectWord', at: pos }]);
+ await editor.idle();
+ const selection = editor.state()?.selection;
+ if (held && selection) dragAnchor = selection.anchor;
+ })
+ .catch(() => {});
+ }
+
+ function touchUp(event: PointerEvent) {
+ const t = touch;
+ clearTimeout(t?.timer);
+ touch = undefined;
+ if (!t || t.id !== event.pointerId) return;
+ const point = pointAt(t.x, t.y);
+ if (!point) return;
+ const double =
+ event.timeStamp - lastTap.time < 350 &&
+ Math.abs(t.x - lastTap.x) < 24 &&
+ Math.abs(t.y - lastTap.y) < 24;
+ lastTap = double
+ ? { time: 0, x: 0, y: 0 }
+ : { time: event.timeStamp, x: t.x, y: t.y };
+ // Focus inside the tap's own handler, so mobile browsers open the
+ // keyboard.
+ input.focus({ preventScroll: true });
+ presses = presses
+ .then(() => press(point, double ? 2 : 1, false))
+ .catch(() => {});
+ }
+
+ /** Ends any press or drag (also when the browser takes the pointer over
+ * to scroll). */
+ function release() {
+ clearTimeout(touch?.timer);
+ touch = undefined;
+ touchSelecting = false;
+ held = false;
+ dragAnchor = undefined;
+ }
+
+ // While a held press selects, the finger must not scroll the page.
+ onMount(() => {
+ const preventScroll = (event: TouchEvent) => {
+ if (touchSelecting) event.preventDefault();
+ };
+ column.addEventListener('touchmove', preventScroll, { passive: false });
+ onCleanup(() => column.removeEventListener('touchmove', preventScroll));
+ });
+
+ function onPointerDown(event: PointerEvent) {
+ if (event.pointerType === 'touch') {
+ touchDown(event);
+ return;
+ }
+ if (event.button !== 0) return;
+ const point = pointAt(event.clientX, event.clientY);
+ if (!point) return;
+ event.preventDefault();
+ input.focus({ preventScroll: true });
+ const clicks = clickCount(event);
+ const shift = event.shiftKey;
+ held = true;
+ column.setPointerCapture(event.pointerId);
+ presses = presses.then(() => press(point, clicks, shift)).catch(() => {});
+ }
+
+ async function press(
+ point: { page: number; x: number; y: number },
+ clicks: number,
+ shift: boolean
+ ) {
+ if (await switchStory(point, clicks)) return;
+ const pos = await editor.hitTest(point.page, point.x, point.y);
+ if (!pos) return;
+ if (clicks === 2) {
+ editor.run([{ op: 'selectWord', at: pos }]);
+ return;
+ }
+ if (clicks >= 3) {
+ editor.run([{ op: 'selectParagraph', at: pos }]);
+ return;
+ }
+ const current = editor.state()?.selection;
+ const anchor = shift && current ? current.anchor : pos;
+ editor.run([{ op: 'select', anchor, focus: pos }]);
+ if (held) dragAnchor = anchor;
+ if (!shift) props.onTextClick?.(pos);
+ }
+
+ function onPointerMove(event: PointerEvent) {
+ if (
+ touch &&
+ touch.id === event.pointerId &&
+ Math.hypot(event.clientX - touch.x, event.clientY - touch.y) > TAP_SLOP
+ ) {
+ // A scroll, not a tap.
+ clearTimeout(touch.timer);
+ touch = undefined;
+ }
+ if (!dragAnchor) return;
+ const anchor = dragAnchor;
+ const { clientX, clientY } = event;
+ cancelAnimationFrame(dragFrame);
+ dragFrame = requestAnimationFrame(async () => {
+ const point = pointAt(clientX, clientY);
+ if (!point) return;
+ const pos = await editor.hitTest(point.page, point.x, point.y);
+ if (pos && dragAnchor) editor.run([{ op: 'select', anchor, focus: pos }]);
+ });
+ }
+
+ function onPointerUp(event: PointerEvent) {
+ if (event.pointerType === 'touch' && !touchSelecting) touchUp(event);
+ release();
+ if (column.hasPointerCapture(event.pointerId))
+ column.releasePointerCapture(event.pointerId);
+ }
+
+ async function pageMove(forward: boolean, extend: boolean) {
+ const c = editor.state()?.caret;
+ const scroller = props.scroller;
+ if (!c || !scroller) return;
+ const box = caretBox(geometry(), c);
+ if (!box) return;
+ const delta = scroller.clientHeight * 0.9 * (forward ? 1 : -1);
+ const bounds = column.getBoundingClientRect();
+ const point = pointAt(
+ bounds.left + box.left,
+ bounds.top + box.top + box.height / 2 + delta
+ );
+ if (!point) return;
+ const pos = await editor.hitTest(point.page, point.x, point.y);
+ const selection = editor.state()?.selection;
+ if (!pos || !selection) return;
+ scroller.scrollTop += delta;
+ editor.run([
+ { op: 'select', anchor: extend ? selection.anchor : pos, focus: pos },
+ ]);
+ }
+
+ function onKeyDown(event: KeyboardEvent) {
+ if (composing() !== null || event.isComposing) return;
+ if (event.key === 'Escape' && editor.state()?.story.kind !== 'body') {
+ event.preventDefault();
+ run([{ op: 'exitStory' }]);
+ return;
+ }
+ const action = keyAction(event, isMac);
+ if (!action) return;
+ event.preventDefault();
+ switch (action.kind) {
+ case 'ops':
+ run(action.ops, action.group);
+ break;
+ case 'undo':
+ void editor.undo();
+ break;
+ case 'redo':
+ void editor.redo();
+ break;
+ case 'comment':
+ props.onComment?.();
+ break;
+ case 'find':
+ props.onFind?.(action.replace);
+ break;
+ case 'findNext':
+ props.onFindNext?.(action.forward);
+ break;
+ case 'page':
+ void pageMove(action.forward, action.extend);
+ break;
+ case 'tab': {
+ const state = editor.state();
+ const selection = state?.selection;
+ const spans =
+ selection && selection.anchor.block !== selection.focus.block;
+ const atListStart = state?.format.list && selection?.focus.offset === 0;
+ if (spans || atListStart || !action.forward)
+ run([{ op: 'indent', forward: action.forward }]);
+ else run([{ op: 'insertText', text: '\t' }], 'typing');
+ break;
+ }
+ }
+ }
+
+ function typeText(text: string) {
+ if (!text) return;
+ run([{ op: 'insertText', text }], 'typing');
+ }
+
+ function onInput(event: InputEvent) {
+ if (composing() !== null || event.isComposing) return;
+ const value = input.value;
+ input.value = '';
+ // Mobile keyboards send Enter and Backspace as input events.
+ if (
+ event.inputType === 'insertParagraph' ||
+ event.inputType === 'insertLineBreak'
+ ) {
+ run([{ op: 'insertParagraph' }]);
+ return;
+ }
+ if (event.inputType === 'deleteContentBackward') {
+ run([{ op: 'delete', forward: false }], 'delete');
+ return;
+ }
+ typeText(value.replace(/\r\n?/g, '\n'));
+ }
+
+ function onPaste(event: ClipboardEvent) {
+ event.preventDefault();
+ if (!props.editable) return;
+ const html = event.clipboardData?.getData('text/html') ?? '';
+ const text = event.clipboardData?.getData('text/plain') ?? '';
+ const rich = html ? readClipboardHtml(html, documentId()) : undefined;
+ if (rich?.paragraphs.some((p) => p.runs.length)) {
+ run([
+ {
+ op: 'paste',
+ paragraphs: rich.paragraphs,
+ sameDocument: rich.sameDocument,
+ },
+ ]);
+ return;
+ }
+ if (text) run([{ op: 'insertText', text: text.replace(/\r\n?/g, '\n') }]);
+ }
+
+ /** Puts the selection on the clipboard; false when nothing is selected. */
+ function copy(event: ClipboardEvent): boolean {
+ event.preventDefault();
+ const selection = editor.state()?.selection;
+ if (
+ !selection ||
+ (selection.anchor.block === selection.focus.block &&
+ selection.anchor.offset === selection.focus.offset)
+ )
+ return false;
+ const ready = clipboard?.key === selectionKey() ? clipboard.clip : null;
+ if (ready && event.clipboardData) {
+ event.clipboardData.setData('text/plain', ready.text);
+ event.clipboardData.setData(
+ 'text/html',
+ clipboardHtml(ready, documentId())
+ );
+ return true;
+ }
+ // Not fetched yet: the clipboard API takes the content when it is.
+ const clip = editor.copySelection();
+ const blob = (type: string, data: (c: Clip) => string) =>
+ clip.then((c) => new Blob([data(c)], { type }));
+ void navigator.clipboard
+ ?.write([
+ new ClipboardItem({
+ 'text/plain': blob('text/plain', (c) => c.text),
+ 'text/html': blob('text/html', (c) => clipboardHtml(c, documentId())),
+ }),
+ ])
+ .catch(() => {});
+ return true;
+ }
+
+ function onCopy(event: ClipboardEvent) {
+ copy(event);
+ }
+
+ function onCut(event: ClipboardEvent) {
+ if (copy(event) && props.editable) run([{ op: 'delete', forward: false }]);
+ }
+
+ // Blink the caret only while the input has focus and nothing is selected.
+ const showCaret = () => focused() && rects().length === 0;
+
+ return (
+ <div
+ ref={column}
+ class="relative mx-auto select-none [-webkit-touch-callout:none]"
+ style={{
+ width: `${geometry().width}px`,
+ height: `${geometry().height}px`,
+ }}
+ onPointerDown={onPointerDown}
+ onPointerMove={onPointerMove}
+ onPointerUp={onPointerUp}
+ onPointerCancel={release}
+ // A tap's compatibility mousedown would move focus off the input.
+ onMouseDown={(event) => event.preventDefault()}
+ data-docx-pages
+ >
+ {/* By position: every layout brings new page objects, and a page's
+ canvas must survive them to be repainted strip by strip. */}
+ <Index each={editor.pages()}>
+ {(_, index) => (
+ <Show when={geometry().boxes[index]}>
+ {(box) => (
+ <Page
+ editor={editor}
+ index={index}
+ box={box()}
+ root={props.scroller}
+ />
+ )}
+ </Show>
+ )}
+ </Index>
+ <div class="pointer-events-none absolute inset-0" data-docx-overlay>
+ <StoryChrome
+ editor={editor}
+ geometry={geometry()}
+ onClose={() => run([{ op: 'exitStory' }])}
+ />
+ <For each={rects()}>
+ {(r) => (
+ <div
+ class="docx-selection absolute"
+ style={{
+ left: `${r.left}px`,
+ top: `${r.top}px`,
+ width: `${r.width}px`,
+ height: `${r.height}px`,
+ }}
+ />
+ )}
+ </For>
+ {props.overlay?.(geometry)}
+ <Show when={caret()}>
+ {(c) => (
+ <>
+ <Show when={showCaret()}>
+ <div
+ class="docx-caret absolute w-px"
+ data-docx-caret
+ style={{
+ left: `${c().left}px`,
+ top: `${c().top}px`,
+ height: `${c().height}px`,
+ }}
+ />
+ </Show>
+ <Show when={composing()}>
+ {(text) => (
+ <span
+ class="docx-composition absolute whitespace-pre"
+ style={{
+ left: `${c().left}px`,
+ top: `${c().top}px`,
+ 'font-size': `${c().height * 0.8}px`,
+ 'line-height': `${c().height}px`,
+ }}
+ >
+ {text()}
+ </span>
+ )}
+ </Show>
+ </>
+ )}
+ </Show>
+ </div>
+ <textarea
+ ref={(el) => {
+ input = el;
+ props.inputRef?.(el);
+ }}
+ class="absolute resize-none overflow-hidden border-0 bg-transparent p-0 opacity-0 outline-none"
+ style={{
+ left: `${caret()?.left ?? 0}px`,
+ top: `${caret()?.top ?? 0}px`,
+ width: '2px',
+ height: `${Math.max(caret()?.height ?? 16, 16)}px`,
+ 'font-size': '16px',
+ }}
+ aria-label="Document text"
+ aria-multiline="true"
+ readOnly={!props.editable}
+ autocapitalize="off"
+ autocomplete="off"
+ spellcheck={false}
+ data-docx-input
+ onFocus={() => setFocused(true)}
+ onBlur={() => setFocused(false)}
+ onKeyDown={onKeyDown}
+ onInput={(e) => onInput(e as InputEvent)}
+ onCompositionStart={() => setComposing('')}
+ onCompositionUpdate={(e) => setComposing(e.data)}
+ onCompositionEnd={(e) => {
+ setComposing(null);
+ input.value = '';
+ typeText(e.data);
+ }}
+ onPaste={onPaste}
+ onCopy={onCopy}
+ onCut={onCut}
+ />
+ </div>
+ );
+}
diff --git a/apps/web/src/features/block-write/views/DocxWordComment.tsx b/apps/web/src/features/block-write/views/DocxWordComment.tsx
new file mode 100644
index 0000000000..435ca2f901
--- /dev/null
+++ b/apps/web/src/features/block-write/views/DocxWordComment.tsx
@@ -0,0 +1,58 @@
+import type { DocComment } from '@core/docx-engine/types';
+import { For, Show } from 'solid-js';
+
+/** A comment date as the card shows it (the stored text when unparsable). */
+function shownDate(date: string) {
+ const parsed = new Date(date);
+ return Number.isNaN(parsed.getTime())
+ ? date
+ : parsed.toLocaleDateString(undefined, {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric',
+ });
+}
+
+/**
+ * A comment the document itself carries (written in Word), with its
+ * replies: read-only, beside the text it is on.
+ */
+export function DocxWordCommentCard(props: {
+ comment: DocComment;
+ replies: DocComment[];
+}) {
+ return (
+ <div
+ class="pointer-events-auto rounded-xl border border-edge bg-surface p-2 text-sm shadow-md shadow-drop-shadow"
+ data-docx-word-comment={props.comment.id}
+ >
+ <For each={[props.comment, ...props.replies]}>
+ {(comment, index) => (
+ <div
+ class="flex flex-col gap-0.5 px-1 py-1"
+ classList={{ 'border-t border-edge-muted': index() > 0 }}
+ >
+ <div class="flex items-baseline gap-2">
+ <span class="truncate font-medium text-ink">
+ {comment.author || 'Unknown author'}
+ </span>
+ <Show when={comment.date}>
+ {(date) => (
+ <span class="shrink-0 text-xs text-ink-muted">
+ {shownDate(date())}
+ </span>
+ )}
+ </Show>
+ </div>
+ <p class="whitespace-pre-wrap break-words text-ink">
+ {comment.text}
+ </p>
+ </div>
+ )}
+ </For>
+ <div class="px-1 pt-1 text-xs text-ink-extra-muted">
+ {props.comment.done ? 'In the document · Resolved' : 'In the document'}
+ </div>
+ </div>
+ );
+}
diff --git a/apps/web/src/lib/core/docx-engine/.gitignore b/apps/web/src/lib/core/docx-engine/.gitignore
new file mode 100644
index 0000000000..0d3be24eb1
--- /dev/null
+++ b/apps/web/src/lib/core/docx-engine/.gitignore
@@ -0,0 +1 @@
+wasm/
diff --git a/apps/web/src/lib/core/docx-engine/client.ts b/apps/web/src/lib/core/docx-engine/client.ts
new file mode 100644
index 0000000000..fd7bb99174
--- /dev/null
+++ b/apps/web/src/lib/core/docx-engine/client.ts
@@ -0,0 +1,309 @@
+/**
+ * The DOCX engine as the app calls it: async functions, worker behind them.
+ *
+ * One worker per tab, started on first use and kept, so the wasm module is
+ * compiled once however many documents are open. Each open document is
+ * addressed by a caller-chosen `docKey`.
+ */
+
+import type { DocxRequest, DocxResponse } from './protocol';
+import type {
+ CaretRect,
+ Clip,
+ CollabState,
+ DocComment,
+ EditOp,
+ EditResult,
+ FindOptions,
+ FindResult,
+ PageInfo,
+ PageRect,
+ ParagraphText,
+ Pos,
+ RemoteChange,
+ StyleInfo,
+ V1State,
+} from './types';
+
+type Ok = Extract<DocxResponse, { ok: true }>;
+
+interface Pending {
+ resolve: (response: Ok) => void;
+ reject: (error: Error) => void;
+}
+
+let worker: Worker | undefined;
+const pending = new Map<number, Pending>();
+let nextId = 0;
+
+/**
+ * Lazily constructed on purpose: on iOS, WKWebView deadlocks when a module
+ * Worker is constructed eagerly over `tauri://` (apps/web/AGENTS.md).
+ */
+function ensureWorker(): Worker {
+ if (worker) return worker;
+ const started = new Worker(new URL('./docx.worker.ts', import.meta.url), {
+ type: 'module',
+ });
+ started.addEventListener('message', (event: MessageEvent<DocxResponse>) => {
+ const response = event.data;
+ const waiting = pending.get(response.id);
+ if (!waiting) return;
+ pending.delete(response.id);
+ if (response.ok) waiting.resolve(response);
+ else waiting.reject(new Error(response.error));
+ });
+ started.addEventListener('error', (event) => {
+ // The worker died: nothing in flight will be answered, and every open
+ // document died with it.
+ const error = new Error(`docx engine worker failed: ${event.message}`);
+ for (const waiting of pending.values()) waiting.reject(error);
+ pending.clear();
+ worker = undefined;
+ });
+ worker = started;
+ return started;
+}
+
+type RequestBody = DocxRequest extends infer R
+ ? R extends { id: number }
+ ? Omit<R, 'id'>
+ : never
+ : never;
+
+function request<K extends Ok['kind']>(
+ body: RequestBody,
+ expect: K,
+ transfer: Transferable[] = []
+): Promise<Extract<Ok, { kind: K }>> {
+ const id = nextId++;
+ return new Promise((resolve, reject) => {
+ pending.set(id, {
+ resolve: (response) => {
+ if (response.kind === expect) {
+ resolve(response as Extract<Ok, { kind: K }>);
+ } else {
+ reject(
+ new Error(`unexpected ${response.kind} response to ${body.kind}`)
+ );
+ }
+ },
+ reject,
+ });
+ ensureWorker().postMessage({ ...body, id } as DocxRequest, transfer);
+ });
+}
+
+export type Opened = { pages: PageInfo[]; state: EditResult };
+
+/** Opens a `.docx` (the bytes are transferred to the worker). */
+export async function openDocument(
+ docKey: string,
+ bytes: ArrayBuffer
+): Promise<Opened> {
+ const r = await request({ kind: 'open', docKey, bytes }, 'open', [bytes]);
+ return { pages: r.pages, state: r.state };
+}
+
+/**
+ * Opens the document shared state describes. `seed` (unique per peer)
+ * keeps the ids of new blocks and parts from colliding.
+ */
+export async function openCollabDocument(
+ docKey: string,
+ state: CollabState,
+ seed: number
+): Promise<Opened> {
+ const r = await request(
+ { kind: 'openCollab', docKey, state: JSON.stringify(state), seed },
+ 'open'
+ );
+ return { pages: r.pages, state: r.state };
+}
+
+/** Opens a document stored in the first shared format. */
+export async function openV1Document(
+ docKey: string,
+ state: V1State
+): Promise<Opened> {
+ const r = await request(
+ { kind: 'openV1', docKey, state: JSON.stringify(state) },
+ 'open'
+ );
+ return { pages: r.pages, state: r.state };
+}
+
+/** The document's shared state. */
+export async function collabState(docKey: string): Promise<CollabState> {
+ const r = await request({ kind: 'collabState', docKey }, 'collabState');
+ return JSON.parse(r.state) as CollabState;
+}
+
+export async function closeDocument(docKey: string): Promise<void> {
+ await request({ kind: 'close', docKey }, 'close');
+}
+
+/** Applies operations (one undo step, merged with the last of the same `group`). */
+export async function applyOps(
+ docKey: string,
+ ops: EditOp[],
+ group?: string
+): Promise<EditResult | null> {
+ const r = await request(
+ { kind: 'apply', docKey, ops: JSON.stringify(ops), group },
+ 'edit'
+ );
+ return r.result;
+}
+
+/** Applies other peers' changes. */
+export async function applyRemote(
+ docKey: string,
+ changes: RemoteChange[]
+): Promise<EditResult | null> {
+ const r = await request(
+ { kind: 'applyRemote', docKey, changes: JSON.stringify(changes) },
+ 'edit'
+ );
+ return r.result;
+}
+
+export async function currentState(docKey: string): Promise<EditResult | null> {
+ const r = await request({ kind: 'state', docKey }, 'edit');
+ return r.result;
+}
+
+/** Shows tracked changes inline (`true`) or the final text. */
+export async function setMarkup(
+ docKey: string,
+ markup: boolean
+): Promise<EditResult | null> {
+ const r = await request({ kind: 'setMarkup', docKey, markup }, 'edit');
+ return r.result;
+}
+
+/** Leaves undo history to the shared document's undo manager. */
+export async function setExternalUndo(
+ docKey: string,
+ external: boolean
+): Promise<void> {
+ await request({ kind: 'setExternalUndo', docKey, external }, 'done');
+}
+
+/** The name tracked changes are recorded under. */
+export async function setAuthor(docKey: string, author: string) {
+ await request({ kind: 'setAuthor', docKey, author }, 'done');
+}
+
+export async function breakGroup(docKey: string): Promise<void> {
+ await request({ kind: 'breakGroup', docKey }, 'done');
+}
+
+export async function undo(docKey: string): Promise<EditResult | null> {
+ const r = await request({ kind: 'undo', docKey }, 'edit');
+ return r.result;
+}
+
+export async function redo(docKey: string): Promise<EditResult | null> {
+ const r = await request({ kind: 'redo', docKey }, 'edit');
+ return r.result;
+}
+
+export type Rendered = { bitmap: ImageBitmap; millis: number };
+
+/** Renders a page `width` pixels wide. */
+export async function renderPage(
+ docKey: string,
+ page: number,
+ width: number
+): Promise<Rendered> {
+ const r = await request({ kind: 'render', docKey, page, width }, 'render');
+ return { bitmap: r.bitmap, millis: r.millis };
+}
+
+/** Renders a strip (`top..bottom` points) of a page `width` pixels wide. */
+export async function renderBand(
+ docKey: string,
+ page: number,
+ width: number,
+ top: number,
+ bottom: number
+): Promise<Rendered> {
+ const r = await request(
+ { kind: 'renderBand', docKey, page, width, top, bottom },
+ 'render'
+ );
+ return { bitmap: r.bitmap, millis: r.millis };
+}
+
+/** The position at a point on a page (points). */
+export async function hitTest(
+ docKey: string,
+ page: number,
+ x: number,
+ y: number
+): Promise<Pos | null> {
+ const r = await request({ kind: 'hitTest', docKey, page, x, y }, 'pos');
+ return r.pos;
+}
+
+export async function caretAt(
+ docKey: string,
+ pos: Pos
+): Promise<CaretRect | null> {
+ const r = await request({ kind: 'caretAt', docKey, pos }, 'caret');
+ return r.caret;
+}
+
+export async function rangeRects(
+ docKey: string,
+ from: Pos,
+ to: Pos
+): Promise<PageRect[]> {
+ const r = await request({ kind: 'rangeRects', docKey, from, to }, 'rects');
+ return r.rects;
+}
+
+/** The selection for the clipboard: paragraphs, HTML and plain text. */
+export async function copySelection(docKey: string): Promise<Clip> {
+ const r = await request({ kind: 'copySelection', docKey }, 'clip');
+ return r.clip;
+}
+
+/** The matches of a search in the body, with their highlights. */
+export async function find(
+ docKey: string,
+ query: string,
+ options: FindOptions = {}
+): Promise<FindResult> {
+ const r = await request({ kind: 'find', docKey, query, options }, 'find');
+ return r.result;
+}
+
+/** The selected text, for the clipboard. */
+export async function selectedText(docKey: string): Promise<string> {
+ const r = await request({ kind: 'selectedText', docKey }, 'text');
+ return r.text;
+}
+
+/** The comments stored in the document (Word's). */
+export async function documentComments(docKey: string): Promise<DocComment[]> {
+ const r = await request({ kind: 'documentComments', docKey }, 'comments');
+ return r.comments;
+}
+
+export async function paragraphs(docKey: string): Promise<ParagraphText[]> {
+ const r = await request({ kind: 'paragraphs', docKey }, 'paragraphs');
+ return r.paragraphs;
+}
+
+export async function styles(docKey: string): Promise<StyleInfo[]> {
+ const r = await request({ kind: 'styles', docKey }, 'styles');
+ return r.styles;
+}
+
+/** Serializes the document to `.docx` bytes. */
+export async function saveDocument(docKey: string): Promise<Uint8Array> {
+ const r = await request({ kind: 'save', docKey }, 'save');
+ return new Uint8Array(r.bytes);
+}
diff --git a/apps/web/src/lib/core/docx-engine/docx.worker.ts b/apps/web/src/lib/core/docx-engine/docx.worker.ts
new file mode 100644
index 0000000000..be2a35b66c
--- /dev/null
+++ b/apps/web/src/lib/core/docx-engine/docx.worker.ts
@@ -0,0 +1,448 @@
+/// <reference lib="webworker" />
+
+/**
+ * Hosts the DOCX engine (Rust compiled to wasm) off the main thread.
+ *
+ * Parsing, layout, rasterization, editing and saving all happen here, so
+ * the editor's UI thread only composites bitmaps and positions overlays.
+ * Rendered pages and strips come back as transferable `ImageBitmap`s.
+ * Requests are served one at a time in the order they were posted, which
+ * keeps edits, renders and saves consistent.
+ */
+
+import { match } from 'ts-pattern';
+import type { DocxRequest, DocxResponse } from './protocol';
+import type {
+ CaretRect,
+ Clip,
+ DocComment,
+ EditResult,
+ FindResult,
+ PageInfo,
+ PageRect,
+ ParagraphText,
+ Pos,
+ StyleInfo,
+} from './types';
+import {
+ discardDocxEngineWasm,
+ isWasmTrap,
+ loadDocxEngineWasm,
+ type WasmDocxDocument,
+} from './wasm-module';
+
+const scope = self as unknown as DedicatedWorkerGlobalScope;
+
+/** A state change, replayed onto a fresh instance after a trap. */
+type LogEntry =
+ | { kind: 'apply'; ops: string; group?: string }
+ | { kind: 'applyRemote'; changes: string }
+ | { kind: 'undo' }
+ | { kind: 'redo' }
+ | { kind: 'breakGroup' }
+ | { kind: 'setMarkup'; markup: boolean }
+ | { kind: 'setExternalUndo'; external: boolean }
+ | { kind: 'setAuthor'; author: string };
+
+/** What a document was opened from. */
+type Source =
+ | { kind: 'bytes'; bytes: Uint8Array }
+ | { kind: 'collab'; state: string; seed: number }
+ | { kind: 'v1'; state: string };
+
+interface OpenDocument {
+ doc: WasmDocxDocument;
+ source: Source;
+ /** Every change since opening, in order. */
+ log: LogEntry[];
+}
+
+const documents = new Map<string, OpenDocument>();
+
+let queue: Promise<void> = Promise.resolve();
+
+function entryFor(docKey: string): OpenDocument {
+ const entry = documents.get(docKey);
+ if (!entry) throw new Error(`document ${docKey} is not open`);
+ return entry;
+}
+
+function documentFor(docKey: string): WasmDocxDocument {
+ return entryFor(docKey).doc;
+}
+
+/** Applies a change and records it for replay. */
+function record<T>(
+ docKey: string,
+ entry: LogEntry,
+ run: (doc: WasmDocxDocument) => T
+): T {
+ const open = entryFor(docKey);
+ const result = run(open.doc);
+ open.log.push(entry);
+ return result;
+}
+
+type WasmModule = Awaited<ReturnType<typeof loadDocxEngineWasm>>;
+
+function openSource(wasm: WasmModule, source: Source): WasmDocxDocument {
+ return match(source)
+ .with({ kind: 'bytes' }, ({ bytes }) => new wasm.DocxDocument(bytes))
+ .with({ kind: 'collab' }, ({ state, seed }) =>
+ wasm.DocxDocument.fromCollab(state, seed)
+ )
+ .with({ kind: 'v1' }, ({ state }) => wasm.DocxDocument.fromV1(state))
+ .exhaustive();
+}
+
+/**
+ * A Rust panic traps the wasm instance and can leave its objects unusable.
+ * Start a fresh instance and rebuild every open document from its source
+ * and change log, so no edit is lost.
+ */
+async function recover() {
+ discardDocxEngineWasm();
+ const wasm = await loadDocxEngineWasm();
+ for (const [key, open] of [...documents]) {
+ try {
+ const doc = openSource(wasm, open.source);
+ // Replaying the same calls in order also replays the same random ids.
+ for (const step of open.log) {
+ match(step)
+ .with({ kind: 'apply' }, ({ ops, group }) => doc.apply(ops, group))
+ .with({ kind: 'applyRemote' }, ({ changes }) =>
+ doc.applyRemote(changes)
+ )
+ .with({ kind: 'undo' }, () => doc.undo())
+ .with({ kind: 'redo' }, () => doc.redo())
+ .with({ kind: 'breakGroup' }, () => doc.breakGroup())
+ .with({ kind: 'setMarkup' }, ({ markup }) => doc.setMarkup(markup))
+ .with({ kind: 'setExternalUndo' }, ({ external }) =>
+ doc.setExternalUndo(external)
+ )
+ .with({ kind: 'setAuthor' }, ({ author }) => doc.setAuthor(author))
+ .exhaustive();
+ }
+ open.doc = doc;
+ } catch {
+ documents.delete(key);
+ }
+ }
+}
+
+async function toBitmap(
+ pixels: Uint8Array,
+ width: number
+): Promise<ImageBitmap> {
+ const height = Math.max(1, Math.round(pixels.length / 4 / width));
+ const clamped = new Uint8ClampedArray(
+ pixels.buffer as ArrayBuffer,
+ pixels.byteOffset,
+ pixels.byteLength
+ );
+ return createImageBitmap(new ImageData(clamped, width, height));
+}
+
+type Served = [DocxResponse, Transferable[]];
+
+function edit(id: number, json: string | undefined): Served {
+ return [
+ {
+ id,
+ ok: true,
+ kind: 'edit',
+ result: json ? (JSON.parse(json) as EditResult) : null,
+ },
+ [],
+ ];
+}
+
+function opened(id: number, doc: WasmDocxDocument): Served {
+ return [
+ {
+ id,
+ ok: true,
+ kind: 'open',
+ pages: JSON.parse(doc.pages()) as PageInfo[],
+ state: JSON.parse(doc.state()) as EditResult,
+ },
+ [],
+ ];
+}
+
+function install(docKey: string, doc: WasmDocxDocument, source: Source) {
+ documents.get(docKey)?.doc.free();
+ documents.set(docKey, { doc, source, log: [] });
+}
+
+async function serve(request: DocxRequest): Promise<Served> {
+ const wasm = await loadDocxEngineWasm();
+ const { id } = request;
+ return match(request)
+ .with({ kind: 'open' }, ({ docKey, bytes }): Served => {
+ const source: Source = { kind: 'bytes', bytes: new Uint8Array(bytes) };
+ // Parse first: a file that fails to open leaves the current one in place.
+ const doc = openSource(wasm, source);
+ install(docKey, doc, source);
+ return opened(id, doc);
+ })
+ .with({ kind: 'openCollab' }, ({ docKey, state, seed }): Served => {
+ const source: Source = { kind: 'collab', state, seed };
+ const doc = openSource(wasm, source);
+ install(docKey, doc, source);
+ return opened(id, doc);
+ })
+ .with({ kind: 'openV1' }, ({ docKey, state }): Served => {
+ const source: Source = { kind: 'v1', state };
+ const doc = openSource(wasm, source);
+ install(docKey, doc, source);
+ return opened(id, doc);
+ })
+ .with(
+ { kind: 'collabState' },
+ ({ docKey }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'collabState',
+ state: documentFor(docKey).collabState(),
+ },
+ [],
+ ]
+ )
+ .with({ kind: 'close' }, ({ docKey }): Served => {
+ documents.get(docKey)?.doc.free();
+ documents.delete(docKey);
+ return [{ id, ok: true, kind: 'close' }, []];
+ })
+ .with({ kind: 'apply' }, ({ docKey, ops, group }) =>
+ edit(
+ id,
+ record(docKey, { kind: 'apply', ops, group }, (doc) =>
+ doc.apply(ops, group)
+ )
+ )
+ )
+ .with({ kind: 'applyRemote' }, ({ docKey, changes }) =>
+ edit(
+ id,
+ record(docKey, { kind: 'applyRemote', changes }, (doc) =>
+ doc.applyRemote(changes)
+ )
+ )
+ )
+ .with({ kind: 'state' }, ({ docKey }) =>
+ edit(id, documentFor(docKey).state())
+ )
+ .with({ kind: 'setMarkup' }, ({ docKey, markup }) =>
+ edit(
+ id,
+ record(docKey, { kind: 'setMarkup', markup }, (doc) =>
+ doc.setMarkup(markup)
+ )
+ )
+ )
+ .with({ kind: 'setAuthor' }, ({ docKey, author }): Served => {
+ record(docKey, { kind: 'setAuthor', author }, (doc) =>
+ doc.setAuthor(author)
+ );
+ return [{ id, ok: true, kind: 'done' }, []];
+ })
+ .with({ kind: 'setExternalUndo' }, ({ docKey, external }): Served => {
+ record(docKey, { kind: 'setExternalUndo', external }, (doc) =>
+ doc.setExternalUndo(external)
+ );
+ return [{ id, ok: true, kind: 'done' }, []];
+ })
+ .with({ kind: 'breakGroup' }, ({ docKey }): Served => {
+ record(docKey, { kind: 'breakGroup' }, (doc) => doc.breakGroup());
+ return [{ id, ok: true, kind: 'done' }, []];
+ })
+ .with({ kind: 'undo' }, ({ docKey }) =>
+ edit(
+ id,
+ record(docKey, { kind: 'undo' }, (doc) => doc.undo())
+ )
+ )
+ .with({ kind: 'redo' }, ({ docKey }) =>
+ edit(
+ id,
+ record(docKey, { kind: 'redo' }, (doc) => doc.redo())
+ )
+ )
+ .with(
+ { kind: 'render' },
+ async ({ docKey, page, width }): Promise<Served> => {
+ const started = performance.now();
+ const pixels = documentFor(docKey).render(page, width);
+ const bitmap = await toBitmap(pixels, width);
+ const millis = performance.now() - started;
+ return [{ id, ok: true, kind: 'render', bitmap, millis }, [bitmap]];
+ }
+ )
+ .with(
+ { kind: 'renderBand' },
+ async ({ docKey, page, width, top, bottom }): Promise<Served> => {
+ const started = performance.now();
+ const pixels = documentFor(docKey).renderBand(page, width, top, bottom);
+ const bitmap = await toBitmap(pixels, width);
+ const millis = performance.now() - started;
+ return [{ id, ok: true, kind: 'render', bitmap, millis }, [bitmap]];
+ }
+ )
+ .with(
+ { kind: 'hitTest' },
+ ({ docKey, page, x, y }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'pos',
+ pos: JSON.parse(
+ documentFor(docKey).hitTest(page, x, y)
+ ) as Pos | null,
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'caretAt' },
+ ({ docKey, pos }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'caret',
+ caret: JSON.parse(
+ documentFor(docKey).caretAt(JSON.stringify(pos))
+ ) as CaretRect | null,
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'rangeRects' },
+ ({ docKey, from, to }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'rects',
+ rects: JSON.parse(
+ documentFor(docKey).rangeRects(
+ JSON.stringify(from),
+ JSON.stringify(to)
+ )
+ ) as PageRect[],
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'copySelection' },
+ ({ docKey }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'clip',
+ clip: JSON.parse(documentFor(docKey).copySelection()) as Clip,
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'find' },
+ ({ docKey, query, options }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'find',
+ result: JSON.parse(
+ documentFor(docKey).find(query, JSON.stringify(options))
+ ) as FindResult,
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'selectedText' },
+ ({ docKey }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'text',
+ text: documentFor(docKey).selectedText(),
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'documentComments' },
+ ({ docKey }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'comments',
+ comments: JSON.parse(
+ documentFor(docKey).documentComments()
+ ) as DocComment[],
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'paragraphs' },
+ ({ docKey }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'paragraphs',
+ paragraphs: JSON.parse(
+ documentFor(docKey).paragraphs()
+ ) as ParagraphText[],
+ },
+ [],
+ ]
+ )
+ .with(
+ { kind: 'styles' },
+ ({ docKey }): Served => [
+ {
+ id,
+ ok: true,
+ kind: 'styles',
+ styles: JSON.parse(documentFor(docKey).styles()) as StyleInfo[],
+ },
+ [],
+ ]
+ )
+ .with({ kind: 'save' }, ({ docKey }): Served => {
+ const saved = documentFor(docKey).save();
+ const bytes = saved.buffer.slice(
+ saved.byteOffset,
+ saved.byteOffset + saved.byteLength
+ ) as ArrayBuffer;
+ return [{ id, ok: true, kind: 'save', bytes }, [bytes]];
+ })
+ .exhaustive();
+}
+
+scope.addEventListener('message', (event: MessageEvent<DocxRequest>) => {
+ const request = event.data;
+ queue = queue.then(async () => {
+ try {
+ const [response, transfer] = await serve(request);
+ scope.postMessage(response, transfer);
+ } catch (error) {
+ let message = error instanceof Error ? error.message : String(error);
+ if (isWasmTrap(error)) {
+ await recover().catch(() => {});
+ message =
+ 'The document engine hit a problem with this request and was restarted. Your changes are kept.';
+ }
+ const response: DocxResponse = {
+ id: request.id,
+ ok: false,
+ error: message,
+ };
+ scope.postMessage(response);
+ }
+ });
+});
diff --git a/apps/web/src/lib/core/docx-engine/protocol.ts b/apps/web/src/lib/core/docx-engine/protocol.ts
new file mode 100644
index 0000000000..7a8aec5d12
--- /dev/null
+++ b/apps/web/src/lib/core/docx-engine/protocol.ts
@@ -0,0 +1,87 @@
+/**
+ * The messages exchanged with the DOCX engine worker.
+ *
+ * Requests and responses are correlated by `id`. The worker holds every open
+ * document by `docKey` and serves requests strictly in order, so an edit is
+ * always applied before a render posted after it.
+ */
+
+import type {
+ CaretRect,
+ Clip,
+ DocComment,
+ EditResult,
+ FindOptions,
+ FindResult,
+ PageInfo,
+ PageRect,
+ ParagraphText,
+ Pos,
+ StyleInfo,
+} from './types';
+
+interface Base {
+ id: number;
+ docKey: string;
+}
+
+export type DocxRequest =
+ | (Base & { kind: 'open'; bytes: ArrayBuffer })
+ /** Opens shared state (`CollabState` JSON); `seed` is unique per peer. */
+ | (Base & { kind: 'openCollab'; state: string; seed: number })
+ /** Opens a document in the first shared format (`V1State` JSON). */
+ | (Base & { kind: 'openV1'; state: string })
+ | (Base & { kind: 'collabState' })
+ | (Base & { kind: 'close' })
+ | (Base & { kind: 'apply'; ops: string; group?: string })
+ | (Base & { kind: 'applyRemote'; changes: string })
+ | (Base & { kind: 'state' })
+ | (Base & { kind: 'setMarkup'; markup: boolean })
+ | (Base & { kind: 'setExternalUndo'; external: boolean })
+ | (Base & { kind: 'setAuthor'; author: string })
+ | (Base & { kind: 'breakGroup' })
+ | (Base & { kind: 'undo' })
+ | (Base & { kind: 'redo' })
+ | (Base & { kind: 'render'; page: number; width: number })
+ | (Base & {
+ kind: 'renderBand';
+ page: number;
+ width: number;
+ top: number;
+ bottom: number;
+ })
+ | (Base & { kind: 'hitTest'; page: number; x: number; y: number })
+ | (Base & { kind: 'caretAt'; pos: Pos })
+ | (Base & { kind: 'rangeRects'; from: Pos; to: Pos })
+ | (Base & { kind: 'selectedText' })
+ | (Base & { kind: 'copySelection' })
+ | (Base & { kind: 'find'; query: string; options: FindOptions })
+ | (Base & { kind: 'paragraphs' })
+ | (Base & { kind: 'documentComments' })
+ | (Base & { kind: 'styles' })
+ | (Base & { kind: 'save' });
+
+export type DocxResponse =
+ | { id: number; ok: true; kind: 'open'; pages: PageInfo[]; state: EditResult }
+ | { id: number; ok: true; kind: 'close' }
+ | { id: number; ok: true; kind: 'collabState'; state: string }
+ | { id: number; ok: true; kind: 'edit'; result: EditResult | null }
+ | {
+ id: number;
+ ok: true;
+ kind: 'render';
+ bitmap: ImageBitmap;
+ millis: number;
+ }
+ | { id: number; ok: true; kind: 'pos'; pos: Pos | null }
+ | { id: number; ok: true; kind: 'caret'; caret: CaretRect | null }
+ | { id: number; ok: true; kind: 'rects'; rects: PageRect[] }
+ | { id: number; ok: true; kind: 'text'; text: string }
+ | { id: number; ok: true; kind: 'clip'; clip: Clip }
+ | { id: number; ok: true; kind: 'find'; result: FindResult }
+ | { id: number; ok: true; kind: 'paragraphs'; paragraphs: ParagraphText[] }
+ | { id: number; ok: true; kind: 'comments'; comments: DocComment[] }
+ | { id: number; ok: true; kind: 'styles'; styles: StyleInfo[] }
+ | { id: number; ok: true; kind: 'save'; bytes: ArrayBuffer }
+ | { id: number; ok: true; kind: 'done' }
+ | { id: number; ok: false; error: string };
diff --git a/apps/web/src/lib/core/docx-engine/types.ts b/apps/web/src/lib/core/docx-engine/types.ts
new file mode 100644
index 0000000000..8299191b01
--- /dev/null
+++ b/apps/web/src/lib/core/docx-engine/types.ts
@@ -0,0 +1,339 @@
+/**
+ * Types of the DOCX engine's JSON API. They mirror the Rust serde shapes in
+ * `crates/docx_engine` (`edit`, `collab`); positions and sizes are points.
+ */
+
+/** A position in the body: a paragraph and a UTF-16 offset in its text. */
+export type Pos = {
+ block: string;
+ offset: number;
+ /** At a line wrap, show the caret at the end of the earlier line. */
+ upstream?: boolean;
+};
+
+export type Selection = { anchor: Pos; focus: Pos };
+
+export type Unit =
+ | 'char'
+ | 'word'
+ | 'line'
+ | 'lineBoundary'
+ | 'paragraph'
+ | 'document';
+
+export type BreakKind = 'line' | 'page' | 'column';
+
+export type ListKind = 'bullet' | 'number';
+
+export type Toggle =
+ | 'bold'
+ | 'italic'
+ | 'underline'
+ | 'strike'
+ | 'superscript'
+ | 'subscript'
+ | 'smallCaps'
+ | 'allCaps';
+
+export type Alignment = 'left' | 'center' | 'right' | 'justify';
+
+export type Spacing = { rule: 'auto' | 'exact' | 'atLeast'; value: number };
+
+/** Character formatting: a present field sets (or with `null` clears) it. */
+export type RunPatch = {
+ font?: string | null;
+ size?: number | null;
+ /** `RRGGBB`. */
+ color?: string | null;
+ /** A Word highlight name (`yellow`, `green`, ...). */
+ highlight?: string | null;
+};
+
+export type ParaPatch = {
+ align?: Alignment;
+ indentLeft?: number;
+ indentRight?: number;
+ /** Negative for a hanging indent. */
+ firstLine?: number;
+ spaceBefore?: number;
+ spaceAfter?: number;
+ lineSpacing?: Spacing;
+ keepNext?: boolean;
+ keepLines?: boolean;
+ pageBreakBefore?: boolean;
+ widowControl?: boolean;
+};
+
+export type EditOp =
+ | { op: 'select'; anchor: Pos; focus: Pos }
+ /**
+ * Move the caret (or extend the selection). With `visual` (arrow keys),
+ * `forward` means rightwards, which is backwards in right-to-left text.
+ */
+ | {
+ op: 'move';
+ unit?: Unit;
+ forward: boolean;
+ extend?: boolean;
+ visual?: boolean;
+ }
+ | { op: 'selectAll' }
+ | { op: 'selectWord'; at: Pos }
+ | { op: 'selectParagraph'; at: Pos }
+ | { op: 'insertText'; text: string }
+ | { op: 'insertParagraph' }
+ | { op: 'insertBreak'; kind: BreakKind }
+ /** A footnote (or endnote) at the caret; the caret moves into it. */
+ | { op: 'insertNote'; endnote?: boolean }
+ | { op: 'delete'; forward: boolean; unit?: Unit }
+ | { op: 'toggleFormat'; format: Toggle }
+ | ({ op: 'setFormat' } & RunPatch)
+ | { op: 'clearFormat' }
+ | ({ op: 'setParagraph' } & ParaPatch)
+ | { op: 'setStyle'; style: string }
+ | { op: 'toggleList'; kind: ListKind }
+ | { op: 'indent'; forward: boolean }
+ | { op: 'insertTable'; rows: number; cols: number }
+ | { op: 'insertRow'; below: boolean }
+ | { op: 'insertColumn'; right: boolean }
+ | { op: 'deleteRow' }
+ | { op: 'deleteColumn' }
+ | { op: 'deleteTable' }
+ /** Edit the header, footer or body at a point on a page (points). */
+ | { op: 'enterStory'; page: number; x: number; y: number }
+ /** Back from a header or footer to the body. */
+ | { op: 'exitStory' }
+ /** Turn tracking changes on or off for the document. */
+ | { op: 'setTracking'; on: boolean }
+ /** Accept the changes in the selection (the one at a caret), or all. */
+ | { op: 'acceptChanges'; all?: boolean }
+ /** Reject the changes in the selection (the one at a caret), or all. */
+ | { op: 'rejectChanges'; all?: boolean }
+ /** Paste paragraphs over the selection. */
+ | { op: 'paste'; paragraphs: ClipParagraph[]; sameDocument?: boolean }
+ /**
+ * Replace matches of a search in the body: every match with `all`,
+ * otherwise the one the selection holds, then select the next one (with
+ * no match selected, only select the next one).
+ */
+ | {
+ op: 'replace';
+ query: string;
+ options?: FindOptions;
+ with: string;
+ all?: boolean;
+ };
+
+export type CaretRect = { page: number; x: number; y: number; height: number };
+
+export type PageRect = {
+ page: number;
+ x: number;
+ y: number;
+ w: number;
+ h: number;
+};
+
+/** A page's header or footer area (points). */
+export type PageArea = {
+ top: number;
+ bottom: number;
+ /** Whether the section has a header or footer part there to edit. */
+ editable: boolean;
+};
+
+export type PageInfo = {
+ width: number;
+ height: number;
+ fingerprint: string;
+ header?: PageArea;
+ footer?: PageArea;
+ /** Where the page's footnotes and endnotes are. */
+ notes?: PageArea;
+};
+
+/** The story the selection is in. */
+export type StoryState = {
+ kind: 'body' | 'header' | 'footer' | 'footnote' | 'endnote';
+ /** The page whose header or footer (or the first showing the note) is
+ * being edited. */
+ page?: number;
+};
+
+/** A horizontal strip of a page that changed. */
+export type Band = { page: number; top: number; bottom: number };
+
+export type FormatState = {
+ bold: boolean;
+ italic: boolean;
+ underline: boolean;
+ strike: boolean;
+ superscript: boolean;
+ subscript: boolean;
+ font: string | null;
+ size: number | null;
+ color: string | null;
+ /** A Word highlight name (`yellow`, ...), when highlighted. */
+ highlight: string | null;
+ style: string | null;
+ styleName: string | null;
+ align: Alignment | null;
+ list: boolean;
+ /** Line spacing as a multiple of single spacing, when it is one. */
+ lineSpacing: number | null;
+ /** The selection starts in a table. */
+ table: boolean;
+ /** The document records everyone's edits as tracked changes. */
+ tracking: boolean;
+ /** The selection (or the caret) touches a tracked change. */
+ revision: boolean;
+ canUndo: boolean;
+ canRedo: boolean;
+};
+
+/** One op of a rich-text delta (Quill's format, as Loro reads and writes it). */
+export type DeltaOp =
+ | { insert: string; attributes?: Record<string, string> }
+ | { delete: number }
+ | { retain: number; attributes?: Record<string, string | null> };
+
+/** A block as the shared maps store it. */
+export type BlockRecord = {
+ id: string;
+ /** Kind: `p`, `tbl`, `tr`, `tc`, `sdt` or `x`. */
+ k: string;
+ /** Parent block id (`''` at the top level). */
+ p: string;
+ /** Position key among siblings. */
+ o: string;
+ /** Element attributes. */
+ a: string;
+ /** Property XML. */
+ x: string;
+ /** Paragraph text (paragraphs only). */
+ t?: DeltaOp[];
+};
+
+/** A change the engine made, for the shared maps. */
+export type Change =
+ | { t: 'block'; block: BlockRecord }
+ | { t: 'fields'; id: string; fields: Record<string, string> }
+ | { t: 'text'; id: string; delta: DeltaOp[] }
+ | { t: 'remove'; id: string }
+ | { t: 'entry'; container: string; key: string; value: string | null };
+
+/** A run of copied or pasted text. */
+export type ClipRun = {
+ text: string;
+ /** The run's attributes, from a copy in this editor. */
+ attrs?: Record<string, string>;
+ bold?: boolean;
+ italic?: boolean;
+ underline?: boolean;
+ strike?: boolean;
+ superscript?: boolean;
+ subscript?: boolean;
+};
+
+/** A copied or pasted paragraph. */
+export type ClipParagraph = {
+ runs: ClipRun[];
+ /** Paragraph properties (`w:pPr`), from a copy in this editor. */
+ props?: string;
+ /** Heading level, 1 to 9. */
+ heading?: number;
+ list?: ListKind;
+ /** List level, 0 for the outermost. */
+ level?: number;
+};
+
+/** What a selection copies. */
+export type Clip = { paragraphs: ClipParagraph[]; html: string; text: string };
+
+/** How a search compares text. */
+export type FindOptions = { matchCase?: boolean; wholeWord?: boolean };
+
+/** One match of a search, with its highlight rectangles. */
+export type FindMatch = { from: Pos; to: Pos; rects: PageRect[] };
+
+/** The matches of a search in document order. */
+export type FindResult = {
+ matches: FindMatch[];
+ /** The match at the selection, or the first one after it. */
+ current?: number;
+ /** The search stopped at its limit (10,000 matches). */
+ truncated?: boolean;
+};
+
+/** A change other peers made, as the shared maps now hold it. */
+export type RemoteChange =
+ | {
+ t: 'block';
+ block: BlockRecord;
+ /**
+ * The text changes from the engine's copy of the paragraph to this
+ * one, in order, when known: carets follow them exactly.
+ */
+ deltas?: DeltaOp[][];
+ }
+ | { t: 'remove'; id: string }
+ | { t: 'entry'; container: string; key: string; value: string | null };
+
+export type EditResult = {
+ changed: boolean;
+ changes: Change[];
+ selection: Selection;
+ /** The selection's ends in document order. */
+ range: { from: Pos; to: Pos };
+ caret: CaretRect | null;
+ rects: PageRect[];
+ /** Present when the layout changed. */
+ pages?: PageInfo[];
+ /** Strips of pages that changed since the previous result. */
+ bands?: Band[];
+ format: FormatState;
+ story: StoryState;
+};
+
+/** The whole shared state of a document. */
+export type CollabState = {
+ parts: Record<string, string>;
+ types: Record<string, string>;
+ rels: Record<string, string>;
+ blocks: BlockRecord[];
+};
+
+/** A document in the first shared format. */
+export type V1State = {
+ order: string[];
+ blocks: Record<string, string>;
+ parts: Record<string, string>;
+};
+
+export type ParagraphText = { id: string; text: string };
+
+/** A comment stored in the document (Word's comments part). */
+export type DocComment = {
+ id: string;
+ author: string;
+ initials?: string;
+ /** ISO 8601, as written. */
+ date?: string;
+ /** Paragraphs separated by newlines. */
+ text: string;
+ /** The commented text. */
+ from: Pos;
+ to: Pos;
+ /** The comment it replies to. */
+ parent?: string;
+ /** Marked done (resolved). */
+ done: boolean;
+};
+
+export type StyleInfo = {
+ id: string;
+ name: string;
+ /** Shown in the quick style gallery. */
+ quick: boolean;
+ priority: number;
+};
diff --git a/apps/web/src/lib/core/docx-engine/wasm-module.ts b/apps/web/src/lib/core/docx-engine/wasm-module.ts
new file mode 100644
index 0000000000..c9232978f2
--- /dev/null
+++ b/apps/web/src/lib/core/docx-engine/wasm-module.ts
@@ -0,0 +1,130 @@
+/**
+ * Typed surface of the generated wasm package (`docx_engine`), loaded
+ * dynamically so the repo type-checks without the generated artifacts.
+ *
+ * Build the package with:
+ * just build-docx-engine-wasm
+ * which runs wasm-pack over crates/docx_engine into
+ * src/lib/core/docx-engine/wasm/ (gitignored).
+ */
+
+/**
+ * One open document with its editing session. Mirrors
+ * `docx_engine::wasm::DocxDocument`. Structured results are JSON strings;
+ * every method throws an `Error` when the engine rejects the call.
+ */
+export interface WasmDocxDocument {
+ /** The shared state (`CollabState` JSON). */
+ collabState: () => string;
+ setExternalUndo: (external: boolean) => void;
+ setAuthor: (author: string) => void;
+ /** Applies an `EditOp[]` JSON batch; returns `EditResult` JSON. */
+ apply: (ops: string, group?: string) => string;
+ /** Applies `RemoteChange[]` JSON; returns `EditResult` JSON. */
+ applyRemote: (changes: string) => string;
+ /** `EditResult` JSON for the current state. */
+ state: () => string;
+ /** `PageInfo[]` JSON. */
+ pages: () => string;
+ /** Straight-alpha RGBA, `width × height × 4` bytes. */
+ render: (page: number, width: number) => Uint8Array;
+ /** A strip of a page (`top..bottom` points) at the page width `width`. */
+ renderBand: (
+ page: number,
+ width: number,
+ top: number,
+ bottom: number
+ ) => Uint8Array;
+ /** `Pos` JSON or `null`. */
+ hitTest: (page: number, x: number, y: number) => string;
+ /** `CaretRect` JSON or `null`. */
+ caretAt: (pos: string) => string;
+ /** `PageRect[]` JSON. */
+ rangeRects: (from: string, to: string) => string;
+ /** The selected text, for the clipboard. */
+ selectedText: () => string;
+ copySelection: () => string;
+ /** `FindResult` JSON; `options` is `FindOptions` JSON. */
+ find: (query: string, options: string) => string;
+ /** `ParagraphText[]` JSON. */
+ paragraphs: () => string;
+ /** `DocComment[]` JSON. */
+ documentComments: () => string;
+ /** `StyleInfo[]` JSON. */
+ styles: () => string;
+ /** Shows tracked changes inline or not; returns `EditResult` JSON. */
+ setMarkup: (markup: boolean) => string;
+ breakGroup: () => void;
+ undo: () => string | undefined;
+ redo: () => string | undefined;
+ canUndo: () => boolean;
+ canRedo: () => boolean;
+ save: () => Uint8Array;
+ /** JSON array of requested font families that are not available. */
+ missingFonts: () => string;
+ free: () => void;
+}
+
+interface DocxEngineWasmModule {
+ default: (input?: { module_or_path?: unknown }) => Promise<unknown>;
+ DocxDocument: {
+ new (bytes: Uint8Array): WasmDocxDocument;
+ /** Opens the document a `CollabState` JSON describes. */
+ fromCollab: (state: string, seed: number) => WasmDocxDocument;
+ /** Opens a document stored in the first shared format (`V1State` JSON). */
+ fromV1: (state: string) => WasmDocxDocument;
+ };
+ registerFont: (bytes: Uint8Array) => number;
+}
+
+let modulePromise: Promise<DocxEngineWasmModule> | undefined;
+let generation = 0;
+
+/** Loads and initializes the wasm module once per worker; a failed load is tried again. */
+export function loadDocxEngineWasm(): Promise<DocxEngineWasmModule> {
+ if (!modulePromise) {
+ const instance = generation;
+ modulePromise = (async () => {
+ try {
+ const base = new URL('./wasm/docx_engine.js', import.meta.url);
+ // A replacement instance needs its own copy of the generated module,
+ // whose memory lives in module-level state.
+ if (instance > 0) base.searchParams.set('instance', String(instance));
+ const mod = (await import(
+ /* @vite-ignore */ base.href
+ )) as DocxEngineWasmModule;
+ // The generated JS's own relative wasm URL 404s in production; a static
+ // `new URL` makes vite emit and rewrite the binary.
+ const wasmUrl = new URL('./wasm/docx_engine_bg.wasm', import.meta.url);
+ await mod.default({ module_or_path: wasmUrl });
+ return mod;
+ } catch (error) {
+ modulePromise = undefined;
+ throw error;
+ }
+ })();
+ }
+ return modulePromise;
+}
+
+/**
+ * Discards the current instance after a trap (a Rust panic aborts the
+ * instance and can leave its objects unusable); the next load starts fresh.
+ */
+export function discardDocxEngineWasm(): void {
+ modulePromise = undefined;
+ generation++;
+}
+
+/** Whether an error came from a trapped (panicked) wasm instance. */
+export function isWasmTrap(error: unknown): boolean {
+ if (
+ typeof WebAssembly !== 'undefined' &&
+ error instanceof WebAssembly.RuntimeError
+ )
+ return true;
+ const message = error instanceof Error ? error.message : String(error);
+ return /unreachable|recursive use of an object|already borrowed|already mutably borrowed/i.test(
+ message
+ );
+}
diff --git a/apps/web/src/vite-env.d.ts b/apps/web/src/vite-env.d.ts
index e7addf046e..7d089cb8da 100644
--- a/apps/web/src/vite-env.d.ts
+++ b/apps/web/src/vite-env.d.ts
@@ -4,8 +4,6 @@ interface ImportMetaEnv {
readonly __APP_BUILD_TIME__?: number;
readonly __LOCAL_JWT__: string;
readonly __GIT_BRANCH__: string;
- /** Docxodus release whose WebAssembly runtime the build serves. */
- readonly DOCXODUS_VERSION?: string;
readonly VITE_SEGMENT_WRITE_KEY: string;
readonly VITE_POSTHOG_API_KEY: string;
diff --git a/apps/web/tests/native/build.sh b/apps/web/tests/native/build.sh
index 74fb88e6ba..2175b38bee 100644
--- a/apps/web/tests/native/build.sh
+++ b/apps/web/tests/native/build.sh
@@ -17,6 +17,7 @@ just ensure-cache-wasm
just ensure-agent-fold-wasm
just ensure-database-sql-wasm
just ensure-pptx-engine-wasm
+just ensure-docx-engine-wasm
# build.rs reads this ignored file. Restore it even if compilation fails.
env_file="$web/tauri/src-tauri/.macro-tauri-env"
diff --git a/apps/web/vite.base.ts b/apps/web/vite.base.ts
index ccfb1dcc46..a4e550f571 100644
--- a/apps/web/vite.base.ts
+++ b/apps/web/vite.base.ts
@@ -11,7 +11,6 @@ import tsconfigpaths from 'vite-tsconfig-paths';
// @ts-ignore
import { version } from './package.json';
import { devHttps } from './scripts/dev-https';
-import { docxodusRuntime } from './scripts/docxodus-runtime';
import { hostedDevProxy } from './scripts/hosted-dev-proxy';
import { keepImportMetaDev } from './scripts/keep-import-meta-dev';
import { localDevServer } from './scripts/local-dev-server';
@@ -100,7 +99,6 @@ export const createAppViteConfig = (): UserConfigFn => {
root: './',
}),
gitBranchHmrPlugin(),
- docxodusRuntime(),
],
define: defineEnv(ENV_MODE, command),
clearScreen: false,
diff --git a/bun.lock b/bun.lock
index 71b93567d6..ab3f948a2e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -135,7 +135,6 @@
"detect-browser": "^5.3.0",
"diff": "^9.0.0",
"dinero.js": "2.0.0-alpha.8",
- "docxodus": "12.6.5",
"effect": "^4.0.0-rc.111",
"email-validator": "^2.0.4",
"emojibase-data": "^17.0.0",
@@ -583,10 +582,6 @@
"@asyncapi/specs": ["@asyncapi/[email protected]", "", { "dependencies": { "@types/json-schema": "^7.0.11" } }, "sha512-A3WBLqAKGoJ2+6FWFtpjBlCQ1oFCcs4GxF7zsIGvNqp/klGUHjlA3aAcZ9XMMpLGE8zPeYDz2x9FmO6DSuKraQ=="],
- "@atlaskit/pragmatic-drag-and-drop": ["@atlaskit/[email protected]", "", { "dependencies": { "@babel/runtime": "^7.0.0", "bind-event-listener": "^3.0.0", "raf-schd": "^4.0.3" } }, "sha512-ou1j+lBqutK7p2S80lMresJeKu9qAL1zr1K+N0OyCTzbMpD6pXRHray8VkRoHgJICI7Wp1fk5ScJh6EctyAuPw=="],
-
- "@atlaskit/pragmatic-drag-and-drop-auto-scroll": ["@atlaskit/[email protected]", "", { "dependencies": { "@atlaskit/pragmatic-drag-and-drop": "^4.0.0", "@babel/runtime": "^7.0.0" } }, "sha512-2fhWAG48EjPoKhoHLG6RcT3/VaCzYEbRb6BtA/Vcfx4FrL0P1KrEgBJ6OAwB0X8MOV6UH22YgjFFHjv8fQD9rA=="],
-
"@aws-crypto/sha256-js": ["@aws-crypto/[email protected]", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA=="],
"@aws-crypto/util": ["@aws-crypto/[email protected]", "", { "dependencies": { "@aws-sdk/types": "^3.222.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ=="],
@@ -1977,8 +1972,6 @@
"binary-search-bounds": ["[email protected]", "", {}, "sha512-H0ea4Fd3lS1+sTEB2TgcLoK21lLhwEJzlQv3IN47pJS976Gx4zoWe0ak3q+uYh60ppQxg9F16Ri4tS1sfD4+jA=="],
- "bind-event-listener": ["[email protected]", "", {}, "sha512-PJvH288AWQhKs2v9zyfYdPzlPqf5bXbGMmhmUIY9x4dAUGIWgomO771oBQNwJnMQSnUIXhKu6sgzpBRXTlvb8Q=="],
-
"bitf": ["[email protected]", "", {}, "sha512-l3PytekTpJOq4W8QmXQQtDRI29Fp3ds2F9SfK+RTc9rvfDk0RFtFRjTuVSpYOyh0qITJP6walQq9TkxjY7gAFw=="],
"bl": ["[email protected]", "", { "dependencies": { "buffer": "^5.5.0", "inherits": "^2.0.4", "readable-stream": "^3.4.0" } }, "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w=="],
@@ -2269,8 +2262,6 @@
"dir-glob": ["[email protected]", "", { "dependencies": { "path-type": "^4.0.0" } }, "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA=="],
- "docxodus": ["[email protected]", "", { "dependencies": { "@atlaskit/pragmatic-drag-and-drop": "^2.0.2", "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "^3.0.0" }, "peerDependencies": { "react": ">=16.8.0" }, "optionalPeers": ["react"] }, "sha512-TnZr0/InZAEIesK2tNZ8BmNHOGafYfoHooHzXboj+bO6EmBngvP5C9jGaIYkGLmztIXd4epdSDIPvSJp1xPF6A=="],
-
"dogapi": ["[email protected]", "", { "dependencies": { "extend": "^3.0.2", "json-bigint": "^1.0.0", "lodash": "^4.17.21", "minimist": "^1.2.5", "rc": "^1.2.8" }, "bin": { "dogapi": "bin/dogapi" } }, "sha512-065fsvu5dB0o4+ENtLjZILvXMClDNH/yA9H6L8nsdcNiz9l0Hzpn7aQaCOPYXxqyzq4CRPOdwkFXUjDOXfRGbg=="],
"dom-accessibility-api": ["[email protected]", "", {}, "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg=="],
@@ -3221,8 +3212,6 @@
"raf": ["[email protected]", "", { "dependencies": { "performance-now": "^2.1.0" } }, "sha512-Sq4CW4QhwOHE8ucn6J34MqtZCeWFP2aQSmrlroYgqAV1PjStIhJXxYuTgUIfkEk7zTLjmIjLmU5q+fbD1NnOJA=="],
- "raf-schd": ["[email protected]", "", {}, "sha512-tQkJl2GRWh83ui2DiPTJz9wEiMN20syf+5oKfB03yYP7ioZcJwsIK8FjrtLwH1m7C7e+Tt2yYBlrOpdT+dyeIQ=="],
-
"random-js": ["[email protected]", "", {}, "sha512-CRUyWmnzmZBA7RZSVGq0xMqmgCyPPxbiKNLFA5ud7KenojVX2s7Gv+V7eB52beKTPGxWRnVZ7D/tCIgYJJ8vNQ=="],
"randombytes": ["[email protected]", "", { "dependencies": { "safe-buffer": "^5.1.0" } }, "sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ=="],
@@ -3797,8 +3786,6 @@
"@asamuzakjp/css-color/lru-cache": ["[email protected]", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
- "@atlaskit/pragmatic-drag-and-drop-auto-scroll/@atlaskit/pragmatic-drag-and-drop": ["@atlaskit/[email protected]", "", { "dependencies": { "@babel/runtime": "^7.0.0", "bind-event-listener": "^3.0.0", "raf-schd": "^4.0.3" } }, "sha512-pyDo2B5NiaExoKGmgeXKGNUL4aR4UzzSZm8QWWjYTEyBLVqSqKyKUwtVxMw2YEkakagOGFONUdHM32LAH2nPug=="],
-
"@babel/core/semver": ["[email protected]", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
"@babel/helper-compilation-targets/lru-cache": ["[email protected]", "", { "dependencies": { "yallist": "^3.0.2" } }, "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w=="],
diff --git a/crates/docx_engine/Cargo.toml b/crates/docx_engine/Cargo.toml
new file mode 100644
index 0000000000..41ca4bd983
--- /dev/null
+++ b/crates/docx_engine/Cargo.toml
@@ -0,0 +1,41 @@
+[package]
+edition = "2024"
+name = "docx_engine"
+publish = false
+version = "0.1.0"
+
+[lib]
+# `cdylib` for the browser build; `rlib` so native tools and tests link it.
+crate-type = ["cdylib", "rlib"]
+
+[features]
+default = []
+# Compile the bundled font set into native builds (tests, the corpus CLI).
+# The wasm build always includes it: the browser worker has no font directory.
+embedded-fonts = ["pptx_engine/embedded-fonts"]
+# The `docx_corpus` developer CLI (rendering reports, fidelity scoring).
+cli = ["dep:clap", "embedded-fonts"]
+
+[[bin]]
+name = "docx_corpus"
+required-features = ["cli"]
+
+[dependencies]
+base64 = { workspace = true }
+clap = { workspace = true, optional = true }
+# The PPTX engine supplies the shared Office foundation: the ZIP container,
+# OPC packaging, DrawingML colors/fills/geometry/charts, the font database,
+# image and metafile decoding, and the tiny-skia rasterizer.
+pptx_engine = { path = "../pptx_engine", default-features = false }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+
+# The wasm-bindgen shell in `wasm`, which only exists on wasm32.
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+console_error_panic_hook = { workspace = true }
+js-sys = { workspace = true }
+wasm-bindgen = { workspace = true }
+
+[package.metadata.wasm-pack.profile.release]
+wasm-opt = false
diff --git a/crates/docx_engine/README.md b/crates/docx_engine/README.md
new file mode 100644
index 0000000000..b2fe863819
--- /dev/null
+++ b/crates/docx_engine/README.md
@@ -0,0 +1,198 @@
+# docx_engine
+
+A from-scratch Word (`.docx`) engine: it parses, paginates, renders, edits
+and saves documents. The same Rust code runs natively (tests, the corpus
+CLI) and as WebAssembly in the web app's DOCX editor worker
+(`apps/web/src/lib/core/docx-engine`). It builds on `pptx_engine` for the
+shared Office foundation: the ZIP container, OPC packaging, DrawingML
+(colors, fills, geometry, charts, pictures), the font database and the
+tiny-skia rasterizer. Everything Word-specific is implemented here, with no
+other dependencies.
+
+## Design
+
+A paragraph is an attributed string: text plus spans of attributes, where
+every run property element is its own attribute (`r:w:b` holds `<w:b/>`)
+and non-text content (pictures, field characters, note references,
+bookmarks) is an object character (U+FFFC) carrying its XML. Elements that
+wrap runs (hyperlinks, tracked changes, content controls, simple fields)
+are a `wrap` attribute listing them. Paragraphs sit in a tree of blocks
+(paragraphs, tables, rows, cells, content controls, opaque XML) with
+stable ids and fractional position keys. Offsets are UTF-16 code units,
+the unit JavaScript and the CRDT use.
+
+That shape is also the collaborative state: each block is a Loro map with
+its paragraph text as a rich `LoroText`, so a keystroke is one small text
+operation and two people formatting overlapping text in different ways
+both win. Content the engine does not interpret stays as XML snippets and
+is written back unchanged; parts an edit did not touch keep their bytes.
+
+```
+xml, units namespace-aware XML trees and snippets, twips/EMU/points
+model blocks and content, parsing and writing, styles, numbering,
+ sections, settings, run/paragraph/table properties
+document the package, the body story, headers, footers and notes
+layout formatting (style inheritance), inline items and fields,
+ line breaking (Word's justification and tab rules), tables
+ (autofit, borders, rows across pages, repeated headers),
+ floats, frames, headers/footers, footnotes, columns,
+ sections, line numbers, and a cache keyed by block version
+render pages to tiny-skia pixmaps (whole pages or changed strips)
+edit sessions: selection, caret and hit testing, edit operations
+ as transactions with undo, lists, tables, header/footer
+ editing, tracked changes (revise.rs)
+collab the document as shared maps, applying peers' changes,
+ migrating the first collaborative format
+wasm the wasm-bindgen API used by the browser worker
+```
+
+### Editing
+
+`Session::apply(&[EditOp], group, &FontDb)` runs operations as one
+transaction and returns an `EditResult`: the collaborative changes
+(text deltas, block fields, new and removed blocks, part entries), the
+selection with its caret and highlight geometry, page fingerprints and the
+strips of pages that changed (the editor repaints only those), and the
+formatting at the selection for toolbars. Operations cover selection and
+movement by character, word, line and document, typing, Enter, breaks,
+deleting across paragraphs and tables, character and paragraph formatting,
+styles, lists, tables (insert, rows, columns), header and footer editing
+(`enterStory`/`exitStory`), tracked changes (`setTracking`,
+`acceptChanges`, `rejectChanges`) and replacing search matches (`replace`,
+one or all). Batches with the same group (typing) merge into one undo step;
+in collaborative mode undo is the shared document's instead.
+
+`Session::document_comments` lists the comments the file carries (Word's
+comments part, with threads and done flags from `commentsExtended`), each
+with the body range it is on, for showing beside the pages.
+
+`Session::find` searches the body's visible text (field codes, deleted and
+hidden text are left out; straight and typographic quotes match each
+other) and returns the matches with their highlight rectangles.
+
+While the document tracks changes (`w:trackRevisions`, shared through the
+settings part), typed text is recorded as the author's `w:ins`, deleted text
+as `w:del` (an author's own insertions are removed outright) and paragraph
+marks as inserted or deleted. Formatting text or changing paragraph
+properties keeps the formatting from before (`w:rPrChange`, `w:pPrChange`),
+except in text the author inserted; changing it back drops the record.
+Accept and reject resolve the selection, the revision at the caret or
+everything. With markup, a bar in the left margin marks every line that
+holds a change, and a list label shows its paragraph mark's revision.
+
+Headers, footers, footnotes and endnotes are stories of their own: their
+blocks get ids prefixed with the part (or note), transactions target the
+active story, and an edited part (`footnotes.xml` for any footnote) is
+written back as XML and shared as one entry (footnotes and endnotes one
+note per entry, so typing in a note shares that note only). A click in a page's notes
+area (`PageInfo::notes`) enters the note under it. `insertNote` adds a
+footnote or endnote at the caret, as Word does: the reference in the text
+(Footnote Reference style), the note (Footnote Text, starting with its
+mark), the notes part with its separators and the styles when the document
+lacks them; the caret moves into the new note. Pasting a note reference
+within the document copies its note under a new id (a note has one
+reference); pasted from another document, the reference is left out.
+
+### Collaboration
+
+`collab` describes a document as the web app's Loro containers:
+`wordBlocks` (one map per block, paragraph text as rich text), `wordParts`
+(every other part; the main part is a shell with a placeholder for the
+blocks), `wordRels` and `wordTypes`. `Session::from_collab` opens that
+state; `apply_remote` applies peers' changes, keeping the selection on the
+same text (through the exact text deltas when the caller knows them).
+Collaborative sessions number new blocks from a per-peer random source so
+concurrent inserts never collide. `collab::v1` migrates documents shared in
+the editor's first format.
+
+### Fonts
+
+Layout uses `pptx_engine`'s bundled metric-compatible fonts (Liberation,
+Carlito, Caladea, DejaVu and others) and its substitution table, with Noto
+faces for Arabic and Hebrew (in the serif or sans-serif style of the text
+around them). Native builds compile them in with the `embedded-fonts`
+feature; the wasm build always does. Hosts can register more fonts.
+
+### Right-to-left text
+
+`layout::bidi` resolves embedding levels with the Unicode Bidirectional
+Algorithm for paragraphs that are right to left (`w:bidi`) or hold
+right-to-left text, then lays each line out in visual order: a
+right-to-left paragraph's line is mirrored so its start (indent, list
+number, first tab) is on the right, and runs against the paragraph's
+direction are reversed in place; brackets mirror. Word's own behaviour is
+followed where it differs: in runs marked `w:rtl`, separators do not join
+numbers (`78/265` shows as `265/78`) and Latin letters and digits keep the
+Latin font. Carets, hit testing, selections and the arrow keys follow the
+visual order.
+
+## Using it
+
+```rust
+use docx_engine::Document;
+use docx_engine::edit::{EditOp, Session, Toggle};
+use docx_engine::render::ImageCache;
+use pptx_engine::font::FontDb;
+
+let doc = Document::open(std::fs::read("contract.docx")?)?;
+let fonts = FontDb::global(); // needs the `embedded-fonts` feature
+let layout = doc.layout(fonts);
+let mut images = ImageCache::new();
+let first_page = doc.render_page(&layout, 0, 1224, fonts, &mut images); // pixels
+let mut session = Session::new(doc);
+session.apply(
+ &[EditOp::SelectAll, EditOp::ToggleFormat { format: Toggle::Bold }],
+ None,
+ fonts,
+)?;
+std::fs::write("edited.docx", session.document().save()?)?;
+```
+
+The browser build: `just build-docx-engine-wasm` from `apps/web` (wasm-pack,
+`--target web`, SIMD enabled); `just ensure-docx-engine-wasm` rebuilds only
+when sources changed, and `bun run dev` runs it.
+
+## Testing
+
+- `cargo test -p docx_engine` runs the unit tests: parsing and writing,
+ layout (lines, tables, floats, frames, headers, notes, fields), editing,
+ header/footer editing, tracked changes and the collaborative state.
+- The `docx_corpus` CLI (`--features cli`) renders documents, scores them
+ against LibreOffice and Word reference renders (SSIM and page counts, with
+ an HTML report) and dumps line positions for line-break comparisons. The
+ corpus is listed in [tests/corpus](tests/corpus/README.md).
+- The web editor has Playwright tests against the real sync service:
+ `apps/web/src/features/block-write/browser-test`.
+
+Current state (61 documents, 36 of them legal; references rendered with the
+engine's fonts): against Word's own PDF exports (18 documents) mean SSIM
+0.84 with equal page counts for all 18; against LibreOffice 24.2 (61
+documents) mean SSIM 0.66 with equal page counts for 42. Page SSIM is
+strict: a line that wraps one word differently shifts everything below it,
+so the page counts are the better summary. LibreOffice is a reference, not ground truth;
+where Word PDFs exist they decide.
+
+## Known gaps
+
+- Text: Arabic joins through the Unicode presentation forms (contextual
+ letter shapes and the lam-alef ligatures), without OpenType mark
+ positioning; other complex scripts (Indic, Thai) are not shaped. Explicit
+ bidi embedding characters are ignored (Word documents use run and
+ paragraph properties instead). No automatic hyphenation (soft hyphens are
+ honoured).
+- Layout: no vertical text, no text wrapping around tight polygon wraps
+ (square wrap is used), no balancing of continuous-section columns.
+- Fields are shown with their cached results, except page numbers, which
+ are computed; a table of contents is not regenerated.
+- Editing does not create text boxes or pictures and does not edit inside
+ text boxes (it keeps them); new comments are Macro threads anchored in the
+ body, and Word's comments in the file are shown read-only. Undoing a new
+ footnote removes its reference; the empty note stays in the notes part,
+ unreferenced.
+- Two people editing the same footnote or endnote at once: the last write
+ of the note wins (different notes merge: notes are shared one by one).
+- Tracked changes show without balloons (formatting changes only get a
+ change bar); table property changes (`w:tcPrChange`, `w:tblPrChange`)
+ are not recorded.
+- Two people editing the same header or footer at once: the last write of
+ the part wins.
diff --git a/crates/docx_engine/scripts/fetch_corpus.py b/crates/docx_engine/scripts/fetch_corpus.py
new file mode 100755
index 0000000000..0cc8b92a9b
--- /dev/null
+++ b/crates/docx_engine/scripts/fetch_corpus.py
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Download the fidelity corpus listed in tests/corpus/manifest.json.
+
+Usage:
+ python3 crates/docx_engine/scripts/fetch_corpus.py OUT_DIR [--manifest PATH]
+
+Each entry's `source_url` is saved as OUT_DIR/<file>. When the entry names a
+Word-exported PDF (`word_pdf`) and its notes give the PDF's source URL, that
+PDF is saved next to it as OUT_DIR/<stem>.word.pdf, which
+`render_references.py` turns into Word reference pages. Files already present
+are kept. The documents stay outside the repository: they belong to their
+publishers (see each entry's `license` and `provenance`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import urllib.request
+from pathlib import Path
+
+DEFAULT_MANIFEST = Path(__file__).resolve().parent.parent / "tests" / "corpus" / "manifest.json"
+# A PDF URL ends in `.pdf`, or asks an API for one (`t=pdf`, as the UN's
+# document system does).
+PDF_SOURCE = re.compile(r"source (https?://\S+?(?:\.pdf|[?&]t=pdf))", re.IGNORECASE)
+
+
+def fetch(url: str, dest: Path) -> bool:
+ if dest.exists() and dest.stat().st_size > 0:
+ return True
+ request = urllib.request.Request(url, headers={"User-Agent": "docx-engine-corpus/1.0"})
+ try:
+ with urllib.request.urlopen(request, timeout=120) as response:
+ data = response.read()
+ except Exception as error: # noqa: BLE001 - report and continue
+ print(f" failed: {url}: {error}", file=sys.stderr)
+ return False
+ dest.write_bytes(data)
+ return True
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument("out", type=Path)
+ parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+ args = parser.parse_args()
+ args.out.mkdir(parents=True, exist_ok=True)
+ entries = json.loads(args.manifest.read_text())
+ failed = 0
+ for entry in entries:
+ name = entry["file"]
+ print(name)
+ if not fetch(entry["source_url"], args.out / name):
+ failed += 1
+ continue
+ pdf = entry.get("word_pdf")
+ match = PDF_SOURCE.search(entry.get("notes", ""))
+ if pdf and match and not fetch(match.group(1), args.out / pdf):
+ failed += 1
+ print(f"{len(entries) - failed} of {len(entries)} documents ready in {args.out}")
+ return 1 if failed else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/crates/docx_engine/scripts/render_references.py b/crates/docx_engine/scripts/render_references.py
new file mode 100755
index 0000000000..86fa9815ca
--- /dev/null
+++ b/crates/docx_engine/scripts/render_references.py
@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Render reference PNGs for .docx files (pixel-diff baselines).
+
+Usage:
+ python3 crates/docx_engine/scripts/render_references.py OUT_DIR doc.docx [...] \
+ [--width 816] [--jobs N] [--force] [--timeout 300] [--fontconfig FONTS_CONF]
+
+For every input document this writes:
+ OUT_DIR/lo/<stem>/page-001.png ... LibreOffice's rendering (via PDF export)
+ OUT_DIR/lo/<stem>/meta.json {pages, width, height, libreoffice_version, source_sha256, ...}
+and, when a Word-exported PDF of the same document sits next to it as
+`<stem>.word.pdf`:
+ OUT_DIR/word/<stem>/page-001.png ... Microsoft Word's rendering
+
+With --fontconfig (from `docx_corpus fontconfig --out FONTS_CONF`), LibreOffice
+uses the engine's bundled fonts and substitutions, so its renders differ from
+the engine's in layout and rasterization rather than in fallback-font choice.
+Word PDFs embed Word's real fonts and are the ground truth for layout.
+
+A document is skipped when its meta.json records the same source hash, width
+and fontconfig (use --force to re-render). Parallel workers each use a private
+LibreOffice profile.
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures as cf
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+from pathlib import Path
+
+_thread_state = threading.local()
+_profiles: list[str] = []
+_profiles_lock = threading.Lock()
+_print_lock = threading.Lock()
+
+
+def log(msg: str) -> None:
+ with _print_lock:
+ print(msg, file=sys.stderr, flush=True)
+
+
+def soffice_binary() -> str:
+ for name in ("soffice", "libreoffice"):
+ path = shutil.which(name)
+ if path:
+ return path
+ sys.exit("error: soffice/libreoffice not found on PATH")
+
+
+def libreoffice_version(soffice: str) -> str:
+ try:
+ out = subprocess.run([soffice, "--version"], capture_output=True, text=True, timeout=120).stdout.strip()
+ except (OSError, subprocess.TimeoutExpired):
+ return "unknown"
+ return out or "unknown"
+
+
+def sha256_file(path: Path) -> str:
+ h = hashlib.sha256()
+ with path.open("rb") as fh:
+ for chunk in iter(lambda: fh.read(1 << 20), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def pdf_pages(pdf: Path) -> int | None:
+ try:
+ out = subprocess.run(["pdfinfo", str(pdf)], capture_output=True, text=True, timeout=120).stdout
+ except (OSError, subprocess.TimeoutExpired):
+ return None
+ m = re.search(r"^Pages:\s+(\d+)", out, re.M)
+ return int(m.group(1)) if m else None
+
+
+def worker_profile() -> str:
+ prof = getattr(_thread_state, "profile", None)
+ if prof is None:
+ prof = tempfile.mkdtemp(prefix="docx-ref-lo-profile-")
+ _thread_state.profile = prof
+ with _profiles_lock:
+ _profiles.append(prof)
+ return prof
+
+
+def png_size(path: Path) -> tuple[int, int]:
+ with path.open("rb") as fh:
+ head = fh.read(24)
+ return int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")
+
+
+def rasterize(pdf: Path, out_dir: Path, width: int, timeout: int) -> list[Path]:
+ with tempfile.TemporaryDirectory(prefix="docx-ref-png-") as tmp:
+ prefix = Path(tmp) / "page"
+ subprocess.run(
+ ["pdftoppm", "-png", "-scale-to-x", str(width), "-scale-to-y", "-1", str(pdf), str(prefix)],
+ check=True,
+ capture_output=True,
+ timeout=timeout,
+ )
+ pngs = sorted(Path(tmp).glob("page-*.png"), key=lambda p: int(re.search(r"-(\d+)\.png$", p.name).group(1)))
+ if out_dir.exists():
+ for old in out_dir.glob("page-*.png"):
+ old.unlink()
+ out_dir.mkdir(parents=True, exist_ok=True)
+ out = []
+ for i, p in enumerate(pngs, start=1):
+ dest = out_dir / f"page-{i:03d}.png"
+ shutil.move(str(p), dest)
+ out.append(dest)
+ return out
+
+
+def cached(meta_path: Path, digest: str, args) -> dict | None:
+ if args.force or not meta_path.exists():
+ return None
+ try:
+ old = json.loads(meta_path.read_text())
+ except (OSError, ValueError):
+ return None
+ fc = sha256_file(Path(args.fontconfig)) if args.fontconfig else None
+ if old.get("source_sha256") == digest and old.get("requested_width") == args.width and old.get("fontconfig_sha256") == fc and old.get("ok"):
+ return old
+ return None
+
+
+def render_one(src: Path, out_root: Path, args, soffice: str, lo_version: str) -> dict:
+ stem = src.stem
+ result: dict = {"file": str(src)}
+ # Word's own PDF, when the corpus has one.
+ word_pdf = src.with_name(stem + ".word.pdf")
+ if word_pdf.exists():
+ word_dir = out_root / "word" / stem
+ meta_path = word_dir / "meta.json"
+ digest = sha256_file(word_pdf)
+ if cached(meta_path, digest, argparse.Namespace(force=args.force, fontconfig=None, width=args.width)) is None:
+ pngs = rasterize(word_pdf, word_dir, args.width, args.timeout)
+ w, h = png_size(pngs[0]) if pngs else (None, None)
+ meta_path.write_text(json.dumps({
+ "source": word_pdf.name, "source_sha256": digest, "pages": len(pngs),
+ "requested_width": args.width, "width": w, "height": h,
+ "fontconfig_sha256": None, "ok": bool(pngs),
+ }, indent=2) + "\n")
+ result["word"] = True
+
+ lo_dir = out_root / "lo" / stem
+ meta_path = lo_dir / "meta.json"
+ digest = sha256_file(src)
+ old = cached(meta_path, digest, args)
+ if old is not None:
+ result.update(status="cached", meta=old)
+ return result
+ profile = worker_profile()
+ with tempfile.TemporaryDirectory(prefix="docx-ref-") as tmp:
+ tmp_path = Path(tmp)
+ work_src = tmp_path / ("input" + src.suffix.lower())
+ shutil.copyfile(src, work_src)
+ cmd = [soffice, f"-env:UserInstallation=file://{profile}", "--headless", "--norestore", "--nologo",
+ "--convert-to", "pdf:writer_pdf_Export", "--outdir", str(tmp_path), str(work_src)]
+ env = dict(os.environ)
+ if args.fontconfig:
+ env["FONTCONFIG_FILE"] = str(Path(args.fontconfig).resolve())
+ try:
+ proc = subprocess.run(cmd, capture_output=True, text=True, timeout=args.timeout, env=env)
+ lo_log = (proc.stdout + proc.stderr).strip()
+ except subprocess.TimeoutExpired:
+ result.update(status="error", error=f"soffice timed out after {args.timeout}s")
+ return result
+ pdf = tmp_path / "input.pdf"
+ if not pdf.exists():
+ result.update(status="error", error="no PDF produced", log=lo_log[-2000:])
+ return result
+ pages = pdf_pages(pdf)
+ try:
+ pngs = rasterize(pdf, lo_dir, args.width, args.timeout)
+ except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
+ result.update(status="error", error=f"pdftoppm failed: {e}")
+ return result
+ if args.keep_pdf:
+ shutil.copyfile(pdf, lo_dir / f"{stem}.pdf")
+ w, h = png_size(pngs[0]) if pngs else (None, None)
+ meta = {
+ "source": src.name, "source_sha256": digest, "pages": len(pngs), "pdf_pages": pages,
+ "requested_width": args.width, "width": w, "height": h,
+ "libreoffice_version": lo_version,
+ "fontconfig_sha256": sha256_file(Path(args.fontconfig)) if args.fontconfig else None,
+ "ok": bool(pngs),
+ }
+ meta_path.write_text(json.dumps(meta, indent=2) + "\n")
+ result.update(status="rendered" if pngs else "error", meta=meta)
+ return result
+
+
+def main(argv: list[str]) -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("out_dir")
+ ap.add_argument("files", nargs="+")
+ ap.add_argument("--width", type=int, default=816, help="PNG width in pixels (default 816 = 96 DPI Letter)")
+ ap.add_argument("--jobs", "-j", type=int, default=1, help="parallel LibreOffice workers")
+ ap.add_argument("--force", action="store_true", help="ignore the meta.json cache")
+ ap.add_argument("--keep-pdf", action="store_true", help="also keep the LibreOffice PDF")
+ ap.add_argument("--timeout", type=int, default=300, help="per-step timeout in seconds")
+ ap.add_argument("--fontconfig", help="FONTCONFIG_FILE for LibreOffice (see `docx_corpus fontconfig`)")
+ args = ap.parse_args(argv)
+
+ files = [Path(f) for f in args.files if f.lower().endswith((".docx", ".docm", ".dotx"))]
+ missing = [str(f) for f in files if not f.is_file()]
+ if missing:
+ sys.exit(f"error: not a file: {', '.join(missing)}")
+ out_root = Path(args.out_dir)
+ out_root.mkdir(parents=True, exist_ok=True)
+ soffice = soffice_binary()
+ lo_version = libreoffice_version(soffice)
+ failures = 0
+ try:
+ with cf.ThreadPoolExecutor(max_workers=max(1, args.jobs)) as ex:
+ futs = {ex.submit(render_one, f, out_root, args, soffice, lo_version): f for f in files}
+ for fut in cf.as_completed(futs):
+ src = futs[fut]
+ try:
+ res = fut.result()
+ except Exception as e: # noqa: BLE001
+ res = {"file": str(src), "status": "error", "error": repr(e)}
+ meta = res.get("meta", {})
+ line = f"[{res.get('status', '?'):8s}] {src} pages={meta.get('pages')}"
+ if res.get("word"):
+ line += " +word"
+ if res.get("status") == "error":
+ failures += 1
+ line += f" ERROR: {res.get('error')}"
+ log(line)
+ finally:
+ for prof in _profiles:
+ shutil.rmtree(prof, ignore_errors=True)
+ log(f"done: {len(files)} documents, {failures} failed")
+ return 1 if failures else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/crates/docx_engine/src/bin/docx_corpus/check.rs b/crates/docx_engine/src/bin/docx_corpus/check.rs
new file mode 100644
index 0000000000..33428f81bd
--- /dev/null
+++ b/crates/docx_engine/src/bin/docx_corpus/check.rs
@@ -0,0 +1,425 @@
+//! `docx_corpus check`: every document through the engine's paths, not only
+//! rendering: layout and every page drawn, the collaborative state round
+//! trip, edits with undo and redo, tracked changes, a header edit, a note
+//! edit, copy and paste, and saving and reopening. Any panic or mismatch fails the document.
+
+use docx_engine::Document;
+use docx_engine::collab::CollabState;
+use docx_engine::edit::{EditOp, Pos, Session};
+use docx_engine::render::ImageCache;
+use pptx_engine::font::FontDb;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::path::PathBuf;
+use std::time::Instant;
+
+/// Options of `docx_corpus check`.
+#[derive(clap::Args)]
+pub struct Args {
+ /// Page width in pixels for the render pass.
+ #[arg(long, default_value_t = 200)]
+ width: u32,
+ /// Documents.
+ files: Vec<PathBuf>,
+}
+
+type Check = Result<(), String>;
+
+fn texts(doc: &Document) -> Vec<String> {
+ doc.body()
+ .paragraphs()
+ .iter()
+ .filter_map(|id| doc.body().get(id).map(|b| b.content.text()))
+ .collect()
+}
+
+fn ensure(ok: bool, what: impl FnOnce() -> String) -> Check {
+ if ok { Ok(()) } else { Err(what()) }
+}
+
+fn apply(s: &mut Session, ops: Vec<EditOp>, fonts: &FontDb) -> Check {
+ s.apply(&ops, None, fonts)
+ .map(|_| ())
+ .map_err(|e| e.to_string())
+}
+
+/// Applies an edit that must change the document.
+fn change(s: &mut Session, op: EditOp, fonts: &FontDb) -> Check {
+ let what = format!("{op:?}");
+ let sel = format!("{:?}", s.selection());
+ let r = s.apply(&[op], None, fonts).map_err(|e| e.to_string())?;
+ ensure(r.changed, || format!("{what} at {sel} changed nothing"))
+}
+
+/// Applies an edit that may legitimately change nothing (deleting across
+/// empty table cells); returns whether it changed the document.
+fn maybe(s: &mut Session, op: EditOp, fonts: &FontDb) -> Result<bool, String> {
+ let r = s.apply(&[op], None, fonts).map_err(|e| e.to_string())?;
+ Ok(r.changed)
+}
+
+fn select(s: &mut Session, a: Pos, f: Pos, fonts: &FontDb) -> Check {
+ apply(
+ s,
+ vec![EditOp::Select {
+ anchor: a,
+ focus: f,
+ }],
+ fonts,
+ )
+}
+
+/// Paragraphs to edit: up to `n`, spread through the document.
+fn targets(doc: &Document, n: usize) -> Vec<(docx_engine::model::block::BlockId, usize)> {
+ let ids = doc.body().paragraphs();
+ if ids.is_empty() {
+ return Vec::new();
+ }
+ let step = (ids.len() / n).max(1);
+ ids.iter()
+ .step_by(step)
+ .take(n)
+ .filter_map(|id| Some((id.clone(), doc.body().get(id)?.content.len())))
+ .collect()
+}
+
+fn check_render(doc: &Document, width: u32, fonts: &FontDb) -> Result<usize, String> {
+ let layout = doc.layout(fonts);
+ let mut images = ImageCache::new();
+ for i in 0..layout.pages.len() {
+ doc.render_page(&layout, i, width, fonts, &mut images)
+ .ok_or_else(|| format!("page {i} did not render"))?;
+ }
+ Ok(layout.pages.len())
+}
+
+fn check_collab(doc: &Document, pages: usize, fonts: &FontDb) -> Check {
+ let state = doc.collab_state().map_err(|e| e.to_string())?;
+ let json = serde_json::to_string(&state).map_err(|e| e.to_string())?;
+ let back: CollabState = serde_json::from_str(&json).map_err(|e| e.to_string())?;
+ let shared = Document::from_collab_state(&back, 7).map_err(|e| e.to_string())?;
+ ensure(texts(&shared) == texts(doc), || {
+ "shared text differs".into()
+ })?;
+ let shared_pages = shared.layout(fonts).pages.len();
+ ensure(shared_pages == pages, || {
+ format!("shared state lays out {shared_pages} pages, the file {pages}")
+ })?;
+ // The shared state saves as a package that opens again.
+ let saved = shared.save().map_err(|e| e.to_string())?;
+ let reopened = Document::open(saved).map_err(|e| e.to_string())?;
+ ensure(texts(&reopened) == texts(doc), || {
+ "saved shared state differs".into()
+ })
+}
+
+fn check_edits(doc: &Document, fonts: &FontDb) -> Check {
+ let original = texts(doc);
+ let mut s = Session::new(doc.clone());
+ // Plain edits: a document saved with Track Changes on records them.
+ apply(&mut s, vec![EditOp::SetTracking { on: false }], fonts)?;
+ let mut steps = 0;
+ for (id, len) in targets(doc, 8) {
+ let at = Pos::new(id, len.min(3));
+ select(&mut s, at.clone(), at, fonts)?;
+ change(&mut s, EditOp::InsertText { text: "XYZ".into() }, fonts)?;
+ steps += 1;
+ }
+ // Enter in the middle of a paragraph, and a delete across two.
+ let ids = s.document().body().paragraphs();
+ if let Some(id) = ids.get(ids.len() / 2) {
+ let len = s.document().body().get(id).map_or(0, |b| b.content.len());
+ let at = Pos::new(id.clone(), len / 2);
+ select(&mut s, at.clone(), at, fonts)?;
+ change(&mut s, EditOp::InsertParagraph, fonts)?;
+ steps += 1;
+ }
+ let ids = s.document().body().paragraphs();
+ if ids.len() > 4 {
+ let a = &ids[ids.len() / 3];
+ let b = &ids[ids.len() / 3 + 1];
+ let a_len = s.document().body().get(a).map_or(0, |x| x.content.len());
+ let b_len = s.document().body().get(b).map_or(0, |x| x.content.len());
+ select(
+ &mut s,
+ Pos::new(a.clone(), a_len.min(1)),
+ Pos::new(b.clone(), b_len.min(1)),
+ fonts,
+ )?;
+ let deleted = maybe(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Default::default(),
+ },
+ fonts,
+ )?;
+ steps += usize::from(deleted);
+ }
+ let edited = texts(s.document());
+ for _ in 0..steps {
+ s.undo(fonts).ok_or("nothing to undo")?;
+ }
+ ensure(texts(s.document()) == original, || {
+ "undo did not restore the text".into()
+ })?;
+ for _ in 0..steps {
+ s.redo(fonts).ok_or("nothing to redo")?;
+ }
+ ensure(texts(s.document()) == edited, || {
+ "redo did not repeat the edits".into()
+ })?;
+ let saved = s.document().save().map_err(|e| e.to_string())?;
+ let reopened = Document::open(saved).map_err(|e| e.to_string())?;
+ ensure(texts(&reopened) == edited, || {
+ "the saved edits differ".into()
+ })
+}
+
+fn check_tracking(doc: &Document, fonts: &FontDb) -> Check {
+ let original = texts(doc);
+ let mut s = Session::new(doc.clone());
+ s.set_author("Corpus");
+ apply(&mut s, vec![EditOp::SetTracking { on: true }], fonts)?;
+ let tracked = texts(s.document());
+ ensure(tracked == original, || {
+ "turning tracking on changed the text".into()
+ })?;
+ let picks = targets(doc, 4);
+ for (id, len) in &picks {
+ let at = Pos::new(id.clone(), (*len).min(2));
+ select(&mut s, at.clone(), at, fonts)?;
+ apply(
+ &mut s,
+ vec![EditOp::InsertText { text: "QQ".into() }],
+ fonts,
+ )?;
+ if *len > 4 {
+ apply(
+ &mut s,
+ vec![EditOp::Delete {
+ forward: true,
+ unit: Default::default(),
+ }],
+ fonts,
+ )?;
+ }
+ }
+ let mut rejected = Session::new(s.document().clone());
+ apply(
+ &mut rejected,
+ vec![EditOp::RejectChanges { all: true }],
+ fonts,
+ )?;
+ // Rejecting returns the text this check started from. Revisions the
+ // file already had are rejected too, so compare with that state.
+ let mut baseline = Session::new(doc.clone());
+ apply(
+ &mut baseline,
+ vec![EditOp::RejectChanges { all: true }],
+ fonts,
+ )?;
+ ensure(
+ texts(rejected.document()) == texts(baseline.document()),
+ || "rejecting the tracked edits did not restore the text".into(),
+ )?;
+ apply(&mut s, vec![EditOp::AcceptChanges { all: true }], fonts)?;
+ let saved = s.document().save().map_err(|e| e.to_string())?;
+ Document::open(saved).map(|_| ()).map_err(|e| e.to_string())
+}
+
+fn check_header(doc: &Document, fonts: &FontDb) -> Check {
+ let mut s = Session::new(doc.clone());
+ let pages = s.pages(fonts);
+ let Some(area) = pages
+ .first()
+ .and_then(|p| p.header.clone())
+ .filter(|a| a.editable)
+ else {
+ return Ok(());
+ };
+ let width = pages[0].width;
+ let r = s
+ .apply(
+ &[EditOp::EnterStory {
+ page: 0,
+ x: width / 2.0,
+ y: (area.top + area.bottom) / 2.0,
+ }],
+ None,
+ fonts,
+ )
+ .map_err(|e| e.to_string())?;
+ if r.story.kind != docx_engine::edit::StoryKind::Header {
+ return Ok(());
+ }
+ apply(
+ &mut s,
+ vec![EditOp::InsertText { text: "HDR".into() }],
+ fonts,
+ )?;
+ apply(&mut s, vec![EditOp::ExitStory], fonts)?;
+ let saved = s.document().save().map_err(|e| e.to_string())?;
+ let reopened = Document::open(saved).map_err(|e| e.to_string())?;
+ let xml_has = reopened.package().part_names().any(|name| {
+ name.contains("header")
+ && reopened
+ .package()
+ .read(name)
+ .is_ok_and(|b| String::from_utf8_lossy(&b).contains("HDR"))
+ });
+ ensure(xml_has, || "the header edit was not saved".into())?;
+ ensure(texts(&reopened) == texts(doc), || {
+ "the header edit changed the body".into()
+ })
+}
+
+/// Types into the first footnote or endnote shown, and checks that the
+/// edit reaches the saved notes part and leaves the body alone.
+fn check_note(doc: &Document, fonts: &FontDb) -> Check {
+ let mut s = Session::new(doc.clone());
+ let pages = s.pages(fonts);
+ let Some((page, area)) = pages
+ .iter()
+ .enumerate()
+ .find_map(|(i, p)| p.notes.clone().map(|a| (i, a)))
+ else {
+ return Ok(());
+ };
+ let r = s
+ .apply(
+ &[EditOp::EnterStory {
+ page,
+ x: pages[page].width / 2.0,
+ y: (area.top + area.bottom) / 2.0,
+ }],
+ None,
+ fonts,
+ )
+ .map_err(|e| e.to_string())?;
+ use docx_engine::edit::StoryKind;
+ let endnote = match r.story.kind {
+ StoryKind::Footnote => false,
+ StoryKind::Endnote => true,
+ _ => return Err("a click in the notes area did not enter a note".into()),
+ };
+ change(
+ &mut s,
+ EditOp::InsertText {
+ text: "NOTE".into(),
+ },
+ fonts,
+ )?;
+ apply(&mut s, vec![EditOp::ExitStory], fonts)?;
+ let saved = s.document().save().map_err(|e| e.to_string())?;
+ let reopened = Document::open(saved).map_err(|e| e.to_string())?;
+ let notes = if endnote {
+ reopened.endnotes()
+ } else {
+ reopened.footnotes()
+ };
+ let has = notes.by_id.values().any(|n| {
+ n.story.paragraphs().iter().any(|id| {
+ n.story
+ .get(id)
+ .is_some_and(|b| b.content.text().contains("NOTE"))
+ })
+ });
+ ensure(has, || "the note edit was not saved".into())?;
+ ensure(texts(&reopened) == texts(doc), || {
+ "the note edit changed the body".into()
+ })
+}
+
+fn check_clipboard(doc: &Document, fonts: &FontDb) -> Check {
+ let mut s = Session::new(doc.clone());
+ let ids = s.document().body().paragraphs();
+ if ids.len() < 3 {
+ return Ok(());
+ }
+ let a = ids[1].clone();
+ let b = ids[2].clone();
+ let b_len = s.document().body().get(&b).map_or(0, |x| x.content.len());
+ select(&mut s, Pos::new(a, 0), Pos::new(b, b_len), fonts)?;
+ let clip = s.copy_selection();
+ let last = ids[ids.len() - 1].clone();
+ let len = s
+ .document()
+ .body()
+ .get(&last)
+ .map_or(0, |x| x.content.len());
+ select(
+ &mut s,
+ Pos::new(last.clone(), len),
+ Pos::new(last, len),
+ fonts,
+ )?;
+ let before = s.document().body().paragraphs().len();
+ apply(
+ &mut s,
+ vec![EditOp::Paste {
+ paragraphs: clip.paragraphs.clone(),
+ same_document: true,
+ }],
+ fonts,
+ )?;
+ let after = s.document().body().paragraphs().len();
+ ensure(after + 1 >= before + clip.paragraphs.len(), || {
+ format!(
+ "pasting {} paragraphs made {}",
+ clip.paragraphs.len(),
+ after - before
+ )
+ })?;
+ let saved = s.document().save().map_err(|e| e.to_string())?;
+ Document::open(saved).map(|_| ()).map_err(|e| e.to_string())
+}
+
+fn check(file: &PathBuf, width: u32, fonts: &FontDb) -> Result<String, String> {
+ let bytes = std::fs::read(file).map_err(|e| e.to_string())?;
+ let doc = Document::open(bytes).map_err(|e| format!("open: {e}"))?;
+ let pages = check_render(&doc, width, fonts).map_err(|e| format!("render: {e}"))?;
+ check_collab(&doc, pages, fonts).map_err(|e| format!("collab: {e}"))?;
+ check_edits(&doc, fonts).map_err(|e| format!("edits: {e}"))?;
+ check_tracking(&doc, fonts).map_err(|e| format!("tracking: {e}"))?;
+ check_header(&doc, fonts).map_err(|e| format!("header: {e}"))?;
+ check_note(&doc, fonts).map_err(|e| format!("note: {e}"))?;
+ check_clipboard(&doc, fonts).map_err(|e| format!("clipboard: {e}"))?;
+ Ok(format!("{pages} pages"))
+}
+
+/// Runs the command.
+pub fn run(args: &Args) -> Result<bool, Box<dyn std::error::Error>> {
+ let fonts = FontDb::global();
+ let mut failed = 0;
+ // Panics are reported per document, not printed by the hook.
+ std::panic::set_hook(Box::new(|_| {}));
+ for file in &args.files {
+ let started = Instant::now();
+ let outcome = catch_unwind(AssertUnwindSafe(|| check(file, args.width, fonts)))
+ .unwrap_or_else(|panic| {
+ let message = panic
+ .downcast_ref::<String>()
+ .cloned()
+ .or_else(|| panic.downcast_ref::<&str>().map(|s| (*s).to_owned()))
+ .unwrap_or_default();
+ Err(format!("panic: {message}"))
+ });
+ let name = file
+ .file_name()
+ .map_or_else(String::new, |n| n.to_string_lossy().into_owned());
+ let ms = started.elapsed().as_millis();
+ match outcome {
+ Ok(summary) => println!("ok {name}: {summary} ({ms} ms)"),
+ Err(error) => {
+ failed += 1;
+ println!("FAIL {name}: {error} ({ms} ms)");
+ }
+ }
+ }
+ println!(
+ "{} of {} documents passed",
+ args.files.len() - failed,
+ args.files.len()
+ );
+ Ok(failed == 0)
+}
diff --git a/crates/docx_engine/src/bin/docx_corpus/fontconfig.rs b/crates/docx_engine/src/bin/docx_corpus/fontconfig.rs
new file mode 100644
index 0000000000..49b59a37d1
--- /dev/null
+++ b/crates/docx_engine/src/bin/docx_corpus/fontconfig.rs
@@ -0,0 +1,66 @@
+//! `docx_corpus fontconfig`: a fontconfig file that makes LibreOffice use
+//! the engine's font files and substitutions for reference renders.
+
+use pptx_engine::font::{MONO_FALLBACK, SANS_FALLBACK, SERIF_FALLBACK, SUBSTITUTES};
+use std::path::{Path, PathBuf};
+
+/// Options of `docx_corpus fontconfig`.
+#[derive(clap::Args)]
+pub struct Args {
+ /// Where to write the file (`FONTCONFIG_FILE` for LibreOffice).
+ #[arg(long)]
+ out: PathBuf,
+}
+
+fn escape(s: &str) -> String {
+ s.replace('&', "&amp;")
+ .replace('<', "&lt;")
+ .replace('>', "&gt;")
+}
+
+fn document(font_dir: &Path) -> String {
+ let mut xml = String::from(
+ "<?xml version=\"1.0\"?>\n<!DOCTYPE fontconfig SYSTEM \"fonts.dtd\">\n<!-- Generated by `docx_corpus fontconfig`. -->\n<fontconfig>\n",
+ );
+ xml.push_str(&format!(
+ " <dir>{}</dir>\n",
+ escape(&font_dir.display().to_string())
+ ));
+ for (family, substitutes) in SUBSTITUTES {
+ let Some(first) = substitutes.first() else {
+ continue;
+ };
+ if family.eq_ignore_ascii_case(first) {
+ continue;
+ }
+ xml.push_str(&format!(
+ " <match target=\"pattern\"><test name=\"family\" ignore-blanks=\"true\"><string>{}</string></test><edit name=\"family\" mode=\"assign\" binding=\"strong\"><string>{}</string></edit></match>\n",
+ escape(family),
+ escape(first)
+ ));
+ }
+ xml.push_str(" <match target=\"pattern\"><test qual=\"all\" name=\"family\" compare=\"not_eq\"><string>sans-serif</string></test><test qual=\"all\" name=\"family\" compare=\"not_eq\"><string>serif</string></test><test qual=\"all\" name=\"family\" compare=\"not_eq\"><string>monospace</string></test><edit name=\"family\" mode=\"append_last\"><string>sans-serif</string></edit></match>\n");
+ for (generic, family) in [
+ ("sans-serif", SANS_FALLBACK),
+ ("serif", SERIF_FALLBACK),
+ ("monospace", MONO_FALLBACK),
+ ] {
+ xml.push_str(&format!(
+ " <alias binding=\"strong\"><family>{generic}</family><prefer><family>{}</family></prefer></alias>\n",
+ escape(family)
+ ));
+ }
+ xml.push_str(
+ " <include ignore_missing=\"yes\">/etc/fonts/fonts.conf</include>\n</fontconfig>\n",
+ );
+ xml
+}
+
+/// Runs the command.
+pub fn run(args: &Args) -> Result<bool, Box<dyn std::error::Error>> {
+ let fonts = Path::new(env!("CARGO_MANIFEST_DIR")).join("../pptx_engine/fonts");
+ let fonts = std::fs::canonicalize(&fonts).unwrap_or(fonts);
+ std::fs::write(&args.out, document(&fonts))?;
+ println!("{}", args.out.display());
+ Ok(true)
+}
diff --git a/crates/docx_engine/src/bin/docx_corpus/lines.rs b/crates/docx_engine/src/bin/docx_corpus/lines.rs
new file mode 100644
index 0000000000..b94bdd7b7c
--- /dev/null
+++ b/crates/docx_engine/src/bin/docx_corpus/lines.rs
@@ -0,0 +1,238 @@
+//! `docx_corpus lines`: the text lines of every page with their positions,
+//! as JSON, for comparing line and page breaks with a reference PDF.
+
+use docx_engine::Document;
+use docx_engine::layout::inline::Kind;
+use docx_engine::layout::{Item, PlacedLine, StoryRef};
+use pptx_engine::font::FontDb;
+use serde::Serialize;
+use std::path::PathBuf;
+
+/// Options of `docx_corpus lines`.
+#[derive(clap::Args)]
+pub struct Args {
+ /// Output JSON file (stdout when absent).
+ #[arg(long)]
+ out: Option<PathBuf>,
+ /// Print the cluster positions of lines containing this text instead.
+ #[arg(long)]
+ chars: Option<String>,
+ /// The document.
+ file: PathBuf,
+}
+
+/// One placed line.
+#[derive(Serialize)]
+struct LineOut {
+ /// Story: `body`, `part`, `footnote`, `endnote` or `textbox`.
+ story: &'static str,
+ /// Page x of the line's text start (points).
+ x: f32,
+ /// Page y of the line's top (points).
+ y: f32,
+ /// Page y of the baseline (points).
+ baseline: f32,
+ /// Line height (points).
+ height: f32,
+ /// Width of the content without trailing spaces (points).
+ width: f32,
+ /// Right edge of the line's text area (page x, points).
+ right: f32,
+ /// The text shown.
+ text: String,
+ /// The paragraph's style.
+ style: Option<String>,
+ /// The paragraph's line spacing rule.
+ spacing: String,
+ /// Whether the line starts its paragraph.
+ first: bool,
+ /// The paragraph's space before (points).
+ before: f32,
+ /// The paragraph's space after (points).
+ after: f32,
+ /// Whether the line ends its paragraph.
+ last: bool,
+ /// Whether the paragraph starts on a new page (`pageBreakBefore`).
+ page_break_before: bool,
+ /// Room for the line's content (points).
+ avail: f32,
+ /// See [`fit_stats`].
+ fit: [f32; 4],
+}
+
+/// The natural width of a line's content and of its spaces, the natural
+/// width of the next line's first word with the space before it (0 at the
+/// paragraph's end), and of the line's last word: what decides whether one
+/// more word fits.
+fn fit_stats(l: &PlacedLine) -> [f32; 4] {
+ let pb = &l.para;
+ let line = l.line();
+ let clusters = &pb.inline.clusters;
+ let mut end = line.end;
+ while end > line.start && matches!(clusters[end - 1].kind, Kind::Space | Kind::End | Kind::Zero)
+ {
+ end -= 1;
+ }
+ let content = &clusters[line.start..end];
+ let natural: f32 = content.iter().map(|c| c.advance).sum();
+ let spaces: f32 = content
+ .iter()
+ .filter(|c| c.kind == Kind::Space)
+ .map(|c| c.advance)
+ .sum();
+ let gap: f32 = clusters[end..line.end]
+ .iter()
+ .filter(|c| c.kind == Kind::Space)
+ .map(|c| c.advance)
+ .sum();
+ let next = pb.lines.lines.get(l.line + 1).map_or(0.0, |n| {
+ gap + clusters[n.start..n.end]
+ .iter()
+ .take_while(|c| c.kind != Kind::Space)
+ .map(|c| c.advance)
+ .sum::<f32>()
+ });
+ let last: f32 = content
+ .iter()
+ .rev()
+ .take_while(|c| c.kind != Kind::Space)
+ .map(|c| c.advance)
+ .sum();
+ [natural, spaces, next, last]
+}
+
+/// One page.
+#[derive(Serialize)]
+struct PageOut {
+ width: f32,
+ height: f32,
+ lines: Vec<LineOut>,
+ /// Drawings: (x, y, width, height).
+ drawings: Vec<[f32; 4]>,
+ /// The body area: (x, y, width, height).
+ body: [f32; 4],
+}
+
+fn story_name(s: &StoryRef) -> &'static str {
+ match s {
+ StoryRef::Body => "body",
+ StoryRef::Part(_) => "part",
+ StoryRef::Footnote(_) => "footnote",
+ StoryRef::Endnote(_) => "endnote",
+ StoryRef::TextBox(..) => "textbox",
+ }
+}
+
+fn line_text(l: &PlacedLine) -> String {
+ let line = l.line();
+ let clusters = &l.para.inline.clusters;
+ let mut s = String::new();
+ for c in &clusters[line.start..line.end.min(clusters.len())] {
+ match c.kind {
+ Kind::Text => s.push(c.ch),
+ Kind::Space => s.push(' '),
+ Kind::Tab => s.push('\t'),
+ Kind::Object(_) => s.push('\u{FFFC}'),
+ _ => {}
+ }
+ }
+ s
+}
+
+fn print_clusters(page: usize, l: &PlacedLine) {
+ let line = l.line();
+ let pb = &l.para;
+ println!(
+ "page {} y {:.2} left {:.2} right {:.2} width {:.2} height {:.2} ends {:?}",
+ page + 1,
+ l.y,
+ l.x + line.left,
+ l.x + line.right,
+ line.width,
+ line.height,
+ line.ends
+ );
+ let mut out = String::new();
+ for k in line.start..line.end {
+ let c = &pb.inline.clusters[k];
+ let shown = match c.kind {
+ Kind::Space => ' ',
+ Kind::Tab => '→',
+ Kind::Text => c.ch,
+ _ => continue,
+ };
+ out.push_str(&format!(
+ "{shown}@{:.2}+{:.3} ",
+ l.x + pb.lines.x[k],
+ pb.lines.adv[k]
+ ));
+ }
+ println!(" {out}");
+}
+
+/// Runs the command.
+pub fn run(args: &Args) -> Result<bool, Box<dyn std::error::Error>> {
+ let fonts = FontDb::global();
+ let doc = Document::open(std::fs::read(&args.file)?)?;
+ let layout = doc.layout(fonts);
+ if let Some(needle) = &args.chars {
+ for (pi, page) in layout.pages.iter().enumerate() {
+ for item in page.all_items() {
+ if let Item::Line(l) = item
+ && line_text(l).contains(needle.as_str())
+ {
+ print_clusters(pi, l);
+ }
+ }
+ }
+ return Ok(true);
+ }
+ let mut pages = Vec::with_capacity(layout.pages.len());
+ for page in &layout.pages {
+ let mut lines = Vec::new();
+ let drawings = page
+ .all_items()
+ .filter_map(|i| match i {
+ Item::Drawing(d) => Some([d.rect.x, d.rect.y, d.rect.w, d.rect.h]),
+ _ => None,
+ })
+ .collect();
+ for item in page.all_items() {
+ if let Item::Line(l) = item {
+ let line = l.line();
+ lines.push(LineOut {
+ story: story_name(&l.para.story),
+ x: l.x + line.left,
+ y: l.y,
+ baseline: l.baseline(),
+ height: line.height,
+ width: line.width,
+ right: l.x + line.right,
+ text: line_text(l),
+ style: l.para.format.props.style.clone(),
+ spacing: format!("{:?}", l.para.format.props.line),
+ first: line.start == 0,
+ before: l.para.format.props.before,
+ after: l.para.format.props.after,
+ last: l.line + 1 == l.para.lines.lines.len(),
+ page_break_before: l.para.format.props.page_break_before,
+ avail: line.right - line.left,
+ fit: fit_stats(l),
+ });
+ }
+ }
+ pages.push(PageOut {
+ width: page.width,
+ height: page.height,
+ lines,
+ drawings,
+ body: [page.body.x, page.body.y, page.body.w, page.body.h],
+ });
+ }
+ let json = serde_json::to_string(&pages)?;
+ match &args.out {
+ Some(p) => std::fs::write(p, json)?,
+ None => println!("{json}"),
+ }
+ Ok(true)
+}
diff --git a/crates/docx_engine/src/bin/docx_corpus/main.rs b/crates/docx_engine/src/bin/docx_corpus/main.rs
new file mode 100644
index 0000000000..3831c7f186
--- /dev/null
+++ b/crates/docx_engine/src/bin/docx_corpus/main.rs
@@ -0,0 +1,50 @@
+//! `docx_corpus`: renders documents and scores them against reference renders.
+
+mod check;
+mod fontconfig;
+mod lines;
+mod render;
+mod score;
+
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(about = "DOCX engine corpus tools")]
+struct Cli {
+ #[command(subcommand)]
+ command: Command,
+}
+
+#[derive(Subcommand)]
+enum Command {
+ /// Renders documents to PNG pages.
+ Render(render::Args),
+ /// Compares renders with reference renders and writes a report.
+ Score(score::Args),
+ /// Writes a fontconfig file for LibreOffice reference renders.
+ Fontconfig(fontconfig::Args),
+ /// Dumps the text lines of every page with their positions as JSON.
+ Lines(lines::Args),
+ /// Runs every document through rendering, the collaborative state,
+ /// editing, tracked changes, header edits, copy/paste and saving.
+ Check(check::Args),
+}
+
+fn main() {
+ let cli = Cli::parse();
+ let ok = match cli.command {
+ Command::Render(args) => render::run(&args),
+ Command::Score(args) => score::run(&args),
+ Command::Fontconfig(args) => fontconfig::run(&args),
+ Command::Lines(args) => lines::run(&args),
+ Command::Check(args) => check::run(&args),
+ };
+ match ok {
+ Ok(true) => {}
+ Ok(false) => std::process::exit(1),
+ Err(e) => {
+ eprintln!("error: {e}");
+ std::process::exit(2);
+ }
+ }
+}
diff --git a/crates/docx_engine/src/bin/docx_corpus/render.rs b/crates/docx_engine/src/bin/docx_corpus/render.rs
new file mode 100644
index 0000000000..a65ccd0478
--- /dev/null
+++ b/crates/docx_engine/src/bin/docx_corpus/render.rs
@@ -0,0 +1,66 @@
+//! `docx_corpus render`: PNG pages of documents.
+
+use docx_engine::Document;
+use docx_engine::render::ImageCache;
+use pptx_engine::font::FontDb;
+use std::path::PathBuf;
+use std::time::Instant;
+
+/// Options of `docx_corpus render`.
+#[derive(clap::Args)]
+pub struct Args {
+ /// Output directory (one subdirectory per document).
+ #[arg(long)]
+ out: PathBuf,
+ /// Page width in pixels.
+ #[arg(long, default_value_t = 816)]
+ width: u32,
+ /// Only the first N pages.
+ #[arg(long)]
+ pages: Option<usize>,
+ /// Documents.
+ files: Vec<PathBuf>,
+}
+
+/// Runs the command.
+pub fn run(args: &Args) -> Result<bool, Box<dyn std::error::Error>> {
+ let fonts = FontDb::global();
+ let mut ok = true;
+ for file in &args.files {
+ let stem = file
+ .file_stem()
+ .map(|s| s.to_string_lossy().into_owned())
+ .unwrap_or_else(|| "doc".into());
+ let started = Instant::now();
+ let doc = match Document::open(std::fs::read(file)?) {
+ Ok(d) => d,
+ Err(e) => {
+ eprintln!("{}: {e}", file.display());
+ ok = false;
+ continue;
+ }
+ };
+ let opened = started.elapsed();
+ let layout = doc.layout(fonts);
+ let laid = started.elapsed() - opened;
+ let dir = args.out.join(&stem);
+ std::fs::create_dir_all(&dir)?;
+ let mut images = ImageCache::new();
+ let count = args
+ .pages
+ .map_or(layout.pages.len(), |n| n.min(layout.pages.len()));
+ for i in 0..count {
+ if let Some(r) = doc.render_page(&layout, i, args.width, fonts, &mut images) {
+ std::fs::write(dir.join(format!("page-{:03}.png", i + 1)), r.to_png())?;
+ }
+ }
+ println!(
+ "{stem}: {} pages (open {:.0} ms, layout {:.0} ms, total {:.0} ms)",
+ layout.pages.len(),
+ opened.as_secs_f64() * 1000.0,
+ laid.as_secs_f64() * 1000.0,
+ started.elapsed().as_secs_f64() * 1000.0
+ );
+ }
+ Ok(ok)
+}
diff --git a/crates/docx_engine/src/bin/docx_corpus/score.rs b/crates/docx_engine/src/bin/docx_corpus/score.rs
new file mode 100644
index 0000000000..96ce61bcbf
--- /dev/null
+++ b/crates/docx_engine/src/bin/docx_corpus/score.rs
@@ -0,0 +1,322 @@
+//! `docx_corpus score`: renders documents and compares every page with
+//! reference renders (LibreOffice, and Word where a Word PDF exists).
+
+use docx_engine::Document;
+use docx_engine::render::ImageCache;
+use pptx_engine::fidelity::{self, Score};
+use pptx_engine::font::FontDb;
+use pptx_engine::render::image::decode_raster;
+use pptx_engine::render::scene::Raster;
+use serde::Serialize;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::time::Instant;
+
+/// Options of `docx_corpus score`.
+#[derive(clap::Args)]
+pub struct Args {
+ /// Reference renders (OUT_DIR of scripts/render_references.py).
+ #[arg(long)]
+ refs: PathBuf,
+ /// Directory for our renders and report.html.
+ #[arg(long)]
+ out: PathBuf,
+ /// Page width in pixels (must match the references).
+ #[arg(long, default_value_t = 816)]
+ width: u32,
+ /// Worker threads.
+ #[arg(long, default_value_t = 4)]
+ jobs: usize,
+ /// Documents.
+ files: Vec<PathBuf>,
+}
+
+/// Scores of one document against one reference set.
+#[derive(Clone, Debug, Default, Serialize)]
+pub struct RefScore {
+ /// Reference page count.
+ pub pages: usize,
+ /// Per-page scores (pages both have).
+ pub page_scores: Vec<Score>,
+ /// Mean SSIM over the compared pages.
+ pub ssim: f32,
+}
+
+/// Results for one document.
+#[derive(Clone, Debug, Default, Serialize)]
+pub struct DocResult {
+ /// File stem.
+ pub stem: String,
+ /// Our page count.
+ pub pages: usize,
+ /// Layout + render time.
+ pub millis: u128,
+ /// Error, when the document failed.
+ pub error: Option<String>,
+ /// Against LibreOffice.
+ pub lo: Option<RefScore>,
+ /// Against Word.
+ pub word: Option<RefScore>,
+}
+
+fn load_refs(dir: &Path) -> Vec<Raster> {
+ let mut out = Vec::new();
+ for i in 1.. {
+ let p = dir.join(format!("page-{i:03}.png"));
+ let Ok(bytes) = std::fs::read(&p) else {
+ break;
+ };
+ match decode_raster(&bytes) {
+ Ok(r) => out.push(r),
+ Err(_) => break,
+ }
+ }
+ out
+}
+
+fn score(ours: &[Raster], refs: &[Raster]) -> RefScore {
+ let n = ours.len().min(refs.len());
+ let page_scores: Vec<Score> = (0..n)
+ .map(|i| fidelity::compare(&ours[i], &refs[i]))
+ .collect();
+ let ssim = if n == 0 {
+ 0.0
+ } else {
+ page_scores.iter().map(|s| s.ssim).sum::<f32>() / n as f32
+ };
+ RefScore {
+ pages: refs.len(),
+ page_scores,
+ ssim,
+ }
+}
+
+fn process(file: &Path, args: &Args, fonts: &FontDb) -> DocResult {
+ let stem = file
+ .file_stem()
+ .map(|s| s.to_string_lossy().into_owned())
+ .unwrap_or_default();
+ let started = Instant::now();
+ let mut result = DocResult {
+ stem: stem.clone(),
+ ..DocResult::default()
+ };
+ let bytes = match std::fs::read(file) {
+ Ok(b) => b,
+ Err(e) => {
+ result.error = Some(e.to_string());
+ return result;
+ }
+ };
+ let doc = match Document::open(bytes) {
+ Ok(d) => d,
+ Err(e) => {
+ result.error = Some(e.to_string());
+ return result;
+ }
+ };
+ let layout = doc.layout(fonts);
+ let mut images = ImageCache::new();
+ let dir = args.out.join(&stem);
+ let _ = std::fs::create_dir_all(&dir);
+ let mut ours = Vec::new();
+ for i in 0..layout.pages.len() {
+ if let Some(r) = doc.render_page(&layout, i, args.width, fonts, &mut images) {
+ let _ = std::fs::write(dir.join(format!("page-{:03}.png", i + 1)), r.to_png());
+ ours.push(r);
+ }
+ }
+ result.millis = started.elapsed().as_millis();
+ result.pages = ours.len();
+ let lo = load_refs(&args.refs.join("lo").join(&stem));
+ if !lo.is_empty() {
+ result.lo = Some(score(&ours, &lo));
+ }
+ let word = load_refs(&args.refs.join("word").join(&stem));
+ if !word.is_empty() {
+ result.word = Some(score(&ours, &word));
+ }
+ result
+}
+
+fn rel(from: &Path, to: &Path) -> String {
+ pathdiff(to, from).unwrap_or_else(|| to.display().to_string())
+}
+
+fn pathdiff(path: &Path, base: &Path) -> Option<String> {
+ let path = std::fs::canonicalize(path).ok()?;
+ let base = std::fs::canonicalize(base).ok()?;
+ let mut pc = path.components().peekable();
+ let mut bc = base.components().peekable();
+ while let (Some(a), Some(b)) = (pc.peek(), bc.peek()) {
+ if a != b {
+ break;
+ }
+ pc.next();
+ bc.next();
+ }
+ let mut out = PathBuf::new();
+ for _ in bc {
+ out.push("..");
+ }
+ for c in pc {
+ out.push(c);
+ }
+ Some(out.display().to_string())
+}
+
+fn report(results: &[DocResult], args: &Args) -> std::io::Result<()> {
+ let mut html = String::from(
+ "<!doctype html><meta charset=utf-8><title>DOCX fidelity</title><style>body{font:13px system-ui;margin:16px}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:3px 6px}img{width:300px;border:1px solid #ddd;margin:2px}.p{display:flex;gap:4px;align-items:flex-start}.bad{background:#fdd}</style><h1>DOCX fidelity</h1><table><tr><th>document</th><th>pages</th><th>LO pages</th><th>LO SSIM</th><th>Word pages</th><th>Word SSIM</th><th>ms</th></tr>",
+ );
+ for r in results {
+ let lo = r.lo.as_ref();
+ let wd = r.word.as_ref();
+ let cls = |s: Option<&RefScore>| {
+ if s.is_some_and(|s| s.pages != r.pages) {
+ " class=bad"
+ } else {
+ ""
+ }
+ };
+ html.push_str(&format!(
+ "<tr><td><a href='#{0}'>{0}</a>{1}</td><td>{2}</td><td{3}>{4}</td><td>{5}</td><td{6}>{7}</td><td>{8}</td><td>{9}</td></tr>",
+ r.stem,
+ r.error.as_ref().map(|e| format!(" <b>{e}</b>")).unwrap_or_default(),
+ r.pages,
+ cls(lo),
+ lo.map_or("-".into(), |s| s.pages.to_string()),
+ lo.map_or("-".into(), |s| format!("{:.3}", s.ssim)),
+ cls(wd),
+ wd.map_or("-".into(), |s| s.pages.to_string()),
+ wd.map_or("-".into(), |s| format!("{:.3}", s.ssim)),
+ r.millis
+ ));
+ }
+ html.push_str("</table>");
+ for r in results {
+ html.push_str(&format!("<h2 id='{0}'>{0}</h2>", r.stem));
+ let pages = r
+ .pages
+ .max(r.lo.as_ref().map_or(0, |s| s.pages))
+ .max(r.word.as_ref().map_or(0, |s| s.pages));
+ for i in 1..=pages {
+ html.push_str(&format!("<div>page {i}"));
+ if let Some(s) = r.lo.as_ref().and_then(|s| s.page_scores.get(i - 1)) {
+ html.push_str(&format!(" LO ssim {:.3}", s.ssim));
+ }
+ if let Some(s) = r.word.as_ref().and_then(|s| s.page_scores.get(i - 1)) {
+ html.push_str(&format!(" Word ssim {:.3}", s.ssim));
+ }
+ html.push_str("</div><div class=p>");
+ let ours = args.out.join(&r.stem).join(format!("page-{i:03}.png"));
+ let lo = args
+ .refs
+ .join("lo")
+ .join(&r.stem)
+ .join(format!("page-{i:03}.png"));
+ let word = args
+ .refs
+ .join("word")
+ .join(&r.stem)
+ .join(format!("page-{i:03}.png"));
+ for (label, p) in [("ours", ours), ("LibreOffice", lo), ("Word", word)] {
+ if p.exists() {
+ html.push_str(&format!(
+ "<figure><img loading=lazy src='{}'><figcaption>{label}</figcaption></figure>",
+ rel(&args.out, &p)
+ ));
+ }
+ }
+ html.push_str("</div>");
+ }
+ }
+ std::fs::write(args.out.join("report.html"), html)
+}
+
+/// Runs the command.
+pub fn run(args: &Args) -> Result<bool, Box<dyn std::error::Error>> {
+ std::fs::create_dir_all(&args.out)?;
+ let fonts = FontDb::global();
+ let files: Vec<PathBuf> = args.files.clone();
+ let queue = Mutex::new(files.iter().enumerate().collect::<Vec<_>>());
+ let results: Mutex<Vec<(usize, DocResult)>> = Mutex::new(Vec::new());
+ std::thread::scope(|s| {
+ for _ in 0..args.jobs.max(1) {
+ s.spawn(|| {
+ loop {
+ let next = queue.lock().ok().and_then(|mut q| q.pop());
+ let Some((i, f)) = next else {
+ break;
+ };
+ let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ process(f, args, fonts)
+ }))
+ .unwrap_or_else(|_| DocResult {
+ stem: f.display().to_string(),
+ error: Some("panicked".into()),
+ ..DocResult::default()
+ });
+ if let Ok(mut rs) = results.lock() {
+ rs.push((i, r));
+ }
+ }
+ });
+ }
+ });
+ let mut results: Vec<(usize, DocResult)> = results.into_inner().unwrap_or_default();
+ results.sort_by_key(|(i, _)| *i);
+ let results: Vec<DocResult> = results.into_iter().map(|(_, r)| r).collect();
+ println!(
+ "{:<60} {:>5} {:>5} {:>7} {:>5} {:>7} {:>7}",
+ "document", "pages", "lo", "ssim", "word", "ssim", "ms"
+ );
+ let (mut lo_sum, mut lo_n, mut wd_sum, mut wd_n) = (0.0, 0, 0.0, 0);
+ let (mut lo_pages_ok, mut wd_pages_ok) = (0, 0);
+ for r in &results {
+ let lo = r.lo.as_ref();
+ let wd = r.word.as_ref();
+ if let Some(s) = lo {
+ lo_sum += s.ssim;
+ lo_n += 1;
+ lo_pages_ok += usize::from(s.pages == r.pages);
+ }
+ if let Some(s) = wd {
+ wd_sum += s.ssim;
+ wd_n += 1;
+ wd_pages_ok += usize::from(s.pages == r.pages);
+ }
+ println!(
+ "{:<60} {:>5} {:>5} {:>7} {:>5} {:>7} {:>7}{}",
+ r.stem.chars().take(60).collect::<String>(),
+ r.pages,
+ lo.map_or("-".into(), |s| s.pages.to_string()),
+ lo.map_or("-".into(), |s| format!("{:.3}", s.ssim)),
+ wd.map_or("-".into(), |s| s.pages.to_string()),
+ wd.map_or("-".into(), |s| format!("{:.3}", s.ssim)),
+ r.millis,
+ r.error
+ .as_ref()
+ .map(|e| format!(" ERROR {e}"))
+ .unwrap_or_default()
+ );
+ }
+ if lo_n > 0 {
+ println!(
+ "LibreOffice: mean SSIM {:.4} over {lo_n} documents; page counts equal for {lo_pages_ok}",
+ lo_sum / lo_n as f32
+ );
+ }
+ if wd_n > 0 {
+ println!(
+ "Word: mean SSIM {:.4} over {wd_n} documents; page counts equal for {wd_pages_ok}",
+ wd_sum / wd_n as f32
+ );
+ }
+ std::fs::write(
+ args.out.join("scores.json"),
+ serde_json::to_string_pretty(&results)?,
+ )?;
+ report(&results, args)?;
+ Ok(results.iter().all(|r| r.error.is_none()))
+}
diff --git a/crates/docx_engine/src/collab.rs b/crates/docx_engine/src/collab.rs
new file mode 100644
index 0000000000..7d6bf25819
--- /dev/null
+++ b/crates/docx_engine/src/collab.rs
@@ -0,0 +1,724 @@
+//! Collaborative editing: a document as CRDT containers.
+//!
+//! Peers share a document through these containers (Loro maps in the web
+//! app and on the sync service):
+//!
+//! | container | key | value |
+//! | --- | --- | --- |
+//! | `docxMeta` | `formatVersion` | [`FORMAT_VERSION`] (written by the client) |
+//! | `wordParts` | part name | XML text, or `b64:` + base64; the main part is its shell, with [`Shell::BLOCKS`] where the body's blocks go; a footnotes or endnotes part is its XML without the notes, each note under `part\|id` |
+//! | `wordTypes` | `default\|ext`, `override\|part` | content type |
+//! | `wordRels` | `relsPart\|rId` | `<Relationship/>` element |
+//! | `wordBlocks` | block id | map: `k` kind, `p` parent, `o` position key, `a` attributes, `x` properties, `t` rich text |
+//!
+//! Every paragraph's text is its own rich-text container whose marks are the
+//! span attributes, so concurrent typing in one paragraph merges character by
+//! character, and formatting different properties of the same text merges
+//! too. Block fields are last-writer-wins. Ids of new blocks, parts and
+//! relationships are random per peer so concurrent additions never collide.
+//! Notes are shared one by one, so typing in a footnote shares that note
+//! (not the whole part) and two people can edit different notes at once.
+
+use crate::document::{Document, Shell};
+use crate::edit::{BlockRecord, Change};
+use crate::error::{Error, Result};
+use crate::model::block::{IdGen, Story};
+use crate::xml::XmlTree;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD;
+use pptx_engine::opc::{CONTENT_TYPES_PART, ContentTypes, Package, TargetMode};
+use pptx_engine::zip::{WriteData, Writer};
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+
+/// Version of the container layout (`docxMeta.formatVersion`).
+pub const FORMAT_VERSION: u32 = 2;
+
+/// Separates a part name from the item it scopes in composite keys.
+pub const KEY_SEPARATOR: char = '|';
+
+/// Names of the containers.
+pub mod container {
+ /// Format metadata (shared with the first format).
+ pub const META: &str = "docxMeta";
+ /// Parts by name.
+ pub const PARTS: &str = "wordParts";
+ /// Content types.
+ pub const TYPES: &str = "wordTypes";
+ /// Relationships.
+ pub const RELS: &str = "wordRels";
+ /// Blocks by id.
+ pub const BLOCKS: &str = "wordBlocks";
+}
+
+const RELATIONSHIPS_NS: &str = "http://schemas.openxmlformats.org/package/2006/relationships";
+const CONTENT_TYPES_NS: &str = "http://schemas.openxmlformats.org/package/2006/content-types";
+
+/// The whole shared state of a document.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct CollabState {
+ /// `wordParts`.
+ pub parts: BTreeMap<String, String>,
+ /// `wordTypes`.
+ pub types: BTreeMap<String, String>,
+ /// `wordRels`.
+ pub rels: BTreeMap<String, String>,
+ /// `wordBlocks`, parents before children.
+ pub blocks: Vec<BlockRecord>,
+}
+
+/// Whether `name` is a relationships part.
+fn is_rels_part(name: &str) -> bool {
+ name.ends_with(".rels") && name.contains("_rels/")
+}
+
+fn scoped(part: &str, item: &str) -> String {
+ format!("{part}{KEY_SEPARATOR}{item}")
+}
+
+fn escape(out: &mut String, value: &str) {
+ for c in value.chars() {
+ match c {
+ '&' => out.push_str("&amp;"),
+ '<' => out.push_str("&lt;"),
+ '>' => out.push_str("&gt;"),
+ '"' => out.push_str("&quot;"),
+ _ => out.push(c),
+ }
+ }
+}
+
+fn relationship_xml(r: &pptx_engine::opc::Relationship) -> String {
+ let mut s = String::from("<Relationship Id=\"");
+ escape(&mut s, &r.id);
+ s.push_str("\" Type=\"");
+ escape(&mut s, &r.rel_type);
+ s.push_str("\" Target=\"");
+ escape(&mut s, &r.target);
+ s.push('"');
+ if r.mode == TargetMode::External {
+ s.push_str(" TargetMode=\"External\"");
+ }
+ s.push_str("/>");
+ s
+}
+
+/// A part's bytes as a shared string: XML as text, anything else base64.
+fn encode_part(pkg: &Package, name: &str, bytes: &[u8]) -> String {
+ let xml =
+ pkg.content_type(name).is_some_and(|ct| ct.ends_with("xml")) || name.ends_with(".xml");
+ if xml
+ && !bytes.starts_with(b"b64:")
+ && let Ok(text) = std::str::from_utf8(bytes)
+ {
+ return text.to_owned();
+ }
+ format!("b64:{}", STANDARD.encode(bytes))
+}
+
+fn decode_part(value: &str) -> Vec<u8> {
+ match value.strip_prefix("b64:") {
+ Some(data) => STANDARD.decode(data).unwrap_or_default(),
+ None => value.as_bytes().to_vec(),
+ }
+}
+
+/// Content type entries of a package.
+fn type_entries(types: &ContentTypes) -> BTreeMap<String, String> {
+ let mut out = BTreeMap::new();
+ for (ext, ct) in types.defaults() {
+ out.insert(scoped("default", &ext.to_ascii_lowercase()), ct.to_owned());
+ }
+ for (part, ct) in types.overrides() {
+ out.insert(scoped("override", part), ct.to_owned());
+ }
+ out
+}
+
+/// `[Content_Types].xml` from its entries.
+fn content_types_xml(types: &BTreeMap<String, String>) -> String {
+ let mut s = format!(
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<Types xmlns=\"{CONTENT_TYPES_NS}\">"
+ );
+ for (key, ct) in types {
+ if let Some(ext) = key.strip_prefix("default|") {
+ s.push_str("<Default Extension=\"");
+ escape(&mut s, ext);
+ s.push_str("\" ContentType=\"");
+ escape(&mut s, ct);
+ s.push_str("\"/>");
+ }
+ }
+ for (key, ct) in types {
+ if let Some(part) = key.strip_prefix("override|") {
+ s.push_str("<Override PartName=\"");
+ escape(&mut s, part);
+ s.push_str("\" ContentType=\"");
+ escape(&mut s, ct);
+ s.push_str("\"/>");
+ }
+ }
+ s.push_str("</Types>");
+ s
+}
+
+/// rIds sort numerically when they can (`rId2` before `rId10`).
+fn rid_order(id: &str) -> (u64, &str) {
+ let n = id
+ .strip_prefix("rId")
+ .and_then(|n| n.parse().ok())
+ .unwrap_or(u64::MAX);
+ (n, id)
+}
+
+/// A relationships part from its entries.
+fn relationships_xml(rels: &BTreeMap<String, String>, part: &str) -> Option<String> {
+ let prefix = scoped(part, "");
+ let mut items: Vec<(&str, &str)> = rels
+ .range::<str, _>((
+ std::ops::Bound::Included(prefix.as_str()),
+ std::ops::Bound::Unbounded,
+ ))
+ .take_while(|(k, _)| k.starts_with(&prefix))
+ .map(|(k, v)| (&k[prefix.len()..], v.as_str()))
+ .collect();
+ if items.is_empty() {
+ return None;
+ }
+ items.sort_by(|a, b| rid_order(a.0).cmp(&rid_order(b.0)));
+ let mut s = format!(
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<Relationships xmlns=\"{RELATIONSHIPS_NS}\">"
+ );
+ for (_, xml) in items {
+ s.push_str(xml);
+ }
+ s.push_str("</Relationships>");
+ Some(s)
+}
+
+/// A footnotes or endnotes part's XML split into the XML without its notes
+/// and the notes by id (each as written).
+fn split_notes(name: &str, xml: &[u8]) -> Option<(String, BTreeMap<i64, String>)> {
+ let tree = XmlTree::parse(xml, name).ok()?;
+ let root = tree.root();
+ if !(tree.is_w(root, "footnotes") || tree.is_w(root, "endnotes")) {
+ return None;
+ }
+ let src = tree.source();
+ let mut skeleton = String::with_capacity(src.len() / 8);
+ let mut notes = BTreeMap::new();
+ let mut at = 0;
+ for n in tree.children(root) {
+ let is_note = tree.is_w(n, "footnote") || tree.is_w(n, "endnote");
+ let id = is_note
+ .then(|| tree.w_attr(n, "id").and_then(crate::xml::parse_int))
+ .flatten()
+ .filter(|id| !notes.contains_key(id));
+ let Some(id) = id else {
+ continue;
+ };
+ let span = tree.span(n);
+ skeleton.push_str(&src[at..span.start]);
+ at = span.end;
+ notes.insert(id, src[span.start..span.end].to_owned());
+ }
+ skeleton.push_str(&src[at..]);
+ Some((skeleton, notes))
+}
+
+/// A notes part's XML from its shared form: the notes go back in after
+/// the root's start tag, in id order.
+fn join_notes<'a>(name: &str, skeleton: &str, notes: impl Iterator<Item = &'a String>) -> String {
+ let notes: String = notes.map(String::as_str).collect();
+ let Ok(tree) = XmlTree::parse(skeleton.as_bytes(), name) else {
+ return skeleton.to_owned();
+ };
+ let root = tree.root();
+ let src = tree.source();
+ let span = tree.span(root);
+ let tag = tree.start_tag(root);
+ match tag.strip_suffix("/>") {
+ Some(open) => format!(
+ "{}{}>{notes}</{}>{}",
+ &src[..span.start],
+ open.trim_end(),
+ tree.qname(root),
+ &src[span.end..]
+ ),
+ None => {
+ let at = span.start + tag.len();
+ format!("{}{notes}{}", &src[..at], &src[at..])
+ }
+ }
+}
+
+/// The note id a `wordParts` key names (`part|id`), with its part.
+fn note_key(key: &str) -> Option<(&str, i64)> {
+ let (part, id) = key.rsplit_once(KEY_SEPARATOR)?;
+ Some((part, id.parse().ok()?))
+}
+
+/// The block records of a story, parents before children.
+fn story_records(story: &Story) -> Vec<BlockRecord> {
+ let mut out = Vec::with_capacity(story.len());
+ story.walk(|b, _| out.push(BlockRecord::of(b)));
+ // Orphans (from concurrent deletes) are not part of the document.
+ out
+}
+
+impl Document {
+ /// The main part's shell: its XML around the blocks, with the final
+ /// section properties.
+ pub fn shell_template(&self) -> String {
+ self.shell.to_template()
+ }
+
+ /// The shared state of this document.
+ pub fn collab_state(&self) -> Result<CollabState> {
+ let mut state = CollabState::default();
+ let pkg = &self.pkg;
+ let names: Vec<String> = pkg.part_names().map(str::to_owned).collect();
+ for name in &names {
+ if name.eq_ignore_ascii_case(CONTENT_TYPES_PART) {
+ continue;
+ }
+ if is_rels_part(name) {
+ let source = rels_source(name);
+ let rels = pkg.rels(&source)?;
+ for r in rels.iter() {
+ state.rels.insert(scoped(name, &r.id), relationship_xml(r));
+ }
+ continue;
+ }
+ if *name == self.main {
+ state.parts.insert(name.clone(), self.shell.to_template());
+ continue;
+ }
+ let bytes = pkg.read(name)?;
+ if self.is_notes_part(name)
+ && let Some((skeleton, notes)) = split_notes(name, &bytes)
+ {
+ state.parts.insert(name.clone(), skeleton);
+ for (id, xml) in notes {
+ state.parts.insert(scoped(name, &id.to_string()), xml);
+ }
+ continue;
+ }
+ state
+ .parts
+ .insert(name.clone(), encode_part(pkg, name, &bytes));
+ }
+ state.types = type_entries(pkg.content_types());
+ state.blocks = story_records(&self.body);
+ Ok(state)
+ }
+
+ /// Opens the document a shared state describes. `seed` makes this
+ /// peer's new block ids unique.
+ pub fn from_collab_state(state: &CollabState, seed: u64) -> Result<Document> {
+ if state.parts.is_empty() {
+ return Err(Error::Collab("the shared document is empty".into()));
+ }
+ let bytes = assemble(state)?;
+ let mut doc = Document::open_with_ids(bytes, IdGen::random(seed))?;
+ let mut story = Story::new();
+ for record in &state.blocks {
+ if let Some(b) = record.to_block() {
+ story.insert(b);
+ }
+ }
+ doc.body = story;
+ doc.body_dirty = true;
+ Ok(doc)
+ }
+
+ /// Whether a part holds the footnotes or endnotes.
+ pub(crate) fn is_notes_part(&self, name: &str) -> bool {
+ self.footnotes().part.as_deref() == Some(name)
+ || self.endnotes().part.as_deref() == Some(name)
+ }
+
+ /// Applies changes to the flat maps made by other peers (parts,
+ /// relationships, content types), reloading what they affect. Returns
+ /// whether the shared parts (styles, numbering...) were reloaded.
+ pub fn apply_entries(&mut self, changes: &[(String, String, Option<String>)]) -> Result<bool> {
+ if changes.is_empty() {
+ return Ok(false);
+ }
+ let mut links = self.link_entries()?;
+ // Whole parts, and notes by part, as the changes leave them.
+ let mut parts: BTreeMap<String, Option<String>> = BTreeMap::new();
+ let mut notes: BTreeMap<String, BTreeMap<i64, Option<String>>> = BTreeMap::new();
+ let mut touched: BTreeSet<String> = BTreeSet::new();
+ let mut types_changed = false;
+ for (container, key, value) in changes {
+ match container.as_str() {
+ container::PARTS => match note_key(key) {
+ Some((part, id)) => {
+ notes
+ .entry(part.to_owned())
+ .or_default()
+ .insert(id, value.clone());
+ touched.insert(part.to_owned());
+ }
+ None => {
+ parts.insert(key.clone(), value.clone());
+ touched.insert(key.clone());
+ }
+ },
+ container::RELS => {
+ match value {
+ Some(v) => links.rels.insert(key.clone(), v.clone()),
+ None => links.rels.remove(key),
+ };
+ if let Some((part, _)) = key.rsplit_once(KEY_SEPARATOR) {
+ touched.insert(part.to_owned());
+ }
+ }
+ container::TYPES => {
+ match value {
+ Some(v) => links.types.insert(key.clone(), v.clone()),
+ None => links.types.remove(key),
+ };
+ types_changed = true;
+ }
+ _ => {}
+ }
+ }
+ for name in &touched {
+ if is_rels_part(name) {
+ match relationships_xml(&links.rels, name) {
+ Some(xml) => self.pkg.write(name, xml.into_bytes(), None),
+ None => self.pkg.delete(name),
+ }
+ continue;
+ }
+ if *name == self.main {
+ if let Some(Some(template)) = parts.get(name)
+ && let Some(shell) = Shell::from_template(template)
+ {
+ self.shell = shell;
+ self.body_dirty = true;
+ }
+ continue;
+ }
+ let note_changes = notes.get(name);
+ if note_changes.is_some() || self.is_notes_part(name) {
+ // The notes part as it is, with the changes on top.
+ let current = self.pkg.read(name).ok().and_then(|b| split_notes(name, &b));
+ let (mut skeleton, mut by_id) = current.unwrap_or_default();
+ match parts.get(name) {
+ Some(None) => {
+ self.pkg.delete(name);
+ continue;
+ }
+ Some(Some(value)) => {
+ let bytes = decode_part(value);
+ match split_notes(name, &bytes) {
+ // A whole part (with its notes) replaces them all.
+ Some((s, n)) if !n.is_empty() => (skeleton, by_id) = (s, n),
+ Some((s, _)) => skeleton = s,
+ None => {
+ self.pkg.write(name, bytes, None);
+ continue;
+ }
+ }
+ }
+ None => {}
+ }
+ for (id, xml) in note_changes.into_iter().flatten() {
+ match xml {
+ Some(x) => by_id.insert(*id, x.clone()),
+ None => by_id.remove(id),
+ };
+ }
+ if skeleton.is_empty() {
+ continue;
+ }
+ let xml = join_notes(name, &skeleton, by_id.values());
+ self.pkg.write(name, xml.into_bytes(), None);
+ continue;
+ }
+ match parts.get(name) {
+ Some(Some(v)) => self.pkg.write(name, decode_part(v), None),
+ Some(None) => self.pkg.delete(name),
+ None => {}
+ }
+ }
+ if types_changed {
+ let types = ContentTypes::parse(content_types_xml(&links.types).as_bytes())?;
+ self.pkg.set_content_types(types);
+ }
+ let main_rels = pptx_engine::opc::rels_part_name(&self.main);
+ if touched.contains(&main_rels) {
+ self.main_rels = std::sync::Arc::new(self.pkg.rels(&self.main)?);
+ }
+ let reload = touched.iter().any(|n| *n != self.main);
+ if reload {
+ self.load_parts()?;
+ }
+ Ok(reload)
+ }
+
+ /// Identities of every part, for detecting which ones an edit changed.
+ pub(crate) fn part_identities(&self) -> HashMap<String, (bool, usize)> {
+ self.pkg
+ .part_names()
+ .filter_map(|n| Some((n.to_owned(), self.pkg.part_identity(n)?)))
+ .collect()
+ }
+
+ /// Relationship and content-type entries as they are.
+ pub(crate) fn link_entries(&self) -> Result<Links> {
+ let mut rels = BTreeMap::new();
+ for name in self.pkg.part_names() {
+ if !is_rels_part(name) {
+ continue;
+ }
+ for r in self.pkg.rels(&rels_source(name))?.iter() {
+ rels.insert(scoped(name, &r.id), relationship_xml(r));
+ }
+ }
+ Ok(Links {
+ rels,
+ types: type_entries(self.pkg.content_types()),
+ })
+ }
+
+ /// Flat-map changes since a [`Snapshot`] of the package.
+ pub(crate) fn entry_changes(&self, before: &Snapshot) -> Result<Vec<Change>> {
+ let mut out = Vec::new();
+ let now = self.part_identities();
+ let mut names: BTreeSet<&String> = now.keys().collect();
+ names.extend(before.identities.keys());
+ let mut links_changed = false;
+ for name in names {
+ if before.identities.get(name) == now.get(name) {
+ continue;
+ }
+ links_changed = true;
+ if name.eq_ignore_ascii_case(CONTENT_TYPES_PART)
+ || *name == self.main
+ || is_rels_part(name)
+ {
+ continue;
+ }
+ if let Some(notes) = [self.footnotes(), self.endnotes()]
+ .into_iter()
+ .find(|n| n.part.as_deref() == Some(name.as_str()))
+ .filter(|n| !n.rewritten && !n.edited.is_empty())
+ {
+ // The notes edited in place: only those.
+ for &id in &notes.edited {
+ out.push(Change::Entry {
+ container: container::PARTS.to_owned(),
+ key: scoped(name, &id.to_string()),
+ value: notes.note_xml(id),
+ });
+ }
+ continue;
+ }
+ if self.is_notes_part(name)
+ && let Some((skeleton, notes)) =
+ self.pkg.read(name).ok().and_then(|b| split_notes(name, &b))
+ {
+ // Only the notes that changed.
+ let (old_skeleton, old_notes) = before
+ .pkg
+ .read(name)
+ .ok()
+ .and_then(|b| split_notes(name, &b))
+ .unwrap_or_default();
+ let entry = |key: String, value: Option<String>| Change::Entry {
+ container: container::PARTS.to_owned(),
+ key,
+ value,
+ };
+ if skeleton != old_skeleton {
+ out.push(entry(name.clone(), Some(skeleton)));
+ }
+ for (id, xml) in &notes {
+ if old_notes.get(id) != Some(xml) {
+ out.push(entry(scoped(name, &id.to_string()), Some(xml.clone())));
+ }
+ }
+ for id in old_notes.keys() {
+ if !notes.contains_key(id) {
+ out.push(entry(scoped(name, &id.to_string()), None));
+ }
+ }
+ continue;
+ }
+ let value = if self.pkg.has_part(name) {
+ let bytes = self.pkg.read(name)?;
+ Some(encode_part(&self.pkg, name, &bytes))
+ } else {
+ None
+ };
+ out.push(Change::Entry {
+ container: container::PARTS.to_owned(),
+ key: name.clone(),
+ value,
+ });
+ }
+ let shell = self.shell.to_template();
+ if shell != before.shell {
+ out.push(Change::Entry {
+ container: container::PARTS.to_owned(),
+ key: self.main.clone(),
+ value: Some(shell),
+ });
+ }
+ if links_changed {
+ let links = self.link_entries()?;
+ let old = before.links()?;
+ for (container, new, old) in [
+ (container::RELS, &links.rels, &old.rels),
+ (container::TYPES, &links.types, &old.types),
+ ] {
+ for (k, v) in new {
+ if old.get(k) != Some(v) {
+ out.push(Change::Entry {
+ container: container.to_owned(),
+ key: k.clone(),
+ value: Some(v.clone()),
+ });
+ }
+ }
+ for k in old.keys() {
+ if !new.contains_key(k) {
+ out.push(Change::Entry {
+ container: container.to_owned(),
+ key: k.clone(),
+ value: None,
+ });
+ }
+ }
+ }
+ }
+ Ok(out)
+ }
+
+ /// The package's state before an edit, to find the parts it changes.
+ /// It also starts noting which footnotes and endnotes the edit changes.
+ pub(crate) fn snapshot(&mut self) -> Snapshot {
+ for endnote in [false, true] {
+ let notes = self.notes_of_mut(endnote);
+ notes.edited.clear();
+ notes.rewritten = false;
+ }
+ Snapshot {
+ identities: self.part_identities(),
+ shell: self.shell.to_template(),
+ pkg: self.pkg.clone(),
+ }
+ }
+}
+
+/// Relationship and content-type entries.
+#[derive(Clone, Debug, Default)]
+pub(crate) struct Links {
+ pub rels: BTreeMap<String, String>,
+ pub types: BTreeMap<String, String>,
+}
+
+/// A package's state before an edit.
+pub(crate) struct Snapshot {
+ identities: HashMap<String, (bool, usize)>,
+ shell: String,
+ /// Cheap to clone: parts are shared until written.
+ pkg: Package,
+}
+
+impl Snapshot {
+ fn links(&self) -> Result<Links> {
+ let mut rels = BTreeMap::new();
+ for name in self.pkg.part_names() {
+ if !is_rels_part(name) {
+ continue;
+ }
+ for r in self.pkg.rels(&rels_source(name))?.iter() {
+ rels.insert(scoped(name, &r.id), relationship_xml(r));
+ }
+ }
+ Ok(Links {
+ rels,
+ types: type_entries(self.pkg.content_types()),
+ })
+ }
+}
+
+/// The part a relationships part belongs to (`/` for the package).
+fn rels_source(rels_part: &str) -> String {
+ let Some((dir, file)) = rels_part.rsplit_once("_rels/") else {
+ return "/".to_owned();
+ };
+ let dir = dir.trim_end_matches('/');
+ let file = file.strip_suffix(".rels").unwrap_or(file);
+ if dir.is_empty() && file.is_empty() {
+ "/".to_owned()
+ } else {
+ format!("{dir}/{file}")
+ }
+}
+
+/// Builds a package from shared state, with an empty body (the blocks are
+/// read from their records directly).
+fn assemble(state: &CollabState) -> Result<Vec<u8>> {
+ let mut files: Vec<(String, Vec<u8>)> = Vec::new();
+ files.push((
+ CONTENT_TYPES_PART.trim_start_matches('/').to_owned(),
+ content_types_xml(&state.types).into_bytes(),
+ ));
+ let mut rels_parts: BTreeSet<String> = BTreeSet::new();
+ for key in state.rels.keys() {
+ if let Some((part, _)) = key.rsplit_once(KEY_SEPARATOR) {
+ rels_parts.insert(part.to_owned());
+ }
+ }
+ for part in &rels_parts {
+ if let Some(xml) = relationships_xml(&state.rels, part) {
+ files.push((part.trim_start_matches('/').to_owned(), xml.into_bytes()));
+ }
+ }
+ // Notes by part, in id order.
+ let mut notes: BTreeMap<&str, BTreeMap<i64, &String>> = BTreeMap::new();
+ for (key, value) in &state.parts {
+ if let Some((part, id)) = note_key(key) {
+ notes.entry(part).or_default().insert(id, value);
+ }
+ }
+ for (name, value) in &state.parts {
+ if note_key(name).is_some() {
+ continue;
+ }
+ let bytes = match value.split_once(Shell::BLOCKS) {
+ // The main part's shell: an empty body for now.
+ Some((head, tail)) if !value.starts_with("b64:") => {
+ format!("{head}{tail}").into_bytes()
+ }
+ _ => match notes.get(name.as_str()) {
+ Some(by_id) => join_notes(name, value, by_id.values().copied()).into_bytes(),
+ None => decode_part(value),
+ },
+ };
+ files.push((name.trim_start_matches('/').to_owned(), bytes));
+ }
+ let mut w = Writer::new();
+ for (name, data) in &files {
+ w.add(
+ name,
+ WriteData::Fresh {
+ data,
+ compress: false,
+ },
+ )?;
+ }
+ Ok(w.finish()?)
+}
+
+#[cfg(test)]
+mod test;
+mod v1;
+
+pub use v1::{V1_PLACEHOLDER, V1State};
diff --git a/crates/docx_engine/src/collab/test.rs b/crates/docx_engine/src/collab/test.rs
new file mode 100644
index 0000000000..cc354a2cee
--- /dev/null
+++ b/crates/docx_engine/src/collab/test.rs
@@ -0,0 +1,442 @@
+use super::*;
+use crate::edit::{EditOp, Pos, RemoteChange, Session};
+use crate::model::block::BlockId;
+use crate::model::content::Content;
+use crate::test_support::{Parts, docx, fonts};
+use std::collections::BTreeMap;
+
+fn fixture(name: &str) -> Vec<u8> {
+ std::fs::read(
+ std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+ .join("tests/fixtures")
+ .join(name),
+ )
+ .expect("fixture")
+}
+
+fn texts(doc: &Document) -> Vec<String> {
+ doc.body()
+ .paragraphs()
+ .iter()
+ .map(|id| doc.body().get(id).unwrap().content.text())
+ .collect()
+}
+
+/// The shared containers as the web app holds them.
+#[derive(Default, Clone)]
+struct Shared {
+ blocks: BTreeMap<BlockId, BlockRecord>,
+ parts: BTreeMap<String, String>,
+ rels: BTreeMap<String, String>,
+ types: BTreeMap<String, String>,
+}
+
+impl Shared {
+ fn seed(state: &CollabState) -> Self {
+ Self {
+ blocks: state
+ .blocks
+ .iter()
+ .map(|b| (b.id.clone(), b.clone()))
+ .collect(),
+ parts: state.parts.clone(),
+ rels: state.rels.clone(),
+ types: state.types.clone(),
+ }
+ }
+
+ fn state(&self) -> CollabState {
+ // Parents before children, as a reader walking the maps would order them.
+ let mut blocks: Vec<BlockRecord> = self.blocks.values().cloned().collect();
+ blocks.sort_by_key(|b| (!b.p.is_empty(), b.id.clone()));
+ CollabState {
+ parts: self.parts.clone(),
+ types: self.types.clone(),
+ rels: self.rels.clone(),
+ blocks,
+ }
+ }
+
+ /// Applies one peer's changes; returns what another peer is told.
+ fn apply(&mut self, changes: &[Change]) -> Vec<RemoteChange> {
+ let mut out = Vec::new();
+ for c in changes {
+ match c {
+ Change::Block { block } => {
+ self.blocks.insert(block.id.clone(), block.clone());
+ out.push(RemoteChange::Block {
+ block: block.clone(),
+ deltas: Vec::new(),
+ });
+ }
+ Change::Fields { id, fields } => {
+ let b = self.blocks.get_mut(id).expect("block");
+ for (k, v) in fields {
+ match k.as_str() {
+ "p" => b.p = v.clone(),
+ "o" => b.o = v.clone(),
+ "a" => b.a = v.clone(),
+ "x" => b.x = v.clone(),
+ _ => {}
+ }
+ }
+ out.push(RemoteChange::Block {
+ block: b.clone(),
+ deltas: Vec::new(),
+ });
+ }
+ Change::Text { id, delta } => {
+ let b = self.blocks.get_mut(id).expect("block");
+ let mut content = Content::from_delta(b.t.as_deref().unwrap_or_default());
+ content.apply_delta(delta);
+ b.t = Some(content.to_delta());
+ out.push(RemoteChange::Block {
+ block: b.clone(),
+ deltas: vec![delta.clone()],
+ });
+ }
+ Change::Remove { id } => {
+ self.blocks.remove(id);
+ out.push(RemoteChange::Remove { id: id.clone() });
+ }
+ Change::Entry {
+ container,
+ key,
+ value,
+ } => {
+ let map = match container.as_str() {
+ container::PARTS => &mut self.parts,
+ container::RELS => &mut self.rels,
+ _ => &mut self.types,
+ };
+ match value {
+ Some(v) => map.insert(key.clone(), v.clone()),
+ None => map.remove(key),
+ };
+ out.push(RemoteChange::Entry {
+ container: container.clone(),
+ key: key.clone(),
+ value: value.clone(),
+ });
+ }
+ }
+ }
+ out
+ }
+}
+
+#[test]
+fn shared_state_round_trips_a_real_document() {
+ let doc = Document::open(fixture("complex-msa.docx")).unwrap();
+ let pages = doc.layout(fonts()).pages.len();
+ let state = doc.collab_state().unwrap();
+ assert!(state.parts.values().any(|v| v.contains(Shell::BLOCKS)));
+ assert!(
+ state
+ .rels
+ .keys()
+ .any(|k| k.starts_with("/word/_rels/document.xml.rels|"))
+ );
+ assert!(state.types.contains_key("override|/word/document.xml"));
+ // Through JSON, as it crosses to the web app.
+ let json = serde_json::to_string(&state).unwrap();
+ let back: CollabState = serde_json::from_str(&json).unwrap();
+ let shared = Document::from_collab_state(&back, 42).unwrap();
+ assert_eq!(texts(&shared), texts(&doc));
+ assert_eq!(shared.layout(fonts()).pages.len(), pages);
+ // And it saves as a normal package.
+ let saved = Document::open(shared.save().unwrap()).unwrap();
+ assert_eq!(texts(&saved), texts(&doc));
+ assert_eq!(
+ saved.collab_state().unwrap().blocks.len(),
+ state.blocks.len()
+ );
+}
+
+#[test]
+fn two_peers_converge_through_the_shared_maps() {
+ let body = r#"<w:p><w:r><w:t>Alpha</w:t></w:r></w:p><w:p><w:r><w:t>Beta</w:t></w:r></w:p>"#;
+ let doc = Document::open(docx(body, &Parts::default())).unwrap();
+ let mut shared = Shared::seed(&doc.collab_state().unwrap());
+ let mut a = Session::from_collab(&shared.state(), 1).unwrap();
+ let mut b = Session::from_collab(&shared.state(), 2).unwrap();
+ let first = a.document().body().paragraphs()[0].clone();
+ // A types and splits a paragraph.
+ let r = a
+ .apply(
+ &[
+ EditOp::Select {
+ anchor: Pos::new(first.clone(), 5),
+ focus: Pos::new(first.clone(), 5),
+ },
+ EditOp::InsertText {
+ text: " one".into(),
+ },
+ EditOp::InsertParagraph,
+ EditOp::InsertText {
+ text: "Inserted".into(),
+ },
+ ],
+ None,
+ fonts(),
+ )
+ .unwrap();
+ let remote = shared.apply(&r.changes);
+ // B has its caret at the end of "Alpha" and keeps it on that text.
+ b.apply(
+ &[EditOp::Select {
+ anchor: Pos::new(first.clone(), 5),
+ focus: Pos::new(first.clone(), 5),
+ }],
+ None,
+ fonts(),
+ )
+ .unwrap();
+ let rb = b.apply_remote(&remote, fonts()).unwrap();
+ assert_eq!(texts(b.document()), vec!["Alpha one", "Inserted", "Beta"]);
+ assert_eq!(texts(b.document()), texts(a.document()));
+ assert!(rb.pages.is_some());
+ // B's edit goes back to A.
+ let second = b.document().body().paragraphs()[2].clone();
+ let r = b
+ .apply(
+ &[
+ EditOp::Select {
+ anchor: Pos::new(second.clone(), 0),
+ focus: Pos::new(second.clone(), 4),
+ },
+ EditOp::ToggleFormat {
+ format: crate::edit::Toggle::Bold,
+ },
+ ],
+ None,
+ fonts(),
+ )
+ .unwrap();
+ let remote = shared.apply(&r.changes);
+ a.apply_remote(&remote, fonts()).unwrap();
+ let bold = |s: &Session| {
+ let id = s.document().body().paragraphs()[2].clone();
+ s.document().body().get(&id).unwrap().content.spans()[0]
+ .attrs
+ .has("r:w:b")
+ };
+ assert!(bold(&a));
+ assert!(bold(&b));
+ // A fresh peer reading the maps sees the same document.
+ let c = Session::from_collab(&shared.state(), 3).unwrap();
+ assert_eq!(texts(c.document()), texts(a.document()));
+}
+
+#[test]
+fn new_blocks_get_peer_unique_ids() {
+ let body = r#"<w:p><w:r><w:t>Text</w:t></w:r></w:p>"#;
+ let doc = Document::open(docx(body, &Parts::default())).unwrap();
+ let state = doc.collab_state().unwrap();
+ let mut ids = Vec::new();
+ for seed in [1, 2] {
+ let mut s = Session::from_collab(&state, seed).unwrap();
+ let first = s.document().body().paragraphs()[0].clone();
+ let r = s
+ .apply(
+ &[
+ EditOp::Select {
+ anchor: Pos::new(first.clone(), 4),
+ focus: Pos::new(first, 4),
+ },
+ EditOp::InsertParagraph,
+ ],
+ None,
+ fonts(),
+ )
+ .unwrap();
+ ids.push(r.selection.focus.block.clone());
+ }
+ assert_ne!(ids[0], ids[1]);
+}
+
+#[test]
+fn part_changes_from_peers_reload_styles() {
+ let styles = r#"<w:docDefaults><w:rPrDefault><w:rPr><w:sz w:val="20"/></w:rPr></w:rPrDefault></w:docDefaults>"#;
+ let body = r#"<w:p><w:r><w:t>Some text</w:t></w:r></w:p>"#;
+ let doc = Document::open(docx(
+ body,
+ &Parts {
+ styles: Some(styles),
+ ..Parts::default()
+ },
+ ))
+ .unwrap();
+ let state = doc.collab_state().unwrap();
+ let mut s = Session::from_collab(&state, 9).unwrap();
+ assert_eq!(s.state(fonts()).format.size, Some(10.0));
+ let bigger = state.parts["/word/styles.xml"].replace("w:val=\"20\"", "w:val=\"40\"");
+ let r = s
+ .apply_remote(
+ &[RemoteChange::Entry {
+ container: container::PARTS.into(),
+ key: "/word/styles.xml".into(),
+ value: Some(bigger),
+ }],
+ fonts(),
+ )
+ .unwrap();
+ assert_eq!(r.format.size, Some(20.0));
+}
+
+/// Texts of a peer's footnotes by id.
+fn footnote_texts(doc: &Document) -> BTreeMap<i64, String> {
+ doc.footnotes()
+ .by_id
+ .iter()
+ .filter(|(_, n)| n.is_text())
+ .map(|(id, n)| {
+ let text: Vec<String> = n
+ .story
+ .paragraphs()
+ .iter()
+ .map(|p| n.story.get(p).unwrap().content.text())
+ .collect();
+ (*id, text.join("\n").replace('\u{FFFC}', "^"))
+ })
+ .collect()
+}
+
+#[test]
+fn notes_are_shared_one_by_one_and_merge() {
+ let reference = |id: i64| {
+ format!(
+ r#"<w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:footnoteReference w:id="{id}"/></w:r>"#
+ )
+ };
+ let body = format!(
+ r#"<w:p><w:r><w:t>Alpha</w:t></w:r>{}</w:p><w:p><w:r><w:t>Beta</w:t></w:r>{}</w:p>"#,
+ reference(1),
+ reference(2)
+ );
+ let note = |id: i64, text: &str| {
+ format!(
+ r#"<w:footnote w:id="{id}"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> {text}</w:t></w:r></w:p></w:footnote>"#
+ )
+ };
+ let notes = format!(
+ r#"<w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote>{}{}"#,
+ note(1, "First note."),
+ note(2, "Second note.")
+ );
+ let doc = Document::open(docx(
+ &body,
+ &Parts {
+ footnotes: Some(&notes),
+ ..Parts::default()
+ },
+ ))
+ .unwrap();
+ let state = doc.collab_state().unwrap();
+ // The part's own entry holds no notes; each note has its own.
+ let part = "/word/footnotes.xml";
+ assert!(
+ !state.parts[part].contains("<w:footnote "),
+ "{}",
+ state.parts[part]
+ );
+ for id in [-1, 1, 2] {
+ assert!(state.parts.contains_key(&format!("{part}|{id}")), "{id}");
+ }
+ let mut shared = Shared::seed(&state);
+ let mut a = Session::from_collab(&shared.state(), 1).unwrap();
+ let mut b = Session::from_collab(&shared.state(), 2).unwrap();
+ assert_eq!(footnote_texts(a.document()), footnote_texts(&doc));
+
+ // Each types at the end of a different note at the same time.
+ let type_in = |s: &mut Session, id: i64, text: &str| {
+ let para = s.document().footnotes().by_id[&id].story.paragraphs()[0].clone();
+ let len = s.document().footnotes().by_id[&id]
+ .story
+ .get(&para)
+ .unwrap()
+ .content
+ .len();
+ s.apply(
+ &[
+ EditOp::Select {
+ anchor: Pos::new(para.clone(), len),
+ focus: Pos::new(para, len),
+ },
+ EditOp::InsertText { text: text.into() },
+ ],
+ None,
+ fonts(),
+ )
+ .unwrap()
+ };
+ let ra = type_in(&mut a, 1, " (A)");
+ let rb = type_in(&mut b, 2, " (B)");
+ // Only the edited note is shared, not the part.
+ let keys = |r: &crate::edit::EditResult| -> Vec<String> {
+ r.changes
+ .iter()
+ .filter_map(|c| match c {
+ Change::Entry { key, .. } => Some(key.clone()),
+ _ => None,
+ })
+ .collect()
+ };
+ assert_eq!(keys(&ra), vec![format!("{part}|1")]);
+ assert_eq!(keys(&rb), vec![format!("{part}|2")]);
+ let to_b = shared.apply(&ra.changes);
+ let to_a = shared.apply(&rb.changes);
+ a.apply_remote(&to_a, fonts()).unwrap();
+ b.apply_remote(&to_b, fonts()).unwrap();
+ let want: BTreeMap<i64, String> = [
+ (1, "^ First note. (A)".to_owned()),
+ (2, "^ Second note. (B)".to_owned()),
+ ]
+ .into();
+ assert_eq!(footnote_texts(a.document()), want);
+ assert_eq!(footnote_texts(b.document()), want);
+ // A fresh peer, and a saved file, have both.
+ let c = Session::from_collab(&shared.state(), 3).unwrap();
+ assert_eq!(footnote_texts(c.document()), want);
+ let saved = Document::open(c.document().save().unwrap()).unwrap();
+ assert_eq!(footnote_texts(&saved), want);
+ assert_eq!(saved.footnotes().by_id[&-1].kind, "separator");
+}
+
+#[test]
+fn a_new_note_reaches_other_peers() {
+ let doc = Document::open(docx(
+ r#"<w:p><w:r><w:t>Alpha</w:t></w:r></w:p>"#,
+ &Parts::default(),
+ ))
+ .unwrap();
+ let mut shared = Shared::seed(&doc.collab_state().unwrap());
+ let mut a = Session::from_collab(&shared.state(), 1).unwrap();
+ let mut b = Session::from_collab(&shared.state(), 2).unwrap();
+ let first = a.document().body().paragraphs()[0].clone();
+ let r = a
+ .apply(
+ &[
+ EditOp::Select {
+ anchor: Pos::new(first.clone(), 5),
+ focus: Pos::new(first, 5),
+ },
+ EditOp::InsertNote { endnote: false },
+ EditOp::InsertText {
+ text: "Noted.".into(),
+ },
+ ],
+ None,
+ fonts(),
+ )
+ .unwrap();
+ let remote = shared.apply(&r.changes);
+ b.apply_remote(&remote, fonts()).unwrap();
+ let texts_b: Vec<String> = footnote_texts(b.document()).into_values().collect();
+ assert_eq!(texts_b, vec!["^ Noted.".to_owned()]);
+ assert_eq!(footnote_texts(b.document()), footnote_texts(a.document()));
+ let c = Session::from_collab(&shared.state(), 3).unwrap();
+ assert_eq!(footnote_texts(c.document()), footnote_texts(a.document()));
+ // B lays the note out at the foot of its page.
+ assert!(b.pages(fonts())[0].notes.is_some());
+}
diff --git a/crates/docx_engine/src/collab/v1.rs b/crates/docx_engine/src/collab/v1.rs
new file mode 100644
index 0000000000..6ac2cfcf20
--- /dev/null
+++ b/crates/docx_engine/src/collab/v1.rs
@@ -0,0 +1,308 @@
+//! Reading the first collaborative format: the body's top-level elements
+//! as XML strings keyed by the previous engine's paragraph ids, with every
+//! other part verbatim (`docxBlocks`, `docxOrder`, `docxParts`).
+
+use crate::document::Document;
+use crate::error::{Error, Result};
+use crate::model::block::{Block, BlockId, IdGen, Story};
+use pptx_engine::zip::{WriteData, Writer};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// Where the first format's shell holds the body's blocks.
+pub const V1_PLACEHOLDER: &str = "<!--macro-docx-blocks-->";
+
+/// The previous engine's namespace for its paragraph ids.
+const POWERTOOLS_NS: &str = "http://powertools.codeplex.com/2011";
+
+/// A document in the first collaborative format.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct V1State {
+ /// Block ids in document order.
+ pub order: Vec<String>,
+ /// Block id → element XML.
+ pub blocks: BTreeMap<String, String>,
+ /// Part name (no leading slash) → content (`b64:` for binary parts).
+ pub parts: BTreeMap<String, String>,
+}
+
+/// Removes attributes (and declarations) of the namespace `uri` from every
+/// start tag of `xml`.
+fn strip_namespace(xml: &str, uri: &str) -> String {
+ // Prefixes bound to the namespace anywhere in the text.
+ let mut prefixes: Vec<String> = Vec::new();
+ let needle = format!("=\"{uri}\"");
+ let mut search = 0;
+ while let Some(i) = xml[search..].find(&needle) {
+ let at = search + i;
+ if let Some(start) = xml[..at].rfind("xmlns:") {
+ let p = &xml[start + 6..at];
+ if !p.is_empty()
+ && p.chars()
+ .all(|c| c.is_alphanumeric() || c == '_' || c == '-' || c == '.')
+ && !prefixes.iter().any(|x| x == p)
+ {
+ prefixes.push(p.to_owned());
+ }
+ }
+ search = at + needle.len();
+ }
+ if prefixes.is_empty() {
+ return xml.to_owned();
+ }
+ let mut out = String::with_capacity(xml.len());
+ let bytes = xml.as_bytes();
+ let mut i = 0;
+ while i < xml.len() {
+ // Copy text up to the next tag unchanged.
+ let Some(lt) = xml[i..].find('<').map(|k| i + k) else {
+ out.push_str(&xml[i..]);
+ break;
+ };
+ out.push_str(&xml[i..lt]);
+ // Comments, CDATA and declarations pass through.
+ if xml[lt..].starts_with("<!--")
+ || xml[lt..].starts_with("<![CDATA[")
+ || xml[lt..].starts_with("<?")
+ || xml[lt..].starts_with("</")
+ {
+ let end = if xml[lt..].starts_with("<!--") {
+ xml[lt..].find("-->").map(|k| lt + k + 3)
+ } else if xml[lt..].starts_with("<![CDATA[") {
+ xml[lt..].find("]]>").map(|k| lt + k + 3)
+ } else {
+ xml[lt..].find('>').map(|k| lt + k + 1)
+ }
+ .unwrap_or(xml.len());
+ out.push_str(&xml[lt..end]);
+ i = end;
+ continue;
+ }
+ // A start tag: copy it attribute by attribute.
+ let mut j = lt + 1;
+ while j < xml.len()
+ && !bytes[j].is_ascii_whitespace()
+ && bytes[j] != b'>'
+ && bytes[j] != b'/'
+ {
+ j += 1;
+ }
+ out.push_str(&xml[lt..j]);
+ loop {
+ let ws_start = j;
+ while j < xml.len() && bytes[j].is_ascii_whitespace() {
+ j += 1;
+ }
+ if j >= xml.len() || bytes[j] == b'>' || bytes[j] == b'/' {
+ out.push_str(&xml[ws_start..j]);
+ break;
+ }
+ let name_start = j;
+ while j < xml.len()
+ && bytes[j] != b'='
+ && !bytes[j].is_ascii_whitespace()
+ && bytes[j] != b'>'
+ {
+ j += 1;
+ }
+ let name = &xml[name_start..j];
+ while j < xml.len() && bytes[j] != b'"' && bytes[j] != b'\'' && bytes[j] != b'>' {
+ j += 1;
+ }
+ if j >= xml.len() || bytes[j] == b'>' {
+ out.push_str(&xml[ws_start..j]);
+ break;
+ }
+ let quote = bytes[j];
+ let mut k = j + 1;
+ while k < xml.len() && bytes[k] != quote {
+ k += 1;
+ }
+ let end = (k + 1).min(xml.len());
+ let drop = prefixes.iter().any(|p| {
+ name == format!("xmlns:{p}")
+ || name
+ .strip_prefix(p.as_str())
+ .is_some_and(|r| r.starts_with(':'))
+ });
+ if name.ends_with(":Ignorable") && end > j + 1 {
+ // A prefix listed as ignorable must stay declared.
+ let value = &xml[j + 1..end - 1];
+ let kept: Vec<&str> = value
+ .split_whitespace()
+ .filter(|t| !prefixes.iter().any(|p| p == t))
+ .collect();
+ if !kept.is_empty() {
+ out.push_str(&xml[ws_start..=j]);
+ out.push_str(&kept.join(" "));
+ out.push(quote as char);
+ }
+ } else if !drop {
+ out.push_str(&xml[ws_start..end]);
+ }
+ j = end;
+ }
+ let close = xml[j..].find('>').map_or(xml.len(), |k| j + k + 1);
+ out.push_str(&xml[j..close]);
+ i = close;
+ }
+ // Prefixes named in mc:Ignorable lists stay harmless; leave them.
+ out
+}
+
+impl V1State {
+ /// The package the state describes.
+ fn package(&self) -> Result<Vec<u8>> {
+ let shell = self
+ .parts
+ .get("word/document.xml")
+ .ok_or_else(|| Error::Collab("the shared document has no body".into()))?;
+ let body: String = self
+ .order
+ .iter()
+ .filter_map(|id| self.blocks.get(id))
+ .map(String::as_str)
+ .collect();
+ let document = strip_namespace(&shell.replacen(V1_PLACEHOLDER, &body, 1), POWERTOOLS_NS);
+ let mut files: Vec<(String, Vec<u8>)> = Vec::new();
+ for (name, value) in &self.parts {
+ let bytes = if name == "word/document.xml" {
+ document.clone().into_bytes()
+ } else {
+ match value.strip_prefix("b64:") {
+ Some(data) => {
+ use base64::Engine;
+ base64::engine::general_purpose::STANDARD
+ .decode(data)
+ .unwrap_or_default()
+ }
+ None => value.as_bytes().to_vec(),
+ }
+ };
+ files.push((name.clone(), bytes));
+ }
+ // Content types first, as Office expects.
+ files.sort_by_key(|(n, _)| n != "[Content_Types].xml");
+ let mut w = Writer::new();
+ for (name, data) in &files {
+ w.add(
+ name,
+ WriteData::Fresh {
+ data,
+ compress: false,
+ },
+ )?;
+ }
+ Ok(w.finish()?)
+ }
+}
+
+/// Renames the top-level blocks of `story` to `ids` (in order), keeping
+/// sequential ids where the counts disagree.
+fn adopt_ids(story: &Story, ids: &[String]) -> Story {
+ let top: Vec<BlockId> = story.children(None).to_vec();
+ if top.len() != ids.len() {
+ return story.clone();
+ }
+ let rename: std::collections::HashMap<BlockId, BlockId> = top
+ .iter()
+ .zip(ids)
+ .map(|(old, new)| (old.clone(), BlockId::new(new)))
+ .collect();
+ let mut out = Story::new();
+ let mut blocks: Vec<Block> = story.blocks().cloned().collect();
+ blocks.sort_by(|a, b| a.id.cmp(&b.id));
+ for mut b in blocks {
+ if let Some(n) = rename.get(&b.id) {
+ b.id = n.clone();
+ }
+ if let Some(p) = b.parent.as_ref().and_then(|p| rename.get(p)) {
+ b.parent = Some(p.clone());
+ }
+ out.insert(b);
+ }
+ out
+}
+
+impl Document {
+ /// Opens a document stored in the first collaborative format. Top-level
+ /// blocks keep their ids (comments are anchored to them); the previous
+ /// engine's id attributes are dropped.
+ pub fn from_v1(state: &V1State) -> Result<Document> {
+ let bytes = state.package()?;
+ let mut doc = Document::open_with_ids(bytes, IdGen::sequential())?;
+ doc.body = adopt_ids(&doc.body, &state.order);
+ doc.body_dirty = true;
+ Ok(doc)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn strips_the_previous_engines_ids() {
+ let xml = r#"<w:p xmlns:pt14="http://powertools.codeplex.com/2011" mc:Ignorable="w14 pt14" pt14:Unid="abc" w:rsidR="1"><w:r pt14:Unid='d'><w:t>a > b</w:t></w:r><!-- pt14:Unid="x" --></w:p>"#;
+ assert_eq!(
+ strip_namespace(xml, POWERTOOLS_NS),
+ r#"<w:p mc:Ignorable="w14" w:rsidR="1"><w:r><w:t>a > b</w:t></w:r><!-- pt14:Unid="x" --></w:p>"#
+ );
+ }
+
+ #[test]
+ fn opens_the_first_format_with_its_ids() {
+ let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main""#;
+ let pt = r#"xmlns:pt14="http://powertools.codeplex.com/2011""#;
+ let mut parts = BTreeMap::new();
+ parts.insert(
+ "[Content_Types].xml".to_owned(),
+ r#"<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>"#.to_owned(),
+ );
+ parts.insert(
+ "_rels/.rels".to_owned(),
+ r#"<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>"#.to_owned(),
+ );
+ parts.insert(
+ "word/document.xml".to_owned(),
+ format!(r#"<?xml version="1.0"?><w:document {ns} {pt}><w:body><!--macro-docx-blocks--><w:sectPr/></w:body></w:document>"#),
+ );
+ let mut blocks = BTreeMap::new();
+ blocks.insert(
+ "AAA".to_owned(),
+ format!(
+ r#"<w:p {ns} {pt} pt14:Unid="AAA"><w:r pt14:Unid="r1"><w:t>First</w:t></w:r></w:p>"#
+ ),
+ );
+ blocks.insert(
+ "BBB".to_owned(),
+ format!(r#"<w:tbl {ns}><w:tr><w:tc><w:p><w:r><w:t>Cell</w:t></w:r></w:p></w:tc></w:tr></w:tbl>"#),
+ );
+ let state = V1State {
+ order: vec!["AAA".into(), "BBB".into()],
+ blocks,
+ parts,
+ };
+ let doc = Document::from_v1(&state).unwrap();
+ let top: Vec<&str> = doc
+ .body()
+ .children(None)
+ .iter()
+ .map(|b| b.as_str())
+ .collect();
+ assert_eq!(top, vec!["AAA", "BBB"]);
+ let first = doc.body().get(&BlockId::new("AAA")).unwrap();
+ assert_eq!(first.content.text(), "First");
+ assert!(!first.attrs.contains("Unid"));
+ assert!(
+ first.content.spans()[0]
+ .attrs
+ .iter()
+ .all(|(k, _)| !k.contains("Unid"))
+ );
+ // The table's rows are its children under the adopted id.
+ let rows = doc.body().children(Some(&BlockId::new("BBB")));
+ assert_eq!(rows.len(), 1);
+ assert!(!doc.document_xml().contains("powertools"));
+ }
+}
diff --git a/crates/docx_engine/src/document.rs b/crates/docx_engine/src/document.rs
new file mode 100644
index 0000000000..6dafeabd7b
--- /dev/null
+++ b/crates/docx_engine/src/document.rs
@@ -0,0 +1,742 @@
+//! An open Word document: its package, parsed parts and stories.
+
+use crate::error::{Error, Result};
+use crate::model::block::{BlockId, IdGen, Story};
+use crate::model::numbering::Numbering;
+use crate::model::parse::StoryReader;
+use crate::model::props::ThemeInfo;
+use crate::model::section::Section;
+use crate::model::settings::Settings;
+use crate::model::styles::Styles;
+use crate::model::write::Writer;
+use crate::xml::{Decl, XmlTree};
+use pptx_engine::opc::{Package, Relationships};
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+use std::sync::Arc;
+
+/// The main document part when the package does not say otherwise.
+pub const DEFAULT_MAIN_PART: &str = "/word/document.xml";
+
+/// Relationship types by their last path segment (transitional and strict
+/// URIs share it).
+pub mod rel {
+ /// Styles.
+ pub const STYLES: &str = "styles";
+ /// Numbering.
+ pub const NUMBERING: &str = "numbering";
+ /// Settings.
+ pub const SETTINGS: &str = "settings";
+ /// Theme.
+ pub const THEME: &str = "theme";
+ /// Footnotes.
+ pub const FOOTNOTES: &str = "footnotes";
+ /// Endnotes.
+ pub const ENDNOTES: &str = "endnotes";
+ /// Comments.
+ pub const COMMENTS: &str = "comments";
+ /// Header.
+ pub const HEADER: &str = "header";
+ /// Footer.
+ pub const FOOTER: &str = "footer";
+ /// Image.
+ pub const IMAGE: &str = "image";
+ /// Hyperlink.
+ pub const HYPERLINK: &str = "hyperlink";
+ /// The office document (package relationship).
+ pub const OFFICE_DOCUMENT: &str = "officeDocument";
+}
+
+/// The last segment of a relationship type URI.
+pub fn rel_kind(rel_type: &str) -> &str {
+ rel_type.rsplit('/').next().unwrap_or(rel_type)
+}
+
+/// `document.xml` around the body's blocks.
+#[derive(Clone, Debug, Default)]
+pub struct Shell {
+ /// Everything up to and including the `w:body` start tag.
+ pub head: String,
+ /// The body's final section properties, verbatim.
+ pub final_sect_pr: Option<String>,
+ /// Everything from the `w:body` end tag on.
+ pub tail: String,
+}
+
+impl Shell {
+ /// Placeholder the collaborative shell carries in place of the blocks.
+ pub const BLOCKS: &'static str = "<!--docx-blocks-->";
+
+ /// The shell as one string with the blocks placeholder.
+ pub fn to_template(&self) -> String {
+ format!(
+ "{}{}{}{}",
+ self.head,
+ Self::BLOCKS,
+ self.final_sect_pr.as_deref().unwrap_or(""),
+ self.tail
+ )
+ }
+
+ /// Splits a template produced by [`Shell::to_template`].
+ pub fn from_template(template: &str) -> Option<Self> {
+ let (head, rest) = template.split_once(Self::BLOCKS)?;
+ let body_close = find_body_close(rest)?;
+ let sect = rest[..body_close].trim();
+ Some(Self {
+ head: head.to_owned(),
+ final_sect_pr: (!sect.is_empty()).then(|| sect.to_owned()),
+ tail: rest[body_close..].to_owned(),
+ })
+ }
+}
+
+/// Byte offset of the `</…body>` end tag in `rest`.
+fn find_body_close(rest: &str) -> Option<usize> {
+ let mut search = 0;
+ while let Some(i) = rest[search..].find("</") {
+ let at = search + i;
+ let name_end = rest[at + 2..].find('>').map(|e| at + 2 + e)?;
+ let name = &rest[at + 2..name_end];
+ if name == "body" || name.ends_with(":body") {
+ return Some(at);
+ }
+ search = at + 2;
+ }
+ None
+}
+
+/// A story kept in its own part (header, footer) or note.
+#[derive(Clone, Debug)]
+pub struct PartStory {
+ /// The blocks.
+ pub story: Story,
+ /// Namespace declarations of the part's root (for reading snippets).
+ pub decls: Arc<Vec<Decl>>,
+ /// The part's XML before its blocks (through the root start tag).
+ pub(crate) head: String,
+ /// The part's XML after its blocks (from the root end tag).
+ pub(crate) tail: String,
+ /// The prefix the part binds to WordprocessingML.
+ pub(crate) w: String,
+ /// The part's bytes the story was read from (or last written as).
+ pub(crate) identity: Option<(bool, usize)>,
+}
+
+/// The story edits apply to.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[serde(tag = "kind", content = "part", rename_all = "camelCase")]
+pub enum StoryTarget {
+ /// The body.
+ #[default]
+ Body,
+ /// A header or footer part, by part name.
+ Part(String),
+ /// A footnote or endnote.
+ Note {
+ /// An endnote (else a footnote).
+ endnote: bool,
+ /// The note's id.
+ id: i64,
+ },
+}
+
+/// An element's markup around its children: through the start tag, and
+/// from the end tag on (a self-closing element is opened and closed).
+fn split_element(tree: &XmlTree, node: crate::xml::NodeId) -> (String, String) {
+ let span = tree.span(node);
+ let src = tree.source();
+ let tag = tree.start_tag(node);
+ if tag.ends_with("/>") {
+ let open = format!("{}>", tag.trim_end_matches("/>").trim_end());
+ (
+ format!("{}{open}", &src[..span.start]),
+ format!("</{}>{}", tree.qname(node), &src[span.end..]),
+ )
+ } else {
+ let close_start = span.end - (tree.qname(node).len() + 3);
+ (
+ src[..span.start + tag.len()].to_owned(),
+ src[close_start..].to_owned(),
+ )
+ }
+}
+
+/// A footnote or endnote.
+#[derive(Clone, Debug)]
+pub struct Note {
+ /// `w:type` (`separator`, `continuationSeparator`...), empty for normal notes.
+ pub kind: String,
+ /// The note's content.
+ pub story: Story,
+ /// The note element's start tag.
+ pub(crate) open: String,
+ /// Its end tag.
+ pub(crate) close: String,
+}
+
+impl Note {
+ /// Whether people write in it (not a separator or notice).
+ pub fn is_text(&self) -> bool {
+ self.kind.is_empty() || self.kind == "normal"
+ }
+}
+
+/// A child of a notes part, in order.
+#[derive(Clone, Debug)]
+pub(crate) enum NoteSlot {
+ /// A note, by id.
+ Note(i64),
+ /// Anything else, as written.
+ Other(String),
+}
+
+/// The notes of one notes part.
+#[derive(Clone, Debug, Default)]
+pub struct Notes {
+ /// The part name.
+ pub part: Option<String>,
+ /// Notes by id.
+ pub by_id: BTreeMap<i64, Note>,
+ /// Root declarations of the part.
+ pub decls: Arc<Vec<Decl>>,
+ /// The part's markup through the root's start tag, and from its end tag.
+ pub(crate) head: String,
+ pub(crate) tail: String,
+ /// The root's children in order.
+ pub(crate) slots: Vec<NoteSlot>,
+ /// The part's WordprocessingML prefix.
+ pub(crate) w: String,
+ /// The part's bytes the notes were read from (or last written as).
+ pub(crate) identity: Option<(bool, usize)>,
+ /// Notes edited since the last snapshot (see `Document::snapshot`).
+ pub(crate) edited: BTreeSet<i64>,
+ /// The part was rewritten some other way since the last snapshot.
+ pub(crate) rewritten: bool,
+}
+
+impl Notes {
+ /// One note's XML as it now is.
+ pub(crate) fn note_xml(&self, id: i64) -> Option<String> {
+ let n = self.by_id.get(&id)?;
+ let writer = Writer { w: &self.w };
+ Some(format!("{}{}{}", n.open, writer.story(&n.story), n.close))
+ }
+
+ /// The part's XML as its notes now are.
+ pub(crate) fn xml(&self) -> String {
+ let writer = Writer { w: &self.w };
+ let mut out = self.head.clone();
+ for slot in &self.slots {
+ match slot {
+ NoteSlot::Note(id) => {
+ if let Some(n) = self.by_id.get(id) {
+ out.push_str(&n.open);
+ out.push_str(&writer.story(&n.story));
+ out.push_str(&n.close);
+ }
+ }
+ NoteSlot::Other(xml) => out.push_str(xml),
+ }
+ }
+ out.push_str(&self.tail);
+ out
+ }
+}
+
+/// Parsed parts shared by layout.
+#[derive(Clone, Debug, Default)]
+pub struct Parts {
+ /// Theme colors and fonts.
+ pub theme: Arc<ThemeInfo>,
+ /// The parsed theme (DrawingML), for drawings and charts.
+ pub theme_full: Option<Arc<pptx_engine::model::theme::Theme>>,
+ /// Styles.
+ pub styles: Arc<Styles>,
+ /// Numbering.
+ pub numbering: Arc<Numbering>,
+ /// Settings.
+ pub settings: Arc<Settings>,
+}
+
+/// An open Word document.
+#[derive(Clone)]
+pub struct Document {
+ pub(crate) pkg: Package,
+ pub(crate) main: String,
+ pub(crate) shell: Shell,
+ pub(crate) body: Story,
+ pub(crate) ids: Arc<std::sync::Mutex<IdGen>>,
+ pub(crate) decls: Arc<Vec<Decl>>,
+ pub(crate) w: String,
+ pub(crate) parts: Parts,
+ pub(crate) main_rels: Arc<Relationships>,
+ /// Headers and footers by part name.
+ pub(crate) stories: HashMap<String, PartStory>,
+ pub(crate) footnotes: Notes,
+ pub(crate) endnotes: Notes,
+ /// The body changed since opening (document.xml must be rewritten).
+ pub(crate) body_dirty: bool,
+ /// Changes whenever the shared parts (styles, numbering, settings,
+ /// theme) are reloaded; layout caches key on it.
+ pub(crate) generation: u64,
+}
+
+impl std::fmt::Debug for Document {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("Document")
+ .field("main", &self.main)
+ .field("blocks", &self.body.len())
+ .finish()
+ }
+}
+
+/// Reads a part as an XML tree.
+fn read_tree(pkg: &Package, name: &str) -> Result<XmlTree> {
+ let bytes = pkg.read(name)?;
+ XmlTree::parse(&bytes, name)
+}
+
+/// The prefix bound to the WordprocessingML namespace (`w` in practice).
+fn w_prefix(decls: &[Decl]) -> String {
+ decls
+ .iter()
+ .find(|d| {
+ d.uri == "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+ || d.uri == "http://purl.oclc.org/ooxml/wordprocessingml/main"
+ })
+ .map_or_else(|| "w".to_owned(), |d| d.prefix.clone())
+}
+
+impl Document {
+ /// Opens a `.docx` (or `.dotx`, `.docm`) file.
+ pub fn open(bytes: Vec<u8>) -> Result<Self> {
+ Self::open_with_ids(bytes, IdGen::sequential())
+ }
+
+ /// Opens a file, numbering blocks with `ids`.
+ pub fn open_with_ids(bytes: Vec<u8>, mut ids: IdGen) -> Result<Self> {
+ let pkg = Package::open(bytes)?;
+ let main = Self::find_main(&pkg)?;
+ let tree = read_tree(&pkg, &main)?;
+ let root = tree.root();
+ if !tree.is_w(root, "document") {
+ return Err(Error::NotWord(format!(
+ "{main} is <{}>, not a WordprocessingML document",
+ tree.qname(root)
+ )));
+ }
+ let body = tree
+ .w_child(root, "body")
+ .ok_or_else(|| Error::NotWord("the document has no body".into()))?;
+ let (head, tail) = split_element(&tree, body);
+ let read = StoryReader::new(&tree, &mut ids).read(body);
+ let decls = Arc::new(tree.root_decls().to_vec());
+ let w = w_prefix(&decls);
+ let main_rels = Arc::new(pkg.rels(&main)?);
+ let mut doc = Document {
+ pkg,
+ main,
+ shell: Shell {
+ head,
+ final_sect_pr: read.final_sect_pr,
+ tail,
+ },
+ body: read.story,
+ ids: Arc::new(std::sync::Mutex::new(ids)),
+ decls,
+ w,
+ parts: Parts::default(),
+ main_rels,
+ stories: HashMap::new(),
+ footnotes: Notes::default(),
+ endnotes: Notes::default(),
+ body_dirty: false,
+ generation: 0,
+ };
+ doc.load_parts()?;
+ Ok(doc)
+ }
+
+ fn find_main(pkg: &Package) -> Result<String> {
+ if let Ok(rels) = pkg.rels("/") {
+ for r in rels.iter() {
+ if rel_kind(&r.rel_type) == rel::OFFICE_DOCUMENT {
+ return Ok(rels.resolve(r));
+ }
+ }
+ }
+ if pkg.has_part(DEFAULT_MAIN_PART) {
+ return Ok(DEFAULT_MAIN_PART.to_owned());
+ }
+ Err(Error::NotWord("no main document part".into()))
+ }
+
+ /// The part a relationship of the main part points to.
+ fn related(&self, kind: &str) -> Option<String> {
+ self.main_rels
+ .iter()
+ .find(|r| {
+ rel_kind(&r.rel_type) == kind && r.mode == pptx_engine::opc::TargetMode::Internal
+ })
+ .map(|r| self.main_rels.resolve(r))
+ .filter(|p| self.pkg.has_part(p))
+ }
+
+ /// (Re)parses styles, numbering, settings, theme, headers, footers and notes.
+ pub(crate) fn load_parts(&mut self) -> Result<()> {
+ let mut theme = ThemeInfo::default();
+ let mut theme_full = None;
+ if let Some(name) = self.related(rel::THEME)
+ && let Ok(bytes) = self.pkg.read(&name)
+ && let Ok(doc) = pptx_engine::xml::XmlDoc::parse(&bytes, &name)
+ {
+ let parsed = pptx_engine::model::theme::Theme::parse(Arc::new(doc));
+ theme.colors = parsed.colors.clone();
+ theme.major = parsed.major.clone();
+ theme.minor = parsed.minor.clone();
+ theme_full = Some(Arc::new(parsed));
+ }
+ let styles = match self.related(rel::STYLES) {
+ Some(name) => Styles::parse(&read_tree(&self.pkg, &name)?, &theme),
+ None => Styles::default(),
+ };
+ let numbering = match self.related(rel::NUMBERING) {
+ Some(name) => Numbering::parse(&read_tree(&self.pkg, &name)?, &theme),
+ None => Numbering::default(),
+ };
+ let settings = match self.related(rel::SETTINGS) {
+ Some(name) => Settings::parse(&read_tree(&self.pkg, &name)?),
+ None => Settings::default(),
+ };
+ self.generation = crate::model::block::next_version();
+ self.parts = Parts {
+ theme: Arc::new(theme),
+ theme_full,
+ styles: Arc::new(styles),
+ numbering: Arc::new(numbering),
+ settings: Arc::new(settings),
+ };
+ self.load_stories()
+ }
+
+ /// Parses headers, footers and notes. Their blocks get ids prefixed
+ /// with the part (or note), so they never collide with the body's and
+ /// stay the same when the part is read again.
+ pub(crate) fn load_stories(&mut self) -> Result<()> {
+ // A story whose part did not change since it was read stays as it
+ // is (with the blocks an editor may be positioned in).
+ let mut previous = std::mem::take(&mut self.stories);
+ let parts: Vec<String> = self
+ .main_rels
+ .iter()
+ .filter(|r| matches!(rel_kind(&r.rel_type), rel::HEADER | rel::FOOTER))
+ .map(|r| self.main_rels.resolve(r))
+ .collect();
+ for name in parts {
+ if self.stories.contains_key(&name) {
+ continue;
+ }
+ let identity = self.pkg.part_identity(&name);
+ if let Some(kept) = previous.remove(&name)
+ && kept.identity.is_some()
+ && kept.identity == identity
+ {
+ self.stories.insert(name, kept);
+ continue;
+ }
+ let Ok(tree) = read_tree(&self.pkg, &name) else {
+ continue;
+ };
+ let mut ids = IdGen::prefixed(&format!("{}#", name.trim_start_matches('/')));
+ let read = StoryReader::new(&tree, &mut ids).read(tree.root());
+ let (head, tail) = split_element(&tree, tree.root());
+ let decls = Arc::new(tree.root_decls().to_vec());
+ let w = w_prefix(&decls);
+ self.stories.insert(
+ name,
+ PartStory {
+ story: read.story,
+ decls,
+ head,
+ tail,
+ w,
+ identity,
+ },
+ );
+ }
+ let footnotes = std::mem::take(&mut self.footnotes);
+ self.footnotes = self.load_notes(rel::FOOTNOTES, "footnote", "fn", footnotes);
+ let endnotes = std::mem::take(&mut self.endnotes);
+ self.endnotes = self.load_notes(rel::ENDNOTES, "endnote", "en", endnotes);
+ Ok(())
+ }
+
+ /// The story edits to `target` change (the body when the part is gone).
+ pub(crate) fn story(&self, target: &StoryTarget) -> &Story {
+ match target {
+ StoryTarget::Body => &self.body,
+ StoryTarget::Part(name) => self.stories.get(name).map_or(&self.body, |p| &p.story),
+ StoryTarget::Note { endnote, id } => self
+ .notes_of(*endnote)
+ .by_id
+ .get(id)
+ .map_or(&self.body, |n| &n.story),
+ }
+ }
+
+ /// The story edits to `target` change, for changing.
+ pub(crate) fn story_mut(&mut self, target: &StoryTarget) -> &mut Story {
+ match target {
+ StoryTarget::Part(name) if self.stories.contains_key(name) => {
+ &mut self.stories.get_mut(name).expect("checked").story
+ }
+ StoryTarget::Note { endnote, id } if self.notes_of(*endnote).by_id.contains_key(id) => {
+ let notes = self.notes_of_mut(*endnote);
+ &mut notes.by_id.get_mut(id).expect("checked").story
+ }
+ _ => &mut self.body,
+ }
+ }
+
+ /// Whether `target` names a story the document has.
+ pub(crate) fn has_story(&self, target: &StoryTarget) -> bool {
+ match target {
+ StoryTarget::Body => true,
+ StoryTarget::Part(name) => self.stories.contains_key(name),
+ StoryTarget::Note { endnote, id } => self
+ .notes_of(*endnote)
+ .by_id
+ .get(id)
+ .is_some_and(Note::is_text),
+ }
+ }
+
+ /// The story holding a block, if any.
+ pub(crate) fn story_of(&self, id: &BlockId) -> Option<StoryTarget> {
+ if self.body.contains(id) {
+ return Some(StoryTarget::Body);
+ }
+ if let Some((name, _)) = self.stories.iter().find(|(_, p)| p.story.contains(id)) {
+ return Some(StoryTarget::Part(name.clone()));
+ }
+ [false, true].into_iter().find_map(|endnote| {
+ let (note, _) = self
+ .notes_of(endnote)
+ .by_id
+ .iter()
+ .find(|(_, n)| n.story.contains(id))?;
+ Some(StoryTarget::Note { endnote, id: *note })
+ })
+ }
+
+ /// A header or footer part's XML as its story now is.
+ pub(crate) fn part_story_xml(&self, part: &str) -> Option<String> {
+ let ps = self.stories.get(part)?;
+ let writer = Writer { w: &ps.w };
+ Some(format!("{}{}{}", ps.head, writer.story(&ps.story), ps.tail))
+ }
+
+ /// Writes an edited header or footer story back into its part.
+ pub(crate) fn write_part_story(&mut self, part: &str) {
+ if let Some(xml) = self.part_story_xml(part) {
+ self.pkg.write(part, xml.into_bytes(), None);
+ let identity = self.pkg.part_identity(part);
+ if let Some(ps) = self.stories.get_mut(part) {
+ ps.identity = identity;
+ }
+ }
+ }
+
+ /// Reads a notes part. Notes whose part did not change since they were
+ /// read (`previous`) stay as they are, with the blocks an editor may be
+ /// positioned in.
+ fn load_notes(&self, kind: &str, element: &str, prefix: &str, previous: Notes) -> Notes {
+ let Some(name) = self.related(kind) else {
+ return Notes::default();
+ };
+ let identity = self.pkg.part_identity(&name);
+ if previous.part.as_deref() == Some(name.as_str())
+ && previous.identity.is_some()
+ && previous.identity == identity
+ {
+ return previous;
+ }
+ let Ok(tree) = read_tree(&self.pkg, &name) else {
+ return Notes::default();
+ };
+ let root = tree.root();
+ let (head, tail) = split_element(&tree, root);
+ let decls = Arc::new(tree.root_decls().to_vec());
+ let w = w_prefix(&decls);
+ let mut notes = Notes {
+ part: Some(name),
+ by_id: BTreeMap::new(),
+ decls,
+ head,
+ tail,
+ slots: Vec::new(),
+ w,
+ identity,
+ edited: BTreeSet::new(),
+ rewritten: true,
+ };
+ for n in tree.children(root) {
+ let id = tree
+ .is_w(n, element)
+ .then(|| tree.w_attr(n, "id").and_then(crate::xml::parse_int))
+ .flatten()
+ .filter(|id| !notes.by_id.contains_key(id));
+ let Some(id) = id else {
+ notes.slots.push(NoteSlot::Other(tree.raw(n).to_owned()));
+ continue;
+ };
+ let mut ids = IdGen::prefixed(&format!("{prefix}{id}#"));
+ let read = StoryReader::new(&tree, &mut ids).read(n);
+ let tag = tree.start_tag(n);
+ let open = match tag.strip_suffix("/>") {
+ Some(t) => format!("{}>", t.trim_end()),
+ None => tag.to_owned(),
+ };
+ notes.by_id.insert(
+ id,
+ Note {
+ kind: tree.w_attr(n, "type").unwrap_or("").to_owned(),
+ story: read.story,
+ open,
+ close: format!("</{}>", tree.qname(n)),
+ },
+ );
+ notes.slots.push(NoteSlot::Note(id));
+ }
+ notes
+ }
+
+ pub(crate) fn notes_of(&self, endnote: bool) -> &Notes {
+ if endnote {
+ &self.endnotes
+ } else {
+ &self.footnotes
+ }
+ }
+
+ pub(crate) fn notes_of_mut(&mut self, endnote: bool) -> &mut Notes {
+ if endnote {
+ &mut self.endnotes
+ } else {
+ &mut self.footnotes
+ }
+ }
+
+ /// Writes edited notes back into their part, noting which one changed
+ /// (`None`: any of them) for sharing.
+ pub(crate) fn write_notes(&mut self, endnote: bool, edited: Option<i64>) {
+ let notes = self.notes_of(endnote);
+ let Some(part) = notes.part.clone() else {
+ return;
+ };
+ let xml = notes.xml();
+ self.pkg.write(&part, xml.into_bytes(), None);
+ let identity = self.pkg.part_identity(&part);
+ let notes = self.notes_of_mut(endnote);
+ notes.identity = identity;
+ match edited {
+ Some(id) => {
+ notes.edited.insert(id);
+ }
+ None => notes.rewritten = true,
+ }
+ }
+
+ /// The main part name.
+ pub fn main_part(&self) -> &str {
+ &self.main
+ }
+
+ /// The body.
+ pub fn body(&self) -> &Story {
+ &self.body
+ }
+
+ /// Parsed shared parts.
+ pub fn parts(&self) -> &Parts {
+ &self.parts
+ }
+
+ /// Root namespace declarations of the main part.
+ pub fn decls(&self) -> &Arc<Vec<Decl>> {
+ &self.decls
+ }
+
+ /// The prefix the document binds to WordprocessingML.
+ pub fn w_prefix(&self) -> &str {
+ &self.w
+ }
+
+ /// Relationships of the main part.
+ pub fn main_rels(&self) -> &Relationships {
+ &self.main_rels
+ }
+
+ /// The package.
+ pub fn package(&self) -> &Package {
+ &self.pkg
+ }
+
+ /// A header or footer story by part name.
+ pub fn part_story(&self, part: &str) -> Option<&PartStory> {
+ self.stories.get(part)
+ }
+
+ /// The footnotes.
+ pub fn footnotes(&self) -> &Notes {
+ &self.footnotes
+ }
+
+ /// The endnotes.
+ pub fn endnotes(&self) -> &Notes {
+ &self.endnotes
+ }
+
+ /// The final section's properties.
+ pub fn final_section(&self) -> Section {
+ self.shell
+ .final_sect_pr
+ .as_deref()
+ .and_then(|s| XmlTree::parse_snippet(s, &self.decls).ok())
+ .map(|t| Section::read(&t, t.root(), &self.parts.theme))
+ .unwrap_or_default()
+ }
+
+ /// The document part's XML as it is now.
+ pub fn document_xml(&self) -> String {
+ let writer = Writer { w: &self.w };
+ let mut out = String::with_capacity(self.shell.head.len() + self.body.len() * 200);
+ out.push_str(&self.shell.head);
+ out.push_str(&writer.story(&self.body));
+ if let Some(s) = &self.shell.final_sect_pr {
+ out.push_str(s);
+ }
+ out.push_str(&self.shell.tail);
+ out
+ }
+
+ /// Serializes the document. Untouched parts keep their original bytes.
+ pub fn save(&self) -> Result<Vec<u8>> {
+ let mut pkg = self.pkg.clone();
+ if self.body_dirty {
+ pkg.write(&self.main, self.document_xml().into_bytes(), None);
+ }
+ Ok(pkg.save()?)
+ }
+
+ /// A new block id.
+ pub fn next_block_id(&self) -> BlockId {
+ match self.ids.lock() {
+ Ok(mut ids) => ids.next_id(),
+ Err(poisoned) => poisoned.into_inner().next_id(),
+ }
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/document/test.rs b/crates/docx_engine/src/document/test.rs
new file mode 100644
index 0000000000..45de6d51a1
--- /dev/null
+++ b/crates/docx_engine/src/document/test.rs
@@ -0,0 +1,63 @@
+use super::*;
+use crate::model::block::BlockKind;
+
+fn fixture(name: &str) -> Vec<u8> {
+ let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+ .join("tests/fixtures")
+ .join(name);
+ std::fs::read(&path).unwrap_or_else(|e| panic!("{}: {e}", path.display()))
+}
+
+/// Every paragraph's text and the block structure, for comparing models.
+fn summary(story: &Story) -> Vec<(usize, &'static str, String)> {
+ let mut out = Vec::new();
+ story.walk(|b, depth| {
+ out.push((depth, b.kind.code(), b.content.text()));
+ });
+ out
+}
+
+#[test]
+fn opens_fixtures_and_round_trips_the_body() {
+ for name in ["mutual-nda.docx", "complex-msa.docx", "simple_test.docx"] {
+ let doc = Document::open(fixture(name)).unwrap();
+ assert!(!doc.body().is_empty(), "{name}: empty body");
+ let xml = doc.document_xml();
+ let tree = XmlTree::parse(xml.as_bytes(), "rewritten").unwrap();
+ let body = tree.w_child(tree.root(), "body").unwrap();
+ let mut ids = IdGen::sequential();
+ let reread = StoryReader::new(&tree, &mut ids).read(body);
+ assert_eq!(
+ summary(doc.body()),
+ summary(&reread.story),
+ "{name}: rewriting changed the content"
+ );
+ // Every block keeps its properties and attributes.
+ let a: Vec<_> = doc.body().paragraphs();
+ let b: Vec<_> = reread.story.paragraphs();
+ for (x, y) in a.iter().zip(&b) {
+ let (x, y) = (doc.body().get(x).unwrap(), reread.story.get(y).unwrap());
+ assert_eq!(x.props, y.props, "{name}");
+ assert_eq!(x.content, y.content, "{name}");
+ }
+ // Saving an unedited document keeps the original bytes of every part.
+ let saved = doc.save().unwrap();
+ let again = Document::open(saved).unwrap();
+ assert_eq!(summary(doc.body()), summary(again.body()));
+ }
+}
+
+#[test]
+fn reads_styles_numbering_and_sections() {
+ let doc = Document::open(fixture("complex-msa.docx")).unwrap();
+ let parts = doc.parts();
+ assert!(parts.styles.all().count() > 5);
+ let section = doc.final_section();
+ assert!(section.page_w > 500.0 && section.page_h > 600.0);
+ let paragraphs = doc
+ .body()
+ .blocks()
+ .filter(|b| b.kind == BlockKind::Paragraph)
+ .count();
+ assert!(paragraphs > 10);
+}
diff --git a/crates/docx_engine/src/edit.rs b/crates/docx_engine/src/edit.rs
new file mode 100644
index 0000000000..ab3da516e8
--- /dev/null
+++ b/crates/docx_engine/src/edit.rs
@@ -0,0 +1,3468 @@
+//! Editing: a [`Session`] holds a document, its layout and a selection.
+//!
+//! Edit operations ([`EditOp`]) run as transactions over the body's blocks.
+//! Each returns an [`EditResult`]: the collaborative changes it made (text
+//! deltas and block fields for the shared maps), the selection afterwards
+//! with its geometry, the formatting at the selection, and page
+//! fingerprints so the caller repaints only pages that changed.
+
+mod clip;
+mod comments;
+mod find;
+mod format;
+mod geometry;
+mod lists;
+mod notes;
+mod revise;
+mod table;
+mod text;
+mod txn;
+mod xmledit;
+
+#[cfg(test)]
+mod test;
+#[cfg(test)]
+mod test_util;
+
+pub use clip::{Clip, ClipParagraph, ClipRun};
+pub use comments::DocComment;
+pub use find::{FindMatch, FindOptions, FindResult};
+pub use format::{Alignment, ParaPatch, RunPatch, Spacing, Toggle};
+pub use geometry::{CaretRect, PageRect, ViewIndex};
+pub use txn::{BlockRecord, Change, Step, content_delta};
+
+use crate::document::{Document, StoryTarget};
+use crate::layout::format::{Formats, ParaFormat, TableCtx};
+use crate::layout::{Item, Layout, LayoutCache, LayoutOptions, Page, ParaBox};
+use crate::model::block::{BlockId, BlockKind, Story};
+use crate::model::content::{Attrs, OBJECT_CHAR, key, utf16_len};
+use crate::model::props::Align;
+use crate::xml::SnippetContext;
+use pptx_engine::font::FontDb;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::hash::{Hash, Hasher};
+use std::sync::Arc;
+use txn::Txn;
+use xmledit::Element;
+
+fn is_false(v: &bool) -> bool {
+ !*v
+}
+
+/// A position in the body: a paragraph and a UTF-16 offset in its content.
+#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Pos {
+ /// The paragraph.
+ pub block: BlockId,
+ /// Offset in its content (UTF-16 code units).
+ pub offset: usize,
+ /// At a line wrap, show the caret at the end of the earlier line.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub upstream: bool,
+}
+
+impl Pos {
+ /// A position.
+ pub fn new(block: BlockId, offset: usize) -> Self {
+ Self {
+ block,
+ offset,
+ upstream: false,
+ }
+ }
+
+ fn same_place(&self, other: &Pos) -> bool {
+ self.block == other.block && self.offset == other.offset
+ }
+}
+
+/// A selection: the anchor stays put while the focus moves.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Selection {
+ /// Where the selection started.
+ pub anchor: Pos,
+ /// Where the caret is.
+ pub focus: Pos,
+}
+
+impl Selection {
+ /// A caret.
+ pub fn caret(pos: Pos) -> Self {
+ Self {
+ anchor: pos.clone(),
+ focus: pos,
+ }
+ }
+
+ /// Whether the selection is a caret.
+ pub fn is_collapsed(&self) -> bool {
+ self.anchor.same_place(&self.focus)
+ }
+}
+
+/// How far a caret movement or deletion goes.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum Unit {
+ /// One character.
+ #[default]
+ Char,
+ /// One word.
+ Word,
+ /// One line up or down.
+ Line,
+ /// To the start or end of the line.
+ LineBoundary,
+ /// To the start of the paragraph (or the next one).
+ Paragraph,
+ /// To the start or end of the document.
+ Document,
+}
+
+/// A manual break.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum BreakKind {
+ /// A line break within the paragraph.
+ Line,
+ /// A page break.
+ Page,
+ /// A column break.
+ Column,
+}
+
+/// A kind of list.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum ListKind {
+ /// Bullets.
+ Bullet,
+ /// Numbers.
+ Number,
+}
+
+/// One edit operation.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "op", rename_all = "camelCase")]
+pub enum EditOp {
+ /// Sets the selection.
+ Select {
+ /// Anchor.
+ anchor: Pos,
+ /// Focus.
+ focus: Pos,
+ },
+ /// Moves the caret, or extends the selection.
+ Move {
+ /// How far.
+ #[serde(default)]
+ unit: Unit,
+ /// Forward (right/down) or backward.
+ forward: bool,
+ /// Extend the selection instead of moving the caret.
+ #[serde(default)]
+ extend: bool,
+ /// `forward` means rightwards on the page (arrow keys): in a
+ /// right-to-left paragraph that is backwards in the text.
+ #[serde(default)]
+ visual: bool,
+ },
+ /// Selects the whole body.
+ SelectAll,
+ /// Selects the word at a position.
+ SelectWord {
+ /// Where.
+ at: Pos,
+ },
+ /// Selects the paragraph at a position.
+ SelectParagraph {
+ /// Where.
+ at: Pos,
+ },
+ /// Types text over the selection (newlines start paragraphs).
+ InsertText {
+ /// The text.
+ text: String,
+ },
+ /// Splits the paragraph at the caret (Enter).
+ InsertParagraph,
+ /// Inserts a manual break.
+ InsertBreak {
+ /// Which.
+ kind: BreakKind,
+ },
+ /// Inserts a footnote (or endnote) at the caret: its reference in the
+ /// text and a new note, which the caret moves into, as in Word.
+ InsertNote {
+ /// An endnote (else a footnote).
+ #[serde(default)]
+ endnote: bool,
+ },
+ /// Deletes the selection, or one unit beside the caret.
+ Delete {
+ /// Forward (Delete) or backward (Backspace).
+ forward: bool,
+ /// How much, for a caret.
+ #[serde(default)]
+ unit: Unit,
+ },
+ /// Turns a character format on or off for the selection.
+ ToggleFormat {
+ /// Which format.
+ format: Toggle,
+ },
+ /// Sets character formatting on the selection.
+ SetFormat {
+ /// The change.
+ #[serde(flatten)]
+ patch: RunPatch,
+ },
+ /// Removes direct character formatting from the selection.
+ ClearFormat,
+ /// Sets paragraph formatting on the selected paragraphs.
+ SetParagraph {
+ /// The change.
+ #[serde(flatten)]
+ patch: ParaPatch,
+ },
+ /// Applies a paragraph style to the selected paragraphs.
+ SetStyle {
+ /// Style id.
+ style: String,
+ },
+ /// Makes the selected paragraphs a list of `kind`, or plain paragraphs
+ /// when they already are one.
+ ToggleList {
+ /// Bullets or numbers.
+ kind: ListKind,
+ },
+ /// Moves list items a level deeper (or out), or changes the left indent.
+ Indent {
+ /// Deeper (true) or shallower.
+ forward: bool,
+ },
+ /// Inserts a table at the caret.
+ InsertTable {
+ /// Rows.
+ rows: usize,
+ /// Columns.
+ cols: usize,
+ },
+ /// Inserts a row next to the caret's.
+ InsertRow {
+ /// Below (true) or above.
+ below: bool,
+ },
+ /// Inserts a column next to the caret's.
+ InsertColumn {
+ /// Right (true) or left.
+ right: bool,
+ },
+ /// Deletes the caret's table row.
+ DeleteRow,
+ /// Deletes the caret's table column.
+ DeleteColumn,
+ /// Deletes the caret's table.
+ DeleteTable,
+ /// Starts editing the header, footer or body at a point on a page, with
+ /// the caret there.
+ EnterStory {
+ /// Page index.
+ page: usize,
+ /// X (points).
+ x: f32,
+ /// Y (points).
+ y: f32,
+ },
+ /// Leaves a header or footer for the body, where the caret was.
+ ExitStory,
+ /// Turns tracking changes on or off for the document (everyone's edits
+ /// are recorded as revisions while it is on).
+ SetTracking {
+ /// On or off.
+ on: bool,
+ },
+ /// Accepts the tracked changes in the selection (the one at a caret),
+ /// or all of them.
+ AcceptChanges {
+ /// Every change in the story.
+ #[serde(default)]
+ all: bool,
+ },
+ /// Rejects the tracked changes in the selection (the one at a caret),
+ /// or all of them.
+ RejectChanges {
+ /// Every change in the story.
+ #[serde(default)]
+ all: bool,
+ },
+ /// Pastes paragraphs over the selection.
+ Paste {
+ /// What to paste.
+ paragraphs: Vec<ClipParagraph>,
+ /// They were copied from this document (pictures, links and list
+ /// numbering then stay as they were).
+ #[serde(default)]
+ same_document: bool,
+ },
+ /// Replaces matches of a search in the body. With `all`, every match;
+ /// otherwise the match the selection holds, then selects the next one
+ /// (when the selection holds no match, selects the next one only).
+ Replace {
+ /// What to search for.
+ query: String,
+ /// How to compare.
+ #[serde(default)]
+ options: FindOptions,
+ /// The replacement text.
+ with: String,
+ /// Replace every match.
+ #[serde(default)]
+ all: bool,
+ },
+}
+
+/// A page's size and a fingerprint of what it shows.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PageInfo {
+ /// Width (points).
+ pub width: f32,
+ /// Height (points).
+ pub height: f32,
+ /// Changes whenever the page's content does (hex).
+ pub fingerprint: String,
+ /// The header area.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub header: Option<Area>,
+ /// The footer area.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub footer: Option<Area>,
+ /// The area of the footnotes and endnotes on the page.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub notes: Option<Area>,
+}
+
+/// A page's header or footer area (points).
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Area {
+ /// Top.
+ pub top: f32,
+ /// Bottom.
+ pub bottom: f32,
+ /// Whether the section has a part here to edit.
+ pub editable: bool,
+}
+
+impl Area {
+ fn of(chrome: &crate::layout::Chrome) -> Self {
+ Self {
+ top: chrome.top,
+ bottom: chrome.bottom,
+ editable: chrome.part.is_some(),
+ }
+ }
+}
+
+/// How far (points) outside the notes' lines a click still lands in a note.
+const NOTE_SLOP: f32 = 4.0;
+
+/// The layout story of a footnote or endnote.
+fn note_story(endnote: bool, id: i64) -> crate::layout::StoryRef {
+ if endnote {
+ crate::layout::StoryRef::Endnote(id)
+ } else {
+ crate::layout::StoryRef::Footnote(id)
+ }
+}
+
+/// The story edits to a note's text go to.
+fn note_target(story: &crate::layout::StoryRef) -> Option<StoryTarget> {
+ match story {
+ crate::layout::StoryRef::Footnote(id) => Some(StoryTarget::Note {
+ endnote: false,
+ id: *id,
+ }),
+ crate::layout::StoryRef::Endnote(id) => Some(StoryTarget::Note {
+ endnote: true,
+ id: *id,
+ }),
+ _ => None,
+ }
+}
+
+/// The band of a page its footnotes' and endnotes' lines take up.
+fn notes_area(page: &Page) -> Option<Area> {
+ let mut band: Option<(f32, f32)> = None;
+ for item in &page.items {
+ // The separator and continuation notice (negative ids) are not notes.
+ if let Item::Line(l) = item
+ && matches!(
+ l.para.story,
+ crate::layout::StoryRef::Footnote(id) | crate::layout::StoryRef::Endnote(id) if id >= 0
+ )
+ {
+ let (top, bottom) = (l.y, l.y + l.line().height);
+ band = Some(band.map_or((top, bottom), |(t, b)| (t.min(top), b.max(bottom))));
+ }
+ }
+ band.map(|(top, bottom)| Area {
+ top,
+ bottom,
+ editable: true,
+ })
+}
+
+/// Which story the selection is in.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum StoryKind {
+ /// The body.
+ #[default]
+ Body,
+ /// A header.
+ Header,
+ /// A footer.
+ Footer,
+ /// A footnote.
+ Footnote,
+ /// An endnote.
+ Endnote,
+}
+
+/// The story being edited.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct StoryState {
+ /// Body, header or footer.
+ pub kind: StoryKind,
+ /// The page whose header or footer is being edited.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub page: Option<usize>,
+}
+
+/// Formatting at the selection, for toolbars.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FormatState {
+ /// Bold.
+ pub bold: bool,
+ /// Italic.
+ pub italic: bool,
+ /// Underlined.
+ pub underline: bool,
+ /// Struck through.
+ pub strike: bool,
+ /// Superscript.
+ pub superscript: bool,
+ /// Subscript.
+ pub subscript: bool,
+ /// Font family.
+ pub font: Option<String>,
+ /// Size (points).
+ pub size: Option<f32>,
+ /// Text color (`RRGGBB`), when not automatic.
+ pub color: Option<String>,
+ /// Highlight color name (`yellow`, `green`...), when highlighted.
+ pub highlight: Option<String>,
+ /// Paragraph style id.
+ pub style: Option<String>,
+ /// Paragraph style name.
+ pub style_name: Option<String>,
+ /// Paragraph alignment.
+ pub align: Option<Alignment>,
+ /// Whether the paragraph is in a list.
+ pub list: bool,
+ /// Line spacing as a multiple of single spacing, when it is one.
+ pub line_spacing: Option<f32>,
+ /// Whether the selection starts in a table.
+ pub table: bool,
+ /// Whether the document tracks changes.
+ pub tracking: bool,
+ /// Whether the selection (or the caret) touches a tracked change.
+ pub revision: bool,
+ /// Whether undo is possible.
+ pub can_undo: bool,
+ /// Whether redo is possible.
+ pub can_redo: bool,
+}
+
+/// What an operation did.
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditResult {
+ /// Whether the document changed.
+ pub changed: bool,
+ /// The changes for the collaborative maps.
+ pub changes: Vec<Change>,
+ /// The selection afterwards.
+ pub selection: Selection,
+ /// The selection's ends in document order.
+ pub range: Range,
+ /// The caret (at the focus).
+ pub caret: Option<CaretRect>,
+ /// Selection highlight rectangles.
+ pub rects: Vec<PageRect>,
+ /// Pages, when the layout changed.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub pages: Option<Vec<PageInfo>>,
+ /// Where pages changed since the previous result, when the layout changed.
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ pub bands: Vec<Band>,
+ /// Formatting at the selection.
+ pub format: FormatState,
+ /// The story being edited.
+ pub story: StoryState,
+}
+
+/// A selection's ends in document order.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Range {
+ /// The start.
+ pub from: Pos,
+ /// The end.
+ pub to: Pos,
+}
+
+/// A change other peers made, as the shared containers now hold it.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "t", rename_all = "camelCase")]
+pub enum RemoteChange {
+ /// A block as it now is (new or changed).
+ Block {
+ /// The block.
+ block: BlockRecord,
+ /// The text changes from this session's copy of the paragraph to
+ /// the new one, in order, when the caller knows them: carets follow
+ /// them exactly instead of being placed by comparing texts.
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ deltas: Vec<Vec<crate::model::content::DeltaOp>>,
+ },
+ /// A block that no longer exists.
+ Remove {
+ /// Block id.
+ id: BlockId,
+ },
+ /// An entry of the parts, relationships or content types maps.
+ Entry {
+ /// The map.
+ container: String,
+ /// The key.
+ key: String,
+ /// The value (`None` = deleted).
+ value: Option<String>,
+ },
+}
+
+/// A paragraph's id and text (object characters included), for anchoring
+/// comments and searching.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct ParagraphText {
+ /// Block id.
+ pub id: BlockId,
+ /// Text.
+ pub text: String,
+}
+
+/// Where an offset moves through a text delta. Text inserted exactly at
+/// the offset goes after it, so someone typing there keeps typing in one
+/// piece while another person's text arrives next to it.
+fn map_through(offset: usize, delta: &[crate::model::content::DeltaOp]) -> usize {
+ use crate::model::content::DeltaOp;
+ let mut index = offset;
+ let mut at = 0;
+ for op in delta {
+ if at > index {
+ break;
+ }
+ match op {
+ DeltaOp::Delete { delete } => {
+ index -= (*delete).min(index - at);
+ }
+ DeltaOp::Retain { retain, .. } => at += retain,
+ DeltaOp::Insert { insert, .. } => {
+ let len = crate::model::content::utf16_len(insert);
+ if at < index {
+ index += len;
+ }
+ at += len;
+ }
+ }
+ }
+ index
+}
+
+/// `text` (UTF-16 units) with a delta applied, ignoring attributes;
+/// `None` when the delta does not fit the text.
+fn apply_text_delta(text: &[u16], delta: &[crate::model::content::DeltaOp]) -> Option<Vec<u16>> {
+ use crate::model::content::DeltaOp;
+ let mut out = Vec::with_capacity(text.len());
+ let mut at = 0;
+ for op in delta {
+ match op {
+ DeltaOp::Insert { insert, .. } => out.extend(insert.encode_utf16()),
+ DeltaOp::Delete { delete } => {
+ at += delete;
+ if at > text.len() {
+ return None;
+ }
+ }
+ DeltaOp::Retain { retain, .. } => {
+ let end = at + retain;
+ out.extend_from_slice(text.get(at..end)?);
+ at = end;
+ }
+ }
+ }
+ out.extend_from_slice(text.get(at..)?);
+ Some(out)
+}
+
+/// Where an offset moves when a paragraph's text changes from `old` to
+/// `new`: text kept at both ends keeps its place, an offset inside the
+/// replaced middle goes to the end of the new middle.
+fn map_offset(old: &str, new: &str, offset: usize) -> usize {
+ let a: Vec<char> = old.chars().collect();
+ let b: Vec<char> = new.chars().collect();
+ let mut prefix = 0;
+ while prefix < a.len() && prefix < b.len() && a[prefix] == b[prefix] {
+ prefix += 1;
+ }
+ let mut suffix = 0;
+ while suffix < a.len() - prefix
+ && suffix < b.len() - prefix
+ && a[a.len() - 1 - suffix] == b[b.len() - 1 - suffix]
+ {
+ suffix += 1;
+ }
+ let units = |cs: &[char]| cs.iter().map(|c| c.len_utf16()).sum::<usize>();
+ let p16 = units(&a[..prefix]);
+ let old_len = units(&a);
+ let new_len = units(&b);
+ let s16 = units(&a[a.len() - suffix..]);
+ if offset <= p16 {
+ offset
+ } else if offset >= old_len - s16 {
+ offset + new_len - old_len
+ } else {
+ new_len - s16
+ }
+}
+
+/// Paragraphs in document order.
+#[derive(Debug, Default)]
+struct ParaOrder {
+ list: Vec<BlockId>,
+ index: HashMap<BlockId, usize>,
+}
+
+/// One undoable step.
+#[derive(Clone, Debug)]
+struct UndoEntry {
+ step: Step,
+ before: Selection,
+ after: Selection,
+ group: Option<String>,
+}
+
+/// A document open for editing.
+pub struct Session {
+ doc: Document,
+ cache: LayoutCache,
+ options: LayoutOptions,
+ layout: Arc<Layout>,
+ index: Arc<ViewIndex>,
+ stale: bool,
+ sel: Selection,
+ /// Formatting for the next typed text at a caret (Ctrl+B with nothing selected).
+ pending: Option<Attrs>,
+ goal_x: Option<f32>,
+ undo: Vec<UndoEntry>,
+ redo: Vec<UndoEntry>,
+ /// The last step may absorb the next one in this group (typing).
+ open_group: Option<String>,
+ /// Undo history is kept by the caller (collaborative editing).
+ external_undo: bool,
+ order: Option<(u64, Arc<ParaOrder>)>,
+ /// Changed strips since the last result.
+ bands: Vec<Band>,
+ line_hashes: LineHashes,
+ keys: PageKeys,
+ fingerprints: Vec<u64>,
+ /// The story being edited.
+ active: StoryTarget,
+ /// The page whose header or footer is being edited.
+ story_page: usize,
+ /// The body's lines (the same as `index` while editing the body).
+ body_index: Arc<ViewIndex>,
+ /// Where the body selection was when a header or footer was entered.
+ body_sel: Option<Selection>,
+ /// The name tracked changes are recorded under.
+ author: String,
+ /// When tracked changes are recorded (ISO 8601; empty leaves it out).
+ now: String,
+}
+
+impl std::fmt::Debug for Session {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("Session")
+ .field("doc", &self.doc)
+ .field("selection", &self.sel)
+ .finish()
+ }
+}
+
+/// A horizontal strip of a page that changed (points).
+#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
+pub struct Band {
+ /// Page index.
+ pub page: usize,
+ /// Top.
+ pub top: f32,
+ /// Bottom.
+ pub bottom: f32,
+}
+
+/// Hashes of a paragraph's lines (glyphs, positions and run styles),
+/// remembered per laid-out paragraph: cached paragraphs keep theirs between
+/// layouts, so fingerprinting a page after an edit costs little. Entries
+/// are found by the box's address, which the weak reference keeps from
+/// being taken by another box while the entry exists.
+#[derive(Default)]
+struct LineHashes {
+ map: crate::hash::FxMap<usize, (std::sync::Weak<ParaBox>, Vec<u64>)>,
+}
+
+fn rgba_bits(c: &pptx_engine::model::color::Rgba) -> [u32; 4] {
+ [c.r.to_bits(), c.g.to_bits(), c.b.to_bits(), c.a.to_bits()]
+}
+
+fn run_hash(r: &crate::layout::inline::RunStyle) -> u64 {
+ let mut h = crate::hash::FxHasher::default();
+ let p = &r.props;
+ (r.size.to_bits(), r.shift.to_bits(), rgba_bits(&r.color)).hash(&mut h);
+ (p.bold, p.italic, p.strike, p.dstrike, p.caps, p.small_caps).hash(&mut h);
+ match &p.underline {
+ Some(u) => {
+ std::mem::discriminant(&u.style).hash(&mut h);
+ u.color.as_ref().map(rgba_bits).hash(&mut h);
+ }
+ None => 0u8.hash(&mut h),
+ }
+ p.highlight.as_ref().map(rgba_bits).hash(&mut h);
+ p.shading.as_ref().map(rgba_bits).hash(&mut h);
+ r.revision.hash(&mut h);
+ h.finish()
+}
+
+fn para_line_hashes(pb: &ParaBox) -> Vec<u64> {
+ let runs: Vec<u64> = pb.inline.runs.iter().map(run_hash).collect();
+ pb.lines
+ .lines
+ .iter()
+ .map(|line| {
+ let mut h = crate::hash::FxHasher::default();
+ (line.width.to_bits(), line.hyphen, line.height.to_bits()).hash(&mut h);
+ for ci in line.start..line.end {
+ let c = &pb.inline.clusters[ci];
+ (c.ch, c.glyph, pb.lines.x[ci].to_bits()).hash(&mut h);
+ if let Some(f) = &c.font {
+ f.face.hash(&mut h);
+ }
+ runs.get(c.run as usize).hash(&mut h);
+ }
+ h.finish()
+ })
+ .collect()
+}
+
+impl LineHashes {
+ /// The hash of a paragraph's line.
+ fn line(&mut self, pb: &Arc<ParaBox>, line: usize) -> Option<u64> {
+ let (_, hashes) = self
+ .map
+ .entry(Arc::as_ptr(pb) as usize)
+ .or_insert_with(|| (Arc::downgrade(pb), para_line_hashes(pb)));
+ hashes.get(line).copied()
+ }
+
+ /// Forgets paragraphs no layout holds any more.
+ fn prune(&mut self) {
+ self.map.retain(|_, (weak, _)| weak.strong_count() > 0);
+ }
+}
+
+/// A hash of one item and the vertical extent it paints.
+fn item_key(item: &Item, lines: &mut LineHashes) -> (u64, f32, f32) {
+ let mut h = crate::hash::FxHasher::default();
+ let (top, bottom) = match item {
+ Item::Line(l) => {
+ 0u8.hash(&mut h);
+ (l.x.to_bits(), l.y.to_bits()).hash(&mut h);
+ if let Some(c) = &l.clip {
+ (c.x.to_bits(), c.y.to_bits(), c.w.to_bits(), c.h.to_bits()).hash(&mut h);
+ }
+ lines.line(&l.para, l.line).hash(&mut h);
+ // Glyphs can reach a little past the line box.
+ (l.y - 3.0, l.y + l.line().height + 3.0)
+ }
+ Item::Fill { rect, color } => {
+ 1u8.hash(&mut h);
+ (
+ rect.x.to_bits(),
+ rect.y.to_bits(),
+ rect.w.to_bits(),
+ rect.h.to_bits(),
+ )
+ .hash(&mut h);
+ rgba_bits(color).hash(&mut h);
+ (rect.y - 1.0, rect.y + rect.h + 1.0)
+ }
+ Item::Rule {
+ x0,
+ y0,
+ x1,
+ y1,
+ border,
+ } => {
+ 2u8.hash(&mut h);
+ (x0.to_bits(), y0.to_bits(), x1.to_bits(), y1.to_bits()).hash(&mut h);
+ (
+ std::mem::discriminant(&border.style),
+ border.width.to_bits(),
+ border.space.to_bits(),
+ )
+ .hash(&mut h);
+ match border.color {
+ crate::model::props::ColorRef::Auto => 0u8.hash(&mut h),
+ crate::model::props::ColorRef::Rgb(c) => (1u8, rgba_bits(&c)).hash(&mut h),
+ }
+ let pad = border.width * 3.0 + 2.0;
+ (y0.min(*y1) - pad, y0.max(*y1) + pad)
+ }
+ Item::Drawing(d) => {
+ 3u8.hash(&mut h);
+ (Arc::as_ptr(&d.drawing) as usize).hash(&mut h);
+ (
+ d.rect.x.to_bits(),
+ d.rect.y.to_bits(),
+ d.rect.w.to_bits(),
+ d.rect.h.to_bits(),
+ )
+ .hash(&mut h);
+ // Rotated or effect-extended drawings can reach further.
+ let pad = d.rect.w.max(d.rect.h) * 0.5;
+ (d.rect.y - pad, d.rect.y + d.rect.h + pad)
+ }
+ Item::LineNumber {
+ text,
+ right,
+ baseline,
+ size,
+ ..
+ } => {
+ 4u8.hash(&mut h);
+ text.hash(&mut h);
+ (right.to_bits(), baseline.to_bits()).hash(&mut h);
+ (baseline - size * 1.2, baseline + size * 0.5)
+ }
+ };
+ (h.finish(), top, bottom)
+}
+
+/// Item keys of every page.
+type PageKeys = Vec<Vec<(u64, f32, f32)>>;
+
+fn page_keys(layout: &Layout, lines: &mut LineHashes) -> PageKeys {
+ layout
+ .pages
+ .iter()
+ .map(|p| p.all_items().map(|i| item_key(i, lines)).collect())
+ .collect()
+}
+
+/// A page's fingerprint from its item keys.
+fn fingerprint(page: &Page, keys: &[(u64, f32, f32)]) -> u64 {
+ let mut h = crate::hash::FxHasher::default();
+ (page.width.to_bits(), page.height.to_bits(), page.number).hash(&mut h);
+ for k in keys {
+ k.0.hash(&mut h);
+ }
+ h.finish()
+}
+
+/// Strips of each page that differ between two layouts; a page whose size
+/// changed (or that is new) is dirty from top to bottom.
+fn dirty_bands(old: &Layout, old_keys: &PageKeys, new: &Layout, new_keys: &PageKeys) -> Vec<Band> {
+ let mut out = Vec::new();
+ for (i, page) in new.pages.iter().enumerate() {
+ let (Some(before), Some(a)) = (old.pages.get(i), old_keys.get(i)) else {
+ out.push(Band {
+ page: i,
+ top: 0.0,
+ bottom: page.height,
+ });
+ continue;
+ };
+ if before.width != page.width
+ || before.height != page.height
+ || before.number != page.number
+ {
+ out.push(Band {
+ page: i,
+ top: 0.0,
+ bottom: page.height,
+ });
+ continue;
+ }
+ let b = &new_keys[i];
+ if a == b {
+ continue;
+ }
+ let mut count: crate::hash::FxMap<u64, i64> = crate::hash::FxMap::default();
+ for k in a {
+ *count.entry(k.0).or_default() += 1;
+ }
+ for k in b {
+ *count.entry(k.0).or_default() -= 1;
+ }
+ // Items rarely swap paint order without moving; compare as multisets.
+ let mut spans: Vec<(f32, f32)> = a
+ .iter()
+ .chain(b)
+ .filter(|k| count.get(&k.0).is_some_and(|c| *c != 0))
+ .map(|k| (k.1.max(0.0), k.2.min(page.height)))
+ .collect();
+ spans.sort_by(|x, y| x.0.total_cmp(&y.0));
+ let mut merged: Vec<(f32, f32)> = Vec::new();
+ for (t, bt) in spans {
+ match merged.last_mut() {
+ Some(last) if t <= last.1 + 2.0 => last.1 = last.1.max(bt),
+ _ => merged.push((t, bt)),
+ }
+ }
+ for (top, bottom) in merged {
+ if bottom > top {
+ out.push(Band {
+ page: i,
+ top,
+ bottom,
+ });
+ }
+ }
+ }
+ out
+}
+
+/// Kinds of characters for word movement.
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum CharClass {
+ Space,
+ Word,
+ Punct,
+}
+
+fn class(c: char) -> CharClass {
+ if c.is_whitespace() || c == OBJECT_CHAR {
+ CharClass::Space
+ } else if c.is_alphanumeric() || c == '_' || c == '\'' || c == '\u{2019}' {
+ CharClass::Word
+ } else {
+ CharClass::Punct
+ }
+}
+
+/// UTF-16 offsets of each char of `text` (plus the end).
+fn char_offsets(text: &str) -> Vec<usize> {
+ let mut out = Vec::with_capacity(text.len() + 1);
+ let mut at = 0;
+ for c in text.chars() {
+ out.push(at);
+ at += c.len_utf16();
+ }
+ out.push(at);
+ out
+}
+
+/// The next word boundary after `offset` (Ctrl+Right: past the word, then
+/// past the spaces after it).
+fn word_forward(text: &str, offset: usize) -> usize {
+ let chars: Vec<char> = text.chars().collect();
+ let offs = char_offsets(text);
+ let mut i = offs
+ .iter()
+ .position(|&o| o >= offset)
+ .unwrap_or(chars.len());
+ if i < chars.len() {
+ let k = class(chars[i]);
+ if k != CharClass::Space {
+ while i < chars.len() && class(chars[i]) == k {
+ i += 1;
+ }
+ }
+ while i < chars.len() && class(chars[i]) == CharClass::Space {
+ i += 1;
+ }
+ }
+ offs[i.min(chars.len())]
+}
+
+/// The previous word boundary before `offset` (Ctrl+Left).
+fn word_backward(text: &str, offset: usize) -> usize {
+ let chars: Vec<char> = text.chars().collect();
+ let offs = char_offsets(text);
+ let mut i = offs
+ .iter()
+ .position(|&o| o >= offset)
+ .unwrap_or(chars.len());
+ while i > 0 && class(chars[i - 1]) == CharClass::Space {
+ i -= 1;
+ }
+ if i > 0 {
+ let k = class(chars[i - 1]);
+ while i > 0 && class(chars[i - 1]) == k {
+ i -= 1;
+ }
+ }
+ offs[i]
+}
+
+/// The word around `offset`.
+fn word_at(text: &str, offset: usize) -> (usize, usize) {
+ let chars: Vec<char> = text.chars().collect();
+ let offs = char_offsets(text);
+ if chars.is_empty() {
+ return (0, 0);
+ }
+ let mut i = offs
+ .iter()
+ .position(|&o| o >= offset)
+ .unwrap_or(chars.len())
+ .min(chars.len() - 1);
+ // At the end of a word, select that word.
+ if i > 0 && class(chars[i]) == CharClass::Space && class(chars[i - 1]) != CharClass::Space {
+ i -= 1;
+ }
+ let k = class(chars[i]);
+ let mut s = i;
+ while s > 0 && class(chars[s - 1]) == k {
+ s -= 1;
+ }
+ let mut e = i + 1;
+ while e < chars.len() && class(chars[e]) == k {
+ e += 1;
+ }
+ (offs[s], offs[e])
+}
+
+impl Session {
+ /// Opens a session over a document; the caret starts at the beginning.
+ pub fn new(doc: Document) -> Self {
+ let first = doc.body().paragraphs().into_iter().next();
+ let mut s = Self {
+ doc,
+ cache: LayoutCache::new(),
+ options: LayoutOptions::default(),
+ layout: Arc::new(Layout::default()),
+ index: Arc::new(ViewIndex::default()),
+ stale: true,
+ sel: Selection::caret(Pos::new(BlockId::new(""), 0)),
+ pending: None,
+ goal_x: None,
+ undo: Vec::new(),
+ redo: Vec::new(),
+ open_group: None,
+ external_undo: false,
+ order: None,
+ bands: Vec::new(),
+ line_hashes: LineHashes::default(),
+ keys: Vec::new(),
+ fingerprints: Vec::new(),
+ active: StoryTarget::Body,
+ story_page: 0,
+ body_index: Arc::new(ViewIndex::default()),
+ body_sel: None,
+ author: "Author".to_owned(),
+ now: String::new(),
+ };
+ let first = first.unwrap_or_else(|| s.ensure_paragraph());
+ s.sel = Selection::caret(Pos::new(first, 0));
+ s
+ }
+
+ /// An empty body gets one paragraph so there is somewhere to type.
+ fn ensure_paragraph(&mut self) -> BlockId {
+ let id = self.doc.next_block_id();
+ let order = self.doc.body.key_after(None, None);
+ self.doc.body.insert(crate::model::block::Block::new(
+ id.clone(),
+ BlockKind::Paragraph,
+ None,
+ order,
+ ));
+ id
+ }
+
+ /// The document.
+ pub fn document(&self) -> &Document {
+ &self.doc
+ }
+
+ /// The document, for changes made outside edit operations (the caller
+ /// must keep the selection valid; the layout is recomputed).
+ pub fn document_mut(&mut self) -> &mut Document {
+ self.stale = true;
+ self.order = None;
+ &mut self.doc
+ }
+
+ /// Leaves undo history to the caller (collaborative editing keeps it
+ /// in the shared document instead).
+ pub fn set_external_undo(&mut self, external: bool) {
+ self.external_undo = external;
+ self.undo.clear();
+ self.redo.clear();
+ }
+
+ /// The name tracked changes are recorded under.
+ pub fn set_author(&mut self, author: &str) {
+ if !author.trim().is_empty() {
+ self.author = author.trim().to_owned();
+ }
+ }
+
+ /// The time tracked changes made from now on are recorded at.
+ pub fn set_now(&mut self, now: &str) {
+ self.now = now.to_owned();
+ }
+
+ /// Who records the next tracked change, when the document tracks them.
+ fn revisor(&self) -> Option<revise::Revisor> {
+ if !self.doc.parts().settings.track_revisions {
+ return None;
+ }
+ Some(revise::Revisor {
+ author: self.author.clone(),
+ date: self.now.clone(),
+ w: self.doc.w_prefix().to_owned(),
+ id: revise::revision_id(self.doc.next_block_id().as_str()),
+ })
+ }
+
+ /// Shows tracked changes inline (`true`) or the document as if they
+ /// were accepted.
+ pub fn set_markup(&mut self, markup: bool) {
+ if self.options.markup != markup {
+ self.options.markup = markup;
+ self.stale = true;
+ }
+ }
+
+ /// Layout choices.
+ pub fn set_options(&mut self, options: LayoutOptions) {
+ self.options = options;
+ self.stale = true;
+ }
+
+ /// The selection.
+ pub fn selection(&self) -> &Selection {
+ &self.sel
+ }
+
+ /// The current layout (recomputed if the document changed).
+ pub fn layout(&mut self, fonts: &FontDb) -> Arc<Layout> {
+ self.ensure_layout(fonts);
+ Arc::clone(&self.layout)
+ }
+
+ /// Pages with their fingerprints.
+ pub fn pages(&mut self, fonts: &FontDb) -> Vec<PageInfo> {
+ self.ensure_layout(fonts);
+ self.page_infos()
+ }
+
+ fn page_infos(&self) -> Vec<PageInfo> {
+ self.layout
+ .pages
+ .iter()
+ .zip(&self.fingerprints)
+ .map(|(p, f)| PageInfo {
+ width: p.width,
+ height: p.height,
+ fingerprint: format!("{f:016x}"),
+ header: p.header.as_ref().map(Area::of),
+ footer: p.footer.as_ref().map(Area::of),
+ notes: notes_area(p),
+ })
+ .collect()
+ }
+
+ fn ensure_layout(&mut self, fonts: &FontDb) -> bool {
+ if !self.stale {
+ return false;
+ }
+ let layout = self.doc.layout_cached(fonts, &self.options, &self.cache);
+ self.body_index = Arc::new(ViewIndex::build(&layout));
+ let keys = page_keys(&layout, &mut self.line_hashes);
+ let bands = dirty_bands(&self.layout, &self.keys, &layout, &keys);
+ self.bands.extend(bands);
+ self.fingerprints = layout
+ .pages
+ .iter()
+ .zip(&keys)
+ .map(|(p, k)| fingerprint(p, k))
+ .collect();
+ self.keys = keys;
+ self.layout = Arc::new(layout);
+ self.reindex();
+ // The old layout is gone: forget its paragraphs' hashes.
+ self.line_hashes.prune();
+ self.stale = false;
+ true
+ }
+
+ /// Indexes the active story's lines: the body's, or a header's or
+ /// footer's on the page being edited.
+ fn reindex(&mut self) {
+ self.index = match &self.active {
+ StoryTarget::Body => Arc::clone(&self.body_index),
+ StoryTarget::Part(name) => {
+ self.story_page = self
+ .story_page
+ .min(self.layout.pages.len().saturating_sub(1));
+ Arc::new(ViewIndex::for_story(
+ &self.layout,
+ &crate::layout::StoryRef::Part(name.clone()),
+ Some(self.story_page),
+ ))
+ }
+ // A note can run on over the next page.
+ StoryTarget::Note { endnote, id } => Arc::new(ViewIndex::for_story(
+ &self.layout,
+ &note_story(*endnote, *id),
+ None,
+ )),
+ };
+ }
+
+ /// The header or footer area at a point, and the part it shows.
+ fn chrome_at(&self, page: usize, y: f32) -> Option<(StoryKind, Option<String>)> {
+ let p = self.layout.pages.get(page)?;
+ if let Some(h) = &p.header
+ && y < h.bottom
+ {
+ return Some((StoryKind::Header, h.part.clone()));
+ }
+ if let Some(f) = &p.footer
+ && y >= f.top
+ {
+ return Some((StoryKind::Footer, f.part.clone()));
+ }
+ None
+ }
+
+ /// The footnote or endnote whose text is nearest a point in a page's
+ /// notes area.
+ fn note_at(&self, page: usize, x: f32, y: f32) -> Option<StoryTarget> {
+ let p = self.layout.pages.get(page)?;
+ let area = notes_area(p)?;
+ if y < area.top - NOTE_SLOP || y > area.bottom + NOTE_SLOP {
+ return None;
+ }
+ let distance = |l: &crate::layout::PlacedLine| {
+ let line = l.line();
+ let dy = if y < l.y {
+ l.y - y
+ } else {
+ (y - (l.y + line.height)).max(0.0)
+ };
+ let left = l.x + line.left;
+ let dx = if x < left {
+ left - x
+ } else {
+ (x - (l.x + line.right)).max(0.0)
+ };
+ (dy, dx)
+ };
+ p.items
+ .iter()
+ .filter_map(|item| match item {
+ Item::Line(l) => {
+ let target = note_target(&l.para.story)?;
+ self.doc.has_story(&target).then(|| (distance(l), target))
+ }
+ _ => None,
+ })
+ .min_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal))
+ .map(|(_, target)| target)
+ }
+
+ /// The first page showing a note.
+ fn note_page(&self, note: &StoryTarget) -> Option<usize> {
+ let StoryTarget::Note { endnote, id } = note else {
+ return None;
+ };
+ let story = note_story(*endnote, *id);
+ self.layout.pages.iter().position(|p| {
+ p.items
+ .iter()
+ .any(|i| matches!(i, Item::Line(l) if l.para.story == story))
+ })
+ }
+
+ /// What the selection is in, for the caller.
+ fn story_state(&self) -> StoryState {
+ if let StoryTarget::Note { endnote, .. } = &self.active {
+ return StoryState {
+ kind: if *endnote {
+ StoryKind::Endnote
+ } else {
+ StoryKind::Footnote
+ },
+ page: self.note_page(&self.active).or(Some(self.story_page)),
+ };
+ }
+ let StoryTarget::Part(name) = &self.active else {
+ return StoryState::default();
+ };
+ let page = self.layout.pages.get(self.story_page);
+ let kind = if page
+ .and_then(|p| p.footer.as_ref())
+ .is_some_and(|f| f.part.as_ref() == Some(name))
+ {
+ StoryKind::Footer
+ } else {
+ StoryKind::Header
+ };
+ StoryState {
+ kind,
+ page: Some(self.story_page),
+ }
+ }
+
+ /// Switches to editing a header or footer on a page.
+ fn enter_part(&mut self, part: String, page: usize) {
+ self.enter(StoryTarget::Part(part), page);
+ }
+
+ /// Switches to editing a story other than the body, shown on a page.
+ fn enter(&mut self, target: StoryTarget, page: usize) {
+ if self.active == StoryTarget::Body {
+ self.body_sel = Some(self.sel.clone());
+ }
+ self.active = target;
+ self.story_page = page;
+ self.order = None;
+ self.pending = None;
+ self.goal_x = None;
+ self.open_group = None;
+ self.reindex();
+ }
+
+ /// Back to the body, with the selection it had.
+ fn leave_story(&mut self) {
+ if self.active == StoryTarget::Body {
+ return;
+ }
+ self.active = StoryTarget::Body;
+ self.story_page = 0;
+ self.order = None;
+ self.pending = None;
+ self.goal_x = None;
+ self.open_group = None;
+ self.sel = self.body_sel.take().unwrap_or_else(|| {
+ let first = self.doc.body().paragraphs().into_iter().next();
+ Selection::caret(Pos::new(first.unwrap_or_else(|| BlockId::new("")), 0))
+ });
+ self.reindex();
+ }
+
+ /// Takes a selection, switching to the story it is in.
+ fn adopt(&mut self, sel: Selection) {
+ match self.doc.story_of(&sel.focus.block) {
+ Some(StoryTarget::Body) => self.leave_story(),
+ Some(StoryTarget::Part(name)) if self.active != StoryTarget::Part(name.clone()) => {
+ // Show it on the first page that has it.
+ let page = self
+ .layout
+ .pages
+ .iter()
+ .position(|p| {
+ [&p.header, &p.footer]
+ .into_iter()
+ .flatten()
+ .any(|c| c.part.as_ref() == Some(&name))
+ })
+ .unwrap_or(0);
+ self.enter_part(name, page);
+ }
+ Some(note @ StoryTarget::Note { .. }) if self.active != note => {
+ let page = self.note_page(&note).unwrap_or(0);
+ self.enter(note, page);
+ }
+ _ => {}
+ }
+ self.sel = sel;
+ self.clamp_selection();
+ }
+
+ /// Positions in the active story as (paragraph index, offset), to find
+ /// them again after the story is read anew.
+ fn story_positions(&self) -> Option<[(usize, usize); 2]> {
+ if self.active == StoryTarget::Body {
+ return None;
+ }
+ let list = self.story().paragraphs();
+ let at = |p: &Pos| {
+ (
+ list.iter().position(|id| *id == p.block).unwrap_or(0),
+ p.offset,
+ )
+ };
+ Some([at(&self.sel.anchor), at(&self.sel.focus)])
+ }
+
+ /// The story being edited.
+ fn story(&self) -> &Story {
+ self.doc.story(&self.active)
+ }
+
+ fn order(&mut self) -> Arc<ParaOrder> {
+ // Paragraph order changes only with the story's structure.
+ let rev = self.story().structure();
+ if let Some((r, o)) = &self.order
+ && *r == rev
+ {
+ return Arc::clone(o);
+ }
+ let list = self.story().paragraphs();
+ let index = list
+ .iter()
+ .enumerate()
+ .map(|(i, id)| (id.clone(), i))
+ .collect();
+ let o = Arc::new(ParaOrder { list, index });
+ self.order = Some((rev, Arc::clone(&o)));
+ o
+ }
+
+ /// The selection's ends in document order.
+ fn ordered(&mut self) -> (Pos, Pos) {
+ let o = self.order();
+ let a = &self.sel.anchor;
+ let f = &self.sel.focus;
+ let ia = o.index.get(&a.block).copied().unwrap_or(0);
+ let ifo = o.index.get(&f.block).copied().unwrap_or(0);
+ if (ia, a.offset) <= (ifo, f.offset) {
+ (a.clone(), f.clone())
+ } else {
+ (f.clone(), a.clone())
+ }
+ }
+
+ /// Paragraphs from `a` to `b` inclusive, in document order.
+ fn paras_between(&mut self, a: &BlockId, b: &BlockId) -> Vec<BlockId> {
+ let o = self.order();
+ let (Some(&i), Some(&j)) = (o.index.get(a), o.index.get(b)) else {
+ return vec![a.clone()];
+ };
+ let (i, j) = if i <= j { (i, j) } else { (j, i) };
+ o.list[i..=j].to_vec()
+ }
+
+ fn para_len(&self, id: &BlockId) -> usize {
+ self.story().get(id).map_or(0, |b| b.content.len())
+ }
+
+ /// Keeps the selection on existing paragraphs and in range.
+ fn clamp_selection(&mut self) {
+ if self.active != StoryTarget::Body
+ && (!self.doc.has_story(&self.active) || self.story().paragraphs().is_empty())
+ {
+ // The header or footer went away: back to the body.
+ self.leave_story();
+ }
+ let fix = |s: &mut Self, p: Pos| -> Pos {
+ match s.story().get(&p.block) {
+ Some(b) if b.kind == BlockKind::Paragraph => {
+ let len = b.content.len();
+ Pos {
+ offset: p.offset.min(len),
+ ..p
+ }
+ }
+ _ => {
+ let first = s.story().paragraphs().into_iter().next();
+ let id = first.unwrap_or_else(|| s.ensure_paragraph());
+ Pos::new(id, 0)
+ }
+ }
+ };
+ let a = fix(self, self.sel.anchor.clone());
+ let f = fix(self, self.sel.focus.clone());
+ self.sel = Selection {
+ anchor: a,
+ focus: f,
+ };
+ }
+
+ /// The shared parts and namespace declarations, detached from the
+ /// document so formatting can be resolved while it is being changed.
+ fn style_env(&self) -> (crate::document::Parts, Arc<Vec<crate::xml::Decl>>) {
+ (self.doc.parts().clone(), Arc::clone(self.doc.decls()))
+ }
+
+ /// A paragraph's format as laid out (falls back to resolving it).
+ fn para_format(&self, formats: &Formats<'_>, id: &BlockId) -> Option<Arc<ParaFormat>> {
+ if let Some(entries) = self.index.lines.get(id)
+ && let Some(&(p, i)) = entries.first()
+ && let Some(Item::Line(l)) = self.layout.pages.get(p).and_then(|pg| pg.items.get(i))
+ {
+ return Some(Arc::clone(&l.para.format));
+ }
+ let b = self.story().get(id)?;
+ Some(formats.paragraph(&b.props, &TableCtx::default()))
+ }
+
+ fn snippets(&self) -> SnippetContext {
+ SnippetContext::new(self.doc.decls())
+ }
+
+ fn typing_attrs_at(&self, pos: &Pos) -> Attrs {
+ if let Some(p) = &self.pending {
+ return p.clone();
+ }
+ let Some(b) = self.story().get(&pos.block) else {
+ return Attrs::empty();
+ };
+ text::typing_attrs(b, pos.offset, self.doc.w_prefix(), &self.snippets())
+ }
+
+ // ----- results -------------------------------------------------------
+
+ fn format_state(&mut self) -> FormatState {
+ let (start, end) = self.ordered();
+ let paras = self.paras_between(&start.block, &end.block);
+ let (parts, decls) = self.style_env();
+ let formats = Formats::new(
+ &parts.styles,
+ &parts.numbering,
+ &parts.settings,
+ &parts.theme,
+ &decls,
+ );
+ let Some(para) = self.para_format(&formats, &start.block) else {
+ return FormatState::default();
+ };
+ let attrs = if self.sel.is_collapsed() {
+ self.typing_attrs_at(&start)
+ } else {
+ self.doc
+ .body
+ .get(&start.block)
+ .and_then(|b| {
+ // The first character of the selection.
+ let at = if start.offset < b.content.len() {
+ start.offset
+ } else {
+ start.offset.saturating_sub(1)
+ };
+ b.content.attrs_at(at).cloned()
+ })
+ .unwrap_or_default()
+ };
+ let props = formats.run(&attrs, &para);
+ let mut state = FormatState {
+ bold: props.bold,
+ italic: props.italic,
+ underline: props.underline.is_some(),
+ strike: props.strike,
+ superscript: props.vert_align == crate::model::props::VertAlign::Super,
+ subscript: props.vert_align == crate::model::props::VertAlign::Sub,
+ font: Some(props.ascii.clone()),
+ size: Some(props.size),
+ color: props
+ .color
+ .map(|c| c.to_hex().trim_start_matches('#').to_uppercase()),
+ ..FormatState::default()
+ };
+ // Toggles show as on only when the whole selection has them.
+ if !self.sel.is_collapsed() {
+ let mut checked = 0usize;
+ 'outer: for (k, id) in paras.iter().enumerate() {
+ let Some(b) = self.story().get(id) else {
+ continue;
+ };
+ let Some(pf) = self.para_format(&formats, id) else {
+ continue;
+ };
+ let s = if k == 0 { start.offset } else { 0 };
+ let e = if k + 1 == paras.len() {
+ end.offset
+ } else {
+ usize::MAX
+ };
+ for (at, span) in b.content.spans_at() {
+ let len = utf16_len(&span.text);
+ if at + len <= s || at >= e || span.attrs.is_object() {
+ continue;
+ }
+ let p = formats.run(&span.attrs, &pf);
+ state.bold &= p.bold;
+ state.italic &= p.italic;
+ state.underline &= p.underline.is_some();
+ state.strike &= p.strike;
+ checked += 1;
+ if checked > 500 {
+ break 'outer;
+ }
+ }
+ }
+ }
+ let styles = &self.doc.parts().styles;
+ let style_id = para
+ .props
+ .style
+ .clone()
+ .or_else(|| styles.default_paragraph_id().map(str::to_owned));
+ state.style_name = style_id
+ .as_deref()
+ .and_then(|id| styles.get(id))
+ .map(|s| s.name.clone());
+ state.style = style_id;
+ state.align = Some(match para.props.jc {
+ Align::Center => Alignment::Center,
+ Align::Right => Alignment::Right,
+ Align::Justify | Align::Distribute => Alignment::Justify,
+ Align::Left => Alignment::Left,
+ });
+ state.list = para.props.num.is_some();
+ state.line_spacing = match para.props.line {
+ crate::model::props::LineSpacing::Auto(m) => Some((m * 100.0).round() / 100.0),
+ _ => None,
+ };
+ state.table = self.story().ancestors(&start.block).iter().any(|id| {
+ self.story()
+ .get(id)
+ .is_some_and(|b| b.kind == BlockKind::Cell)
+ });
+ state.highlight = attrs
+ .run_props()
+ .find(|(q, _)| q.ends_with(":highlight") || *q == "highlight")
+ .and_then(|(_, xml)| revise::attribute(xml, "val"))
+ .filter(|v| v != "none");
+ state.tracking = self.doc.parts().settings.track_revisions;
+ state.revision = self.touches_revision(&start, &end, &paras);
+ state.can_undo = !self.undo.is_empty();
+ state.can_redo = !self.redo.is_empty();
+ state
+ }
+
+ /// Whether the selection (or the caret) touches a tracked change.
+ fn touches_revision(&self, start: &Pos, end: &Pos, paras: &[BlockId]) -> bool {
+ let w = self.doc.w_prefix();
+ let decls = self.doc.decls();
+ if start.same_place(end) {
+ let Some(b) = self.story().get(&start.block) else {
+ return false;
+ };
+ let mark = revise::mark_revision(&b.props, w, decls).and_then(|(_, _, id)| id);
+ return !revise::ids_at(&b.content, start.offset, mark).is_empty()
+ || revise::ppr_change_id(&b.props, w, decls).is_some();
+ }
+ let last = paras.len().saturating_sub(1);
+ paras.iter().take(400).enumerate().any(|(k, id)| {
+ let Some(b) = self.story().get(id) else {
+ return false;
+ };
+ let s = if k == 0 { start.offset } else { 0 };
+ let e = if k == last {
+ end.offset
+ } else {
+ b.content.len()
+ };
+ revise::has_revisions(&b.content, s, e)
+ || (k < last && revise::mark_revision(&b.props, w, decls).is_some())
+ || revise::ppr_change_id(&b.props, w, decls).is_some()
+ })
+ }
+
+ fn result(&mut self, changes: Vec<Change>, relaid: bool) -> EditResult {
+ let (start, end) = self.ordered();
+ let paras = self.paras_between(&start.block, &end.block);
+ let caret = geometry::caret(&self.layout, &self.index, &self.sel.focus);
+ let rects =
+ geometry::selection_rects(&self.layout, &self.index, &self.sel, (&start, &end), &paras);
+ let format = self.format_state();
+ EditResult {
+ changed: !changes.is_empty(),
+ changes,
+ selection: self.sel.clone(),
+ range: Range {
+ from: start.clone(),
+ to: end.clone(),
+ },
+ caret,
+ rects,
+ pages: relaid.then(|| self.page_infos()),
+ bands: std::mem::take(&mut self.bands),
+ format,
+ story: self.story_state(),
+ }
+ }
+
+ /// The selection's current state without changing anything.
+ pub fn state(&mut self, fonts: &FontDb) -> EditResult {
+ let relaid = self.ensure_layout(fonts);
+ self.clamp_selection();
+ self.result(Vec::new(), relaid)
+ }
+
+ /// Opens a session over a shared document; undo history stays with
+ /// the caller.
+ pub fn from_collab(state: &crate::collab::CollabState, seed: u64) -> crate::Result<Self> {
+ let doc = Document::from_collab_state(state, seed)?;
+ let mut s = Self::new(doc);
+ s.external_undo = true;
+ Ok(s)
+ }
+
+ /// The shared state of the document.
+ pub fn collab_state(&self) -> crate::Result<crate::collab::CollabState> {
+ self.doc.collab_state()
+ }
+
+ /// The selected text, paragraphs separated by newlines (objects such
+ /// as pictures and field markers left out), for the clipboard.
+ pub fn selected_text(&mut self) -> String {
+ let (s, e) = self.ordered();
+ if s.same_place(&e) {
+ return String::new();
+ }
+ let paras = self.paras_between(&s.block, &e.block);
+ let mut out = String::new();
+ for (k, id) in paras.iter().enumerate() {
+ let Some(b) = self.story().get(id) else {
+ continue;
+ };
+ if k > 0 {
+ out.push('\n');
+ }
+ let from = if k == 0 { s.offset } else { 0 };
+ let to = if k + 1 == paras.len() {
+ e.offset
+ } else {
+ b.content.len()
+ };
+ for (at, span) in b.content.spans_at() {
+ let len = utf16_len(&span.text);
+ if at + len <= from || at >= to || span.attrs.is_object() || span.attrs.is_instr() {
+ continue;
+ }
+ let lo = from.saturating_sub(at);
+ let hi = (to - at).min(len);
+ let text = &span.text;
+ let a = crate::model::content::byte_at(text, lo);
+ let b = crate::model::content::byte_at(text, hi);
+ out.push_str(&text[a..b]);
+ }
+ }
+ out
+ }
+
+ /// The comments stored in the document (Word's), in the order of the
+ /// text they are on.
+ pub fn document_comments(&self) -> Vec<DocComment> {
+ comments::comments(&self.doc)
+ }
+
+ /// Paragraph ids and texts in document order.
+ pub fn paragraphs(&self) -> Vec<ParagraphText> {
+ self.doc
+ .body
+ .paragraphs()
+ .into_iter()
+ .filter_map(|id| {
+ let text = self.doc.body.get(&id)?.content.text();
+ Some(ParagraphText { id, text })
+ })
+ .collect()
+ }
+
+ /// Applies changes other peers made (or the shared undo history
+ /// replayed), keeping the selection on the same text.
+ pub fn apply_remote(
+ &mut self,
+ changes: &[RemoteChange],
+ fonts: &FontDb,
+ ) -> crate::Result<EditResult> {
+ let mut entries: Vec<(String, String, Option<String>)> = Vec::new();
+ let mut old_texts: HashMap<BlockId, String> = HashMap::new();
+ let mut deltas_of: HashMap<BlockId, &[Vec<crate::model::content::DeltaOp>]> =
+ HashMap::new();
+ for c in changes {
+ match c {
+ RemoteChange::Block { block, deltas } => {
+ let Some(b) = block.to_block() else {
+ continue;
+ };
+ if let Some(old) = self.doc.body.get(&b.id) {
+ old_texts
+ .entry(b.id.clone())
+ .or_insert_with(|| old.content.text());
+ }
+ if !deltas.is_empty() {
+ deltas_of.insert(b.id.clone(), deltas);
+ }
+ self.doc.body.insert(b);
+ self.doc.body_dirty = true;
+ }
+ RemoteChange::Remove { id } => {
+ if self.doc.body.contains(id) {
+ self.doc.body.remove_one(id);
+ self.doc.body_dirty = true;
+ }
+ }
+ RemoteChange::Entry {
+ container,
+ key,
+ value,
+ } => entries.push((container.clone(), key.clone(), value.clone())),
+ }
+ }
+ if !entries.is_empty() {
+ let kept = self.story_positions();
+ if self.doc.apply_entries(&entries)? {
+ // Headers and footers were read anew (with fresh blocks).
+ self.order = None;
+ if let Some(kept) = kept {
+ let list = self.story().paragraphs();
+ let at = |(i, offset): (usize, usize)| {
+ list.get(i)
+ .or(list.last())
+ .map(|id| Pos::new(id.clone(), offset))
+ };
+ if let (Some(a), Some(f)) = (at(kept[0]), at(kept[1])) {
+ self.sel = Selection {
+ anchor: a,
+ focus: f,
+ };
+ }
+ }
+ }
+ }
+ // Keep the caret on the same text: through the changes made when
+ // they are known (and fit), else by comparing the texts.
+ for pos in [&mut self.sel.anchor, &mut self.sel.focus] {
+ let (Some(old), Some(b)) = (old_texts.get(&pos.block), self.doc.body.get(&pos.block))
+ else {
+ continue;
+ };
+ let new = b.content.text();
+ let exact = deltas_of.get(&pos.block).and_then(|deltas| {
+ let mut text: Vec<u16> = old.encode_utf16().collect();
+ let mut offset = pos.offset;
+ for d in deltas.iter() {
+ text = apply_text_delta(&text, d)?;
+ offset = map_through(offset, d);
+ }
+ (text == new.encode_utf16().collect::<Vec<u16>>()).then_some(offset)
+ });
+ pos.offset = exact.unwrap_or_else(|| map_offset(old, &new, pos.offset));
+ }
+ self.stale = true;
+ self.order = None;
+ self.pending = None;
+ let relaid = self.ensure_layout(fonts);
+ self.clamp_selection();
+ Ok(self.result(Vec::new(), relaid))
+ }
+
+ // ----- geometry ------------------------------------------------------
+
+ /// The position at a point on a page (points).
+ pub fn hit_test(&mut self, page: usize, x: f32, y: f32, fonts: &FontDb) -> Option<Pos> {
+ self.ensure_layout(fonts);
+ geometry::hit_test(&self.layout, &self.index, page, x, y)
+ }
+
+ /// Whether a position is in the body while a header or footer is being
+ /// edited (comments and other people's carets stay on the body).
+ fn body_pos_elsewhere(&self, pos: &Pos) -> bool {
+ self.active != StoryTarget::Body && self.doc.body().contains(&pos.block)
+ }
+
+ /// The caret for a position.
+ pub fn caret_at(&mut self, pos: &Pos, fonts: &FontDb) -> Option<CaretRect> {
+ self.ensure_layout(fonts);
+ let index = if self.body_pos_elsewhere(pos) {
+ &self.body_index
+ } else {
+ &self.index
+ };
+ geometry::caret(&self.layout, index, pos)
+ }
+
+ /// Highlight rectangles of a range in one paragraph or across several
+ /// (comments, search results, other people's selections).
+ pub fn range_rects(&mut self, a: &Pos, b: &Pos, fonts: &FontDb) -> Vec<PageRect> {
+ self.ensure_layout(fonts);
+ if self.body_pos_elsewhere(a) {
+ let list = self.doc.body().paragraphs();
+ let at = |p: &Pos| list.iter().position(|id| *id == p.block).unwrap_or(0);
+ let (ia, ib) = (at(a), at(b));
+ let (s, e, i, j) = if (ia, a.offset) <= (ib, b.offset) {
+ (a, b, ia, ib)
+ } else {
+ (b, a, ib, ia)
+ };
+ return geometry::range_rects(
+ &self.layout,
+ &self.body_index,
+ s,
+ e,
+ &list[i..=j.max(i)],
+ );
+ }
+ let o = self.order();
+ let ia = o.index.get(&a.block).copied().unwrap_or(0);
+ let ib = o.index.get(&b.block).copied().unwrap_or(0);
+ let (s, e) = if (ia, a.offset) <= (ib, b.offset) {
+ (a, b)
+ } else {
+ (b, a)
+ };
+ let paras = self.paras_between(&s.block, &e.block);
+ geometry::range_rects(&self.layout, &self.index, s, e, &paras)
+ }
+
+ /// The matches of a search in the body, with their highlight
+ /// rectangles, and the match at or after the selection.
+ pub fn find(&mut self, query: &str, options: &FindOptions, fonts: &FontDb) -> FindResult {
+ self.ensure_layout(fonts);
+ let paras = self.doc.body().paragraphs();
+ let (found, truncated) = find::find(self.doc.body(), &paras, query, options, find::LIMIT);
+ let order: HashMap<&BlockId, usize> =
+ paras.iter().enumerate().map(|(i, id)| (id, i)).collect();
+ let key = |p: &Pos| (order.get(&p.block).copied().unwrap_or(0), p.offset);
+ let sel = if self.active == StoryTarget::Body {
+ Some(&self.sel)
+ } else {
+ self.body_sel.as_ref()
+ };
+ let current = sel.and_then(|sel| {
+ let (a, f) = (key(&sel.anchor), key(&sel.focus));
+ let (start, end) = if a <= f { (a, f) } else { (f, a) };
+ found
+ .iter()
+ .position(|(from, to)| key(from) == start && key(to) == end)
+ .or_else(|| found.iter().position(|(from, _)| key(from) >= start))
+ .or((!found.is_empty()).then_some(0))
+ });
+ let index = if self.active == StoryTarget::Body {
+ &self.index
+ } else {
+ &self.body_index
+ };
+ let matches = found
+ .into_iter()
+ .map(|(from, to)| {
+ let rects = geometry::range_rects(
+ &self.layout,
+ index,
+ &from,
+ &to,
+ std::slice::from_ref(&from.block),
+ );
+ FindMatch { from, to, rects }
+ })
+ .collect();
+ FindResult {
+ matches,
+ current,
+ truncated,
+ }
+ }
+
+ // ----- operations ----------------------------------------------------
+
+ /// Applies operations in order as one undo step (merged into the
+ /// previous step when both carry the same `group`, as typing does).
+ pub fn apply(
+ &mut self,
+ ops: &[EditOp],
+ group: Option<&str>,
+ fonts: &FontDb,
+ ) -> crate::Result<EditResult> {
+ let mut relaid = self.ensure_layout(fonts);
+ self.clamp_selection();
+ let before = self.sel.clone();
+ let snapshot = self.doc.snapshot();
+ // One step per story the operations changed, in order (inserting a
+ // note and typing in it changes the body, then the note).
+ let mut steps: Vec<Step> = Vec::new();
+ for op in ops {
+ if self.stale {
+ relaid |= self.ensure_layout(fonts);
+ }
+ if let Some(s) = self.run_op(op)? {
+ match steps.last_mut() {
+ Some(last) if last.story == s.story => last.merge(s),
+ _ => steps.push(s),
+ }
+ self.stale = true;
+ }
+ }
+ relaid |= self.ensure_layout(fonts);
+ self.clamp_selection();
+ let mut changes: Vec<Change> = steps.iter().flat_map(Step::changes).collect();
+ changes.extend(self.doc.entry_changes(&snapshot)?);
+ steps.retain(|s| !s.is_empty());
+ if !steps.is_empty() {
+ for step in steps {
+ self.record_undo(step, before.clone(), group);
+ }
+ } else if ops.iter().any(|op| {
+ matches!(
+ op,
+ EditOp::Select { .. } | EditOp::Move { .. } | EditOp::SelectAll
+ )
+ }) {
+ self.open_group = None;
+ }
+ Ok(self.result(changes, relaid))
+ }
+
+ fn record_undo(&mut self, step: Step, before: Selection, group: Option<&str>) {
+ if self.external_undo {
+ return;
+ }
+ self.redo.clear();
+ let after = self.sel.clone();
+ if let (Some(g), Some(last)) = (group, self.undo.last_mut())
+ && self.open_group.as_deref() == Some(g)
+ && last.group.as_deref() == Some(g)
+ {
+ last.step.merge(step);
+ last.after = after;
+ return;
+ }
+ self.undo.push(UndoEntry {
+ step,
+ before,
+ after,
+ group: group.map(str::to_owned),
+ });
+ self.open_group = group.map(str::to_owned);
+ if self.undo.len() > 500 {
+ self.undo.remove(0);
+ }
+ }
+
+ /// Ends the current typing group.
+ pub fn break_group(&mut self) {
+ self.open_group = None;
+ }
+
+ /// Undoes the last step.
+ pub fn undo(&mut self, fonts: &FontDb) -> Option<EditResult> {
+ let entry = self.undo.pop()?;
+ let inverse = entry.step.inverse();
+ let snapshot = self.doc.snapshot();
+ txn::apply_step(&mut self.doc, &inverse);
+ self.stale = true;
+ self.order = None;
+ self.pending = None;
+ self.open_group = None;
+ let mut changes = inverse.changes();
+ changes.extend(self.doc.entry_changes(&snapshot).unwrap_or_default());
+ let sel = entry.before.clone();
+ self.redo.push(entry);
+ let relaid = self.ensure_layout(fonts);
+ self.adopt(sel);
+ Some(self.result(changes, relaid))
+ }
+
+ /// Redoes the last undone step.
+ pub fn redo(&mut self, fonts: &FontDb) -> Option<EditResult> {
+ let entry = self.redo.pop()?;
+ let snapshot = self.doc.snapshot();
+ txn::apply_step(&mut self.doc, &entry.step);
+ self.stale = true;
+ self.order = None;
+ self.pending = None;
+ self.open_group = None;
+ let mut changes = entry.step.changes();
+ changes.extend(self.doc.entry_changes(&snapshot).unwrap_or_default());
+ let sel = entry.after.clone();
+ self.undo.push(entry);
+ let relaid = self.ensure_layout(fonts);
+ self.adopt(sel);
+ Some(self.result(changes, relaid))
+ }
+
+ /// Whether undo is possible.
+ pub fn can_undo(&self) -> bool {
+ !self.undo.is_empty()
+ }
+
+ /// Whether redo is possible.
+ pub fn can_redo(&self) -> bool {
+ !self.redo.is_empty()
+ }
+
+ /// Serializes the document.
+ pub fn save(&self) -> crate::Result<Vec<u8>> {
+ self.doc.save()
+ }
+
+ fn set_caret(&mut self, pos: Pos) {
+ self.sel = Selection::caret(pos);
+ }
+
+ /// Runs one operation; returns the transaction step when it changed
+ /// the document.
+ fn run_op(&mut self, op: &EditOp) -> crate::Result<Option<Step>> {
+ if !matches!(
+ op,
+ EditOp::Move {
+ unit: Unit::Line,
+ ..
+ }
+ ) {
+ self.goal_x = None;
+ }
+ match op {
+ EditOp::Select { anchor, focus } => {
+ self.adopt(Selection {
+ anchor: anchor.clone(),
+ focus: focus.clone(),
+ });
+ self.pending = None;
+ Ok(None)
+ }
+ EditOp::EnterStory { page, x, y } => {
+ match self.chrome_at(*page, *y) {
+ Some((_, Some(part))) => {
+ self.enter_part(part, *page);
+ let first = self.story().paragraphs().into_iter().next();
+ let pos = geometry::hit_test(&self.layout, &self.index, *page, *x, *y)
+ .or_else(|| first.map(|id| Pos::new(id, 0)));
+ if let Some(pos) = pos {
+ self.sel = Selection::caret(pos);
+ }
+ self.clamp_selection();
+ }
+ // No header or footer to edit on this page.
+ Some((_, None)) => {}
+ None => match self.note_at(*page, *x, *y) {
+ // Already in it: the selection stays.
+ Some(note) if note == self.active => {}
+ Some(note) => {
+ self.enter(note, *page);
+ if let Some(pos) =
+ geometry::hit_test(&self.layout, &self.index, *page, *x, *y)
+ {
+ self.sel = Selection::caret(pos);
+ }
+ self.clamp_selection();
+ }
+ None => {
+ self.leave_story();
+ if let Some(pos) =
+ geometry::hit_test(&self.layout, &self.index, *page, *x, *y)
+ {
+ self.sel = Selection::caret(pos);
+ }
+ }
+ },
+ }
+ self.pending = None;
+ Ok(None)
+ }
+ EditOp::ExitStory => {
+ self.leave_story();
+ Ok(None)
+ }
+ EditOp::SetTracking { on } => {
+ if revise::set_tracking(&mut self.doc, *on)? {
+ self.order = None;
+ self.stale = true;
+ }
+ Ok(None)
+ }
+ EditOp::Paste {
+ paragraphs,
+ same_document,
+ } => self.paste(paragraphs, *same_document),
+ EditOp::Replace {
+ query,
+ options,
+ with,
+ all,
+ } => Ok(self.replace(query, options, with, *all)),
+ EditOp::AcceptChanges { all } => Ok(self.resolve(true, *all)),
+ EditOp::RejectChanges { all } => Ok(self.resolve(false, *all)),
+ EditOp::SelectAll => {
+ let o = self.order();
+ if let (Some(first), Some(last)) = (o.list.first(), o.list.last()) {
+ let len = self.para_len(last);
+ self.sel = Selection {
+ anchor: Pos::new(first.clone(), 0),
+ focus: Pos::new(last.clone(), len),
+ };
+ }
+ self.pending = None;
+ Ok(None)
+ }
+ EditOp::SelectWord { at } => {
+ let text = self
+ .story()
+ .get(&at.block)
+ .map(|b| b.content.text())
+ .unwrap_or_default();
+ let (s, e) = word_at(&text, at.offset);
+ self.sel = Selection {
+ anchor: Pos::new(at.block.clone(), s),
+ focus: Pos::new(at.block.clone(), e),
+ };
+ self.pending = None;
+ Ok(None)
+ }
+ EditOp::SelectParagraph { at } => {
+ let len = self.para_len(&at.block);
+ self.sel = Selection {
+ anchor: Pos::new(at.block.clone(), 0),
+ focus: Pos::new(at.block.clone(), len),
+ };
+ self.pending = None;
+ Ok(None)
+ }
+ EditOp::Move {
+ unit,
+ forward,
+ extend,
+ visual,
+ } => {
+ let flip = *visual && self.right_to_left(&self.sel.focus.clone());
+ self.move_caret(*unit, *forward != flip, *extend);
+ self.pending = None;
+ Ok(None)
+ }
+ EditOp::InsertText { text } => Ok(Some(self.insert_text(text))),
+ EditOp::InsertParagraph => Ok(Some(self.insert_paragraph())),
+ EditOp::InsertBreak { kind } => Ok(Some(self.insert_break(*kind))),
+ EditOp::InsertNote { endnote } => self.insert_note(*endnote),
+ EditOp::Delete { forward, unit } => Ok(self.delete(*forward, *unit)),
+ EditOp::ToggleFormat { format } => Ok(self.toggle(*format)),
+ EditOp::SetFormat { patch } => {
+ let w = self.doc.w_prefix().to_owned();
+ let patch = patch.clone();
+ Ok(self.map_runs(move |a| patch.apply(a, &w)))
+ }
+ EditOp::ClearFormat => Ok(self.map_runs(format::cleared)),
+ EditOp::SetParagraph { patch } => {
+ let decls = Arc::clone(self.doc.decls());
+ let patch = patch.clone();
+ Ok(self.map_paragraphs(move |e| patch.apply(e, &decls)))
+ }
+ EditOp::SetStyle { style } => {
+ if self.doc.parts().styles.get(style).is_none() {
+ return Err(crate::Error::InvalidEdit(format!("no style `{style}`")));
+ }
+ let style = style.clone();
+ Ok(self.map_paragraphs(move |e| e.set_val("pStyle", Some(&style))))
+ }
+ EditOp::ToggleList { kind } => self.toggle_list(*kind),
+ EditOp::Indent { forward } => Ok(self.indent(*forward)),
+ EditOp::InsertTable { rows, cols } => Ok(self.insert_table(*rows, *cols)),
+ EditOp::InsertRow { below } => {
+ let below = *below;
+ Ok(self.table_op(move |txn, p| table::insert_row(txn, p, below)))
+ }
+ EditOp::InsertColumn { right } => {
+ let right = *right;
+ Ok(self.table_op(move |txn, p| table::insert_column(txn, p, right)))
+ }
+ EditOp::DeleteRow => Ok(self.table_op(table::delete_row)),
+ EditOp::DeleteColumn => Ok(self.table_op(table::delete_column)),
+ EditOp::DeleteTable => Ok(self.table_op(table::delete_table)),
+ }
+ }
+
+ // ----- lists and tables ----------------------------------------------
+
+ /// The list kind each paragraph has (from its formatting).
+ fn list_kinds(&self, paras: &[BlockId]) -> Vec<Option<(ListKind, i64, u8)>> {
+ let (parts, decls) = self.style_env();
+ let formats = Formats::new(
+ &parts.styles,
+ &parts.numbering,
+ &parts.settings,
+ &parts.theme,
+ &decls,
+ );
+ paras
+ .iter()
+ .map(|id| {
+ let pf = self.para_format(&formats, id)?;
+ let (num, ilvl) = pf.props.num?;
+ if num <= 0 {
+ return None;
+ }
+ let level = parts.numbering.level(num, ilvl, &parts.styles)?;
+ Some((lists::kind_of(&level.fmt)?, num, ilvl))
+ })
+ .collect()
+ }
+
+ fn toggle_list(&mut self, kind: ListKind) -> crate::Result<Option<Step>> {
+ let (s, e) = self.ordered();
+ let paras = self.paras_between(&s.block, &e.block);
+ let kinds = self.list_kinds(&paras);
+ let all = kinds.iter().all(|k| k.is_some_and(|(k, _, _)| k == kind));
+ let w = self.doc.w_prefix().to_owned();
+ let q = |l: &str| {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+ };
+ let list_style = self
+ .doc
+ .parts()
+ .styles
+ .id_by_name("List Paragraph")
+ .map(str::to_owned);
+ let default_style = self
+ .doc
+ .parts()
+ .styles
+ .default_paragraph_id()
+ .map(str::to_owned);
+ let rev = self.revisor();
+ if all {
+ // Back to plain paragraphs.
+ let styles = std::sync::Arc::clone(&self.doc.parts().styles);
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ for id in &paras {
+ format::edit_ppr(&mut txn, id, rev.as_ref(), |e| {
+ let style = e.get("pStyle").map(str::to_owned);
+ let style_id = style.as_deref().and_then(|x| {
+ let at = x.find("val=\"")? + 5;
+ x[at..].split('"').next().map(str::to_owned)
+ });
+ let style_numbered = style_id
+ .as_deref()
+ .and_then(|id| styles.get(id))
+ .is_some_and(|st| st.ppr.num.num_id.is_some_and(|n| n > 0));
+ if style_numbered {
+ e.set(
+ "numPr",
+ Some(format!(
+ "<{np}><{nid} {val}=\"0\"/></{np}>",
+ np = q("numPr"),
+ nid = q("numId"),
+ val = q("val")
+ )),
+ );
+ } else {
+ e.set("numPr", None);
+ }
+ if style_id.is_some() && style_id == list_style {
+ e.set("pStyle", None);
+ }
+ });
+ }
+ return Ok(Some(txn.finish()));
+ }
+ // Continue the list just before the selection, if it is this kind.
+ let prev = self.neighbour_para(&paras[0], false);
+ let continued = prev
+ .map(|p| self.list_kinds(&[p]))
+ .and_then(|k| k.into_iter().next().flatten())
+ .filter(|(k, _, _)| *k == kind);
+ let (num, base_level) = match continued {
+ Some((_, num, ilvl)) => (num, ilvl),
+ None => (lists::instance_for(&mut self.doc, kind)?, 0),
+ };
+ self.stale = true;
+ let current = self.list_kinds(&paras);
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ for (id, k) in paras.iter().zip(current) {
+ let ilvl = k.map_or(base_level, |(_, _, l)| l);
+ format::edit_ppr(&mut txn, id, rev.as_ref(), |e| {
+ e.set(
+ "numPr",
+ Some(format!(
+ "<{np}><{il} {val}=\"{ilvl}\"/><{nid} {val}=\"{num}\"/></{np}>",
+ np = q("numPr"),
+ il = q("ilvl"),
+ nid = q("numId"),
+ val = q("val")
+ )),
+ );
+ // Word gives new list items the List Paragraph style.
+ let plain = e.get("pStyle").is_none_or(|x| {
+ default_style
+ .as_deref()
+ .is_some_and(|d| x.contains(&format!("\"{d}\"")))
+ });
+ if plain && let Some(ls) = &list_style {
+ e.set_val("pStyle", Some(ls));
+ }
+ });
+ }
+ Ok(Some(txn.finish()))
+ }
+
+ fn indent(&mut self, forward: bool) -> Option<Step> {
+ let (s, e) = self.ordered();
+ let paras = self.paras_between(&s.block, &e.block);
+ let kinds = self.list_kinds(&paras);
+ let w = self.doc.w_prefix().to_owned();
+ let decls = std::sync::Arc::clone(self.doc.decls());
+ let q = |l: &str| {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+ };
+ let (parts, pdecls) = self.style_env();
+ let formats = Formats::new(
+ &parts.styles,
+ &parts.numbering,
+ &parts.settings,
+ &parts.theme,
+ &pdecls,
+ );
+ let lefts: Vec<f32> = paras
+ .iter()
+ .map(|id| {
+ self.para_format(&formats, id)
+ .map_or(0.0, |pf| pf.props.ind_left)
+ })
+ .collect();
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ for ((id, k), left) in paras.iter().zip(kinds).zip(lefts) {
+ match k {
+ Some((_, num, ilvl)) => {
+ let next = if forward {
+ (ilvl + 1).min(8)
+ } else {
+ ilvl.saturating_sub(1)
+ };
+ format::edit_ppr(&mut txn, id, rev.as_ref(), |e| {
+ e.set(
+ "numPr",
+ Some(format!(
+ "<{np}><{il} {val}=\"{next}\"/><{nid} {val}=\"{num}\"/></{np}>",
+ np = q("numPr"),
+ il = q("ilvl"),
+ nid = q("numId"),
+ val = q("val")
+ )),
+ );
+ });
+ }
+ None => {
+ // Half an inch at a time, to the next multiple.
+ let step = 36.0;
+ let target = if forward {
+ ((left / step).floor() + 1.0) * step
+ } else {
+ (((left / step).ceil() - 1.0) * step).max(0.0)
+ };
+ let twips = ((target * 20.0).round() as i64).to_string();
+ format::edit_ppr(&mut txn, id, rev.as_ref(), |e| {
+ e.set_attrs(
+ "ind",
+ &[("left", Some(twips.clone())), ("start", None)],
+ &decls,
+ );
+ });
+ }
+ }
+ }
+ Some(txn.finish())
+ }
+
+ fn insert_table(&mut self, rows: usize, cols: usize) -> Option<Step> {
+ let at = self.sel.focus.clone();
+ let width = {
+ let section = self.doc.final_section();
+ ((section.text_width() * 20.0).round() as i64).max(1440)
+ };
+ let grid_style = self
+ .doc
+ .parts()
+ .styles
+ .id_by_name("Table Grid")
+ .map(str::to_owned);
+ let sel = self.sel.clone();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let at = if sel.is_collapsed() {
+ at
+ } else {
+ delete_selection(&mut txn, &sel)
+ };
+ // Nested tables get two thirds of the page width.
+ let nested = table::enclosing(&txn, &at.block).is_some();
+ let width = if nested { width * 2 / 3 } else { width };
+ let caret = table::insert_table(&mut txn, &at, rows, cols, width, grid_style.as_deref());
+ let step = txn.finish();
+ if let Some(c) = caret {
+ self.set_caret(c);
+ }
+ Some(step)
+ }
+
+ fn table_op(&mut self, f: impl FnOnce(&mut Txn<'_>, &BlockId) -> Option<Pos>) -> Option<Step> {
+ let at = self.sel.focus.block.clone();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let caret = f(&mut txn, &at);
+ let step = txn.finish();
+ if let Some(c) = caret {
+ self.set_caret(c);
+ }
+ Some(step)
+ }
+
+ // ----- movement ------------------------------------------------------
+
+ fn stops(&self, block: &BlockId) -> Vec<usize> {
+ geometry::para_stops(&self.layout, &self.index, block).unwrap_or_else(|| {
+ let len = self.para_len(block);
+ let text = self
+ .story()
+ .get(block)
+ .map(|b| b.content.text())
+ .unwrap_or_default();
+ let mut offs = char_offsets(&text);
+ offs.retain(|&o| o <= len);
+ offs
+ })
+ }
+
+ fn neighbour_para(&mut self, id: &BlockId, forward: bool) -> Option<BlockId> {
+ let o = self.order();
+ let i = *o.index.get(id)?;
+ if forward {
+ o.list.get(i + 1).cloned()
+ } else {
+ i.checked_sub(1).and_then(|j| o.list.get(j).cloned())
+ }
+ }
+
+ fn step_char(&mut self, from: &Pos, forward: bool) -> Pos {
+ let stops = self.stops(&from.block);
+ if forward {
+ if let Some(&n) = stops.iter().find(|&&s| s > from.offset) {
+ return Pos::new(from.block.clone(), n);
+ }
+ if let Some(next) = self.neighbour_para(&from.block, true) {
+ let first = self.stops(&next).first().copied().unwrap_or(0);
+ return Pos::new(next, first);
+ }
+ } else {
+ if let Some(&p) = stops.iter().rev().find(|&&s| s < from.offset) {
+ return Pos::new(from.block.clone(), p);
+ }
+ if let Some(prev) = self.neighbour_para(&from.block, false) {
+ let len = self.para_len(&prev);
+ return Pos::new(prev, len);
+ }
+ }
+ from.clone()
+ }
+
+ fn step_word(&mut self, from: &Pos, forward: bool) -> Pos {
+ let text = self
+ .story()
+ .get(&from.block)
+ .map(|b| b.content.text())
+ .unwrap_or_default();
+ let len = self.para_len(&from.block);
+ if forward {
+ if from.offset >= len {
+ return self.step_char(from, true);
+ }
+ Pos::new(
+ from.block.clone(),
+ word_forward(&text, from.offset).min(len),
+ )
+ } else {
+ if from.offset == 0 {
+ return self.step_char(from, false);
+ }
+ Pos::new(from.block.clone(), word_backward(&text, from.offset))
+ }
+ }
+
+ /// Whether the paragraph at a position reads right to left.
+ fn right_to_left(&self, pos: &Pos) -> bool {
+ geometry::locate(&self.layout, &self.index, pos)
+ .is_some_and(|(_, pl, _)| pl.para.inline.levels.last().is_some_and(|l| l % 2 == 1))
+ }
+
+ fn move_caret(&mut self, unit: Unit, forward: bool, extend: bool) {
+ let focus = self.sel.focus.clone();
+ // Arrow keys collapse a selection to its edge.
+ if !extend && !self.sel.is_collapsed() && matches!(unit, Unit::Char) {
+ let (s, e) = self.ordered();
+ self.set_caret(if forward { e } else { s });
+ return;
+ }
+ let target = match unit {
+ Unit::Char => self.step_char(&focus, forward),
+ Unit::Word => self.step_word(&focus, forward),
+ Unit::Line => {
+ let Some(caret) = geometry::caret(&self.layout, &self.index, &focus) else {
+ return;
+ };
+ let goal = *self.goal_x.get_or_insert(caret.x);
+ match geometry::vertical(&self.layout, &self.index, &caret, goal, forward) {
+ Some(p) => p,
+ None => {
+ // Past the first or last line: go to the end.
+ let o = self.order();
+ if forward {
+ let last = o.list.last().cloned().unwrap_or(focus.block.clone());
+ let len = self.para_len(&last);
+ Pos::new(last, len)
+ } else {
+ Pos::new(o.list.first().cloned().unwrap_or(focus.block.clone()), 0)
+ }
+ }
+ }
+ }
+ Unit::LineBoundary => match geometry::line_bounds(&self.layout, &self.index, &focus) {
+ Some((s, e)) => {
+ if forward {
+ e
+ } else {
+ s
+ }
+ }
+ None => focus.clone(),
+ },
+ Unit::Paragraph => {
+ if forward {
+ match self.neighbour_para(&focus.block, true) {
+ Some(n) => Pos::new(n, 0),
+ None => Pos::new(focus.block.clone(), self.para_len(&focus.block)),
+ }
+ } else if focus.offset > 0 {
+ Pos::new(focus.block.clone(), 0)
+ } else {
+ match self.neighbour_para(&focus.block, false) {
+ Some(p) => Pos::new(p, 0),
+ None => focus.clone(),
+ }
+ }
+ }
+ Unit::Document => {
+ let o = self.order();
+ if forward {
+ let last = o.list.last().cloned().unwrap_or(focus.block.clone());
+ let len = self.para_len(&last);
+ Pos::new(last, len)
+ } else {
+ Pos::new(o.list.first().cloned().unwrap_or(focus.block.clone()), 0)
+ }
+ }
+ };
+ if extend {
+ self.sel.focus = target;
+ } else {
+ self.set_caret(target);
+ }
+ }
+
+ // ----- editing -------------------------------------------------------
+
+ fn insert_text(&mut self, text: &str) -> Step {
+ let pending = self.pending.take();
+ let sel = self.sel.clone();
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let at = match &rev {
+ // Typing over a selection while tracking goes after the
+ // deleted text.
+ Some(r) => tracked_delete_selection(&mut txn, &sel, r).1,
+ None => delete_selection(&mut txn, &sel),
+ };
+ let mut attrs = pending.unwrap_or_else(|| typing_in(&txn, &at));
+ if let Some(r) = &rev {
+ attrs = revise::inserted(&attrs, char_before(&txn, &at).as_ref(), r);
+ }
+ let end = text::insert_text(&mut txn, &at, text, &attrs, rev.as_ref());
+ let step = txn.finish();
+ self.set_caret(end);
+ step
+ }
+
+ fn insert_paragraph(&mut self) -> Step {
+ self.pending = None;
+ let sel = self.sel.clone();
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let at = match &rev {
+ Some(r) => tracked_delete_selection(&mut txn, &sel, r).1,
+ None => delete_selection(&mut txn, &sel),
+ };
+ let empty_list_item = txn
+ .get(&at.block)
+ .is_some_and(|b| b.content.is_empty() && text::has_direct_numbering(&b.props));
+ let caret = if empty_list_item {
+ // Enter on an empty list item ends the list.
+ format::edit_ppr(&mut txn, &at.block, rev.as_ref(), |e| e.set("numPr", None));
+ at.clone()
+ } else {
+ text::split_tracked(&mut txn, &at, rev.as_ref()).unwrap_or(at.clone())
+ };
+ let step = txn.finish();
+ self.set_caret(caret);
+ step
+ }
+
+ fn insert_note(&mut self, endnote: bool) -> crate::Result<Option<Step>> {
+ // Notes are referenced from the body, as in Word.
+ if self.active != StoryTarget::Body {
+ return Ok(None);
+ }
+ let note = notes::add_note(&mut self.doc, endnote)?;
+ self.stale = true;
+ let w = self.doc.w_prefix().to_owned();
+ let q = |l: &str| {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+ };
+ let local = if endnote {
+ "endnoteReference"
+ } else {
+ "footnoteReference"
+ };
+ let object = format!("<{} {}=\"{}\"/>", q(local), q("id"), note.id);
+ let pending = self.pending.take();
+ let sel = self.sel.clone();
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let at = match &rev {
+ Some(r) => tracked_delete_selection(&mut txn, &sel, r).1,
+ None => delete_selection(&mut txn, &sel),
+ };
+ let mut attrs = pending.unwrap_or_else(|| typing_in(&txn, &at));
+ attrs = match &note.reference_style {
+ Some(id) => attrs.with(
+ &format!("{}{}", key::RUN_PROP, q("rStyle")),
+ Some(&format!("<{} {}=\"{id}\"/>", q("rStyle"), q("val"))),
+ ),
+ None => attrs.with(
+ &format!("{}{}", key::RUN_PROP, q("vertAlign")),
+ Some(&format!(
+ "<{} {}=\"superscript\"/>",
+ q("vertAlign"),
+ q("val")
+ )),
+ ),
+ };
+ if let Some(r) = &rev {
+ attrs = revise::inserted(&attrs, char_before(&txn, &at).as_ref(), r);
+ }
+ attrs = attrs.with(key::OBJ, Some(&object));
+ let mut after = at.clone();
+ if let Some(b) = txn.block_mut(&at.block) {
+ let o = at.offset.min(b.content.len());
+ b.content.insert(o, &OBJECT_CHAR.to_string(), attrs);
+ after = Pos::new(at.block.clone(), o + 1);
+ }
+ let step = txn.finish();
+ // Into the new note, after its mark and space; leaving it comes
+ // back to just after the reference.
+ let target = StoryTarget::Note {
+ endnote,
+ id: note.id,
+ };
+ let first = self.doc.story(&target).paragraphs().into_iter().next();
+ if let Some(first) = first
+ && self.doc.has_story(&target)
+ {
+ let len = self
+ .doc
+ .story(&target)
+ .get(&first)
+ .map_or(0, |b| b.content.len());
+ self.enter(target, 0);
+ self.body_sel = Some(Selection::caret(after));
+ self.sel = Selection::caret(Pos::new(first, len));
+ } else {
+ self.set_caret(after);
+ }
+ Ok(Some(step))
+ }
+
+ fn insert_break(&mut self, kind: BreakKind) -> Step {
+ let w = self.doc.w_prefix().to_owned();
+ let q = |l: &str| {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+ };
+ let object = match kind {
+ BreakKind::Line => None,
+ BreakKind::Page => Some(format!("<{} {}=\"page\"/>", q("br"), q("type"))),
+ BreakKind::Column => Some(format!("<{} {}=\"column\"/>", q("br"), q("type"))),
+ };
+ let pending = self.pending.take();
+ let sel = self.sel.clone();
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let at = match &rev {
+ Some(r) => tracked_delete_selection(&mut txn, &sel, r).1,
+ None => delete_selection(&mut txn, &sel),
+ };
+ let mut attrs = pending.unwrap_or_else(|| typing_in(&txn, &at));
+ if let Some(r) = &rev {
+ attrs = revise::inserted(&attrs, char_before(&txn, &at).as_ref(), r);
+ }
+ let ch = match &object {
+ Some(xml) => {
+ attrs = attrs.with(key::OBJ, Some(xml));
+ OBJECT_CHAR.to_string()
+ }
+ // A line break is a newline inside the paragraph.
+ None => "\n".to_owned(),
+ };
+ let mut end = at.clone();
+ if let Some(b) = txn.block_mut(&at.block) {
+ let o = at.offset.min(b.content.len());
+ b.content.insert(o, &ch, attrs);
+ end.offset = o + utf16_len(&ch);
+ end.upstream = false;
+ }
+ let step = txn.finish();
+ self.set_caret(end);
+ step
+ }
+
+ fn delete(&mut self, forward: bool, unit: Unit) -> Option<Step> {
+ self.pending = None;
+ let rev = self.revisor();
+ if !self.sel.is_collapsed() {
+ let sel = self.sel.clone();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let caret = match &rev {
+ Some(r) => {
+ let (start, end) = tracked_delete_selection(&mut txn, &sel, r);
+ if forward { end } else { start }
+ }
+ None => delete_selection(&mut txn, &sel),
+ };
+ let step = txn.finish();
+ self.set_caret(caret);
+ return Some(step);
+ }
+ let at = self.sel.focus.clone();
+ let len = self.para_len(&at.block);
+ let at_edge = if forward {
+ at.offset >= len
+ } else {
+ at.offset == 0
+ };
+ if at_edge {
+ return self.delete_at_edge(&at, forward);
+ }
+ let other = match unit {
+ Unit::Word => self.step_word(&at, forward),
+ Unit::LineBoundary => match geometry::line_bounds(&self.layout, &self.index, &at) {
+ Some((s, e)) => {
+ if forward {
+ e
+ } else {
+ s
+ }
+ }
+ None => at.clone(),
+ },
+ _ => self.step_char(&at, forward),
+ };
+ if other.block != at.block {
+ return self.delete_at_edge(&at, forward);
+ }
+ let (s, e) = if forward {
+ (at.offset, other.offset)
+ } else {
+ (other.offset, at.offset)
+ };
+ if s >= e {
+ return None;
+ }
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let mut caret = s;
+ if let Some(b) = txn.block_mut(&at.block) {
+ match &rev {
+ // Deleted text stays (marked); the caret steps past it.
+ Some(r) => {
+ let end = revise::delete_in(&mut b.content, s, e, r);
+ if forward {
+ caret = end;
+ }
+ }
+ None => b.content.delete(s, e),
+ }
+ }
+ let step = txn.finish();
+ self.set_caret(Pos::new(at.block.clone(), caret));
+ Some(step)
+ }
+
+ /// Backspace at a paragraph's start or Delete at its end.
+ fn delete_at_edge(&mut self, at: &Pos, forward: bool) -> Option<Step> {
+ let numbered = self
+ .story()
+ .get(&at.block)
+ .is_some_and(|b| text::has_direct_numbering(&b.props));
+ if !forward && numbered {
+ // Backspace at a list item's start removes its number first.
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ format::edit_ppr(&mut txn, &at.block, rev.as_ref(), |e| e.set("numPr", None));
+ return Some(txn.finish());
+ }
+ let other = self.neighbour_para(&at.block, forward)?;
+ let (first, second) = if forward {
+ (at.block.clone(), other.clone())
+ } else {
+ (other.clone(), at.block.clone())
+ };
+ let parent = |s: &Self, id: &BlockId| s.story().get(id).and_then(|b| b.parent.clone());
+ let siblings = parent(self, &first) == parent(self, &second);
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let caret = if siblings && let Some(r) = &rev {
+ // The mark between them is marked deleted (or goes, when the
+ // author inserted it); the caret steps over it.
+ let len = txn.get(&first).map_or(0, |b| b.content.len());
+ if revise::delete_mark(&mut txn, &first, &second, r) {
+ Some(Pos::new(first.clone(), len))
+ } else if forward {
+ Some(Pos::new(second.clone(), 0))
+ } else {
+ Some(Pos::new(first.clone(), len))
+ }
+ } else if siblings {
+ text::join(&mut txn, &first, &second)
+ } else if rev.is_some() {
+ let len = txn.get(&other).map_or(0, |b| b.content.len());
+ Some(Pos::new(other.clone(), if forward { 0 } else { len }))
+ } else {
+ // Across a table edge: an empty paragraph goes, otherwise the
+ // caret just moves.
+ let empty = txn.get(&at.block).is_some_and(|b| b.content.is_empty());
+ let in_cell = txn
+ .get(&at.block)
+ .and_then(|b| b.parent.as_ref())
+ .and_then(|p| txn.get(p))
+ .is_some_and(|p| p.kind == BlockKind::Cell);
+ if empty && !in_cell {
+ txn.remove(&at.block);
+ let len = txn.get(&other).map_or(0, |b| b.content.len());
+ Some(Pos::new(other.clone(), if forward { 0 } else { len }))
+ } else {
+ let len = txn.get(&other).map_or(0, |b| b.content.len());
+ Some(Pos::new(other.clone(), if forward { 0 } else { len }))
+ }
+ };
+ let step = txn.finish();
+ if let Some(c) = caret {
+ self.set_caret(c);
+ }
+ Some(step)
+ }
+
+ /// Replaces the match the selection holds and selects the next one, or
+ /// every match, keeping the caret on its text.
+ fn replace(
+ &mut self,
+ query: &str,
+ options: &FindOptions,
+ with: &str,
+ all: bool,
+ ) -> Option<Step> {
+ self.leave_story();
+ self.pending = None;
+ let matches = |s: &Self| {
+ let paras = s.doc.body().paragraphs();
+ find::find(s.doc.body(), &paras, query, options, usize::MAX).0
+ };
+ let found = matches(self);
+ if found.is_empty() {
+ return None;
+ }
+ let (start, end) = self.ordered();
+ if all {
+ let mut caret = start;
+ let mut step = Step::default();
+ // Last to first, so the earlier matches stay where they were.
+ for (from, to) in found.iter().rev() {
+ let before = self.para_len(&from.block);
+ step.merge(self.replace_range(from, to, with));
+ if caret.block == from.block {
+ if caret.offset >= to.offset {
+ caret.offset =
+ (caret.offset + self.para_len(&from.block)).saturating_sub(before);
+ } else if caret.offset > from.offset {
+ caret.offset = from.offset;
+ }
+ }
+ }
+ self.set_caret(caret);
+ return Some(step);
+ }
+ let held = found
+ .iter()
+ .find(|(from, to)| from.same_place(&start) && to.same_place(&end))
+ .cloned();
+ let Some((from, to)) = held else {
+ self.select_match(&found, &start);
+ return None;
+ };
+ let step = self.replace_range(&from, &to, with);
+ let caret = self.sel.focus.clone();
+ let found = matches(self);
+ if found.is_empty() {
+ self.set_caret(caret);
+ } else {
+ self.select_match(&found, &caret);
+ }
+ Some(step)
+ }
+
+ /// Replaces a range with text in the formatting of its first character.
+ fn replace_range(&mut self, from: &Pos, to: &Pos, with: &str) -> Step {
+ let attrs = self.story().get(&from.block).map(|b| {
+ text::typing_attrs(
+ b,
+ from.offset + 1,
+ self.doc.w_prefix(),
+ &SnippetContext::new(self.doc.decls()),
+ )
+ });
+ self.sel = Selection {
+ anchor: from.clone(),
+ focus: to.clone(),
+ };
+ if with.is_empty() {
+ self.pending = None;
+ return self.delete(true, Unit::Char).unwrap_or_default();
+ }
+ self.pending = attrs;
+ self.insert_text(with)
+ }
+
+ /// Selects the first match at or after a position (or the first).
+ fn select_match(&mut self, found: &[(Pos, Pos)], at: &Pos) {
+ let o = self.order();
+ let key = |p: &Pos| (o.index.get(&p.block).copied().unwrap_or(0), p.offset);
+ let next = found
+ .iter()
+ .find(|(from, _)| key(from) >= key(at))
+ .or(found.first());
+ if let Some((from, to)) = next {
+ self.sel = Selection {
+ anchor: from.clone(),
+ focus: to.clone(),
+ };
+ }
+ }
+
+ /// Pastes paragraphs over the selection.
+ fn paste(
+ &mut self,
+ paragraphs: &[ClipParagraph],
+ same_document: bool,
+ ) -> crate::Result<Option<Step>> {
+ if paragraphs.is_empty() {
+ return Ok(None);
+ }
+ let pending = self.pending.take();
+ let sel = self.sel.clone();
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ let at = match &rev {
+ Some(r) => tracked_delete_selection(&mut txn, &sel, r).1,
+ None => delete_selection(&mut txn, &sel),
+ };
+ let base = pending.unwrap_or_else(|| typing_in(&txn, &at));
+ let before = char_before(&txn, &at);
+ let end = clip::paste(
+ &mut txn,
+ &at,
+ paragraphs,
+ &base,
+ before,
+ same_document,
+ rev.as_ref(),
+ )?;
+ let step = txn.finish();
+ self.set_caret(end);
+ Ok(Some(step))
+ }
+
+ /// The selection for the clipboard: Macro's own form, HTML and text.
+ pub fn copy_selection(&mut self) -> Clip {
+ let (s, e) = self.ordered();
+ if s.same_place(&e) {
+ return Clip::default();
+ }
+ let paras = self.paras_between(&s.block, &e.block);
+ let kinds = self.list_kinds(&paras);
+ let (parts, decls) = self.style_env();
+ let formats = Formats::new(
+ &parts.styles,
+ &parts.numbering,
+ &parts.settings,
+ &parts.theme,
+ &decls,
+ );
+ let w = self.doc.w_prefix().to_owned();
+ let mut out = Clip::default();
+ let mut html = String::from("<meta charset=\"utf-8\">");
+ let mut open_list: Option<ListKind> = None;
+ let last = paras.len().saturating_sub(1);
+ for (k, id) in paras.iter().enumerate() {
+ let Some(b) = self.story().get(id) else {
+ continue;
+ };
+ if b.kind != BlockKind::Paragraph {
+ continue;
+ }
+ let from = if k == 0 { s.offset } else { 0 };
+ let to = if k == last { e.offset } else { b.content.len() };
+ let runs = clip::copy_spans(&b.content, from, to);
+ let Some(pf) = self.para_format(&formats, id) else {
+ continue;
+ };
+ let heading = pf.props.outline_lvl.filter(|l| *l < 9).map(|l| l + 1);
+ let list = kinds.get(k).copied().flatten();
+ // The mark's revision and the section break stay behind.
+ let mut props = revise::set_mark_revision(&b.props, None, &w, &decls);
+ if props.contains("sectPr") {
+ let mut el = xmledit::Element::open(&props, "pPr", &w, &decls, xmledit::PPR_ORDER);
+ el.set("sectPr", None);
+ props = el.finish(true);
+ }
+ match (list, open_list) {
+ (Some((kind, _, _)), Some(open)) if kind == open => {}
+ (list, open) => {
+ if let Some(open) = open {
+ html.push_str(if open == ListKind::Bullet {
+ "</ul>"
+ } else {
+ "</ol>"
+ });
+ }
+ if let Some((kind, _, _)) = list {
+ html.push_str(if kind == ListKind::Bullet {
+ "<ul>"
+ } else {
+ "<ol>"
+ });
+ }
+ open_list = list.map(|(kind, _, _)| kind);
+ }
+ }
+ let tag = match (list, heading) {
+ (Some(_), _) => "li".to_owned(),
+ (None, Some(h)) if h <= 6 => format!("h{h}"),
+ _ => "p".to_owned(),
+ };
+ clip::paragraph_html(&mut html, &runs, &formats, &pf, &tag);
+ out.paragraphs.push(ClipParagraph {
+ runs,
+ props: Some(props),
+ heading,
+ list: list.map(|(kind, _, _)| kind),
+ level: list.map_or(0, |(_, _, l)| l),
+ });
+ }
+ if let Some(open) = open_list {
+ html.push_str(if open == ListKind::Bullet {
+ "</ul>"
+ } else {
+ "</ol>"
+ });
+ }
+ out.html = html;
+ out.text = self.selected_text();
+ out
+ }
+
+ /// Accepts or rejects tracked changes: every one in the story, those in
+ /// the selection, or the one at the caret.
+ fn resolve(&mut self, accept: bool, all: bool) -> Option<Step> {
+ self.pending = None;
+ let (start, end) = self.ordered();
+ let scope = if all {
+ revise::Scope::All
+ } else if start.same_place(&end) {
+ let b = self.story().get(&start.block)?;
+ let (w, decls) = (self.doc.w_prefix(), self.doc.decls());
+ let mark = revise::mark_revision(&b.props, w, decls).and_then(|(_, _, id)| id);
+ let mut ids = revise::ids_at(&b.content, start.offset, mark);
+ // The paragraph's property change applies wherever the caret is in it.
+ ids.extend(revise::ppr_change_id(&b.props, w, decls));
+ if ids.is_empty() {
+ return None;
+ }
+ revise::Scope::Ids(ids)
+ } else {
+ revise::Scope::Range {
+ paras: self.paras_between(&start.block, &end.block),
+ from: start.offset,
+ to: end.offset,
+ }
+ };
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ revise::resolve(&mut txn, &scope, accept);
+ let step = txn.finish();
+ // The selection's start survives; text after it may be gone.
+ self.sel = Selection::caret(Pos {
+ upstream: false,
+ ..start
+ });
+ self.clamp_selection();
+ Some(step)
+ }
+
+ /// Applies `f` to the attributes of every selected span (or to the
+ /// formatting the next typed text gets, at a caret).
+ fn map_runs(&mut self, f: impl Fn(&Attrs) -> Attrs) -> Option<Step> {
+ if self.sel.is_collapsed() {
+ let at = self.sel.focus.clone();
+ let base = self.typing_attrs_at(&at);
+ self.pending = Some(f(&base));
+ return None;
+ }
+ let (s, e) = self.ordered();
+ let paras = self.paras_between(&s.block, &e.block);
+ // While tracking, each run keeps a record of its formatting before.
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ for (k, id) in paras.iter().enumerate() {
+ let Some(len) = txn.get(id).map(|b| b.content.len()) else {
+ continue;
+ };
+ let from = if k == 0 { s.offset } else { 0 };
+ let to = if k + 1 == paras.len() { e.offset } else { len };
+ if from >= to {
+ continue;
+ }
+ let before = txn.get(id).map(|b| b.content.clone()).unwrap_or_default();
+ let mut content = before.clone();
+ // Markers between runs (bookmarks, comment ranges) have no formatting.
+ content.map_attrs(from, to, |a| {
+ if a.marker().is_some() {
+ a.clone()
+ } else {
+ let new = f(a);
+ match &rev {
+ Some(r) => r.format_change(a, &new),
+ None => new,
+ }
+ }
+ });
+ if content != before
+ && let Some(b) = txn.block_mut(id)
+ {
+ b.content = content;
+ }
+ }
+ Some(txn.finish())
+ }
+
+ fn toggle(&mut self, t: Toggle) -> Option<Step> {
+ let w = self.doc.w_prefix().to_owned();
+ let (parts, decls) = self.style_env();
+ let formats = Formats::new(
+ &parts.styles,
+ &parts.numbering,
+ &parts.settings,
+ &parts.theme,
+ &decls,
+ );
+ let (s, e) = self.ordered();
+ let paras = self.paras_between(&s.block, &e.block);
+ let mut fmts: HashMap<BlockId, Arc<ParaFormat>> = HashMap::new();
+ for id in &paras {
+ if let Some(pf) = self.para_format(&formats, id) {
+ fmts.insert(id.clone(), pf);
+ }
+ }
+ // On unless the whole selection already has it.
+ let mut all_on = true;
+ if self.sel.is_collapsed() {
+ let attrs = self.typing_attrs_at(&s);
+ if let Some(pf) = fmts.get(&s.block) {
+ all_on = t.is_on(&formats.run(&attrs, pf));
+ }
+ } else {
+ for (k, id) in paras.iter().enumerate() {
+ let (Some(b), Some(pf)) = (self.story().get(id), fmts.get(id)) else {
+ continue;
+ };
+ let from = if k == 0 { s.offset } else { 0 };
+ let to = if k + 1 == paras.len() {
+ e.offset
+ } else {
+ b.content.len()
+ };
+ for (at, span) in b.content.spans_at() {
+ let len = utf16_len(&span.text);
+ if at + len <= from || at >= to || span.attrs.marker().is_some() {
+ continue;
+ }
+ if !t.is_on(&formats.run(&span.attrs, pf)) {
+ all_on = false;
+ }
+ }
+ }
+ }
+ let on = !all_on;
+ let apply = |a: &Attrs, pf: &Arc<ParaFormat>| {
+ let inh = format::inherited(&formats, a, pf, t, &w);
+ format::toggled(a, t, on, inh, &w)
+ };
+ if self.sel.is_collapsed() {
+ let base = self.typing_attrs_at(&s);
+ if let Some(pf) = fmts.get(&s.block) {
+ self.pending = Some(apply(&base, pf));
+ }
+ return None;
+ }
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ for (k, id) in paras.iter().enumerate() {
+ let Some(pf) = fmts.get(id) else {
+ continue;
+ };
+ let Some(len) = txn.get(id).map(|b| b.content.len()) else {
+ continue;
+ };
+ let from = if k == 0 { s.offset } else { 0 };
+ let to = if k + 1 == paras.len() { e.offset } else { len };
+ if from >= to {
+ continue;
+ }
+ let before = txn.get(id).map(|b| b.content.clone()).unwrap_or_default();
+ let mut content = before.clone();
+ content.map_attrs(from, to, |a| {
+ if a.marker().is_some() {
+ a.clone()
+ } else {
+ let new = apply(a, pf);
+ match &rev {
+ Some(r) => r.format_change(a, &new),
+ None => new,
+ }
+ }
+ });
+ if content != before
+ && let Some(b) = txn.block_mut(id)
+ {
+ b.content = content;
+ }
+ }
+ Some(txn.finish())
+ }
+
+ /// Applies `f` to the `w:pPr` of every selected paragraph.
+ fn map_paragraphs(&mut self, f: impl Fn(&mut Element)) -> Option<Step> {
+ let (s, e) = self.ordered();
+ let paras = self.paras_between(&s.block, &e.block);
+ let rev = self.revisor();
+ let mut txn = Txn::new(&mut self.doc, &self.active);
+ for id in &paras {
+ format::edit_ppr(&mut txn, id, rev.as_ref(), &f);
+ }
+ Some(txn.finish())
+ }
+}
+
+/// Deletes the selection inside a transaction; returns the caret.
+fn delete_selection(txn: &mut Txn<'_>, sel: &Selection) -> Pos {
+ if sel.is_collapsed() {
+ return sel.anchor.clone();
+ }
+ let list = txn.story().paragraphs();
+ let index: HashMap<&BlockId, usize> = list.iter().enumerate().map(|(i, id)| (id, i)).collect();
+ let (a, f) = (&sel.anchor, &sel.focus);
+ let ia = index.get(&a.block).copied().unwrap_or(0);
+ let ifo = index.get(&f.block).copied().unwrap_or(0);
+ let (s, e) = if (ia, a.offset) <= (ifo, f.offset) {
+ (a.clone(), f.clone())
+ } else {
+ (f.clone(), a.clone())
+ };
+ if s.same_place(&e) {
+ return s;
+ }
+ text::delete_range(txn, &s, &e)
+}
+
+/// Deletes the selection while tracking changes; returns its ends after.
+fn tracked_delete_selection(
+ txn: &mut Txn<'_>,
+ sel: &Selection,
+ rev: &revise::Revisor,
+) -> (Pos, Pos) {
+ if sel.is_collapsed() {
+ return (sel.anchor.clone(), sel.anchor.clone());
+ }
+ let list = txn.story().paragraphs();
+ let index: HashMap<&BlockId, usize> = list.iter().enumerate().map(|(i, id)| (id, i)).collect();
+ let (a, f) = (&sel.anchor, &sel.focus);
+ let ia = index.get(&a.block).copied().unwrap_or(0);
+ let ifo = index.get(&f.block).copied().unwrap_or(0);
+ let (s, e) = if (ia, a.offset) <= (ifo, f.offset) {
+ (a.clone(), f.clone())
+ } else {
+ (f.clone(), a.clone())
+ };
+ if s.same_place(&e) {
+ return (s.clone(), s);
+ }
+ revise::delete_range(txn, &s, &e, rev)
+}
+
+/// The attributes of the character before a position.
+fn char_before(txn: &Txn<'_>, at: &Pos) -> Option<Attrs> {
+ let b = txn.get(&at.block)?;
+ b.content.attrs_at(at.offset.checked_sub(1)?).cloned()
+}
+
+/// The formatting text typed at a position inside a transaction gets.
+fn typing_in(txn: &Txn<'_>, at: &Pos) -> Attrs {
+ txn.get(&at.block)
+ .map(|b| {
+ text::typing_attrs(
+ b,
+ at.offset,
+ txn.doc.w_prefix(),
+ &SnippetContext::new(txn.doc.decls()),
+ )
+ })
+ .unwrap_or_default()
+}
diff --git a/crates/docx_engine/src/edit/clip.rs b/crates/docx_engine/src/edit/clip.rs
new file mode 100644
index 0000000000..e85a882807
--- /dev/null
+++ b/crates/docx_engine/src/edit/clip.rs
@@ -0,0 +1,534 @@
+//! The clipboard. A copy is a list of paragraphs: in Macro's own form
+//! (every run's attributes and the paragraph properties, which paste back
+//! losslessly) and as HTML for other applications. Pasted HTML arrives as
+//! the same paragraphs with plain formatting flags instead of attributes.
+
+use super::ListKind;
+use super::revise::{self, Revisor};
+use super::txn::Txn;
+use super::xmledit::{Element, PPR_ORDER};
+use super::{Pos, text};
+use crate::layout::format::{Formats, ParaFormat};
+use crate::model::block::BlockId;
+use crate::model::content::{Attrs, Wrapper, encode_wrappers, key, utf16_len};
+use crate::xml::SnippetContext;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+fn is_false(v: &bool) -> bool {
+ !*v
+}
+
+fn is_zero(v: &u8) -> bool {
+ *v == 0
+}
+
+/// One copied or pasted paragraph.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClipParagraph {
+ /// Its text, run by run.
+ pub runs: Vec<ClipRun>,
+ /// Paragraph properties (`w:pPr`), from a copy in this editor.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub props: Option<String>,
+ /// Heading level, 1 to 9.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub heading: Option<u8>,
+ /// The kind of list it is an item of.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub list: Option<ListKind>,
+ /// Its list level (0 is the outermost).
+ #[serde(default, skip_serializing_if = "is_zero")]
+ pub level: u8,
+}
+
+/// One run of copied or pasted text.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClipRun {
+ /// The text (object characters stand for pictures and fields).
+ pub text: String,
+ /// The run's attributes, from a copy in this editor.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub attrs: Option<BTreeMap<String, String>>,
+ /// Bold.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub bold: bool,
+ /// Italic.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub italic: bool,
+ /// Underlined.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub underline: bool,
+ /// Struck through.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub strike: bool,
+ /// Superscript.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub superscript: bool,
+ /// Subscript.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub subscript: bool,
+}
+
+/// What a selection copies.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct Clip {
+ /// The paragraphs, in Macro's own form.
+ pub paragraphs: Vec<ClipParagraph>,
+ /// The same content as HTML.
+ pub html: String,
+ /// The plain text, paragraphs separated by newlines.
+ pub text: String,
+}
+
+/// A copied span: its text and attributes, without tracked deletions
+/// (copies read as if every change were accepted) and without markers
+/// (bookmarks and comment ranges belong to where they are).
+pub(crate) fn copy_spans(
+ content: &crate::model::content::Content,
+ from: usize,
+ to: usize,
+) -> Vec<ClipRun> {
+ let mut out = Vec::new();
+ for (at, span) in content.spans_at() {
+ let len = utf16_len(&span.text);
+ if at + len <= from || at >= to {
+ continue;
+ }
+ let wrappers = span.attrs.wrappers();
+ if wrappers.iter().any(revise::is_deleted) || span.attrs.marker().is_some() {
+ continue;
+ }
+ let lo = from.saturating_sub(at);
+ let hi = (to - at).min(len);
+ let a = crate::model::content::byte_at(&span.text, lo);
+ let b = crate::model::content::byte_at(&span.text, hi);
+ // Insertions are just text in a copy.
+ let kept: Vec<Wrapper> = wrappers
+ .into_iter()
+ .filter(|w| !revise::is_revision(w))
+ .collect();
+ let attrs = span
+ .attrs
+ .with(key::WRAP, encode_wrappers(&kept).as_deref())
+ .without(|k| {
+ k.strip_prefix(key::RUN_PROP)
+ .is_some_and(|q| q.ends_with(":rPrChange"))
+ });
+ out.push(ClipRun {
+ text: span.text[a..b].to_owned(),
+ attrs: Some(
+ attrs
+ .iter()
+ .map(|(k, v)| (k.to_owned(), v.to_owned()))
+ .collect(),
+ ),
+ ..ClipRun::default()
+ });
+ }
+ out
+}
+
+/// Whether markup refers to a relationship of its part (pictures, links,
+/// embedded objects), which another document does not have.
+fn refers_to_relationship(xml: &str) -> bool {
+ ["r:id=", "r:embed=", "r:link=", "r:pict=", "r:dm="]
+ .iter()
+ .any(|a| xml.contains(a))
+}
+
+/// Whether `xml` is exactly one well-formed element.
+fn one_element(ctx: &SnippetContext, xml: &str) -> bool {
+ ctx.parse_many(xml)
+ .is_ok_and(|(tree, kids)| kids.len() == 1 && tree.is_element(kids[0]))
+}
+
+/// Whether `name` can be written as an attribute name.
+fn attribute_name(name: &str) -> bool {
+ name.chars()
+ .next()
+ .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
+ && name
+ .chars()
+ .all(|c| c.is_ascii_alphanumeric() || matches!(c, ':' | '-' | '_' | '.'))
+}
+
+/// Native run attributes as pasted, which may come from anywhere: only the
+/// kinds this editor writes, and only markup that is well-formed, so a
+/// paste can never break the document's XML. `None` when the run's object
+/// is not well-formed (the run is left out).
+fn well_formed(attrs: Attrs, ctx: &SnippetContext) -> Option<Attrs> {
+ if attrs.object().is_some_and(|xml| !one_element(ctx, xml)) {
+ return None;
+ }
+ let wrappers_ok = attrs
+ .wrappers()
+ .iter()
+ .all(|w| one_element(ctx, &format!("{}{}", w.open, w.close)));
+ let bad: Vec<&str> = attrs
+ .iter()
+ .filter(|(k, v)| match *k {
+ key::OBJ | key::INSTR => false,
+ key::WRAP => !wrappers_ok,
+ _ => {
+ if let Some(name) = k.strip_prefix(key::RUN_ATTR) {
+ !attribute_name(name)
+ } else {
+ !(k.starts_with(key::RUN_PROP) && one_element(ctx, v))
+ }
+ }
+ })
+ .map(|(k, _)| k)
+ .collect();
+ Some(attrs.without(|k| bad.contains(&k)))
+}
+
+/// A pasted run's attributes. Runs copied in this editor keep theirs, minus
+/// what only makes sense in the document they came from when pasted into
+/// another; other runs take the formatting at the caret plus their flags.
+fn run_attrs(
+ run: &ClipRun,
+ base: &Attrs,
+ same_document: bool,
+ w: &str,
+ styles: &crate::model::styles::Styles,
+ ctx: &SnippetContext,
+) -> Option<Attrs> {
+ if let Some(native) = &run.attrs {
+ let attrs = Attrs::from_pairs(native.iter().map(|(k, v)| (k.as_str(), v.as_str())));
+ let mut attrs = well_formed(attrs, ctx)?;
+ if attrs.marker().is_some() {
+ return None;
+ }
+ if !same_document {
+ if attrs.object().is_some_and(refers_to_relationship) {
+ return None;
+ }
+ let kept: Vec<Wrapper> = attrs
+ .wrappers()
+ .into_iter()
+ .filter(|wr| !refers_to_relationship(&wr.open) && wr.local() != "hyperlink")
+ .collect();
+ attrs = attrs.with(key::WRAP, encode_wrappers(&kept).as_deref());
+ // A character style the document lacks would be ignored anyway.
+ let style_key = format!("{}{w}:rStyle", key::RUN_PROP);
+ if let Some(xml) = attrs.get(&style_key)
+ && revise::attribute(xml, "val").is_some_and(|id| styles.get(&id).is_none())
+ {
+ attrs = attrs.with(&style_key, None);
+ }
+ }
+ return Some(attrs);
+ }
+ let q = |l: &str| {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+ };
+ let mut attrs = base.clone();
+ let mut set = |local: &str, xml: String| {
+ attrs = attrs.with(&format!("{}{}", key::RUN_PROP, q(local)), Some(&xml));
+ };
+ if run.bold {
+ set("b", format!("<{}/>", q("b")));
+ }
+ if run.italic {
+ set("i", format!("<{}/>", q("i")));
+ }
+ if run.underline {
+ set("u", format!("<{} {}=\"single\"/>", q("u"), q("val")));
+ }
+ if run.strike {
+ set("strike", format!("<{}/>", q("strike")));
+ }
+ if run.superscript || run.subscript {
+ let v = if run.superscript {
+ "superscript"
+ } else {
+ "subscript"
+ };
+ set(
+ "vertAlign",
+ format!("<{} {}=\"{v}\"/>", q("vertAlign"), q("val")),
+ );
+ }
+ Some(attrs)
+}
+
+/// The paragraph style for a heading level, if the document has one.
+fn heading_style(styles: &crate::model::styles::Styles, level: u8) -> Option<String> {
+ styles
+ .id_by_name(&format!("heading {level}"))
+ .or_else(|| styles.id_by_name(&format!("Heading {level}")))
+ .map(str::to_owned)
+}
+
+/// Gives a pasted paragraph its properties: those it was copied with (from
+/// this document, or without list numbering from another), or a heading
+/// style and list numbering for pasted HTML.
+fn paragraph_props(
+ txn: &mut Txn<'_>,
+ id: &BlockId,
+ para: &ClipParagraph,
+ same_document: bool,
+ lists: &mut BTreeMap<ListKind, i64>,
+) -> crate::Result<()> {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = Arc::clone(txn.doc.decls());
+ let styles = Arc::clone(&txn.doc.parts().styles);
+ let q = |l: &str| {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+ };
+ let list_num = match para.list {
+ Some(kind)
+ if !(same_document && para.props.as_deref().is_some_and(|p| p.contains("numPr"))) =>
+ {
+ let num = match lists.get(&kind) {
+ Some(n) => *n,
+ None => {
+ let n = super::lists::instance_for(txn.doc, kind)?;
+ lists.insert(kind, n);
+ n
+ }
+ };
+ Some(num)
+ }
+ _ => None,
+ };
+ let Some(b) = txn.get(id) else {
+ return Ok(());
+ };
+ let current = b.props.clone();
+ // Properties that are not one well-formed `w:pPr` are not used.
+ let props = para
+ .props
+ .as_deref()
+ .filter(|p| one_element(&SnippetContext::new(&decls), p));
+ let mut e = match props {
+ Some(props) => {
+ let mut e = Element::open(props, "pPr", &w, &decls, PPR_ORDER);
+ if !same_document {
+ e.set("numPr", None);
+ if let Some(style) = e.get("pStyle").and_then(|x| revise::attribute(x, "val"))
+ && styles.get(&style).is_none()
+ {
+ e.set("pStyle", None);
+ }
+ }
+ e
+ }
+ None => Element::open(&current, "pPr", &w, &decls, PPR_ORDER),
+ };
+ // The section break stays with the paragraph mark it belongs to.
+ let sect = Element::open(&current, "pPr", &w, &decls, PPR_ORDER)
+ .get("sectPr")
+ .map(str::to_owned);
+ e.set("sectPr", sect);
+ if props.is_none()
+ && let Some(level) = para.heading
+ && let Some(style) = heading_style(&styles, level)
+ {
+ e.set_val("pStyle", Some(&style));
+ }
+ if let Some(num) = list_num {
+ e.set(
+ "numPr",
+ Some(format!(
+ "<{np}><{il} {val}=\"{lvl}\"/><{ni} {val}=\"{num}\"/></{np}>",
+ np = q("numPr"),
+ il = q("ilvl"),
+ ni = q("numId"),
+ val = q("val"),
+ lvl = para.level.min(8),
+ )),
+ );
+ if let Some(style) = styles.id_by_name("List Paragraph")
+ && !e.has("pStyle")
+ {
+ e.set_val("pStyle", Some(style));
+ }
+ }
+ let props = e.finish(true);
+ if props != current
+ && let Some(b) = txn.block_mut(id)
+ {
+ b.props = props;
+ }
+ Ok(())
+}
+
+/// Pastes paragraphs at `at` (the selection already removed). As in Word,
+/// the first pasted paragraph's mark ends the paragraph the caret is in and
+/// the last pasted paragraph runs into the text after the caret, keeping
+/// that paragraph's formatting. Returns where the caret goes.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn paste(
+ txn: &mut Txn<'_>,
+ at: &Pos,
+ paragraphs: &[ClipParagraph],
+ base: &Attrs,
+ before: Option<Attrs>,
+ same_document: bool,
+ rev: Option<&Revisor>,
+) -> crate::Result<Pos> {
+ let w = txn.doc.w_prefix().to_owned();
+ let styles = Arc::clone(&txn.doc.parts().styles);
+ let snippets = SnippetContext::new(txn.doc.decls());
+ let mut pos = Pos {
+ upstream: false,
+ ..at.clone()
+ };
+ let mut lists: BTreeMap<ListKind, i64> = BTreeMap::new();
+ let mut previous = before;
+ for (i, para) in paragraphs.iter().enumerate() {
+ if i > 0 {
+ let Some(next) = text::split_tracked(txn, &pos, rev) else {
+ break;
+ };
+ // The paragraph just ended carries the pasted paragraph's mark.
+ if let Some(prev) = revise::previous_paragraph(txn, &next.block) {
+ paragraph_props(txn, &prev, &paragraphs[i - 1], same_document, &mut lists)?;
+ }
+ pos = next;
+ }
+ for run in &para.runs {
+ if run.text.is_empty() {
+ continue;
+ }
+ let Some(mut attrs) = run_attrs(run, base, same_document, &w, &styles, &snippets)
+ else {
+ continue;
+ };
+ // A note reference: the note comes along as a copy of its own
+ // within the document, and is left behind from another one.
+ if let Some(object) = attrs.object().map(str::to_owned)
+ && let Some((endnote, id)) = super::notes::reference(&object)
+ {
+ if !same_document {
+ continue;
+ }
+ let Some(copy) = super::notes::duplicate(txn.doc, endnote, id)? else {
+ continue;
+ };
+ let Some(renumbered) = revise::with_attribute(&object, "id", &copy.to_string())
+ else {
+ continue;
+ };
+ attrs = attrs.with(key::OBJ, Some(&renumbered));
+ }
+ if let Some(r) = rev {
+ attrs = revise::inserted(&attrs, previous.as_ref(), r);
+ }
+ let Some(b) = txn.block_mut(&pos.block) else {
+ break;
+ };
+ let offset = pos.offset.min(b.content.len());
+ b.content.insert(offset, &run.text, attrs.clone());
+ pos.offset = offset + utf16_len(&run.text);
+ previous = Some(attrs);
+ }
+ }
+ Ok(pos)
+}
+
+/// A colour as CSS.
+fn css_color(c: &pptx_engine::model::color::Rgba) -> String {
+ c.to_hex()
+}
+
+fn escape_html(out: &mut String, s: &str) {
+ for c in s.chars() {
+ match c {
+ '<' => out.push_str("&lt;"),
+ '>' => out.push_str("&gt;"),
+ '&' => out.push_str("&amp;"),
+ '"' => out.push_str("&quot;"),
+ '\n' => out.push_str("<br>"),
+ crate::model::content::OBJECT_CHAR => {}
+ c => out.push(c),
+ }
+ }
+}
+
+/// One paragraph as HTML (its element and inline styles).
+pub(crate) fn paragraph_html(
+ out: &mut String,
+ runs: &[ClipRun],
+ formats: &Formats<'_>,
+ para: &Arc<ParaFormat>,
+ tag: &str,
+) {
+ let align = match para.props.jc {
+ crate::model::props::Align::Center => "center",
+ crate::model::props::Align::Right => "right",
+ crate::model::props::Align::Justify | crate::model::props::Align::Distribute => "justify",
+ crate::model::props::Align::Left => "left",
+ };
+ out.push_str(&format!("<{tag} style=\"margin:0;text-align:{align}\">"));
+ if runs.iter().all(|r| {
+ r.text
+ .chars()
+ .all(|c| c == crate::model::content::OBJECT_CHAR)
+ }) {
+ out.push_str("<br>");
+ }
+ for run in runs {
+ let attrs = run
+ .attrs
+ .as_ref()
+ .map(|m| Attrs::from_pairs(m.iter().map(|(k, v)| (k.as_str(), v.as_str()))))
+ .unwrap_or_default();
+ if attrs.is_instr() {
+ continue;
+ }
+ let p = formats.run(&attrs, para);
+ if p.vanish {
+ continue;
+ }
+ let mut style = format!(
+ "font-family:'{}';font-size:{}pt",
+ p.ascii.replace('\'', ""),
+ p.size
+ );
+ if p.bold {
+ style.push_str(";font-weight:bold");
+ }
+ if p.italic {
+ style.push_str(";font-style:italic");
+ }
+ let mut deco = Vec::new();
+ if p.underline.is_some() {
+ deco.push("underline");
+ }
+ if p.strike || p.dstrike {
+ deco.push("line-through");
+ }
+ if !deco.is_empty() {
+ style.push_str(&format!(";text-decoration:{}", deco.join(" ")));
+ }
+ if let Some(c) = &p.color {
+ style.push_str(&format!(";color:{}", css_color(c)));
+ }
+ let (open, close) = match p.vert_align {
+ crate::model::props::VertAlign::Super => ("<sup>", "</sup>"),
+ crate::model::props::VertAlign::Sub => ("<sub>", "</sub>"),
+ _ => ("", ""),
+ };
+ out.push_str(&format!("{open}<span style=\"{style}\">"));
+ escape_html(out, &run.text);
+ out.push_str(&format!("</span>{close}"));
+ }
+ out.push_str(&format!("</{tag}>"));
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/edit/clip/test.rs b/crates/docx_engine/src/edit/clip/test.rs
new file mode 100644
index 0000000000..d34e2a3da4
--- /dev/null
+++ b/crates/docx_engine/src/edit/clip/test.rs
@@ -0,0 +1,291 @@
+use super::super::test_util::*;
+use super::super::*;
+use crate::test_support::Parts;
+use std::collections::BTreeMap;
+
+const STYLES: &str = r#"<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style><w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/><w:basedOn w:val="Normal"/><w:pPr><w:outlineLvl w:val="0"/></w:pPr><w:rPr><w:b/><w:sz w:val="32"/></w:rPr></w:style><w:style w:type="paragraph" w:styleId="ListParagraph"><w:name w:val="List Paragraph"/><w:basedOn w:val="Normal"/></w:style>"#;
+
+fn open_styled(body: &str) -> Session {
+ open_with(
+ body,
+ &Parts {
+ styles: Some(STYLES),
+ ..Parts::default()
+ },
+ )
+}
+
+fn heading(text: &str) -> String {
+ format!(
+ r#"<w:p><w:pPr><w:pStyle w:val="Heading1"/></w:pPr><w:r><w:t xml:space="preserve">{text}</w:t></w:r></w:p>"#
+ )
+}
+
+fn bold_p(plain: &str, bold: &str) -> String {
+ format!(
+ r#"<w:p><w:r><w:t xml:space="preserve">{plain}</w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">{bold}</w:t></w:r></w:p>"#
+ )
+}
+
+fn style_of(s: &Session, i: usize) -> String {
+ s.document().body().get(&para(s, i)).unwrap().props.clone()
+}
+
+fn bold_at(s: &Session, i: usize, offset: usize) -> bool {
+ s.document()
+ .body()
+ .get(&para(s, i))
+ .unwrap()
+ .content
+ .attrs_at(offset)
+ .is_some_and(|a| a.has("r:w:b"))
+}
+
+fn paste(s: &mut Session, paragraphs: Vec<ClipParagraph>, same: bool) -> EditResult {
+ run(
+ s,
+ EditOp::Paste {
+ paragraphs,
+ same_document: same,
+ },
+ )
+}
+
+#[test]
+fn copying_and_pasting_in_one_document_keeps_formatting() {
+ let mut s = open_styled(&format!(
+ "{}{}{}",
+ heading("Term"),
+ bold_p("Plain ", "bold"),
+ p("Target.")
+ ));
+ // Copy the heading's mark and the next paragraph.
+ select(&mut s, (0, 0), (1, 10));
+ let clip = s.copy_selection();
+ assert_eq!(clip.paragraphs.len(), 2);
+ assert_eq!(clip.text, "Term\nPlain bold");
+ assert!(clip.html.contains("<h1"), "{}", clip.html);
+ assert!(clip.html.contains("font-weight:bold"), "{}", clip.html);
+ // Paste at the end of the last paragraph.
+ caret_at(&mut s, 2, 7);
+ let r = paste(&mut s, clip.paragraphs, true);
+ assert_eq!(
+ texts(&s),
+ vec!["Term", "Plain bold", "Target.Term", "Plain bold"]
+ );
+ // The first pasted paragraph's mark ends the target paragraph, which
+ // becomes a heading; the last runs into the rest, formatted as copied.
+ assert!(style_of(&s, 2).contains("Heading1"));
+ assert!(!style_of(&s, 3).contains("Heading1"));
+ assert!(bold_at(&s, 3, 7));
+ assert!(!bold_at(&s, 3, 2));
+ assert_eq!(r.selection.focus, Pos::new(para(&s, 3), 10));
+}
+
+#[test]
+fn pasting_one_paragraph_keeps_the_target_paragraph() {
+ let mut s = open_styled(&format!("{}{}", heading("Heading"), bold_p("a ", "b")));
+ select(&mut s, (1, 0), (1, 3));
+ let clip = s.copy_selection();
+ caret_at(&mut s, 0, 7);
+ paste(&mut s, clip.paragraphs, true);
+ assert_eq!(texts(&s)[0], "Headinga b");
+ assert!(style_of(&s, 0).contains("Heading1"));
+ assert!(bold_at(&s, 0, 9));
+}
+
+#[test]
+fn pasted_html_takes_headings_lists_and_flags() {
+ let mut s = open_styled(&p("Start"));
+ caret_at(&mut s, 0, 5);
+ let runs = |t: &str, bold: bool| ClipRun {
+ text: t.to_owned(),
+ bold,
+ ..ClipRun::default()
+ };
+ paste(
+ &mut s,
+ vec![
+ ClipParagraph {
+ runs: vec![runs(" more", false)],
+ ..ClipParagraph::default()
+ },
+ ClipParagraph {
+ runs: vec![runs("Scope", false)],
+ heading: Some(1),
+ ..ClipParagraph::default()
+ },
+ ClipParagraph {
+ runs: vec![runs("first ", false), runs("item", true)],
+ list: Some(ListKind::Number),
+ ..ClipParagraph::default()
+ },
+ ClipParagraph {
+ runs: vec![runs("second item", false)],
+ list: Some(ListKind::Number),
+ ..ClipParagraph::default()
+ },
+ ClipParagraph {
+ runs: vec![runs("End", false)],
+ ..ClipParagraph::default()
+ },
+ ],
+ false,
+ );
+ assert_eq!(
+ texts(&s),
+ vec!["Start more", "Scope", "first item", "second item", "End"]
+ );
+ assert!(style_of(&s, 1).contains("Heading1"));
+ assert!(style_of(&s, 2).contains("numPr"));
+ assert!(style_of(&s, 3).contains("numPr"));
+ // Both items are one list.
+ let num = |i: usize| {
+ let props = style_of(&s, i);
+ let at = props.find("numId w:val=\"").unwrap() + 13;
+ props[at..].split('"').next().unwrap().to_owned()
+ };
+ assert_eq!(num(2), num(3));
+ assert!(bold_at(&s, 2, 7));
+ assert!(!bold_at(&s, 2, 1));
+ // Saved and reopened, the numbering part exists.
+ let saved = Document::open(s.document().save().unwrap()).unwrap();
+ assert!(
+ saved
+ .parts()
+ .numbering
+ .level(num(2).parse().unwrap(), 0, &saved.parts().styles)
+ .is_some()
+ );
+}
+
+#[test]
+fn pasting_into_another_document_drops_what_belongs_to_the_first() {
+ let mut s = open_styled(&p("Here: "));
+ caret_at(&mut s, 0, 6);
+ let mut link_attrs = BTreeMap::new();
+ link_attrs.insert(
+ "wrap".to_owned(),
+ r#"[["<w:hyperlink r:id=\"rId9\">","</w:hyperlink>"]]"#.to_owned(),
+ );
+ let mut picture = BTreeMap::new();
+ picture.insert(
+ "obj".to_owned(),
+ r#"<w:drawing><a:blip r:embed="rId7"/></w:drawing>"#.to_owned(),
+ );
+ paste(
+ &mut s,
+ vec![ClipParagraph {
+ runs: vec![
+ ClipRun {
+ text: "link".to_owned(),
+ attrs: Some(link_attrs),
+ ..ClipRun::default()
+ },
+ ClipRun {
+ text: "\u{FFFC}".to_owned(),
+ attrs: Some(picture),
+ ..ClipRun::default()
+ },
+ ],
+ props: Some(
+ r#"<w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="12"/></w:numPr></w:pPr>"#
+ .to_owned(),
+ ),
+ ..ClipParagraph::default()
+ }],
+ false,
+ );
+ assert_eq!(texts(&s), vec!["Here: link"]);
+ let xml = s.document().document_xml();
+ assert!(!xml.contains("rId9"), "{xml}");
+ assert!(!xml.contains("rId7"), "{xml}");
+}
+
+#[test]
+fn pasting_while_tracking_records_an_insertion() {
+ let mut s = open_with(
+ &p("Fee: "),
+ &Parts {
+ settings: Some("<w:trackRevisions/>"),
+ ..Parts::default()
+ },
+ );
+ s.set_author("Ann");
+ caret_at(&mut s, 0, 5);
+ paste(
+ &mut s,
+ vec![ClipParagraph {
+ runs: vec![ClipRun {
+ text: "$100".to_owned(),
+ ..ClipRun::default()
+ }],
+ ..ClipParagraph::default()
+ }],
+ false,
+ );
+ let xml = s.document().document_xml();
+ assert!(
+ xml.contains("<w:ins ") && xml.contains("w:author=\"Ann\""),
+ "{xml}"
+ );
+ assert_eq!(texts(&s), vec!["Fee: $100"]);
+}
+
+#[test]
+fn pasted_native_markup_that_is_not_well_formed_is_left_out() {
+ let mut s = open_styled(&p("Target."));
+ caret_at(&mut s, 0, 0);
+ let attrs = |pairs: &[(&str, &str)]| {
+ Some(
+ pairs
+ .iter()
+ .map(|(k, v)| ((*k).to_owned(), (*v).to_owned()))
+ .collect::<BTreeMap<_, _>>(),
+ )
+ };
+ let runs = vec![
+ // Bold is kept; a run property that closes the run early is not.
+ ClipRun {
+ text: "kept ".into(),
+ attrs: attrs(&[
+ ("r:w:b", "<w:b/>"),
+ ("r:w:i", "</w:rPr></w:r><w:r><w:instrText>INCLUDETEXT"),
+ ("ra:w:rsidR\"/><w:x", "1"),
+ ("unknown", "<w:y/>"),
+ ]),
+ ..ClipRun::default()
+ },
+ // An object that is not one element drops the run.
+ ClipRun {
+ text: "\u{FFFC}".into(),
+ attrs: attrs(&[("obj", "<w:br/><w:br/>")]),
+ ..ClipRun::default()
+ },
+ // A wrapper that does not close itself is dropped.
+ ClipRun {
+ text: "wrapped".into(),
+ attrs: attrs(&[(
+ "wrap",
+ r#"[["<w:ins w:id=\"1\" w:author=\"x\">","</w:ins><w:p>"]]"#,
+ )]),
+ ..ClipRun::default()
+ },
+ ];
+ let paragraphs = vec![ClipParagraph {
+ runs,
+ props: Some("<w:pPr><w:jc w:val=\"center\"/>".into()),
+ ..ClipParagraph::default()
+ }];
+ paste(&mut s, paragraphs, false);
+ assert_eq!(texts(&s), vec!["kept wrappedTarget."]);
+ assert!(bold_at(&s, 0, 0));
+ let xml = s.document().document_xml();
+ assert!(!xml.contains("INCLUDETEXT"), "{xml}");
+ assert!(!xml.contains("w:x"), "{xml}");
+ assert!(!xml.contains("<w:y/>"), "{xml}");
+ assert!(!xml.contains("<w:ins"), "{xml}");
+ assert!(!xml.contains("<w:jc"), "{xml}");
+ // What is written parses.
+ crate::xml::XmlTree::parse(xml.as_bytes(), "document.xml").expect("well-formed");
+}
diff --git a/crates/docx_engine/src/edit/comments.rs b/crates/docx_engine/src/edit/comments.rs
new file mode 100644
index 0000000000..e1038ba5c4
--- /dev/null
+++ b/crates/docx_engine/src/edit/comments.rs
@@ -0,0 +1,220 @@
+//! Comments stored in the document (Word's comments part): their authors,
+//! text and threads, and the text each is on, for showing beside the pages.
+
+use super::Pos;
+use crate::document::{Document, rel_kind};
+use crate::xml::{NodeId, XmlTree};
+use serde::Serialize;
+use std::collections::HashMap;
+
+/// A comment from the document's comments part.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DocComment {
+ /// Its id (`w:id`).
+ pub id: String,
+ /// Who wrote it.
+ pub author: String,
+ /// Their initials.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub initials: Option<String>,
+ /// When (ISO 8601, as written).
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub date: Option<String>,
+ /// Its text, paragraphs separated by newlines.
+ pub text: String,
+ /// Where the commented text starts in the body.
+ pub from: Pos,
+ /// Where it ends.
+ pub to: Pos,
+ /// The comment it replies to.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub parent: Option<String>,
+ /// Marked done (resolved).
+ pub done: bool,
+}
+
+/// One comment as the comments part has it.
+struct Written {
+ id: String,
+ author: String,
+ initials: Option<String>,
+ date: Option<String>,
+ text: String,
+ /// `w14:paraId` of its last paragraph, which threads refer to.
+ para_id: Option<String>,
+}
+
+/// The value of an attribute by local name, whatever its prefix.
+fn attr_local<'a>(tree: &'a XmlTree, node: NodeId, local: &str) -> Option<&'a str> {
+ tree.attrs(node)
+ .iter()
+ .find(|a| &*a.local == local)
+ .map(|a| &*a.value)
+}
+
+/// The text of a comment paragraph (tabs and breaks included).
+fn paragraph_text(tree: &XmlTree, node: NodeId, out: &mut String) {
+ for c in tree.children(node) {
+ match tree.local(c) {
+ "t" => out.push_str(&tree.text(c)),
+ "tab" => out.push('\t'),
+ "br" | "cr" => out.push('\n'),
+ // Deleted text and field codes are not part of what it says.
+ "delText" | "instrText" => {}
+ _ => paragraph_text(tree, c, out),
+ }
+ }
+}
+
+/// A part related to the main part by a relationship of `kind`.
+fn related_part(doc: &Document, kind: &str) -> Option<XmlTree> {
+ let rels = doc.main_rels();
+ let rel = rels.iter().find(|r| rel_kind(&r.rel_type) == kind)?;
+ let name = rels.resolve(rel);
+ let bytes = doc.package().read(&name).ok()?;
+ XmlTree::parse(&bytes, &name).ok()
+}
+
+fn written(doc: &Document) -> Vec<Written> {
+ let Some(tree) = related_part(doc, "comments") else {
+ return Vec::new();
+ };
+ let mut out = Vec::new();
+ for c in tree.children(tree.root()) {
+ if !tree.is_w(c, "comment") {
+ continue;
+ }
+ let Some(id) = tree.w_attr(c, "id") else {
+ continue;
+ };
+ let mut paragraphs = Vec::new();
+ let mut para_id = None;
+ for p in tree.children(c).filter(|&p| tree.is_w(p, "p")) {
+ let mut text = String::new();
+ paragraph_text(&tree, p, &mut text);
+ paragraphs.push(text);
+ para_id = attr_local(&tree, p, "paraId").map(str::to_owned);
+ }
+ out.push(Written {
+ id: id.to_owned(),
+ author: tree.w_attr(c, "author").unwrap_or_default().to_owned(),
+ initials: tree.w_attr(c, "initials").map(str::to_owned),
+ date: tree.w_attr(c, "date").map(str::to_owned),
+ text: paragraphs.join("\n").trim().to_owned(),
+ para_id,
+ });
+ }
+ out
+}
+
+/// Thread links and done flags (`w15:commentEx`), by paragraph id: the
+/// parent's paragraph id and whether it is done.
+fn extended(doc: &Document) -> HashMap<String, (Option<String>, bool)> {
+ let Some(tree) = related_part(doc, "commentsExtended") else {
+ return HashMap::new();
+ };
+ tree.children(tree.root())
+ .filter(|&c| tree.local(c) == "commentEx")
+ .filter_map(|c| {
+ let para = attr_local(&tree, c, "paraId")?.to_owned();
+ let parent = attr_local(&tree, c, "paraIdParent").map(str::to_owned);
+ let done = attr_local(&tree, c, "done").is_some_and(|v| v == "1" || v == "true");
+ Some((para, (parent, done)))
+ })
+ .collect()
+}
+
+/// The comment id of comment markup (`commentRangeStart`,
+/// `commentRangeEnd`, `commentReference`), with which of the three it is.
+fn comment_mark(xml: &str) -> Option<(&'static str, String)> {
+ let kind = ["commentRangeStart", "commentRangeEnd", "commentReference"]
+ .into_iter()
+ .find(|k| xml.contains(k))?;
+ Some((kind, super::revise::attribute(xml, "id")?))
+}
+
+/// The document's comments in the order of their text, each with the range
+/// it is on; comments whose text is gone are left out.
+pub(crate) fn comments(doc: &Document) -> Vec<DocComment> {
+ let written = written(doc);
+ if written.is_empty() {
+ return Vec::new();
+ }
+ // Where each comment's markers are in the body.
+ let mut starts: HashMap<String, Pos> = HashMap::new();
+ let mut ends: HashMap<String, Pos> = HashMap::new();
+ let mut order: Vec<String> = Vec::new();
+ let body = doc.body();
+ for id in body.paragraphs() {
+ let Some(b) = body.get(&id) else {
+ continue;
+ };
+ for (at, span) in b.content.spans_at() {
+ let Some(xml) = span.attrs.marker().or(span.attrs.object()) else {
+ continue;
+ };
+ let Some((kind, cid)) = comment_mark(xml) else {
+ continue;
+ };
+ let len = span.text.encode_utf16().count();
+ match kind {
+ "commentRangeStart" => {
+ order.push(cid.clone());
+ starts.insert(cid, Pos::new(id.clone(), at + len));
+ }
+ "commentRangeEnd" => {
+ ends.insert(cid, Pos::new(id.clone(), at));
+ }
+ _ => {
+ if !starts.contains_key(&cid) {
+ order.push(cid.clone());
+ starts.insert(cid.clone(), Pos::new(id.clone(), at));
+ }
+ ends.entry(cid).or_insert_with(|| Pos::new(id.clone(), at));
+ }
+ }
+ }
+ }
+ let threads = extended(doc);
+ let by_para: HashMap<&str, &str> = written
+ .iter()
+ .filter_map(|w| Some((w.para_id.as_deref()?, w.id.as_str())))
+ .collect();
+ let mut by_id: HashMap<&str, &Written> = written.iter().map(|w| (w.id.as_str(), w)).collect();
+ let mut out = Vec::new();
+ for cid in &order {
+ let Some(w) = by_id.remove(cid.as_str()) else {
+ continue;
+ };
+ let Some(from) = starts.get(cid) else {
+ continue;
+ };
+ let to = ends.get(cid).unwrap_or(from).clone();
+ let (parent, done) = w.para_id.as_deref().and_then(|p| threads.get(p)).map_or(
+ (None, false),
+ |(parent, done)| {
+ let parent = parent
+ .as_deref()
+ .and_then(|p| by_para.get(p))
+ .map(|id| (*id).to_owned());
+ (parent, *done)
+ },
+ );
+ out.push(DocComment {
+ id: w.id.clone(),
+ author: w.author.clone(),
+ initials: w.initials.clone(),
+ date: w.date.clone(),
+ text: w.text.clone(),
+ from: from.clone(),
+ to,
+ parent,
+ done,
+ });
+ }
+ out
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/edit/comments/test.rs b/crates/docx_engine/src/edit/comments/test.rs
new file mode 100644
index 0000000000..c3a66ff519
--- /dev/null
+++ b/crates/docx_engine/src/edit/comments/test.rs
@@ -0,0 +1,54 @@
+use super::super::test_util::*;
+use super::super::*;
+use crate::test_support::Parts;
+
+const BODY: &str = r#"<w:p><w:r><w:t xml:space="preserve">The </w:t></w:r><w:commentRangeStart w:id="0"/><w:r><w:t>Purchase Price</w:t></w:r><w:commentRangeEnd w:id="0"/><w:r><w:commentReference w:id="0"/></w:r><w:r><w:t xml:space="preserve"> is due.</w:t></w:r></w:p><w:p><w:r><w:t>Closing</w:t></w:r><w:r><w:commentReference w:id="2"/></w:r></w:p>"#;
+
+const COMMENTS: &str = r#"<w:comment w:id="0" w:author="Opposing Counsel" w:date="2026-09-30T10:00:00Z" w:initials="OC"><w:p w14:paraId="1A2B3C4D"><w:r><w:t>Should this include</w:t></w:r><w:r><w:tab/><w:t>fees?</w:t></w:r></w:p></w:comment><w:comment w:id="1" w:author="Us" w:date="2026-10-01T09:00:00Z"><w:p w14:paraId="5E6F7A8B"><w:r><w:t>No.</w:t></w:r></w:p></w:comment><w:comment w:id="2" w:author="Us"><w:p w14:paraId="0C0C0C0C"><w:r><w:t>Date to be confirmed.</w:t></w:r></w:p></w:comment>"#;
+
+const THREADS: &str = r#"<w15:commentEx w15:paraId="1A2B3C4D" w15:done="1"/><w15:commentEx w15:paraId="5E6F7A8B" w15:paraIdParent="1A2B3C4D" w15:done="0"/>"#;
+
+#[test]
+fn word_comments_come_with_their_text_threads_and_ranges() {
+ // The reply has no range of its own here; it is left out of the body
+ // but still listed under its parent.
+ let body = BODY.replace(
+ r#"<w:r><w:commentReference w:id="0"/></w:r>"#,
+ r#"<w:r><w:commentReference w:id="0"/></w:r><w:r><w:commentReference w:id="1"/></w:r>"#,
+ );
+ let s = open_with(
+ &body,
+ &Parts {
+ comments: Some(COMMENTS),
+ comments_extended: Some(THREADS),
+ ..Parts::default()
+ },
+ );
+ let comments = s.document_comments();
+ let ids: Vec<&str> = comments.iter().map(|c| c.id.as_str()).collect();
+ assert_eq!(ids, vec!["0", "1", "2"]);
+ let first = &comments[0];
+ assert_eq!(first.author, "Opposing Counsel");
+ assert_eq!(first.initials.as_deref(), Some("OC"));
+ assert_eq!(first.text, "Should this include\tfees?");
+ assert!(first.done);
+ assert_eq!(first.parent, None);
+ // The range covers "Purchase Price" (after the start marker).
+ let p0 = para(&s, 0);
+ assert_eq!(first.from, Pos::new(p0.clone(), 5));
+ assert_eq!(first.to, Pos::new(p0, 19));
+ // The reply is threaded under the first comment.
+ assert_eq!(comments[1].parent.as_deref(), Some("0"));
+ assert!(!comments[1].done);
+ // A comment on a point (a reference without a range).
+ let p1 = para(&s, 1);
+ assert_eq!(comments[2].from, Pos::new(p1.clone(), 7));
+ assert_eq!(comments[2].to, Pos::new(p1, 7));
+ assert_eq!(comments[2].date, None);
+}
+
+#[test]
+fn documents_without_comments_have_none() {
+ let s = open(&p("Plain"));
+ assert!(s.document_comments().is_empty());
+}
diff --git a/crates/docx_engine/src/edit/find.rs b/crates/docx_engine/src/edit/find.rs
new file mode 100644
index 0000000000..46be52fa4d
--- /dev/null
+++ b/crates/docx_engine/src/edit/find.rs
@@ -0,0 +1,166 @@
+//! Searching the body's text, for the find bar and its replace commands.
+//!
+//! A search runs over each paragraph's visible text: field codes, deleted
+//! and hidden text are left out, and objects (pictures, field markers,
+//! breaks) are barriers no match crosses. Straight and typographic quotes
+//! match each other, as do ordinary and non-breaking spaces, so a search
+//! typed on a keyboard finds the text a word processor wrote.
+
+use super::revise;
+use super::{PageRect, Pos};
+use crate::model::block::{BlockId, Story};
+use crate::model::content::Attrs;
+use serde::{Deserialize, Serialize};
+
+/// How a search compares text.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct FindOptions {
+ /// Upper and lower case must match.
+ pub match_case: bool,
+ /// Matches must be whole words.
+ pub whole_word: bool,
+}
+
+/// One match: its ends and highlight rectangles.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct FindMatch {
+ /// The start.
+ pub from: Pos,
+ /// The end.
+ pub to: Pos,
+ /// Where it is on the pages.
+ pub rects: Vec<PageRect>,
+}
+
+/// The matches of a search, in document order.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct FindResult {
+ /// The matches.
+ pub matches: Vec<FindMatch>,
+ /// The match at the selection, or the first one after it.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub current: Option<usize>,
+ /// Whether the search stopped at [`LIMIT`] matches.
+ #[serde(skip_serializing_if = "std::ops::Not::not")]
+ pub truncated: bool,
+}
+
+/// The most matches a search returns.
+pub const LIMIT: usize = 10_000;
+
+/// Stands in for an object: never matches and is not part of a word.
+const BARRIER: char = '\u{FFFC}';
+
+/// A character as searches compare it.
+fn fold(c: char, match_case: bool) -> char {
+ let c = match c {
+ '\u{2018}' | '\u{2019}' | '\u{201A}' | '\u{201B}' | '\u{2032}' => '\'',
+ '\u{201C}' | '\u{201D}' | '\u{201E}' | '\u{201F}' | '\u{2033}' => '"',
+ '\u{00A0}' | '\u{2007}' | '\u{202F}' => ' ',
+ c => c,
+ };
+ if match_case {
+ return c;
+ }
+ let mut lower = c.to_lowercase();
+ match (lower.next(), lower.next()) {
+ (Some(l), None) => l,
+ _ => c,
+ }
+}
+
+fn is_word(c: char) -> bool {
+ c.is_alphanumeric() || c == '_'
+}
+
+/// Text left out of searches: hidden runs and deleted text.
+fn skipped(attrs: &Attrs) -> bool {
+ if attrs.is_instr() {
+ return true;
+ }
+ let hidden = attrs
+ .run_props()
+ .any(|(q, v)| q.ends_with("vanish") && !v.contains("\"0\"") && !v.contains("\"false\""));
+ hidden || attrs.wrappers().iter().any(revise::is_deleted)
+}
+
+/// A paragraph's searchable characters with the UTF-16 range each covers.
+struct Searchable {
+ chars: Vec<char>,
+ starts: Vec<usize>,
+ ends: Vec<usize>,
+}
+
+fn searchable(story: &Story, id: &BlockId, match_case: bool) -> Option<Searchable> {
+ let block = story.get(id)?;
+ let mut out = Searchable {
+ chars: Vec::new(),
+ starts: Vec::new(),
+ ends: Vec::new(),
+ };
+ for (at, span) in block.content.spans_at() {
+ let object = span.attrs.is_object();
+ if !object && skipped(&span.attrs) {
+ continue;
+ }
+ let mut offset = at;
+ for c in span.text.chars() {
+ let len = c.len_utf16();
+ out.chars
+ .push(if object { BARRIER } else { fold(c, match_case) });
+ out.starts.push(offset);
+ out.ends.push(offset + len);
+ offset += len;
+ }
+ }
+ Some(out)
+}
+
+/// The matches of `query` in the paragraphs, in order, up to `limit`
+/// (the second value says whether the limit cut the search short).
+pub(crate) fn find(
+ story: &Story,
+ paragraphs: &[BlockId],
+ query: &str,
+ options: &FindOptions,
+ limit: usize,
+) -> (Vec<(Pos, Pos)>, bool) {
+ let query: Vec<char> = query.chars().map(|c| fold(c, options.match_case)).collect();
+ let mut out = Vec::new();
+ if query.is_empty() {
+ return (out, false);
+ }
+ let first = query[0];
+ for id in paragraphs {
+ let Some(text) = searchable(story, id, options.match_case) else {
+ continue;
+ };
+ let chars = &text.chars;
+ let mut i = 0;
+ while i + query.len() <= chars.len() {
+ let end = i + query.len();
+ let found = chars[i] == first
+ && chars[i..end] == query[..]
+ && (!options.whole_word
+ || (i.checked_sub(1).is_none_or(|b| !is_word(chars[b]))
+ && chars.get(end).is_none_or(|&c| !is_word(c))));
+ if !found {
+ i += 1;
+ continue;
+ }
+ if out.len() == limit {
+ return (out, true);
+ }
+ out.push((
+ Pos::new(id.clone(), text.starts[i]),
+ Pos::new(id.clone(), text.ends[end - 1]),
+ ));
+ i = end;
+ }
+ }
+ (out, false)
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/edit/find/test.rs b/crates/docx_engine/src/edit/find/test.rs
new file mode 100644
index 0000000000..973d71ddaa
--- /dev/null
+++ b/crates/docx_engine/src/edit/find/test.rs
@@ -0,0 +1,204 @@
+use super::super::test_util::*;
+use super::super::*;
+use crate::test_support::{Parts, fonts};
+
+fn find(s: &mut Session, query: &str, options: FindOptions) -> Vec<(usize, usize, usize)> {
+ let paras = s.document().body().paragraphs();
+ s.find(query, &options, fonts())
+ .matches
+ .iter()
+ .map(|m| {
+ let i = paras.iter().position(|id| *id == m.from.block).unwrap();
+ assert_eq!(m.from.block, m.to.block);
+ (i, m.from.offset, m.to.offset)
+ })
+ .collect()
+}
+
+fn plain(s: &mut Session, query: &str) -> Vec<(usize, usize, usize)> {
+ find(s, query, FindOptions::default())
+}
+
+fn replace(s: &mut Session, query: &str, with: &str, all: bool) -> EditResult {
+ run(
+ s,
+ EditOp::Replace {
+ query: query.to_owned(),
+ options: FindOptions::default(),
+ with: with.to_owned(),
+ all,
+ },
+ )
+}
+
+#[test]
+fn finds_text_across_runs_ignoring_case_unless_asked() {
+ let body = format!(
+ r#"{}<w:p><w:r><w:t xml:space="preserve">The Com</w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t>pany shall pay the company.</w:t></w:r></w:p>"#,
+ p("Company overview")
+ );
+ let mut s = open(&body);
+ assert_eq!(
+ plain(&mut s, "company"),
+ vec![(0, 0, 7), (1, 4, 11), (1, 26, 33)]
+ );
+ let exact = FindOptions {
+ match_case: true,
+ ..FindOptions::default()
+ };
+ assert_eq!(find(&mut s, "company", exact), vec![(1, 26, 33)]);
+ // Every match has highlight rectangles on the first page.
+ let r = s.find("company", &FindOptions::default(), fonts());
+ assert!(
+ r.matches
+ .iter()
+ .all(|m| !m.rects.is_empty() && m.rects.iter().all(|r| r.page == 0))
+ );
+ assert!(plain(&mut s, "").is_empty());
+ assert!(plain(&mut s, "absent").is_empty());
+}
+
+#[test]
+fn whole_words_and_typographic_quotes() {
+ let mut s = open(&format!(
+ "{}{}",
+ p("Art, artist and art."),
+ p("The Company\u{2019}s \u{201C}Shares\u{201D}\u{00A0}today")
+ ));
+ assert_eq!(plain(&mut s, "art").len(), 3);
+ let whole = FindOptions {
+ whole_word: true,
+ ..FindOptions::default()
+ };
+ assert_eq!(find(&mut s, "art", whole), vec![(0, 0, 3), (0, 16, 19)]);
+ assert_eq!(plain(&mut s, "Company's"), vec![(1, 4, 13)]);
+ assert_eq!(plain(&mut s, "\"Shares\" today"), vec![(1, 14, 28)]);
+}
+
+#[test]
+fn skips_deleted_text_and_field_codes_and_stops_at_objects() {
+ let body = concat!(
+ r#"<w:p><w:r><w:t xml:space="preserve">shall </w:t></w:r><w:del w:id="1" w:author="A" w:date="2026-01-01T00:00:00Z"><w:r><w:delText xml:space="preserve">not </w:delText></w:r></w:del><w:r><w:t>pay</w:t></w:r></w:p>"#,
+ r#"<w:p><w:r><w:t xml:space="preserve">Page </w:t></w:r><w:r><w:fldChar w:fldCharType="begin"/></w:r><w:r><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r><w:r><w:fldChar w:fldCharType="separate"/></w:r><w:r><w:t>1</w:t></w:r><w:r><w:fldChar w:fldCharType="end"/></w:r></w:p>"#,
+ r#"<w:p><w:r><w:t>ab</w:t></w:r><w:r><w:br w:type="page"/></w:r><w:r><w:t>cd</w:t></w:r></w:p>"#,
+ );
+ let mut s = open(body);
+ // The text reads "shall pay" once the deletion is accepted.
+ assert_eq!(plain(&mut s, "shall pay"), vec![(0, 0, 13)]);
+ assert!(plain(&mut s, "not").is_empty());
+ let exact = FindOptions {
+ match_case: true,
+ ..FindOptions::default()
+ };
+ assert!(find(&mut s, "PAGE", exact).is_empty());
+ assert_eq!(plain(&mut s, "1").len(), 1);
+ // A page break is an object: no match runs across it.
+ assert!(plain(&mut s, "bc").is_empty());
+ assert_eq!(plain(&mut s, "cd").len(), 1);
+}
+
+#[test]
+fn current_match_follows_the_selection() {
+ let mut s = open(&format!("{}{}", p("one two one"), p("one")));
+ caret_at(&mut s, 0, 5);
+ let r = s.find("one", &FindOptions::default(), fonts());
+ assert_eq!(r.matches.len(), 3);
+ assert_eq!(r.current, Some(1));
+ // A selection holding a match makes it current.
+ select(&mut s, (1, 0), (1, 3));
+ assert_eq!(
+ s.find("one", &FindOptions::default(), fonts()).current,
+ Some(2)
+ );
+ // Past the last match, the search wraps to the first.
+ caret_at(&mut s, 1, 3);
+ assert_eq!(
+ s.find("one", &FindOptions::default(), fonts()).current,
+ Some(0)
+ );
+}
+
+#[test]
+fn the_search_stops_at_its_limit() {
+ let s = open(&p("aaaa"));
+ let paras = s.document().body().paragraphs();
+ let (found, truncated) =
+ super::find(s.document().body(), &paras, "a", &FindOptions::default(), 3);
+ assert_eq!(found.len(), 3);
+ assert!(truncated);
+}
+
+#[test]
+fn replace_takes_the_selected_match_and_moves_to_the_next() {
+ let body = format!(
+ r#"<w:p><w:r><w:t xml:space="preserve">Pay the </w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t>Seller</w:t></w:r><w:r><w:t xml:space="preserve"> now.</w:t></w:r></w:p>{}"#,
+ p("The Seller agrees.")
+ );
+ let mut s = open(&body);
+ caret_at(&mut s, 0, 0);
+ // The selection holds no match yet: the first click selects one.
+ let r = replace(&mut s, "seller", "Buyer", false);
+ assert!(!r.changed);
+ assert_eq!(texts(&s), vec!["Pay the Seller now.", "The Seller agrees."]);
+ let sel = s.selection().clone();
+ assert_eq!((sel.anchor.offset, sel.focus.offset), (8, 14));
+ // Now it replaces, in the replaced text's formatting, and selects the
+ // next match.
+ let r = replace(&mut s, "seller", "Buyer", false);
+ assert!(r.changed);
+ assert_eq!(texts(&s), vec!["Pay the Buyer now.", "The Seller agrees."]);
+ let content = &s.document().body().get(&para(&s, 0)).unwrap().content;
+ assert!(content.attrs_at(9).unwrap().has("r:w:b"));
+ assert!(!content.attrs_at(14).unwrap().has("r:w:b"));
+ let sel = s.selection().clone();
+ assert_eq!(sel.anchor.block, para(&s, 1));
+ assert_eq!((sel.anchor.offset, sel.focus.offset), (4, 10));
+ replace(&mut s, "seller", "Buyer", false);
+ assert_eq!(texts(&s), vec!["Pay the Buyer now.", "The Buyer agrees."]);
+ // No match left: the caret stays after the replacement.
+ let sel = s.selection().clone();
+ assert!(sel.is_collapsed());
+ assert_eq!(sel.focus.offset, 9);
+}
+
+#[test]
+fn replace_all_is_one_step_and_keeps_the_caret_on_its_text() {
+ let mut s = open(&format!("{}{}", p("a cat, a cat"), p("cat")));
+ caret_at(&mut s, 0, 10);
+ let r = replace(&mut s, "cat", "tiger", true);
+ assert!(r.changed);
+ assert_eq!(texts(&s), vec!["a tiger, a tiger", "tiger"]);
+ // The caret was inside the second match: it goes to its start.
+ let sel = s.selection().clone();
+ assert_eq!(
+ (sel.focus.block.clone(), sel.focus.offset),
+ (para(&s, 0), 11)
+ );
+ s.undo(fonts()).unwrap();
+ assert_eq!(texts(&s), vec!["a cat, a cat", "cat"]);
+ // An empty replacement deletes.
+ caret_at(&mut s, 0, 12);
+ replace(&mut s, "cat", "", true);
+ assert_eq!(texts(&s), vec!["a , a ", ""]);
+ assert_eq!(s.selection().focus.offset, 6);
+}
+
+#[test]
+fn replacing_while_tracking_records_the_change() {
+ let mut s = open_with(
+ &p("the Seller"),
+ &Parts {
+ settings: Some("<w:trackRevisions/>"),
+ ..Parts::default()
+ },
+ );
+ s.set_author("Alice");
+ replace(&mut s, "Seller", "Buyer", true);
+ let xml = s.document().document_xml();
+ assert!(xml.contains("<w:delText>Seller</w:delText>"), "{xml}");
+ assert!(xml.contains("<w:t>Buyer</w:t>"), "{xml}");
+ assert!(xml.contains("w:author=\"Alice\""), "{xml}");
+ // The deleted text is no longer found; the inserted text is.
+ assert!(plain(&mut s, "Seller").is_empty());
+ assert_eq!(plain(&mut s, "Buyer").len(), 1);
+}
diff --git a/crates/docx_engine/src/edit/format.rs b/crates/docx_engine/src/edit/format.rs
new file mode 100644
index 0000000000..1c9170000a
--- /dev/null
+++ b/crates/docx_engine/src/edit/format.rs
@@ -0,0 +1,408 @@
+//! Character and paragraph formatting.
+
+use super::revise::Revisor;
+use super::txn::Txn;
+use super::xmledit::{Element, PPR_ORDER};
+use crate::layout::format::{Formats, ParaFormat};
+use crate::model::block::BlockId;
+use crate::model::content::{Attrs, key};
+use crate::model::props::{RunProps, VertAlign};
+use crate::xml::escape_attr;
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+/// A character format that is either on or off.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum Toggle {
+ /// Bold.
+ Bold,
+ /// Italic.
+ Italic,
+ /// Single underline.
+ Underline,
+ /// Strikethrough.
+ Strike,
+ /// Superscript.
+ Superscript,
+ /// Subscript.
+ Subscript,
+ /// Small capitals.
+ SmallCaps,
+ /// All capitals.
+ AllCaps,
+}
+
+impl Toggle {
+ /// Whether resolved properties have the format.
+ pub fn is_on(self, p: &RunProps) -> bool {
+ match self {
+ Toggle::Bold => p.bold,
+ Toggle::Italic => p.italic,
+ Toggle::Underline => p.underline.is_some(),
+ Toggle::Strike => p.strike,
+ Toggle::Superscript => p.vert_align == VertAlign::Super,
+ Toggle::Subscript => p.vert_align == VertAlign::Sub,
+ Toggle::SmallCaps => p.small_caps,
+ Toggle::AllCaps => p.caps,
+ }
+ }
+
+ /// The run property elements the format is written with.
+ fn locals(self) -> &'static [&'static str] {
+ match self {
+ Toggle::Bold => &["b", "bCs"],
+ Toggle::Italic => &["i", "iCs"],
+ Toggle::Underline => &["u"],
+ Toggle::Strike => &["strike"],
+ Toggle::Superscript | Toggle::Subscript => &["vertAlign"],
+ Toggle::SmallCaps => &["smallCaps"],
+ Toggle::AllCaps => &["caps"],
+ }
+ }
+}
+
+fn q(w: &str, local: &str) -> String {
+ if w.is_empty() {
+ local.to_owned()
+ } else {
+ format!("{w}:{local}")
+ }
+}
+
+/// The attribute key of run property `w:{local}`.
+pub(super) fn run_key(w: &str, local: &str) -> String {
+ format!("{}{}", key::RUN_PROP, q(w, local))
+}
+
+fn val_elem(w: &str, local: &str, val: &str) -> String {
+ let mut s = format!("<{} {}=\"", q(w, local), q(w, "val"));
+ escape_attr(&mut s, val);
+ s.push_str("\"/>");
+ s
+}
+
+/// The attributes with a toggle set on or off, given what the text would
+/// have without direct formatting of it (`inherited`).
+pub(super) fn toggled(attrs: &Attrs, t: Toggle, on: bool, inherited: bool, w: &str) -> Attrs {
+ let mut out = attrs.clone();
+ for local in t.locals() {
+ let k = run_key(w, local);
+ let value = match (t, on, inherited) {
+ // Matching what the styles give: no direct formatting needed.
+ (_, true, true) | (_, false, false) => None,
+ (Toggle::Underline, true, false) => Some(val_elem(w, local, "single")),
+ (Toggle::Underline, false, true) => Some(val_elem(w, local, "none")),
+ (Toggle::Superscript, true, false) => Some(val_elem(w, local, "superscript")),
+ (Toggle::Subscript, true, false) => Some(val_elem(w, local, "subscript")),
+ (Toggle::Superscript | Toggle::Subscript, false, true) => {
+ Some(val_elem(w, local, "baseline"))
+ }
+ (_, true, false) => Some(format!("<{}/>", q(w, local))),
+ (_, false, true) => Some(val_elem(w, local, "0")),
+ };
+ out = out.with(&k, value.as_deref());
+ }
+ out
+}
+
+/// A change to character formatting: each field present sets (a value)
+/// or clears (`null`) one property.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RunPatch {
+ /// Font family.
+ #[serde(default, deserialize_with = "present")]
+ pub font: Option<Option<String>>,
+ /// Size in points.
+ #[serde(default, deserialize_with = "present")]
+ pub size: Option<Option<f32>>,
+ /// Text color as `RRGGBB`.
+ #[serde(default, deserialize_with = "present")]
+ pub color: Option<Option<String>>,
+ /// Highlight color name (`yellow`, `green`...).
+ #[serde(default, deserialize_with = "present")]
+ pub highlight: Option<Option<String>>,
+}
+
+/// Deserializes a present field (even `null`) as `Some`.
+fn present<'de, D, T>(d: D) -> Result<Option<T>, D::Error>
+where
+ D: serde::Deserializer<'de>,
+ T: Deserialize<'de>,
+{
+ T::deserialize(d).map(Some)
+}
+
+/// Highlight colors Word accepts.
+const HIGHLIGHTS: &[&str] = &[
+ "black",
+ "blue",
+ "cyan",
+ "green",
+ "magenta",
+ "red",
+ "yellow",
+ "white",
+ "darkBlue",
+ "darkCyan",
+ "darkGreen",
+ "darkMagenta",
+ "darkRed",
+ "darkYellow",
+ "darkGray",
+ "lightGray",
+];
+
+fn hex_color(v: &str) -> Option<String> {
+ let v = v.trim().trim_start_matches('#');
+ (v.len() == 6 && v.chars().all(|c| c.is_ascii_hexdigit())).then(|| v.to_uppercase())
+}
+
+impl RunPatch {
+ /// Applies the patch to a span's attributes.
+ pub fn apply(&self, attrs: &Attrs, w: &str) -> Attrs {
+ let mut out = attrs.clone();
+ if let Some(font) = &self.font {
+ let value = font.as_ref().filter(|f| !f.trim().is_empty()).map(|f| {
+ let mut s = format!("<{}", q(w, "rFonts"));
+ for slot in ["ascii", "hAnsi", "eastAsia", "cs"] {
+ s.push(' ');
+ s.push_str(&q(w, slot));
+ s.push_str("=\"");
+ escape_attr(&mut s, f.trim());
+ s.push('"');
+ }
+ s.push_str("/>");
+ s
+ });
+ out = out.with(&run_key(w, "rFonts"), value.as_deref());
+ }
+ if let Some(size) = self.size {
+ let half = size
+ .filter(|s| s.is_finite() && *s > 0.0)
+ .map(|s| ((s * 2.0).round() as i64).clamp(2, 3276).to_string());
+ for local in ["sz", "szCs"] {
+ let v = half.as_deref().map(|h| val_elem(w, local, h));
+ out = out.with(&run_key(w, local), v.as_deref());
+ }
+ }
+ if let Some(color) = &self.color {
+ let v = color
+ .as_deref()
+ .and_then(hex_color)
+ .map(|c| val_elem(w, "color", &c));
+ out = out.with(&run_key(w, "color"), v.as_deref());
+ }
+ if let Some(h) = &self.highlight {
+ let v = h
+ .as_deref()
+ .and_then(|h| HIGHLIGHTS.iter().find(|n| n.eq_ignore_ascii_case(h)))
+ .map(|n| val_elem(w, "highlight", n));
+ out = out.with(&run_key(w, "highlight"), v.as_deref());
+ }
+ out
+ }
+}
+
+/// Removes direct character formatting (keeping the character style off
+/// too, as Word's Clear Formatting does), wrappers and objects stay.
+pub(super) fn cleared(attrs: &Attrs) -> Attrs {
+ attrs.without(|k| {
+ k.starts_with(key::RUN_PROP) && {
+ let local = k.rsplit(':').next().unwrap_or(k);
+ !matches!(local, "ins" | "del" | "moveFrom" | "moveTo" | "rPrChange")
+ }
+ })
+}
+
+/// Paragraph alignment as the API names it.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum Alignment {
+ /// Left (start).
+ Left,
+ /// Centered.
+ Center,
+ /// Right (end).
+ Right,
+ /// Justified.
+ Justify,
+}
+
+/// Line spacing as the API names it.
+#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "rule", rename_all = "camelCase")]
+pub enum Spacing {
+ /// A multiple of single spacing.
+ Auto {
+ /// Multiple (1 = single).
+ value: f32,
+ },
+ /// Exactly this many points.
+ Exact {
+ /// Points.
+ value: f32,
+ },
+ /// At least this many points.
+ AtLeast {
+ /// Points.
+ value: f32,
+ },
+}
+
+/// A change to paragraph formatting; absent fields stay as they are.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ParaPatch {
+ /// Alignment.
+ #[serde(default)]
+ pub align: Option<Alignment>,
+ /// Left indent (points).
+ #[serde(default)]
+ pub indent_left: Option<f32>,
+ /// Right indent (points).
+ #[serde(default)]
+ pub indent_right: Option<f32>,
+ /// First line indent (points; negative = hanging).
+ #[serde(default)]
+ pub first_line: Option<f32>,
+ /// Space before (points).
+ #[serde(default)]
+ pub space_before: Option<f32>,
+ /// Space after (points).
+ #[serde(default)]
+ pub space_after: Option<f32>,
+ /// Line spacing.
+ #[serde(default)]
+ pub line_spacing: Option<Spacing>,
+ /// Keep with next.
+ #[serde(default)]
+ pub keep_next: Option<bool>,
+ /// Keep lines together.
+ #[serde(default)]
+ pub keep_lines: Option<bool>,
+ /// Page break before.
+ #[serde(default)]
+ pub page_break_before: Option<bool>,
+ /// Widow and orphan control.
+ #[serde(default)]
+ pub widow_control: Option<bool>,
+}
+
+fn twips(points: f32) -> String {
+ ((points * 20.0).round() as i64).to_string()
+}
+
+impl ParaPatch {
+ /// Applies the patch to `w:pPr` markup.
+ pub(crate) fn apply(&self, e: &mut Element, decls: &[crate::xml::Decl]) {
+ if let Some(a) = self.align {
+ let v = match a {
+ Alignment::Left => None,
+ Alignment::Center => Some("center"),
+ Alignment::Right => Some("right"),
+ Alignment::Justify => Some("both"),
+ };
+ // Left is the default, but a style may say otherwise.
+ e.set_val("jc", Some(v.unwrap_or("left")));
+ }
+ let mut ind: Vec<(&str, Option<String>)> = Vec::new();
+ if let Some(v) = self.indent_left {
+ ind.push(("left", Some(twips(v))));
+ ind.push(("start", None));
+ }
+ if let Some(v) = self.indent_right {
+ ind.push(("right", Some(twips(v))));
+ ind.push(("end", None));
+ }
+ if let Some(v) = self.first_line {
+ if v < 0.0 {
+ ind.push(("hanging", Some(twips(-v))));
+ ind.push(("firstLine", None));
+ } else {
+ ind.push(("firstLine", Some(twips(v))));
+ ind.push(("hanging", None));
+ }
+ }
+ if !ind.is_empty() {
+ e.set_attrs("ind", &ind, decls);
+ }
+ let mut sp: Vec<(&str, Option<String>)> = Vec::new();
+ if let Some(v) = self.space_before {
+ sp.push(("before", Some(twips(v.max(0.0)))));
+ sp.push(("beforeAutospacing", None));
+ sp.push(("beforeLines", None));
+ }
+ if let Some(v) = self.space_after {
+ sp.push(("after", Some(twips(v.max(0.0)))));
+ sp.push(("afterAutospacing", None));
+ sp.push(("afterLines", None));
+ }
+ if let Some(l) = self.line_spacing {
+ let (line, rule) = match l {
+ Spacing::Auto { value } => (
+ ((value.max(0.06) * 240.0).round() as i64).to_string(),
+ "auto",
+ ),
+ Spacing::Exact { value } => (twips(value.max(1.0)), "exact"),
+ Spacing::AtLeast { value } => (twips(value.max(0.0)), "atLeast"),
+ };
+ sp.push(("line", Some(line)));
+ sp.push(("lineRule", Some(rule.to_owned())));
+ }
+ if !sp.is_empty() {
+ e.set_attrs("spacing", &sp, decls);
+ }
+ for (local, v) in [
+ ("keepNext", self.keep_next),
+ ("keepLines", self.keep_lines),
+ ("pageBreakBefore", self.page_break_before),
+ ("widowControl", self.widow_control),
+ ] {
+ if let Some(on) = v {
+ e.set_flag(local, Some(on));
+ }
+ }
+ }
+}
+
+/// Applies a function to the `w:pPr` of a paragraph, recording the
+/// properties from before when tracking changes (`rev`).
+pub(super) fn edit_ppr(
+ txn: &mut Txn<'_>,
+ id: &BlockId,
+ rev: Option<&Revisor>,
+ f: impl FnOnce(&mut Element),
+) {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = Arc::clone(txn.doc.decls());
+ let Some(b) = txn.get(id) else {
+ return;
+ };
+ let mut e = Element::open(&b.props, "pPr", &w, &decls, PPR_ORDER);
+ let before = rev.map(|_| e.clone());
+ f(&mut e);
+ if let (Some(r), Some(before)) = (rev, &before) {
+ r.para_change(before, &mut e, &decls);
+ }
+ let xml = e.finish(true);
+ if xml != b.props
+ && let Some(b) = txn.block_mut(id)
+ {
+ b.props = xml;
+ }
+}
+
+/// Whether a toggle would be on for `attrs` without its own direct keys.
+pub(super) fn inherited(
+ formats: &Formats<'_>,
+ attrs: &Attrs,
+ para: &Arc<ParaFormat>,
+ t: Toggle,
+ w: &str,
+) -> bool {
+ let keys: Vec<String> = t.locals().iter().map(|l| run_key(w, l)).collect();
+ let bare = attrs.without(|k| keys.iter().any(|x| x == k));
+ t.is_on(&formats.run(&bare, para))
+}
diff --git a/crates/docx_engine/src/edit/geometry.rs b/crates/docx_engine/src/edit/geometry.rs
new file mode 100644
index 0000000000..18105cd5ff
--- /dev/null
+++ b/crates/docx_engine/src/edit/geometry.rs
@@ -0,0 +1,566 @@
+//! Where positions are on the pages: carets, selection highlights, hit
+//! testing and caret movement by line.
+
+use super::{Pos, Selection};
+use crate::layout::inline::Kind;
+use crate::layout::{Item, Layout, ParaBox, PlacedLine, StoryRef};
+use crate::model::block::BlockId;
+use serde::Serialize;
+
+/// A caret: a vertical bar on a page (points).
+#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
+pub struct CaretRect {
+ /// Page index.
+ pub page: usize,
+ /// Left edge.
+ pub x: f32,
+ /// Top.
+ pub y: f32,
+ /// Height.
+ pub height: f32,
+}
+
+/// A rectangle on a page (points).
+#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
+pub struct PageRect {
+ /// Page index.
+ pub page: usize,
+ /// Left.
+ pub x: f32,
+ /// Top.
+ pub y: f32,
+ /// Width.
+ pub w: f32,
+ /// Height.
+ pub h: f32,
+}
+
+/// One story's placed lines, for finding positions on pages.
+#[derive(Debug, Default)]
+pub struct ViewIndex {
+ /// Placed lines of each paragraph in order: (page, item index).
+ pub lines: crate::hash::FxMap<BlockId, Vec<(usize, usize)>>,
+ /// The story's lines on each page: item indices.
+ pub page_lines: Vec<Vec<usize>>,
+}
+
+impl ViewIndex {
+ /// Indexes the body's lines.
+ pub fn build(layout: &Layout) -> Self {
+ Self::for_story(layout, &StoryRef::Body, None)
+ }
+
+ /// Indexes one story's lines, all of them or (for a header or footer,
+ /// which every page repeats) those on one page.
+ pub fn for_story(layout: &Layout, story: &StoryRef, only_page: Option<usize>) -> Self {
+ let mut index = ViewIndex::default();
+ for (p, page) in layout.pages.iter().enumerate() {
+ let mut on_page = Vec::new();
+ if only_page.is_some_and(|only| only != p) {
+ index.page_lines.push(on_page);
+ continue;
+ }
+ for (i, item) in page.items.iter().enumerate() {
+ if let Item::Line(l) = item
+ && l.para.story == *story
+ {
+ index
+ .lines
+ .entry(l.para.block.clone())
+ .or_default()
+ .push((p, i));
+ on_page.push(i);
+ }
+ }
+ index.page_lines.push(on_page);
+ }
+ index
+ }
+}
+
+/// A place the caret can rest on a line.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub(crate) struct Stop {
+ /// Content offset.
+ pub offset: usize,
+ /// X from the paragraph's text area left edge.
+ pub x: f32,
+ /// Cluster whose metrics size the caret.
+ pub cluster: usize,
+}
+
+/// Whether a cluster reads right to left.
+fn rtl(pb: &ParaBox, ci: usize) -> bool {
+ pb.inline.levels.get(ci).is_some_and(|l| l % 2 == 1)
+}
+
+/// The x of the caret before a cluster: its left edge, or its right edge
+/// in right-to-left text.
+fn leading_x(pb: &ParaBox, ci: usize) -> f32 {
+ let x = pb.lines.x[ci];
+ if rtl(pb, ci) { x + pb.lines.adv[ci] } else { x }
+}
+
+/// The x of the caret after a cluster.
+fn trailing_x(pb: &ParaBox, ci: usize) -> f32 {
+ let x = pb.lines.x[ci];
+ if rtl(pb, ci) { x } else { x + pb.lines.adv[ci] }
+}
+
+/// Caret stops of line `li` of a paragraph, in text order (left to right
+/// unless the line holds right-to-left text).
+pub(crate) fn line_stops(pb: &ParaBox, li: usize) -> Vec<Stop> {
+ let lines = &pb.lines;
+ let Some(line) = lines.lines.get(li) else {
+ return Vec::new();
+ };
+ let clusters = &pb.inline.clusters;
+ let mut stops: Vec<Stop> = Vec::new();
+ let mut last_visible: Option<usize> = None;
+ for (ci, c) in clusters.iter().enumerate().take(line.end).skip(line.start) {
+ if ci < pb.inline.label_len || c.len == 0 && c.kind != Kind::End {
+ continue;
+ }
+ if c.kind == Kind::Zero {
+ continue;
+ }
+ if c.kind == Kind::End {
+ stops.push(Stop {
+ offset: c.offset as usize,
+ x: leading_x(pb, ci),
+ cluster: ci,
+ });
+ last_visible = None;
+ break;
+ }
+ stops.push(Stop {
+ offset: c.offset as usize,
+ x: leading_x(pb, ci),
+ cluster: ci,
+ });
+ last_visible = Some(ci);
+ }
+ // A wrapped line ends after its last character (the next line's start).
+ if let Some(ci) = last_visible {
+ let c = &clusters[ci];
+ stops.push(Stop {
+ offset: c.offset as usize + c.len as usize,
+ x: trailing_x(pb, ci),
+ cluster: ci,
+ });
+ }
+ if stops.is_empty() {
+ // Only hidden content: rest at the line's start.
+ let ci = (line.start..line.end)
+ .find(|&ci| clusters[ci].len > 0 || clusters[ci].kind == Kind::End)
+ .unwrap_or(line.start.min(clusters.len().saturating_sub(1)));
+ if let Some(c) = clusters.get(ci) {
+ stops.push(Stop {
+ offset: c.offset as usize,
+ x: line.left,
+ cluster: ci,
+ });
+ }
+ }
+ stops
+}
+
+/// Whether `li` is the paragraph's last line.
+fn is_last_line(pb: &ParaBox, li: usize) -> bool {
+ li + 1 >= pb.lines.lines.len()
+}
+
+/// The placed line at (page, item).
+pub(crate) fn placed(layout: &Layout, at: (usize, usize)) -> Option<&PlacedLine> {
+ match layout.pages.get(at.0)?.items.get(at.1)? {
+ Item::Line(l) => Some(l),
+ _ => None,
+ }
+}
+
+/// Finds the placed line and stop showing `pos`.
+pub(crate) fn locate<'a>(
+ layout: &'a Layout,
+ index: &ViewIndex,
+ pos: &Pos,
+) -> Option<(usize, &'a PlacedLine, Stop)> {
+ let entries = index.lines.get(&pos.block)?;
+ let mut best: Option<(usize, &PlacedLine, Stop)> = None;
+ for (k, &(page, item)) in entries.iter().enumerate() {
+ let Some(pl) = placed(layout, (page, item)) else {
+ continue;
+ };
+ let stops = line_stops(&pl.para, pl.line);
+ let (Some(first), Some(last)) = (stops.first(), stops.last()) else {
+ continue;
+ };
+ let last_line = k + 1 == entries.len();
+ if pos.offset < first.offset {
+ // In hidden content before the line: show at its start.
+ return Some((page, pl, *first));
+ }
+ if pos.offset >= first.offset && pos.offset <= last.offset {
+ let at_wrap =
+ pos.offset == last.offset && !last_line && !is_last_line(&pl.para, pl.line);
+ if at_wrap && !pos.upstream {
+ // Shown at the start of the next line.
+ best = Some((page, pl, *last));
+ continue;
+ }
+ let stop = stops
+ .iter()
+ .find(|s| s.offset >= pos.offset)
+ .copied()
+ .unwrap_or(*last);
+ return Some((page, pl, stop));
+ }
+ best = Some((page, pl, *last));
+ }
+ best
+}
+
+/// The caret for a position.
+pub fn caret(layout: &Layout, index: &ViewIndex, pos: &Pos) -> Option<CaretRect> {
+ let (page, pl, stop) = locate(layout, index, pos)?;
+ let line = pl.line();
+ let pb = &pl.para;
+ let run = pb
+ .inline
+ .clusters
+ .get(stop.cluster)
+ .and_then(|c| pb.inline.runs.get(c.run as usize));
+ let (ascent, descent) = run.map_or((line.baseline, line.height - line.baseline), |r| {
+ (r.ascent.max(1.0), r.descent.max(0.5))
+ });
+ let baseline = pl.y + line.baseline;
+ let top = (baseline - ascent).max(pl.y);
+ let bottom = (baseline + descent).min(pl.y + line.height.max(ascent + descent));
+ Some(CaretRect {
+ page,
+ x: pl.x + stop.x,
+ y: top,
+ height: (bottom - top).max(4.0),
+ })
+}
+
+/// Distance from (x, y) to a placed line's box, weighting vertical misses
+/// more (a click beside a line belongs to it).
+fn distance(pl: &PlacedLine, x: f32, y: f32) -> f32 {
+ let line = pl.line();
+ let (l, r) = (pl.x + line.left, pl.x + line.right.max(line.left + 1.0));
+ let (t, b) = (pl.y, pl.y + line.height);
+ let dx = if x < l {
+ l - x
+ } else if x > r {
+ x - r
+ } else {
+ 0.0
+ };
+ let dy = if y < t {
+ t - y
+ } else if y > b {
+ y - b
+ } else {
+ 0.0
+ };
+ dy * 4.0 + dx
+}
+
+/// The stop nearest to `x` on a placed line, with its affinity.
+fn stop_at_x(pl: &PlacedLine, x: f32) -> (Stop, bool) {
+ let stops = line_stops(&pl.para, pl.line);
+ let rel = x - pl.x;
+ let mut by_x = stops.clone();
+ by_x.sort_by(|a, b| a.x.total_cmp(&b.x));
+ let mut chosen = by_x.first().copied();
+ for w in by_x.windows(2) {
+ let mid = (w[0].x + w[1].x) / 2.0;
+ if rel >= mid {
+ chosen = Some(w[1]);
+ }
+ }
+ let Some(stop) = chosen else {
+ return (
+ Stop {
+ offset: 0,
+ x: 0.0,
+ cluster: 0,
+ },
+ false,
+ );
+ };
+ let last = stops.last().is_some_and(|s| s.offset == stop.offset);
+ let upstream = last && !is_last_line(&pl.para, pl.line);
+ (stop, upstream)
+}
+
+/// The position at a point on a page (points), if the page shows body text.
+pub fn hit_test(layout: &Layout, index: &ViewIndex, page: usize, x: f32, y: f32) -> Option<Pos> {
+ let page_ref = layout.pages.get(page)?;
+ let items = index.page_lines.get(page)?;
+ let mut best: Option<(&PlacedLine, f32)> = None;
+ for &i in items {
+ if let Some(Item::Line(pl)) = page_ref.items.get(i) {
+ let d = distance(pl, x, y);
+ if best.is_none_or(|(_, bd)| d < bd) {
+ best = Some((pl, d));
+ }
+ }
+ }
+ let (pl, _) = best?;
+ let (stop, upstream) = stop_at_x(pl, x);
+ Some(Pos {
+ block: pl.para.block.clone(),
+ offset: stop.offset,
+ upstream,
+ })
+}
+
+/// The page x of `offset` on a placed line (clamped to the line).
+fn x_on_line(pl: &PlacedLine, offset: usize) -> f32 {
+ let stops = line_stops(&pl.para, pl.line);
+ let stop = stops
+ .iter()
+ .find(|s| s.offset >= offset)
+ .or(stops.last())
+ .copied();
+ pl.x + stop.map_or(0.0, |s| s.x)
+}
+
+/// The page x spans of a line's clusters within offsets `lo..hi`, merged
+/// where they touch; with `mark`, a sliver for the paragraph mark at the
+/// line's end (on the left in a right-to-left paragraph).
+fn cluster_spans(pl: &PlacedLine, lo: usize, hi: usize, mark: bool) -> Vec<(f32, f32)> {
+ let pb = &pl.para;
+ let line = pl.line();
+ let mut spans: Vec<(f32, f32)> = (line.start..line.end)
+ .filter(|&ci| {
+ let c = &pb.inline.clusters[ci];
+ let start = c.offset as usize;
+ ci >= pb.inline.label_len
+ && c.len > 0
+ && c.kind != Kind::End
+ && start >= lo
+ && start < hi
+ })
+ .map(|ci| {
+ let x = pl.x + pb.lines.x[ci];
+ (x, x + pb.lines.adv[ci])
+ })
+ .collect();
+ if mark {
+ let rtl_para = pb.inline.levels.last().is_some_and(|l| l % 2 == 1);
+ let end = (line.start..line.end).find(|&ci| pb.inline.clusters[ci].kind == Kind::End);
+ if let Some(ci) = end {
+ let x = pl.x + pb.lines.x[ci];
+ let right = x + pb.lines.adv[ci];
+ spans.push(if rtl_para {
+ (right - 5.0, right)
+ } else {
+ (x, x + 5.0)
+ });
+ }
+ }
+ spans.sort_by(|a, b| a.0.total_cmp(&b.0));
+ let mut merged: Vec<(f32, f32)> = Vec::new();
+ for (a, b) in spans {
+ match merged.last_mut() {
+ Some(m) if a <= m.1 + 0.5 => m.1 = m.1.max(b),
+ _ => merged.push((a, b)),
+ }
+ }
+ merged
+}
+
+/// Highlight rectangles for the range between two ordered positions;
+/// `paras` lists the paragraphs from `from.block` to `to.block` inclusive.
+pub fn range_rects(
+ layout: &Layout,
+ index: &ViewIndex,
+ from: &Pos,
+ to: &Pos,
+ paras: &[BlockId],
+) -> Vec<PageRect> {
+ let mut out = Vec::new();
+ for (k, id) in paras.iter().enumerate() {
+ let Some(entries) = index.lines.get(id) else {
+ continue;
+ };
+ let first = k == 0;
+ let last = k + 1 == paras.len();
+ let s = if first { from.offset } else { 0 };
+ let e = if last { to.offset } else { usize::MAX };
+ for &(page, item) in entries {
+ let Some(pl) = placed(layout, (page, item)) else {
+ continue;
+ };
+ let stops = line_stops(&pl.para, pl.line);
+ let (Some(a), Some(b)) = (stops.first(), stops.last()) else {
+ continue;
+ };
+ let final_line = is_last_line(&pl.para, pl.line);
+ let lo = s.max(a.offset);
+ let hi = e.min(b.offset);
+ if lo > hi || (!final_line && lo == b.offset) {
+ // Nothing here, or the range starts at the wrap point,
+ // which shows on the next line.
+ continue;
+ }
+ // The paragraph mark is selected too: show it as a sliver.
+ let mark = !last && final_line;
+ if lo == hi && !mark {
+ continue;
+ }
+ let line = pl.line();
+ if !pl.para.inline.levels.is_empty() {
+ // Bidirectional text: the selected clusters, wherever they
+ // are on the line.
+ for (x0, x1) in cluster_spans(pl, lo, hi, mark) {
+ out.push(PageRect {
+ page,
+ x: x0,
+ y: pl.y,
+ w: (x1 - x0).max(1.0),
+ h: line.height,
+ });
+ }
+ continue;
+ }
+ let x0 = x_on_line(pl, lo);
+ let x1 = x_on_line(pl, hi) + if mark { 5.0 } else { 0.0 };
+ out.push(PageRect {
+ page,
+ x: x0,
+ y: pl.y,
+ w: (x1 - x0).max(1.0),
+ h: line.height,
+ });
+ }
+ }
+ out
+}
+
+/// Where vertical movement goes from a caret, at `goal_x`: the stop on
+/// the nearest line above or below.
+pub fn vertical(
+ layout: &Layout,
+ index: &ViewIndex,
+ from: &CaretRect,
+ goal_x: f32,
+ down: bool,
+) -> Option<Pos> {
+ let center = from.y + from.height / 2.0;
+ let mut page = from.page;
+ let mut first_page = true;
+ loop {
+ let items = index.page_lines.get(page)?;
+ let page_ref = &layout.pages[page];
+ let mut best: Option<(&PlacedLine, f32)> = None;
+ for &i in items {
+ let Some(Item::Line(pl)) = page_ref.items.get(i) else {
+ continue;
+ };
+ let line = pl.line();
+ let (t, b) = (pl.y, pl.y + line.height);
+ if first_page {
+ let beyond = if down {
+ t > center + 0.5
+ } else {
+ b < center - 0.5
+ };
+ if !beyond {
+ continue;
+ }
+ }
+ let (l, r) = (pl.x + line.left, pl.x + line.right);
+ let dx = if goal_x < l {
+ l - goal_x
+ } else if goal_x > r {
+ goal_x - r
+ } else {
+ 0.0
+ };
+ let dy = if down {
+ if first_page { t - center } else { t }
+ } else if first_page {
+ center - b
+ } else {
+ page_ref.height - b
+ };
+ let score = dy + dx * 4.0;
+ if best.is_none_or(|(_, s)| score < s) {
+ best = Some((pl, score));
+ }
+ }
+ if let Some((pl, _)) = best {
+ let (stop, upstream) = stop_at_x(pl, goal_x);
+ return Some(Pos {
+ block: pl.para.block.clone(),
+ offset: stop.offset,
+ upstream,
+ });
+ }
+ first_page = false;
+ if down {
+ page += 1;
+ if page >= layout.pages.len() {
+ return None;
+ }
+ } else {
+ page = page.checked_sub(1)?;
+ }
+ }
+}
+
+/// The first and last stops of the line showing `pos`.
+pub fn line_bounds(layout: &Layout, index: &ViewIndex, pos: &Pos) -> Option<(Pos, Pos)> {
+ let (_, pl, _) = locate(layout, index, pos)?;
+ let stops = line_stops(&pl.para, pl.line);
+ let first = stops.first()?;
+ let last = stops.last()?;
+ let wrapped = !is_last_line(&pl.para, pl.line);
+ Some((
+ Pos {
+ block: pos.block.clone(),
+ offset: first.offset,
+ upstream: false,
+ },
+ Pos {
+ block: pos.block.clone(),
+ offset: last.offset,
+ upstream: wrapped,
+ },
+ ))
+}
+
+/// Every caret stop offset of a paragraph, ascending (from its laid-out
+/// lines), or `None` when it is not on any page.
+pub fn para_stops(layout: &Layout, index: &ViewIndex, block: &BlockId) -> Option<Vec<usize>> {
+ let entries = index.lines.get(block)?;
+ let mut out: Vec<usize> = Vec::new();
+ for &(page, item) in entries {
+ let Some(pl) = placed(layout, (page, item)) else {
+ continue;
+ };
+ for s in line_stops(&pl.para, pl.line) {
+ out.push(s.offset);
+ }
+ }
+ out.sort_unstable();
+ out.dedup();
+ Some(out)
+}
+
+/// The selection's rectangles (empty for a caret).
+pub fn selection_rects(
+ layout: &Layout,
+ index: &ViewIndex,
+ sel: &Selection,
+ ordered: (&Pos, &Pos),
+ paras: &[BlockId],
+) -> Vec<PageRect> {
+ if sel.anchor.block == sel.focus.block && sel.anchor.offset == sel.focus.offset {
+ return Vec::new();
+ }
+ range_rects(layout, index, ordered.0, ordered.1, paras)
+}
diff --git a/crates/docx_engine/src/edit/lists.rs b/crates/docx_engine/src/edit/lists.rs
new file mode 100644
index 0000000000..7af53027d9
--- /dev/null
+++ b/crates/docx_engine/src/edit/lists.rs
@@ -0,0 +1,260 @@
+//! Bulleted and numbered lists: list definitions in the numbering part and
+//! list membership of paragraphs.
+
+use super::ListKind;
+use crate::document::{Document, rel_kind};
+use crate::error::Result;
+use crate::model::numbering::NumFmt;
+use crate::xml::XmlTree;
+use std::sync::Arc;
+
+const NUMBERING_REL: &str =
+ "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+const NUMBERING_CT: &str =
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml";
+const W_NS: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+
+/// The kind of list a level's number format makes.
+pub(super) fn kind_of(fmt: &NumFmt) -> Option<ListKind> {
+ match fmt {
+ NumFmt::Bullet => Some(ListKind::Bullet),
+ NumFmt::None => None,
+ _ => Some(ListKind::Number),
+ }
+}
+
+/// Word's default levels for a new list (`w` is the part's prefix).
+fn default_levels(kind: ListKind, w: &str) -> String {
+ let q = |l: &str| format!("{w}:{l}");
+ let mut out = String::new();
+ for i in 0..9u32 {
+ let left = 720 * (i + 1);
+ let (fmt, text, jc, hanging, font) = match kind {
+ ListKind::Bullet => {
+ let (text, font) = match i % 3 {
+ 0 => ("\u{F0B7}", "Symbol"),
+ 1 => ("o", "Courier New"),
+ _ => ("\u{F0A7}", "Wingdings"),
+ };
+ ("bullet", text.to_owned(), "left", 360, Some(font))
+ }
+ ListKind::Number => {
+ let (fmt, jc, hanging) = match i % 3 {
+ 0 => ("decimal", "left", 360),
+ 1 => ("lowerLetter", "left", 360),
+ _ => ("lowerRoman", "right", 180),
+ };
+ (fmt, format!("%{}.", i + 1), jc, hanging, None)
+ }
+ };
+ out.push_str(&format!(
+ "<{lvl} {ilvl}=\"{i}\"><{start} {val}=\"1\"/><{numFmt} {val}=\"{fmt}\"/><{lvlText} {val}=\"{text}\"/><{lvlJc} {val}=\"{jc}\"/><{pPr}><{ind} {left_a}=\"{left}\" {hanging_a}=\"{hanging}\"/></{pPr}>",
+ lvl = q("lvl"),
+ ilvl = q("ilvl"),
+ start = q("start"),
+ val = q("val"),
+ numFmt = q("numFmt"),
+ lvlText = q("lvlText"),
+ lvlJc = q("lvlJc"),
+ pPr = q("pPr"),
+ ind = q("ind"),
+ left_a = q("left"),
+ hanging_a = q("hanging"),
+ ));
+ if let Some(font) = font {
+ out.push_str(&format!(
+ "<{rPr}><{rFonts} {a}=\"{font}\" {h}=\"{font}\" {hint}=\"default\"/></{rPr}>",
+ rPr = q("rPr"),
+ rFonts = q("rFonts"),
+ a = q("ascii"),
+ h = q("hAnsi"),
+ hint = q("hint"),
+ ));
+ }
+ out.push_str(&format!("</{}>", q("lvl")));
+ }
+ out
+}
+
+/// A list instance id no peer is likely to pick at the same time.
+fn fresh_id(used: impl Iterator<Item = i64>, doc: &Document) -> i64 {
+ let used: Vec<i64> = used.collect();
+ let random = doc.ids.lock().ok().and_then(|g| g.source().cloned());
+ match random {
+ Some(source) => loop {
+ let id = source.next_in(10_000..1_000_000_000) as i64;
+ if !used.contains(&id) {
+ return id;
+ }
+ },
+ None => used.iter().copied().max().unwrap_or(0).max(0) + 1,
+ }
+}
+
+/// The numbering part, creating it (with its relationship and content
+/// type) when the document has none. Returns its name.
+fn numbering_part(doc: &mut Document) -> Result<String> {
+ let existing = doc
+ .main_rels
+ .iter()
+ .find(|r| rel_kind(&r.rel_type) == "numbering")
+ .map(|r| doc.main_rels.resolve(r))
+ .filter(|p| doc.pkg.has_part(p));
+ if let Some(p) = existing {
+ return Ok(p);
+ }
+ let name = "/word/numbering.xml".to_owned();
+ let xml = format!(
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<w:numbering xmlns:w=\"{W_NS}\"></w:numbering>"
+ );
+ doc.pkg.write(&name, xml.into_bytes(), Some(NUMBERING_CT));
+ let main = doc.main.clone();
+ let mut rels = doc.pkg.rels(&main)?;
+ rels.add_internal(NUMBERING_REL, &name);
+ doc.pkg.write_rels(&rels);
+ doc.main_rels = Arc::new(doc.pkg.rels(&main)?);
+ Ok(name)
+}
+
+/// Adds an abstract definition (when `abstract_xml` is given) and a list
+/// instance to the numbering part. Returns the new instance's id.
+fn add_definition(
+ doc: &mut Document,
+ kind: ListKind,
+ abstract_id: Option<i64>,
+ restart: bool,
+) -> Result<i64> {
+ let part = numbering_part(doc)?;
+ let bytes = doc.pkg.read(&part)?.into_owned();
+ let tree = XmlTree::parse(&bytes, &part)?;
+ let root = tree.root();
+ let w = tree
+ .qname(root)
+ .split_once(':')
+ .map_or(String::new(), |(p, _)| p.to_owned());
+ let q = |l: &str| {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+ };
+ let numbering = &doc.parts.numbering;
+ let num_id = fresh_id(numbering.num_ids(), doc);
+ let (abstract_id, new_abstract) = match abstract_id {
+ Some(a) => (a, None),
+ None => {
+ let a = fresh_id(numbering.abstract_ids(), doc).max(0);
+ let xml = format!(
+ "<{an} {id}=\"{a}\"><{mlt} {val}=\"hybridMultilevel\"/>{levels}</{an}>",
+ an = q("abstractNum"),
+ id = q("abstractNumId"),
+ mlt = q("multiLevelType"),
+ val = q("val"),
+ levels = default_levels(kind, if w.is_empty() { "w" } else { &w }),
+ );
+ (a, Some(xml))
+ }
+ };
+ let mut num = format!(
+ "<{n} {id}=\"{num_id}\"><{a} {val}=\"{abstract_id}\"/>",
+ n = q("num"),
+ id = q("numId"),
+ a = q("abstractNumId"),
+ val = q("val"),
+ );
+ if restart {
+ num.push_str(&format!(
+ "<{o} {ilvl}=\"0\"><{s} {val}=\"1\"/></{o}>",
+ o = q("lvlOverride"),
+ ilvl = q("ilvl"),
+ s = q("startOverride"),
+ val = q("val"),
+ ));
+ }
+ num.push_str(&format!("</{}>", q("num")));
+ // Schema order: pictures, abstract definitions, instances, cleanup id.
+ let src = tree.source();
+ let kids: Vec<_> = tree.children(root).collect();
+ let first_num = kids
+ .iter()
+ .find(|&&k| tree.is_w(k, "num") || tree.is_w(k, "numIdMacAtCleanup"))
+ .map(|&k| tree.span(k).start);
+ let after_nums = kids
+ .iter()
+ .rev()
+ .find(|&&k| tree.is_w(k, "num"))
+ .map(|&k| tree.span(k).end);
+ let root_span = tree.span(root);
+ let close = root_span.end - (tree.qname(root).len() + 3);
+ let self_closing = tree.start_tag(root).ends_with("/>");
+ let mut out = String::with_capacity(src.len() + 4096);
+ if self_closing {
+ let tag = tree.start_tag(root);
+ out.push_str(&src[..root_span.start]);
+ out.push_str(tag.trim_end_matches("/>").trim_end());
+ out.push('>');
+ out.push_str(new_abstract.as_deref().unwrap_or(""));
+ out.push_str(&num);
+ out.push_str(&format!("</{}>", tree.qname(root)));
+ out.push_str(&src[root_span.end..]);
+ } else {
+ let a_at = first_num.unwrap_or(close);
+ let n_at = after_nums.unwrap_or(a_at).max(a_at);
+ out.push_str(&src[..a_at]);
+ out.push_str(new_abstract.as_deref().unwrap_or(""));
+ out.push_str(&src[a_at..n_at]);
+ out.push_str(&num);
+ out.push_str(&src[n_at..]);
+ }
+ doc.pkg.write(&part, out.into_bytes(), None);
+ doc.load_parts()?;
+ Ok(num_id)
+}
+
+/// A list instance of `kind` for new list paragraphs: an existing bullet
+/// list, or a new instance of an existing numbered definition starting at
+/// one, or a new definition.
+pub(super) fn instance_for(doc: &mut Document, kind: ListKind) -> Result<i64> {
+ let styles = Arc::clone(&doc.parts.styles);
+ let numbering = Arc::clone(&doc.parts.numbering);
+ let mut candidates: Vec<i64> = numbering
+ .num_ids()
+ .filter(|&id| id > 0)
+ .filter(|&id| {
+ numbering
+ .level(id, 0, &styles)
+ .is_some_and(|l| kind_of(&l.fmt) == Some(kind) && is_plain(l, kind))
+ })
+ .collect();
+ candidates.sort_unstable();
+ if kind == ListKind::Bullet
+ && let Some(&id) = candidates.first()
+ {
+ return Ok(id);
+ }
+ if let Some(&id) = candidates.first()
+ && let Some(abs) = numbering.abstract_of(id)
+ && numbering
+ .abstract_num(abs)
+ .is_some_and(|a| a.num_style_link.is_none())
+ {
+ return add_definition(doc, kind, Some(abs), true);
+ }
+ add_definition(doc, kind, None, false)
+}
+
+/// Whether a level looks like an ordinary list (not a heading or legal
+/// outline numbering with its own style).
+fn is_plain(l: &crate::model::numbering::Level, kind: ListKind) -> bool {
+ if l.style.is_some() {
+ return false;
+ }
+ match kind {
+ ListKind::Bullet => true,
+ ListKind::Number => l
+ .text
+ .as_deref()
+ .is_some_and(|t| t.starts_with("%1") && t.len() <= 3),
+ }
+}
diff --git a/crates/docx_engine/src/edit/notes.rs b/crates/docx_engine/src/edit/notes.rs
new file mode 100644
index 0000000000..c617f5fef0
--- /dev/null
+++ b/crates/docx_engine/src/edit/notes.rs
@@ -0,0 +1,354 @@
+//! Creating footnotes and endnotes: the notes part (with Word's separators)
+//! when the document has none, the note and reference styles when its
+//! styles lack them, and the new note itself.
+
+use crate::document::{Document, rel_kind};
+use crate::error::Result;
+use crate::xml::XmlTree;
+use std::sync::Arc;
+
+const W_NS: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const REL: &str = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/";
+const CT: &str = "application/vnd.openxmlformats-officedocument.wordprocessingml.";
+
+/// Names of the two kinds of notes in the package and the XML.
+struct Kind {
+ /// The relationship (and part) name: `footnotes`.
+ part: &'static str,
+ /// The note element: `footnote`.
+ element: &'static str,
+ /// The reference mark inside the note: `footnoteRef`.
+ mark: &'static str,
+ /// Built-in paragraph style of the note's text.
+ text_style: (&'static str, &'static str),
+ /// Built-in character style of the references.
+ reference_style: (&'static str, &'static str),
+}
+
+const FOOTNOTE: Kind = Kind {
+ part: "footnotes",
+ element: "footnote",
+ mark: "footnoteRef",
+ text_style: ("FootnoteText", "footnote text"),
+ reference_style: ("FootnoteReference", "footnote reference"),
+};
+
+const ENDNOTE: Kind = Kind {
+ part: "endnotes",
+ element: "endnote",
+ mark: "endnoteRef",
+ text_style: ("EndnoteText", "endnote text"),
+ reference_style: ("EndnoteReference", "endnote reference"),
+};
+
+fn kind(endnote: bool) -> &'static Kind {
+ if endnote { &ENDNOTE } else { &FOOTNOTE }
+}
+
+/// The prefix a part binds to WordprocessingML (from its root element).
+fn prefix_of(tree: &XmlTree) -> String {
+ tree.qname(tree.root())
+ .split_once(':')
+ .map_or(String::new(), |(p, _)| p.to_owned())
+}
+
+fn qualify(w: &str, local: &str) -> String {
+ if w.is_empty() {
+ local.to_owned()
+ } else {
+ format!("{w}:{local}")
+ }
+}
+
+/// Inserts `xml` as the last children of a part's root element.
+fn append_to_root(tree: &XmlTree, xml: &str) -> String {
+ let src = tree.source();
+ let root = tree.root();
+ let span = tree.span(root);
+ let tag = tree.start_tag(root);
+ if let Some(open) = tag.strip_suffix("/>") {
+ return format!(
+ "{}{}>{xml}</{}>{}",
+ &src[..span.start],
+ open.trim_end(),
+ tree.qname(root),
+ &src[span.end..]
+ );
+ }
+ let close = span.end - (tree.qname(root).len() + 3);
+ format!("{}{xml}{}", &src[..close], &src[close..])
+}
+
+/// The notes part, creating it (with the separator and continuation
+/// separator Word draws above notes, its relationship and content type)
+/// when the document has none. Returns its name.
+fn notes_part(doc: &mut Document, endnote: bool) -> Result<String> {
+ let k = kind(endnote);
+ let existing = doc
+ .main_rels
+ .iter()
+ .find(|r| rel_kind(&r.rel_type) == k.part)
+ .map(|r| doc.main_rels.resolve(r))
+ .filter(|p| doc.pkg.has_part(p));
+ if let Some(p) = existing {
+ return Ok(p);
+ }
+ let name = format!("/word/{}.xml", k.part);
+ let separator = |kind: &str, id: i32, mark: &str| {
+ format!(
+ "<w:{e} w:type=\"{kind}\" w:id=\"{id}\"><w:p><w:pPr><w:spacing w:after=\"0\" w:line=\"240\" w:lineRule=\"auto\"/></w:pPr><w:r><w:{mark}/></w:r></w:p></w:{e}>",
+ e = k.element
+ )
+ };
+ let xml = format!(
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<w:{part} xmlns:w=\"{W_NS}\">{}{}</w:{part}>",
+ separator("separator", -1, "separator"),
+ separator("continuationSeparator", 0, "continuationSeparator"),
+ part = k.part,
+ );
+ let content_type = format!("{CT}{}+xml", k.part);
+ doc.pkg.write(&name, xml.into_bytes(), Some(&content_type));
+ let main = doc.main.clone();
+ let mut rels = doc.pkg.rels(&main)?;
+ rels.add_internal(&format!("{REL}{}", k.part), &name);
+ doc.pkg.write_rels(&rels);
+ doc.main_rels = Arc::new(doc.pkg.rels(&main)?);
+ Ok(name)
+}
+
+/// The ids of the note text and reference styles, adding Word's built-in
+/// definitions to the styles part when it lacks them. `None` when the
+/// document has no styles part (the note then uses direct formatting).
+fn note_styles(doc: &mut Document, endnote: bool) -> Result<Option<(String, String)>> {
+ let k = kind(endnote);
+ let part = doc
+ .main_rels
+ .iter()
+ .find(|r| rel_kind(&r.rel_type) == "styles")
+ .map(|r| doc.main_rels.resolve(r))
+ .filter(|p| doc.pkg.has_part(p));
+ let Some(part) = part else {
+ return Ok(None);
+ };
+ let styles = Arc::clone(&doc.parts.styles);
+ let found = |(_, name): (&str, &str)| styles.id_by_name(name).map(str::to_owned);
+ if let (Some(text), Some(reference)) = (found(k.text_style), found(k.reference_style)) {
+ return Ok(Some((text, reference)));
+ }
+ let bytes = doc.pkg.read(&part)?.into_owned();
+ let tree = XmlTree::parse(&bytes, &part)?;
+ let w = prefix_of(&tree);
+ let q = |l: &str| qualify(&w, l);
+ let mut add = String::new();
+ let mut ids = (String::new(), String::new());
+ for (slot, (id, name), paragraph) in [
+ (&mut ids.0, k.text_style, true),
+ (&mut ids.1, k.reference_style, false),
+ ] {
+ if let Some(existing) = found((id, name)) {
+ *slot = existing;
+ continue;
+ }
+ // A free id (the built-in one unless another style took it).
+ let mut sid = id.to_owned();
+ let mut n = 1;
+ while styles.get(&sid).is_some() {
+ n += 1;
+ sid = format!("{id}{n}");
+ }
+ let based_on = if paragraph {
+ styles
+ .default_paragraph_id()
+ .map(|d| format!("<{} {}=\"{d}\"/>", q("basedOn"), q("val")))
+ .unwrap_or_default()
+ } else {
+ String::new()
+ };
+ let props = if paragraph {
+ format!(
+ "<{pPr}><{sp} {after}=\"0\" {line}=\"240\" {rule}=\"auto\"/></{pPr}><{rPr}><{sz} {val}=\"20\"/><{szCs} {val}=\"20\"/></{rPr}>",
+ pPr = q("pPr"),
+ sp = q("spacing"),
+ after = q("after"),
+ line = q("line"),
+ rule = q("lineRule"),
+ rPr = q("rPr"),
+ sz = q("sz"),
+ szCs = q("szCs"),
+ val = q("val"),
+ )
+ } else {
+ format!(
+ "<{rPr}><{va} {val}=\"superscript\"/></{rPr}>",
+ rPr = q("rPr"),
+ va = q("vertAlign"),
+ val = q("val"),
+ )
+ };
+ add.push_str(&format!(
+ "<{style} {type}=\"{t}\" {styleId}=\"{sid}\"><{nm} {val}=\"{name}\"/>{based_on}<{prio} {val}=\"99\"/><{semi}/><{unhide}/>{props}</{style}>",
+ style = q("style"),
+ type = q("type"),
+ t = if paragraph { "paragraph" } else { "character" },
+ styleId = q("styleId"),
+ nm = q("name"),
+ val = q("val"),
+ prio = q("uiPriority"),
+ semi = q("semiHidden"),
+ unhide = q("unhideWhenUsed"),
+ ));
+ *slot = sid;
+ }
+ let xml = append_to_root(&tree, &add);
+ doc.pkg.write(&part, xml.into_bytes(), None);
+ doc.load_parts()?;
+ Ok(Some(ids))
+}
+
+/// An id no note of a part has, and that a peer adding a note at the same
+/// time is unlikely to pick; kept small, as Word's are.
+fn fresh_id(doc: &Document, tree: &XmlTree) -> i64 {
+ let used: Vec<i64> = tree
+ .children(tree.root())
+ .filter_map(|n| tree.w_attr(n, "id").and_then(crate::xml::parse_int))
+ .collect();
+ let next = used.iter().copied().max().unwrap_or(0).max(0) + 1;
+ let random = doc.ids.lock().ok().and_then(|g| g.source().cloned());
+ match random {
+ Some(source) => (0..64)
+ .map(|_| source.next_in(1_000..30_000) as i64)
+ .find(|id| !used.contains(id))
+ .unwrap_or(next),
+ None => next,
+ }
+}
+
+/// The element and note a reference object points at (`footnoteReference`
+/// or `endnoteReference` markup): whether it is an endnote, and its id.
+pub(super) fn reference(xml: &str) -> Option<(bool, i64)> {
+ let endnote = if xml.contains("footnoteReference") {
+ false
+ } else if xml.contains("endnoteReference") {
+ true
+ } else {
+ return None;
+ };
+ let id = super::revise::attribute(xml, "id")?.parse().ok()?;
+ Some((endnote, id))
+}
+
+/// Copies a note under a new id, for a pasted reference to it (a note
+/// has one reference, so a pasted one gets a note of its own, as in
+/// Word). Returns the new id.
+pub(super) fn duplicate(doc: &mut Document, endnote: bool, id: i64) -> Result<Option<i64>> {
+ let Some(note) = doc.notes_of(endnote).note_xml(id) else {
+ return Ok(None);
+ };
+ let part = notes_part(doc, endnote)?;
+ let bytes = doc.pkg.read(&part)?.into_owned();
+ let tree = XmlTree::parse(&bytes, &part)?;
+ let copy_id = fresh_id(doc, &tree);
+ // The id in the note's start tag.
+ let start_end = note.find('>').unwrap_or(note.len());
+ let (start, rest) = note.split_at(start_end);
+ let Some(at) = start.find(" w:id=\"").or_else(|| start.find(":id=\"")) else {
+ return Ok(None);
+ };
+ let value_start = start[at..].find('"').map_or(start.len(), |q| at + q + 1);
+ let value_end = start[value_start..]
+ .find('"')
+ .map_or(start.len(), |q| value_start + q);
+ let copy = format!(
+ "{}{copy_id}{}{rest}",
+ &start[..value_start],
+ &start[value_end..]
+ );
+ let xml = append_to_root(&tree, &copy);
+ doc.pkg.write(&part, xml.into_bytes(), None);
+ doc.load_parts()?;
+ Ok(Some(copy_id))
+}
+
+/// What a new note needs from the body: the reference's character style
+/// (or `None` for direct superscript).
+pub(super) struct NewNote {
+ /// The note's id.
+ pub id: i64,
+ /// The reference style id.
+ pub reference_style: Option<String>,
+}
+
+/// Adds a note holding its reference mark and a space, ready for text.
+/// The body's reference to it is the caller's to insert.
+pub(super) fn add_note(doc: &mut Document, endnote: bool) -> Result<NewNote> {
+ let k = kind(endnote);
+ let styles = note_styles(doc, endnote)?;
+ let part = notes_part(doc, endnote)?;
+ let bytes = doc.pkg.read(&part)?.into_owned();
+ let tree = XmlTree::parse(&bytes, &part)?;
+ let w = prefix_of(&tree);
+ let q = |l: &str| qualify(&w, l);
+ let id = fresh_id(doc, &tree);
+ let (ppr, mark_rpr) = match &styles {
+ Some((text, reference)) => (
+ format!(
+ "<{pPr}><{ps} {val}=\"{text}\"/></{pPr}>",
+ pPr = q("pPr"),
+ ps = q("pStyle"),
+ val = q("val"),
+ ),
+ format!(
+ "<{rPr}><{rs} {val}=\"{reference}\"/></{rPr}>",
+ rPr = q("rPr"),
+ rs = q("rStyle"),
+ val = q("val"),
+ ),
+ ),
+ None => (
+ format!(
+ "<{pPr}><{sp} {after}=\"0\"/><{rPr}><{sz} {val}=\"20\"/></{rPr}></{pPr}>",
+ pPr = q("pPr"),
+ sp = q("spacing"),
+ after = q("after"),
+ rPr = q("rPr"),
+ sz = q("sz"),
+ val = q("val"),
+ ),
+ format!(
+ "<{rPr}><{va} {val}=\"superscript\"/></{rPr}>",
+ rPr = q("rPr"),
+ va = q("vertAlign"),
+ val = q("val"),
+ ),
+ ),
+ };
+ let text_rpr = if styles.is_none() {
+ format!(
+ "<{rPr}><{sz} {val}=\"20\"/></{rPr}>",
+ rPr = q("rPr"),
+ sz = q("sz"),
+ val = q("val"),
+ )
+ } else {
+ String::new()
+ };
+ let note = format!(
+ "<{e} {idq}=\"{id}\"><{p}>{ppr}<{r}>{mark_rpr}<{mark}/></{r}><{r}>{text_rpr}<{t} xml:space=\"preserve\"> </{t}></{r}></{p}></{e}>",
+ e = q(k.element),
+ idq = q("id"),
+ p = q("p"),
+ r = q("r"),
+ t = q("t"),
+ mark = q(k.mark),
+ );
+ let xml = append_to_root(&tree, &note);
+ doc.pkg.write(&part, xml.into_bytes(), None);
+ doc.load_parts()?;
+ Ok(NewNote {
+ id,
+ reference_style: styles.map(|(_, reference)| reference),
+ })
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/edit/notes/test.rs b/crates/docx_engine/src/edit/notes/test.rs
new file mode 100644
index 0000000000..01299b772f
--- /dev/null
+++ b/crates/docx_engine/src/edit/notes/test.rs
@@ -0,0 +1,268 @@
+use super::super::test_util::*;
+use super::super::*;
+use crate::test_support::{Parts, fonts};
+
+/// Texts of a story's paragraphs, objects shown as `^`.
+fn story_texts(story: &crate::model::block::Story) -> Vec<String> {
+ story
+ .paragraphs()
+ .iter()
+ .map(|id| {
+ story
+ .get(id)
+ .unwrap()
+ .content
+ .text()
+ .replace('\u{FFFC}', "^")
+ })
+ .collect()
+}
+
+#[test]
+fn inserting_a_footnote_creates_the_part_and_moves_into_the_note() {
+ let mut s = open_with(
+ &p("The Seller shall deliver the Shares."),
+ &Parts {
+ styles: Some(
+ r#"<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>"#,
+ ),
+ ..Parts::default()
+ },
+ );
+ caret_at(&mut s, 0, 36);
+ let r = run(&mut s, EditOp::InsertNote { endnote: false });
+ assert_eq!(r.story.kind, StoryKind::Footnote);
+ // The reference is in the body, styled like Word's.
+ let body = s.document().document_xml();
+ assert!(body.contains("<w:footnoteReference w:id="), "{body}");
+ assert!(
+ body.contains(r#"<w:rStyle w:val="FootnoteReference"/>"#),
+ "{body}"
+ );
+ // The note holds its mark and a space; the caret is after them.
+ let notes = s.document().footnotes();
+ let (&id, note) = notes
+ .by_id
+ .iter()
+ .find(|(_, n)| n.is_text())
+ .expect("a note");
+ assert!(body.contains(&format!(r#"w:id="{id}""#)));
+ assert_eq!(story_texts(&note.story), vec!["^ "]);
+ assert_eq!(r.selection.focus.offset, 2);
+ // Word's separators come with a new part, and the styles are added.
+ assert_eq!(notes.by_id.values().filter(|n| !n.is_text()).count(), 2);
+ let styles = &s.document().parts().styles;
+ assert!(styles.id_by_name("footnote text").is_some());
+ assert!(styles.id_by_name("footnote reference").is_some());
+ // Typing goes into the note, which shows at the foot of the page.
+ type_text(&mut s, "As amended.");
+ let note = &s.document().footnotes().by_id[&id];
+ assert_eq!(story_texts(&note.story), vec!["^ As amended."]);
+ let area = s.pages(fonts())[0].notes.clone().expect("notes area");
+ assert!(area.top > 600.0, "{area:?}");
+ // Leaving the note goes back to just after the reference.
+ let r = run(&mut s, EditOp::ExitStory);
+ assert_eq!(r.story.kind, StoryKind::Body);
+ assert_eq!(r.selection.focus.offset, 37);
+ // The saved file opens with the note, its reference and its part.
+ let saved = Document::open(s.document().save().unwrap()).unwrap();
+ assert_eq!(
+ story_texts(&saved.footnotes().by_id[&id].story),
+ vec!["^ As amended."]
+ );
+ let types = String::from_utf8(
+ saved
+ .package()
+ .read("/[Content_Types].xml")
+ .unwrap()
+ .into_owned(),
+ )
+ .unwrap();
+ assert!(types.contains("footnotes+xml"), "{types}");
+}
+
+#[test]
+fn a_second_endnote_goes_into_the_existing_part() {
+ let mut s = open(&p("Alpha Beta"));
+ caret_at(&mut s, 0, 5);
+ run(&mut s, EditOp::InsertNote { endnote: true });
+ type_text(&mut s, "First.");
+ run(&mut s, EditOp::ExitStory);
+ caret_at(&mut s, 0, 11);
+ let r = run(&mut s, EditOp::InsertNote { endnote: true });
+ assert_eq!(r.story.kind, StoryKind::Endnote);
+ type_text(&mut s, "Second.");
+ let notes = s.document().endnotes();
+ let texts: Vec<Vec<String>> = notes
+ .by_id
+ .values()
+ .filter(|n| n.is_text())
+ .map(|n| story_texts(&n.story))
+ .collect();
+ assert_eq!(texts.len(), 2, "{texts:?}");
+ assert!(texts.contains(&vec!["^ First.".to_owned()]));
+ assert!(texts.contains(&vec!["^ Second.".to_owned()]));
+ // Without a styles part, the reference is a plain superscript.
+ assert!(
+ s.document()
+ .document_xml()
+ .contains(r#"<w:vertAlign w:val="superscript"/>"#)
+ );
+}
+
+#[test]
+fn notes_are_inserted_from_the_body_only() {
+ let mut s = open(&p("Alpha"));
+ caret_at(&mut s, 0, 5);
+ run(&mut s, EditOp::InsertNote { endnote: false });
+ // Inside the note, inserting another note does nothing.
+ let r = run(&mut s, EditOp::InsertNote { endnote: false });
+ assert!(!r.changed);
+ assert_eq!(r.story.kind, StoryKind::Footnote);
+}
+
+const WITH_NOTE: &str = r#"<w:p><w:r><w:t>Alpha</w:t></w:r><w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:footnoteReference w:id="1"/></w:r><w:r><w:t xml:space="preserve"> Beta</w:t></w:r></w:p>"#;
+
+const NOTES: &str = r#"<w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote><w:footnote w:id="1"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> Defined terms.</w:t></w:r></w:p></w:footnote>"#;
+
+fn copy_alpha_with_its_note(s: &mut Session) -> Vec<ClipParagraph> {
+ let first = para(s, 0);
+ s.apply(
+ &[EditOp::Select {
+ anchor: Pos::new(first.clone(), 0),
+ focus: Pos::new(first, 6),
+ }],
+ None,
+ fonts(),
+ )
+ .unwrap();
+ s.copy_selection().paragraphs
+}
+
+/// The ids of the notes the body refers to, in order.
+fn references(s: &Session) -> Vec<i64> {
+ let xml = s.document().document_xml();
+ xml.match_indices("<w:footnoteReference w:id=\"")
+ .map(|(i, m)| {
+ let rest = &xml[i + m.len()..];
+ rest[..rest.find('"').unwrap()].parse().unwrap()
+ })
+ .collect()
+}
+
+#[test]
+fn pasting_a_note_reference_copies_the_note() {
+ let mut s = open_with(
+ WITH_NOTE,
+ &Parts {
+ footnotes: Some(NOTES),
+ ..Parts::default()
+ },
+ );
+ let clip = copy_alpha_with_its_note(&mut s);
+ caret_at(&mut s, 0, 11);
+ run(
+ &mut s,
+ EditOp::Paste {
+ paragraphs: clip.clone(),
+ same_document: true,
+ },
+ );
+ let refs = references(&s);
+ assert_eq!(refs.len(), 2, "{refs:?}");
+ assert_eq!(refs[0], 1);
+ assert_ne!(refs[1], 1);
+ // The copy has the note's text.
+ let copy = &s.document().footnotes().by_id[&refs[1]];
+ assert_eq!(story_texts(&copy.story), vec!["^ Defined terms."]);
+ // From another document, the reference is left behind.
+ let mut other = open(&p("Gamma"));
+ caret_at(&mut other, 0, 5);
+ run(
+ &mut other,
+ EditOp::Paste {
+ paragraphs: clip,
+ same_document: false,
+ },
+ );
+ assert_eq!(texts(&other), vec!["GammaAlpha"]);
+ assert!(references(&other).is_empty());
+}
+
+/// Lines of text on the pages as (page, x, y, text), in reading order.
+fn laid_out_lines(s: &mut Session) -> Vec<(usize, f32, f32, String)> {
+ use crate::layout::Item;
+ let layout = s.layout(fonts());
+ let mut out = Vec::new();
+ for (n, page) in layout.pages.iter().enumerate() {
+ for item in page.all_items() {
+ let Item::Line(p) = item else { continue };
+ let l = p.line();
+ let text: String = p.para.inline.clusters[l.start..l.end]
+ .iter()
+ .map(|c| c.ch)
+ .filter(|c| !c.is_control() && *c != '\u{FFFC}')
+ .collect();
+ out.push((n, p.x, p.y, text));
+ }
+ }
+ out
+}
+
+#[test]
+fn endnotes_are_listed_in_the_order_of_their_references() {
+ let mut s = open(&p("Alpha Beta"));
+ // The first endnote made goes at the end, the second before it, so
+ // the second gets the lower number and comes first in the list.
+ caret_at(&mut s, 0, 10);
+ run(&mut s, EditOp::InsertNote { endnote: true });
+ type_text(&mut s, "Made first.");
+ run(&mut s, EditOp::ExitStory);
+ caret_at(&mut s, 0, 5);
+ run(&mut s, EditOp::InsertNote { endnote: true });
+ type_text(&mut s, "Made second.");
+ run(&mut s, EditOp::ExitStory);
+ let lines = laid_out_lines(&mut s);
+ let at = |needle: &str| {
+ lines
+ .iter()
+ .position(|l| l.3.contains(needle))
+ .unwrap_or_else(|| panic!("{needle} not laid out: {lines:?}"))
+ };
+ assert!(at("Made second.") < at("Made first."), "{lines:?}");
+}
+
+#[test]
+fn endnotes_go_in_the_column_they_land_in() {
+ // Two columns; enough endnotes to fill the first and run into the second.
+ let mut refs = String::new();
+ let mut notes = String::new();
+ for i in 1..=60 {
+ refs.push_str(&format!(
+ r#"<w:r><w:t xml:space="preserve">Word {i} </w:t></w:r><w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:endnoteReference w:id="{i}"/></w:r>"#
+ ));
+ notes.push_str(&format!(
+ r#"<w:endnote w:id="{i}"><w:p><w:r><w:endnoteRef/></w:r><w:r><w:t xml:space="preserve"> Endnote number {i} says a little.</w:t></w:r></w:p></w:endnote>"#
+ ));
+ }
+ let body = format!(
+ r#"<w:p>{refs}</w:p><w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/><w:cols w:num="2" w:space="720"/></w:sectPr>"#
+ );
+ let mut s = open_with(
+ &body,
+ &Parts {
+ endnotes: Some(&notes),
+ ..Parts::default()
+ },
+ );
+ let lines = laid_out_lines(&mut s);
+ let notes: Vec<_> = lines
+ .iter()
+ .filter(|l| l.3.contains("Endnote number"))
+ .collect();
+ assert_eq!(notes.len(), 60, "{lines:?}");
+ // The endnotes run from the first column on into the second.
+ let middle = 612.0 / 2.0;
+ assert!(notes.iter().any(|l| l.1 > middle), "{notes:?}");
+ assert!(notes.iter().any(|l| l.1 < middle), "{notes:?}");
+}
diff --git a/crates/docx_engine/src/edit/revise.rs b/crates/docx_engine/src/edit/revise.rs
new file mode 100644
index 0000000000..272d1025f1
--- /dev/null
+++ b/crates/docx_engine/src/edit/revise.rs
@@ -0,0 +1,984 @@
+//! Tracked changes. While the document tracks changes, typed text is
+//! recorded as an insertion and deleting marks text deleted instead of
+//! removing it, each attributed to the editing author; text an author
+//! inserted themselves is simply removed again. Accepting or rejecting
+//! turns revisions back into plain text.
+
+use super::txn::Txn;
+use super::xmledit::{Element, PPR_ORDER};
+use crate::document::{Document, rel_kind};
+use crate::error::Result;
+use crate::model::block::{BlockId, BlockKind};
+use crate::model::content::{Attrs, Content, Wrapper, encode_wrappers, key};
+use crate::model::write::rpr_xml;
+use crate::xml::{Decl, SnippetContext, XmlTree, escape_attr};
+use std::collections::HashSet;
+use std::sync::Arc;
+
+/// Schema order of a paragraph mark's run properties (CT_ParaRPr): the
+/// revision marks come first and `rPrChange` last.
+const MARK_RPR_ORDER: &[&str] = &[
+ "ins",
+ "del",
+ "moveFrom",
+ "moveTo",
+ "rStyle",
+ "rFonts",
+ "b",
+ "bCs",
+ "i",
+ "iCs",
+ "caps",
+ "smallCaps",
+ "strike",
+ "dstrike",
+ "outline",
+ "shadow",
+ "emboss",
+ "imprint",
+ "noProof",
+ "snapToGrid",
+ "vanish",
+ "webHidden",
+ "color",
+ "spacing",
+ "w",
+ "kern",
+ "position",
+ "sz",
+ "szCs",
+ "highlight",
+ "u",
+ "effect",
+ "bdr",
+ "shd",
+ "fitText",
+ "vertAlign",
+ "rtl",
+ "cs",
+ "em",
+ "lang",
+ "eastAsianLayout",
+ "specVanish",
+ "oMath",
+ "rPrChange",
+];
+
+/// Schema order of the settings part's children (CT_Settings).
+const SETTINGS_ORDER: &[&str] = &[
+ "writeProtection",
+ "view",
+ "zoom",
+ "removePersonalInformation",
+ "removeDateAndTime",
+ "doNotDisplayPageBoundaries",
+ "displayBackgroundShape",
+ "printPostScriptOverText",
+ "printFractionalCharacterWidth",
+ "printFormsData",
+ "embedTrueTypeFonts",
+ "embedSystemFonts",
+ "saveSubsetFonts",
+ "saveFormsData",
+ "mirrorMargins",
+ "alignBordersAndEdges",
+ "bordersDoNotSurroundHeader",
+ "bordersDoNotSurroundFooter",
+ "gutterAtTop",
+ "hideSpellingErrors",
+ "hideGrammaticalErrors",
+ "activeWritingStyle",
+ "proofState",
+ "formsDesign",
+ "attachedTemplate",
+ "linkStyles",
+ "stylePaneFormatFilter",
+ "stylePaneSortMethod",
+ "documentType",
+ "mailMerge",
+ "revisionView",
+ "trackRevisions",
+ "doNotTrackMoves",
+ "doNotTrackFormatting",
+ "documentProtection",
+ "autoFormatOverride",
+ "styleLockTheme",
+ "styleLockQFSet",
+ "defaultTabStop",
+ "autoHyphenation",
+ "consecutiveHyphenLimit",
+ "hyphenationZone",
+ "doNotHyphenateCaps",
+ "showEnvelope",
+ "summaryLength",
+ "clickAndTypeStyle",
+ "defaultTableStyle",
+ "evenAndOddHeaders",
+ "bookFoldRevPrinting",
+ "bookFoldPrinting",
+ "bookFoldPrintingSheets",
+ "drawingGridHorizontalSpacing",
+ "drawingGridVerticalSpacing",
+ "displayHorizontalDrawingGridEvery",
+ "displayVerticalDrawingGridEvery",
+ "doNotUseMarginsForDrawingGridOrigin",
+ "drawingGridHorizontalOrigin",
+ "drawingGridVerticalOrigin",
+ "doNotShadeFormData",
+ "noPunctuationKerning",
+ "characterSpacingControl",
+ "printTwoOnOne",
+ "strictFirstAndLastChars",
+ "noLineBreaksAfter",
+ "noLineBreaksBefore",
+ "savePreviewPicture",
+ "doNotValidateAgainstSchema",
+ "saveInvalidXml",
+ "ignoreMixedContent",
+ "alwaysShowPlaceholderText",
+ "doNotDemarcateInvalidXml",
+ "saveXmlDataOnly",
+ "useXSLTWhenSaving",
+ "saveThroughXslt",
+ "showXMLTags",
+ "alwaysMergeEmptyNamespace",
+ "updateFields",
+ "hdrShapeDefaults",
+ "footnotePr",
+ "endnotePr",
+ "compat",
+ "docVars",
+ "rsids",
+ "mathPr",
+ "attachedSchema",
+ "themeFontLang",
+ "clrSchemeMapping",
+ "doNotIncludeSubdocsInStats",
+ "doNotAutoCompressPictures",
+ "forceUpgrade",
+ "captions",
+ "readModeInkLockDown",
+ "smartTagType",
+ "schemaLibrary",
+ "shapeDefaults",
+ "doNotEmbedSmartTags",
+ "decimalSymbol",
+ "listSeparator",
+];
+
+const SETTINGS_REL: &str =
+ "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
+const SETTINGS_CT: &str =
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml";
+const W_NS: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+
+/// Who records tracked changes, and when.
+#[derive(Clone, Debug)]
+pub(crate) struct Revisor {
+ /// The author's name.
+ pub author: String,
+ /// When (ISO 8601).
+ pub date: String,
+ /// The document's WordprocessingML prefix.
+ pub(crate) w: String,
+ /// The id of revisions this edit records.
+ pub(crate) id: u32,
+}
+
+impl Revisor {
+ fn q(&self, local: &str) -> String {
+ if self.w.is_empty() {
+ local.to_owned()
+ } else {
+ format!("{}:{local}", self.w)
+ }
+ }
+
+ /// `w:id`, `w:author` and `w:date` of a revision element. Each kind of
+ /// revision one edit records gets an id of its own, so they are
+ /// accepted and rejected separately.
+ fn attributes(&self, kind: u32) -> String {
+ let id = (self.id.wrapping_add(kind) & 0x7fff_ffff).max(1);
+ let mut s = format!(" {}=\"{id}\" {}=\"", self.q("id"), self.q("author"));
+ escape_attr(&mut s, &self.author);
+ s.push('"');
+ if !self.date.is_empty() {
+ s.push_str(&format!(" {}=\"", self.q("date")));
+ escape_attr(&mut s, &self.date);
+ s.push('"');
+ }
+ s
+ }
+
+ /// Records a formatting change made to a run while tracking: the run
+ /// keeps its formatting from before in a `w:rPrChange` (the earliest
+ /// one when it already has a record). Text tracked as inserted is new
+ /// anyway and records nothing.
+ pub(crate) fn format_change(&self, old: &Attrs, new: &Attrs) -> Attrs {
+ let props = |a: &Attrs| {
+ let mut v: Vec<(String, String)> = a
+ .run_props()
+ .filter(|(q, _)| !q.ends_with("rPrChange"))
+ .map(|(q, x)| (q.to_owned(), x.to_owned()))
+ .collect();
+ v.sort();
+ v
+ };
+ if props(old) == props(new) || old.wrappers().iter().any(is_inserted) {
+ return new.clone();
+ }
+ let change_key = format!("{}{}", key::RUN_PROP, self.q("rPrChange"));
+ let existing = old
+ .iter()
+ .find(|(k, _)| k.starts_with(key::RUN_PROP) && k.ends_with(":rPrChange"))
+ .map(|(_, v)| v.to_owned());
+ let record = match existing {
+ // Formatting changed back to what was recorded: no change left.
+ Some(x) if x.contains(&rpr_xml(new, &self.w)) => None,
+ Some(x) => Some(x),
+ None => {
+ let tag = self.q("rPrChange");
+ Some(format!(
+ "<{tag}{}>{}</{tag}>",
+ self.attributes(4),
+ rpr_xml(old, &self.w)
+ ))
+ }
+ };
+ new.with(&change_key, record.as_deref())
+ }
+
+ /// Records a change to a paragraph's properties made while tracking:
+ /// the paragraph keeps its properties from before in a `w:pPrChange`
+ /// (the earliest record when it already has one). The mark's
+ /// formatting and section break are not part of the record, and a
+ /// paragraph whose mark is tracked as inserted is new anyway.
+ pub(crate) fn para_change(&self, before: &Element, after: &mut Element, decls: &[Decl]) {
+ let recorded = |e: &Element| -> Vec<String> {
+ e.children
+ .iter()
+ .filter(|c| !matches!(c.local(), "rPr" | "sectPr" | "pPrChange"))
+ .map(|c| c.xml.clone())
+ .collect()
+ };
+ let old = recorded(before);
+ let new = recorded(after);
+ if old == new {
+ return;
+ }
+ let mark_inserted = before.get("rPr").is_some_and(|r| {
+ let r = Element::open(r, "rPr", &self.w, decls, MARK_RPR_ORDER);
+ r.has("ins") || r.has("moveTo")
+ });
+ if mark_inserted {
+ return;
+ }
+ if let Some(existing) = before.get("pPrChange") {
+ // Properties changed back to what was recorded: no change left.
+ let change = Element::open(existing, "pPrChange", &self.w, decls, PPR_ORDER);
+ let back = change.get("pPr").is_some_and(|p| {
+ recorded(&Element::open(p, "pPr", &self.w, decls, PPR_ORDER)) == new
+ }) || (change.get("pPr").is_none() && new.is_empty());
+ if back {
+ after.set("pPrChange", None);
+ }
+ return;
+ }
+ let tag = self.q("pPrChange");
+ let ppr = self.q("pPr");
+ let xml = format!(
+ "<{tag}{}><{ppr}>{}</{ppr}></{tag}>",
+ self.attributes(5),
+ old.concat()
+ );
+ after.set("pPrChange", Some(xml));
+ }
+
+ /// A revision element wrapping runs (`ins` or `del`).
+ pub(crate) fn wrapper(&self, local: &str) -> Wrapper {
+ let kind = if local == "ins" { 0 } else { 1 };
+ Wrapper {
+ open: format!("<{}{}>", self.q(local), self.attributes(kind)),
+ close: format!("</{}>", self.q(local)),
+ }
+ }
+
+ /// A revision mark on a paragraph mark (`ins` or `del`).
+ fn mark(&self, local: &str) -> String {
+ let kind = if local == "ins" { 2 } else { 3 };
+ format!("<{}{}/>", self.q(local), self.attributes(kind))
+ }
+
+ /// Whether a wrapper is an insertion this author made.
+ fn owns(&self, w: &Wrapper) -> bool {
+ is_inserted(w) && attribute(&w.open, "author").as_deref() == Some(self.author.as_str())
+ }
+}
+
+/// Whether a wrapper records inserted (or moved-in) text.
+pub(crate) fn is_inserted(w: &Wrapper) -> bool {
+ matches!(w.local(), "ins" | "moveTo")
+}
+
+/// Whether a wrapper records deleted (or moved-away) text.
+pub(crate) fn is_deleted(w: &Wrapper) -> bool {
+ matches!(w.local(), "del" | "moveFrom")
+}
+
+/// Whether a wrapper is a tracked change.
+pub(crate) fn is_revision(w: &Wrapper) -> bool {
+ is_inserted(w) || is_deleted(w)
+}
+
+/// An attribute of a start tag by local name, with entities decoded.
+pub(crate) fn attribute(tag: &str, local: &str) -> Option<String> {
+ let (start, end) = attribute_span(tag, local)?;
+ Some(unescape(&tag[start..end]))
+}
+
+/// The tag with the value of its attribute `local` replaced by `value` (a
+/// plain value, needing no escaping), or `None` when it has no such
+/// attribute.
+pub(crate) fn with_attribute(tag: &str, local: &str, value: &str) -> Option<String> {
+ let (start, end) = attribute_span(tag, local)?;
+ Some(format!("{}{value}{}", &tag[..start], &tag[end..]))
+}
+
+/// Where the (raw) value of attribute `local` sits in a start tag.
+fn attribute_span(tag: &str, local: &str) -> Option<(usize, usize)> {
+ let bytes = tag.as_bytes();
+ let mut search = 0;
+ while let Some(i) = tag[search..].find(local) {
+ let at = search + i;
+ search = at + local.len();
+ let before = at.checked_sub(1).map(|b| bytes[b]);
+ if !matches!(before, Some(b' ' | b':' | b'\t' | b'\n' | b'\r')) {
+ continue;
+ }
+ let after = &tag[search..];
+ let rest = after.trim_start();
+ let Some(rest) = rest.strip_prefix('=') else {
+ continue;
+ };
+ let rest = rest.trim_start();
+ let Some(quote) = rest.chars().next().filter(|c| *c == '"' || *c == '\'') else {
+ continue;
+ };
+ let start = tag.len() - rest.len() + 1;
+ let end = start + tag[start..].find(quote)?;
+ return Some((start, end));
+ }
+ None
+}
+
+fn unescape(s: &str) -> String {
+ if !s.contains('&') {
+ return s.to_owned();
+ }
+ s.replace("&lt;", "<")
+ .replace("&gt;", ">")
+ .replace("&quot;", "\"")
+ .replace("&apos;", "'")
+ .replace("&amp;", "&")
+}
+
+/// A revision id from a per-edit unique token (positive, 31 bits).
+pub(crate) fn revision_id(token: &str) -> u32 {
+ use std::hash::{Hash, Hasher};
+ let mut h = std::collections::hash_map::DefaultHasher::new();
+ token.hash(&mut h);
+ ((h.finish() as u32) & 0x7fff_ffff).max(1)
+}
+
+/// The attributes text typed at a position gets while tracking: `base`
+/// (the formatting it gets anyway) inside an insertion by the author. It
+/// continues the insertion just before it when that is the author's and
+/// sits in the same elements.
+pub(crate) fn inserted(base: &Attrs, before: Option<&Attrs>, rev: &Revisor) -> Attrs {
+ let mut stack: Vec<Wrapper> = base
+ .wrappers()
+ .into_iter()
+ .filter(|w| !is_revision(w))
+ .collect();
+ let continued = before.and_then(|b| {
+ let ws = b.wrappers();
+ let (last, outer) = ws.split_last()?;
+ (rev.owns(last) && outer == stack.as_slice()).then(|| last.clone())
+ });
+ stack.push(continued.unwrap_or_else(|| rev.wrapper("ins")));
+ base.with(key::WRAP, encode_wrappers(&stack).as_deref())
+}
+
+/// Marks `[start, end)` of a paragraph's content deleted by the author.
+/// Text the author inserted is removed outright; text already deleted and
+/// markers (bookmarks, comment ranges) stay as they are. Returns where
+/// `end` is afterwards.
+pub(crate) fn delete_in(content: &mut Content, start: usize, end: usize, rev: &Revisor) -> usize {
+ let len = content.len();
+ let (start, end) = (start.min(len), end.min(len));
+ if start >= end {
+ return start;
+ }
+ let middle = content.slice(start, end);
+ let del = rev.wrapper("del");
+ let mut out = Content::new();
+ for span in middle.spans() {
+ let ws = span.attrs.wrappers();
+ let deleted = ws.iter().any(is_deleted);
+ if !deleted && ws.iter().any(|w| rev.owns(w)) {
+ continue;
+ }
+ if deleted || span.attrs.marker().is_some() {
+ out.push(&span.text, span.attrs.clone());
+ continue;
+ }
+ let mut stack = ws;
+ stack.push(del.clone());
+ out.push(
+ &span.text,
+ span.attrs
+ .with(key::WRAP, encode_wrappers(&stack).as_deref()),
+ );
+ }
+ content.delete(start, end);
+ content.insert_content(start, &out);
+ start + out.len()
+}
+
+/// The revision on a paragraph's mark: inserted (`true`) or deleted, its
+/// author and its id.
+pub(crate) fn mark_revision(
+ ppr: &str,
+ w: &str,
+ decls: &[Decl],
+) -> Option<(bool, Option<String>, Option<String>)> {
+ if !(ppr.contains("ins") || ppr.contains("del") || ppr.contains("move")) {
+ return None;
+ }
+ let e = Element::open(ppr, "pPr", w, decls, PPR_ORDER);
+ let r = Element::open(e.get("rPr")?, "rPr", w, decls, MARK_RPR_ORDER);
+ for (local, inserted) in [
+ ("ins", true),
+ ("moveTo", true),
+ ("del", false),
+ ("moveFrom", false),
+ ] {
+ if let Some(x) = r.get(local) {
+ return Some((inserted, attribute(x, "author"), attribute(x, "id")));
+ }
+ }
+ None
+}
+
+/// The id of a paragraph's tracked property change (`w:pPrChange`).
+pub(crate) fn ppr_change_id(ppr: &str, w: &str, decls: &[Decl]) -> Option<String> {
+ if !ppr.contains("pPrChange") {
+ return None;
+ }
+ Element::open(ppr, "pPr", w, decls, PPR_ORDER)
+ .get("pPrChange")
+ .and_then(|x| attribute(x, "id"))
+}
+
+/// Records (`Some(inserted)`) or clears a revision on a paragraph's mark.
+pub(crate) fn set_mark_revision(
+ ppr: &str,
+ change: Option<(bool, &Revisor)>,
+ w: &str,
+ decls: &[Decl],
+) -> String {
+ let mut e = Element::open(ppr, "pPr", w, decls, PPR_ORDER);
+ let mut r = Element::open(e.get("rPr").unwrap_or(""), "rPr", w, decls, MARK_RPR_ORDER);
+ for local in ["ins", "del", "moveFrom", "moveTo"] {
+ r.set(local, None);
+ }
+ if let Some((inserted, rev)) = change {
+ let local = if inserted { "ins" } else { "del" };
+ r.set(local, Some(rev.mark(local)));
+ }
+ let rpr = r.finish(true);
+ e.set("rPr", (!rpr.is_empty()).then_some(rpr));
+ e.finish(true)
+}
+
+/// The revision element on a paragraph's mark, as written.
+fn mark_element(ppr: &str, w: &str, decls: &[Decl]) -> Option<(String, String)> {
+ let e = Element::open(ppr, "pPr", w, decls, PPR_ORDER);
+ let r = Element::open(e.get("rPr")?, "rPr", w, decls, MARK_RPR_ORDER);
+ ["ins", "del", "moveFrom", "moveTo"]
+ .into_iter()
+ .find_map(|l| r.get(l).map(|x| (l.to_owned(), x.to_owned())))
+}
+
+/// Joins two paragraphs. The joined paragraph ends with the second's mark,
+/// so it takes that mark's revision (if any).
+pub(crate) fn join(txn: &mut Txn<'_>, first: &BlockId, second: &BlockId) -> Option<super::Pos> {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = Arc::clone(txn.doc.decls());
+ let kept = mark_element(&txn.get(second)?.props, &w, &decls);
+ let pos = super::text::join(txn, first, second)?;
+ let props = txn.get(first)?.props.clone();
+ let mut e = Element::open(&props, "pPr", &w, &decls, PPR_ORDER);
+ let mut r = Element::open(
+ e.get("rPr").unwrap_or(""),
+ "rPr",
+ &w,
+ &decls,
+ MARK_RPR_ORDER,
+ );
+ for local in ["ins", "del", "moveFrom", "moveTo"] {
+ r.set(local, None);
+ }
+ if let Some((local, xml)) = kept {
+ r.set(&local, Some(xml));
+ }
+ let rpr = r.finish(true);
+ e.set("rPr", (!rpr.is_empty()).then_some(rpr));
+ let props = e.finish(true);
+ if let Some(b) = txn.block_mut(first)
+ && b.props != props
+ {
+ b.props = props;
+ }
+ Some(pos)
+}
+
+/// Marks the paragraph mark of `id` inserted by the author.
+pub(crate) fn mark_inserted(txn: &mut Txn<'_>, id: &BlockId, rev: &Revisor) {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = Arc::clone(txn.doc.decls());
+ let Some(b) = txn.get(id) else {
+ return;
+ };
+ let props = set_mark_revision(&b.props, Some((true, rev)), &w, &decls);
+ if let Some(b) = txn.block_mut(id) {
+ b.props = props;
+ }
+}
+
+/// The paragraph before `id` among its siblings.
+pub(crate) fn previous_paragraph(txn: &Txn<'_>, id: &BlockId) -> Option<BlockId> {
+ let parent = txn.get(id)?.parent.clone();
+ let kids = txn.story().children(parent.as_ref());
+ let i = kids.iter().position(|k| k == id)?;
+ let prev = kids.get(i.checked_sub(1)?)?;
+ (txn.get(prev)?.kind == BlockKind::Paragraph).then(|| prev.clone())
+}
+
+/// Deletes a paragraph mark while tracking: a mark the author inserted
+/// goes (joining the paragraphs), any other is marked deleted. Returns
+/// whether the paragraphs were joined.
+pub(crate) fn delete_mark(
+ txn: &mut Txn<'_>,
+ first: &BlockId,
+ second: &BlockId,
+ rev: &Revisor,
+) -> bool {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = Arc::clone(txn.doc.decls());
+ let Some(b) = txn.get(first) else {
+ return false;
+ };
+ let revision = mark_revision(&b.props, &w, &decls);
+ let own = revision
+ .as_ref()
+ .is_some_and(|(inserted, author, _)| *inserted && author.as_deref() == Some(&rev.author));
+ if own {
+ return join(txn, first, second).is_some();
+ }
+ if revision.is_some_and(|(inserted, _, _)| !inserted) {
+ return false;
+ }
+ let props = set_mark_revision(&b.props, Some((false, rev)), &w, &decls);
+ if let Some(b) = txn.block_mut(first) {
+ b.props = props;
+ }
+ false
+}
+
+/// Deletes `[from, to)` across paragraphs while tracking: text is marked
+/// deleted (the author's own insertions go), and so are the marks of every
+/// paragraph but the last. Returns the range's ends afterwards.
+pub(crate) fn delete_range(
+ txn: &mut Txn<'_>,
+ from: &super::Pos,
+ to: &super::Pos,
+ rev: &Revisor,
+) -> (super::Pos, super::Pos) {
+ use super::Pos;
+ let list = txn.story().paragraphs();
+ let i = list.iter().position(|id| *id == from.block);
+ let j = list.iter().position(|id| *id == to.block);
+ let (Some(i), Some(j)) = (i, j) else {
+ return (from.clone(), from.clone());
+ };
+ if i > j {
+ return (from.clone(), from.clone());
+ }
+ let paras = list[i..=j].to_vec();
+ let last = paras.len() - 1;
+ let mut end = Pos {
+ upstream: false,
+ ..to.clone()
+ };
+ for (k, id) in paras.iter().enumerate().rev() {
+ let s = if k == 0 { from.offset } else { 0 };
+ let e = if k == last { to.offset } else { usize::MAX };
+ if let Some(b) = txn.block_mut(id) {
+ let e = e.min(b.content.len());
+ let new_end = delete_in(&mut b.content, s, e, rev);
+ if k == last {
+ end.offset = new_end;
+ }
+ }
+ if k < last {
+ let next = &paras[k + 1];
+ let parent = |id: &BlockId| txn.get(id).map(|b| b.parent.clone());
+ if parent(id) == parent(next) {
+ let len = txn.get(id).map_or(0, |b| b.content.len());
+ if delete_mark(txn, id, next, rev) && end.block == *next {
+ end = Pos::new(id.clone(), len + end.offset);
+ }
+ }
+ }
+ }
+ (
+ Pos {
+ upstream: false,
+ ..from.clone()
+ },
+ end,
+ )
+}
+
+/// Which revisions to accept or reject.
+#[derive(Clone, Debug)]
+pub(crate) enum Scope {
+ /// Every revision in `[from, to)` of the listed paragraphs (offsets in
+ /// the first and last), including marks of all but the last.
+ Range {
+ /// Paragraphs in order.
+ paras: Vec<BlockId>,
+ /// Start offset in the first.
+ from: usize,
+ /// End offset in the last.
+ to: usize,
+ },
+ /// Revisions with these ids, wherever they are in the story.
+ Ids(HashSet<String>),
+ /// Every revision in the story.
+ All,
+}
+
+fn wrapper_id(w: &Wrapper) -> Option<String> {
+ attribute(&w.open, "id")
+}
+
+/// Revision ids at a position: around the caret, and the paragraph mark's
+/// when the caret is at the paragraph's end.
+pub(crate) fn ids_at(content: &Content, offset: usize, mark: Option<String>) -> HashSet<String> {
+ let mut out = HashSet::new();
+ for at in [offset.checked_sub(1), Some(offset)].into_iter().flatten() {
+ if let Some(a) = content.attrs_at(at) {
+ for w in a.wrappers() {
+ if is_revision(&w)
+ && let Some(id) = wrapper_id(&w)
+ {
+ out.insert(id);
+ }
+ }
+ if let Some(change) = a.run_props().find(|(q, _)| q.ends_with(":rPrChange"))
+ && let Some(id) = attribute(change.1, "id")
+ {
+ out.insert(id);
+ }
+ }
+ }
+ if offset >= content.len()
+ && let Some(id) = mark
+ {
+ out.insert(id);
+ }
+ out
+}
+
+/// Whether the content has any revision in `[start, end)`.
+pub(crate) fn has_revisions(content: &Content, start: usize, end: usize) -> bool {
+ let mut at = 0;
+ for span in content.spans() {
+ let len = crate::model::content::utf16_len(&span.text);
+ let overlaps = at < end.max(start + 1) && at + len > start;
+ at += len;
+ if !overlaps {
+ continue;
+ }
+ if span.attrs.wrappers().iter().any(is_revision)
+ || span
+ .attrs
+ .run_props()
+ .any(|(q, _)| q.ends_with(":rPrChange"))
+ {
+ return true;
+ }
+ }
+ false
+}
+
+/// A run's formatting after its tracked formatting change is accepted
+/// (the record dropped) or rejected (the recorded formatting restored).
+fn resolve_format(attrs: &Attrs, accept: bool, ctx: &SnippetContext) -> Attrs {
+ let Some((change_key, xml)) = attrs
+ .iter()
+ .find(|(k, _)| k.starts_with(key::RUN_PROP) && k.ends_with(":rPrChange"))
+ .map(|(k, v)| (k.to_owned(), v.to_owned()))
+ else {
+ return attrs.clone();
+ };
+ if accept {
+ return attrs.with(&change_key, None);
+ }
+ // The formatting before the change, from the record's `w:rPr`.
+ let old: Vec<(String, String)> = ctx
+ .parse(&xml)
+ .ok()
+ .and_then(|t| {
+ let rpr = t.w_child(t.root(), "rPr")?;
+ Some(
+ t.children(rpr)
+ .map(|c| (format!("{}{}", key::RUN_PROP, t.qname(c)), t.snippet(c)))
+ .collect(),
+ )
+ })
+ .unwrap_or_default();
+ let mut out = attrs.without(|k| k.starts_with(key::RUN_PROP));
+ for (k, v) in old {
+ out = out.with(&k, Some(&v));
+ }
+ out
+}
+
+/// Resolves the revisions of one paragraph's `[start, end)` that `wanted`
+/// selects.
+fn resolve_text(
+ content: &Content,
+ start: usize,
+ end: usize,
+ accept: bool,
+ wanted: &dyn Fn(&str) -> bool,
+ ctx: &SnippetContext,
+) -> Content {
+ let len = content.len();
+ let (start, end) = (start.min(len), end.min(len));
+ let mut out = content.slice(0, start);
+ for span in content.slice(start, end).spans() {
+ let ws = span.attrs.wrappers();
+ let picked = |w: &Wrapper| is_revision(w) && wrapper_id(w).is_some_and(|id| wanted(&id));
+ let deleted = ws.iter().any(|w| is_deleted(w) && picked(w));
+ let inserted = ws.iter().any(|w| is_inserted(w) && picked(w));
+ if (accept && deleted) || (!accept && inserted) {
+ continue;
+ }
+ let kept: Vec<Wrapper> = ws.iter().filter(|w| !picked(w)).cloned().collect();
+ let mut attrs = span
+ .attrs
+ .with(key::WRAP, encode_wrappers(&kept).as_deref());
+ let change_id = attrs
+ .run_props()
+ .find(|(q, _)| q.ends_with(":rPrChange"))
+ .and_then(|(_, x)| attribute(x, "id"));
+ if change_id.is_some_and(|id| wanted(&id)) {
+ attrs = resolve_format(&attrs, accept, ctx);
+ }
+ out.push(&span.text, attrs);
+ }
+ out.insert_content(out.len(), &content.slice(end, len));
+ out
+}
+
+/// A paragraph's properties after its tracked property change is
+/// accepted (record dropped) or rejected (recorded properties restored).
+fn resolve_ppr_change(ppr: &str, accept: bool, w: &str, decls: &[Decl]) -> String {
+ let e = Element::open(ppr, "pPr", w, decls, PPR_ORDER);
+ let Some(change) = e.get("pPrChange").map(str::to_owned) else {
+ return ppr.to_owned();
+ };
+ let mut out = e.clone();
+ out.set("pPrChange", None);
+ if !accept {
+ let old = Element::open(&change, "pPrChange", w, decls, PPR_ORDER);
+ if let Some(old_ppr) = old.get("pPr") {
+ let restored = Element::open(old_ppr, "pPr", w, decls, PPR_ORDER);
+ // The mark's formatting and the section break are not part of
+ // the recorded properties.
+ let rpr = e.get("rPr").map(str::to_owned);
+ let sect = e.get("sectPr").map(str::to_owned);
+ out = restored;
+ out.set("rPr", rpr);
+ out.set("sectPr", sect);
+ }
+ }
+ out.finish(true)
+}
+
+/// Accepts or rejects revisions in a story.
+pub(crate) fn resolve(txn: &mut Txn<'_>, scope: &Scope, accept: bool) {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = Arc::clone(txn.doc.decls());
+ let ctx = SnippetContext::new(&decls);
+ let (paras, from, to, ids, every_mark): (
+ Vec<BlockId>,
+ usize,
+ usize,
+ Option<&HashSet<String>>,
+ bool,
+ ) = match scope {
+ Scope::Range { paras, from, to } => (paras.clone(), *from, *to, None, false),
+ Scope::Ids(ids) => (txn.story().paragraphs(), 0, usize::MAX, Some(ids), true),
+ Scope::All => (txn.story().paragraphs(), 0, usize::MAX, None, true),
+ };
+ let wanted = |id: &str| ids.is_none_or(|set| set.contains(id));
+ let last = paras.len().saturating_sub(1);
+ // Marks to join with the paragraph after them, resolved last to first.
+ let mut joins: Vec<(BlockId, BlockId)> = Vec::new();
+ for (k, id) in paras.iter().enumerate() {
+ let Some(b) = txn.get(id) else {
+ continue;
+ };
+ if b.kind != BlockKind::Paragraph {
+ continue;
+ }
+ let start = if k == 0 { from } else { 0 };
+ let end = if k == last { to } else { usize::MAX };
+ let content = resolve_text(&b.content, start, end, accept, &wanted, &ctx);
+ let mut props = b.props.clone();
+ if ppr_change_id(&props, &w, &decls).is_some_and(|i| wanted(&i)) {
+ props = resolve_ppr_change(&props, accept, &w, &decls);
+ }
+ // The mark is in scope for every paragraph but the last of a range.
+ let mark_in_scope = every_mark || k < last;
+ if mark_in_scope
+ && let Some((inserted, _, mark_id)) = mark_revision(&props, &w, &decls)
+ && mark_id.as_deref().is_none_or(&wanted)
+ {
+ props = set_mark_revision(&props, None, &w, &decls);
+ // An inserted mark rejected, or a deleted one accepted, goes.
+ if inserted != accept
+ && let Some(next) = next_paragraph(txn, id)
+ {
+ joins.push((id.clone(), next));
+ }
+ }
+ let changed = content != b.content || props != b.props;
+ if changed && let Some(b) = txn.block_mut(id) {
+ b.content = content;
+ b.props = props;
+ }
+ }
+ for (first, second) in joins.into_iter().rev() {
+ join(txn, &first, &second);
+ }
+}
+
+/// The paragraph after `id` among its siblings.
+fn next_paragraph(txn: &Txn<'_>, id: &BlockId) -> Option<BlockId> {
+ let parent = txn.get(id)?.parent.clone();
+ let kids = txn.story().children(parent.as_ref());
+ let i = kids.iter().position(|k| k == id)?;
+ let next = kids.get(i + 1)?;
+ (txn.get(next)?.kind == BlockKind::Paragraph).then(|| next.clone())
+}
+
+/// The settings part, creating it (with its relationship and content type)
+/// when the document has none. Returns its name.
+fn settings_part(doc: &mut Document) -> Result<String> {
+ let existing = doc
+ .main_rels
+ .iter()
+ .find(|r| rel_kind(&r.rel_type) == "settings")
+ .map(|r| doc.main_rels.resolve(r))
+ .filter(|p| doc.pkg.has_part(p));
+ if let Some(p) = existing {
+ return Ok(p);
+ }
+ let name = "/word/settings.xml".to_owned();
+ let xml = format!(
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<w:settings xmlns:w=\"{W_NS}\"></w:settings>"
+ );
+ doc.pkg.write(&name, xml.into_bytes(), Some(SETTINGS_CT));
+ let main = doc.main.clone();
+ let mut rels = doc.pkg.rels(&main)?;
+ rels.add_internal(SETTINGS_REL, &name);
+ doc.pkg.write_rels(&rels);
+ doc.main_rels = Arc::new(doc.pkg.rels(&main)?);
+ Ok(name)
+}
+
+/// Turns tracking changes on or off for everyone (`w:trackRevisions` in
+/// the settings part). Returns whether anything changed.
+pub(crate) fn set_tracking(doc: &mut Document, on: bool) -> Result<bool> {
+ if doc.parts().settings.track_revisions == on {
+ return Ok(false);
+ }
+ let part = settings_part(doc)?;
+ let bytes = doc.pkg.read(&part)?;
+ let tree = XmlTree::parse(&bytes, &part)?;
+ let root = tree.root();
+ let src = tree.source();
+ let w = tree
+ .qname(root)
+ .split_once(':')
+ .map_or("", |(p, _)| p)
+ .to_owned();
+ let tag = if w.is_empty() {
+ "trackRevisions".to_owned()
+ } else {
+ format!("{w}:trackRevisions")
+ };
+ let kids: Vec<_> = tree.children(root).collect();
+ let existing = kids
+ .iter()
+ .copied()
+ .find(|&c| tree.is_w(c, "trackRevisions"));
+ let out = match (existing, on) {
+ (Some(c), false) => {
+ let span = tree.span(c);
+ format!("{}{}", &src[..span.start], &src[span.end..])
+ }
+ (Some(c), true) => {
+ // Present but off (`w:val="0"`).
+ let span = tree.span(c);
+ format!("{}<{tag}/>{}", &src[..span.start], &src[span.end..])
+ }
+ (None, false) => return Ok(false),
+ (None, true) => {
+ let rank = |local: &str| SETTINGS_ORDER.iter().position(|n| *n == local);
+ let mine = rank("trackRevisions").unwrap_or(0);
+ let before = kids.iter().copied().find(|&c| {
+ let known = tree.is_w(c, tree.local(c));
+ !known || rank(tree.local(c)).is_none_or(|r| r > mine)
+ });
+ let root_span = tree.span(root);
+ let start_tag = tree.start_tag(root);
+ if start_tag.ends_with("/>") {
+ let open = format!("{}>", start_tag.trim_end_matches("/>").trim_end());
+ format!(
+ "{}{open}<{tag}/></{}>{}",
+ &src[..root_span.start],
+ tree.qname(root),
+ &src[root_span.end..]
+ )
+ } else {
+ let at = before.map_or(root_span.end - (tree.qname(root).len() + 3), |c| {
+ tree.span(c).start
+ });
+ format!("{}<{tag}/>{}", &src[..at], &src[at..])
+ }
+ }
+ };
+ doc.pkg.write(&part, out.into_bytes(), None);
+ doc.load_parts()?;
+ Ok(true)
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/edit/revise/test.rs b/crates/docx_engine/src/edit/revise/test.rs
new file mode 100644
index 0000000000..827638f410
--- /dev/null
+++ b/crates/docx_engine/src/edit/revise/test.rs
@@ -0,0 +1,392 @@
+use super::super::test_util::*;
+use super::super::*;
+use crate::test_support::{Parts, fonts};
+
+const TRACKING: &str = "<w:trackRevisions/>";
+
+fn tracked(body: &str) -> Session {
+ let mut s = open_with(
+ body,
+ &Parts {
+ settings: Some(TRACKING),
+ ..Parts::default()
+ },
+ );
+ s.set_author("Alice");
+ s.set_now("2026-10-04T12:00:00Z");
+ s
+}
+
+fn xml(s: &Session) -> String {
+ s.document().document_xml()
+}
+
+fn count(haystack: &str, needle: &str) -> usize {
+ haystack.matches(needle).count()
+}
+
+#[test]
+fn typing_is_recorded_as_the_authors_insertion() {
+ let mut s = tracked(&p("Hello"));
+ caret_at(&mut s, 0, 5);
+ type_text(&mut s, " world");
+ type_text(&mut s, "!");
+ let out = xml(&s);
+ // One insertion, continued by the second keystroke.
+ assert_eq!(count(&out, "<w:ins "), 1, "{out}");
+ assert!(out.contains("w:author=\"Alice\""), "{out}");
+ assert!(out.contains("w:date=\"2026-10-04T12:00:00Z\""), "{out}");
+ assert!(
+ out.contains("<w:t xml:space=\"preserve\"> world!</w:t>"),
+ "{out}"
+ );
+ assert_eq!(texts(&s), vec!["Hello world!"]);
+ let r = s.state(fonts());
+ assert!(r.format.tracking);
+ assert!(r.format.revision);
+}
+
+#[test]
+fn deleting_marks_text_deleted_but_removes_the_authors_own_insertions() {
+ let mut s = tracked(&p("Hello"));
+ caret_at(&mut s, 0, 5);
+ type_text(&mut s, "XY");
+ // Backspace over the author's own insertion removes it.
+ run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ assert_eq!(texts(&s), vec!["HelloX"]);
+ // Backspace over original text marks it deleted; the caret steps
+ // before it.
+ run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ let r = run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ assert_eq!(texts(&s), vec!["Hello"]);
+ assert_eq!(r.selection.focus.offset, 4);
+ let out = xml(&s);
+ assert!(out.contains("<w:del "), "{out}");
+ assert!(out.contains("<w:delText>o</w:delText>"), "{out}");
+ // Deleting a selection over a mix: own text goes, the rest is marked.
+ let mut s = tracked(&p("one two"));
+ caret_at(&mut s, 0, 3);
+ type_text(&mut s, " new");
+ select(&mut s, (0, 0), (0, 11));
+ let r = run(
+ &mut s,
+ EditOp::Delete {
+ forward: true,
+ unit: Unit::Char,
+ },
+ );
+ assert_eq!(texts(&s), vec!["one two"]);
+ assert_eq!(r.selection.focus.offset, 7);
+ assert!(!xml(&s).contains("<w:ins "));
+}
+
+#[test]
+fn enter_records_an_inserted_paragraph_mark_and_backspace_takes_it_back() {
+ let mut s = tracked(&p("Hello world"));
+ caret_at(&mut s, 0, 5);
+ run(&mut s, EditOp::InsertParagraph);
+ assert_eq!(texts(&s), vec!["Hello", " world"]);
+ let out = xml(&s);
+ assert!(out.contains("<w:rPr><w:ins "), "{out}");
+ // Backspace at the start of the second paragraph removes the mark the
+ // author inserted.
+ run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ assert_eq!(texts(&s), vec!["Hello world"]);
+ assert!(!xml(&s).contains("<w:ins "));
+ // Another author's mark is marked deleted instead.
+ let mut s = tracked(&format!("{}{}", p("First"), p("Second")));
+ caret_at(&mut s, 1, 0);
+ run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ assert_eq!(texts(&s), vec!["First", "Second"]);
+ assert!(xml(&s).contains("<w:rPr><w:del "), "{}", xml(&s));
+}
+
+#[test]
+fn accepting_and_rejecting_changes() {
+ let mut s = tracked(&p("The fee is ten dollars."));
+ // Replace "ten" with "twenty".
+ select(&mut s, (0, 11), (0, 14));
+ type_text(&mut s, "twenty");
+ assert_eq!(texts(&s), vec!["The fee is tentwenty dollars."]);
+ let before = xml(&s);
+ assert!(before.contains("<w:delText>ten</w:delText>"), "{before}");
+
+ // Rejecting everything restores the original.
+ let mut rejected = tracked(&p("The fee is ten dollars."));
+ select(&mut rejected, (0, 11), (0, 14));
+ type_text(&mut rejected, "twenty");
+ run(&mut rejected, EditOp::RejectChanges { all: true });
+ assert_eq!(texts(&rejected), vec!["The fee is ten dollars."]);
+ assert!(!xml(&rejected).contains("<w:ins "));
+ assert!(!xml(&rejected).contains("<w:del "));
+
+ // Accepting at the caret takes just the change there.
+ caret_at(&mut s, 0, 12);
+ let r = run(&mut s, EditOp::AcceptChanges { all: false });
+ assert!(r.changed);
+ assert_eq!(texts(&s), vec!["The fee is twenty dollars."]);
+ // The insertion was a separate revision; it is still there.
+ assert!(xml(&s).contains("<w:ins "));
+ run(&mut s, EditOp::AcceptChanges { all: true });
+ assert!(!xml(&s).contains("<w:ins "));
+ assert_eq!(texts(&s), vec!["The fee is twenty dollars."]);
+}
+
+#[test]
+fn accepting_a_deleted_paragraph_mark_joins_the_paragraphs() {
+ let mut s = tracked(&format!("{}{}", p("First"), p("Second")));
+ caret_at(&mut s, 1, 0);
+ run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ run(&mut s, EditOp::AcceptChanges { all: true });
+ assert_eq!(texts(&s), vec!["FirstSecond"]);
+}
+
+#[test]
+fn word_revisions_by_other_authors_resolve_by_id() {
+ let body = r#"<w:p><w:r><w:t xml:space="preserve">Pay </w:t></w:r><w:del w:id="7" w:author="Bob" w:date="2025-01-01T00:00:00Z"><w:r><w:delText>30</w:delText></w:r></w:del><w:ins w:id="8" w:author="Bob" w:date="2025-01-01T00:00:00Z"><w:r><w:t>45</w:t></w:r></w:ins><w:r><w:t xml:space="preserve"> days</w:t></w:r></w:p>"#;
+ let mut s = tracked(body);
+ assert_eq!(texts(&s), vec!["Pay 3045 days"]);
+ // The caret inside "45" is in revision 8 only.
+ caret_at(&mut s, 0, 7);
+ run(&mut s, EditOp::RejectChanges { all: false });
+ assert_eq!(texts(&s), vec!["Pay 30 days"]);
+ let out = xml(&s);
+ assert!(out.contains("<w:del w:id=\"7\""), "{out}");
+ caret_at(&mut s, 0, 5);
+ run(&mut s, EditOp::RejectChanges { all: false });
+ assert_eq!(texts(&s), vec!["Pay 30 days"]);
+ assert!(!xml(&s).contains("<w:del "));
+}
+
+#[test]
+fn turning_tracking_on_writes_the_shared_setting() {
+ let mut s = open_with(
+ &p("Text"),
+ &Parts {
+ settings: Some("<w:defaultTabStop w:val=\"720\"/>"),
+ ..Parts::default()
+ },
+ );
+ let r = run(&mut s, EditOp::SetTracking { on: true });
+ assert!(r.format.tracking);
+ let entry = r.changes.iter().find_map(|c| match c {
+ Change::Entry {
+ key,
+ value: Some(v),
+ ..
+ } if key.ends_with("settings.xml") => Some(v.clone()),
+ _ => None,
+ });
+ let settings = entry.expect("settings entry");
+ // In schema order: before the default tab stop.
+ let track = settings.find("<w:trackRevisions/>").expect("setting");
+ assert!(
+ track < settings.find("defaultTabStop").unwrap(),
+ "{settings}"
+ );
+ // Typing is now tracked.
+ caret_at(&mut s, 0, 4);
+ type_text(&mut s, "!");
+ assert!(xml(&s).contains("<w:ins "));
+ let r = run(&mut s, EditOp::SetTracking { on: false });
+ assert!(!r.format.tracking);
+ type_text(&mut s, "?");
+ assert_eq!(count(&xml(&s), "<w:ins "), 1);
+ assert_eq!(texts(&s), vec!["Text!?"]);
+}
+
+#[test]
+fn formatting_while_tracking_is_recorded_and_can_be_rejected() {
+ let mut s = tracked(&p("Pay the Seller"));
+ select(&mut s, (0, 8), (0, 14));
+ run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Bold,
+ },
+ );
+ let out = xml(&s);
+ assert!(out.contains("<w:rPrChange"), "{out}");
+ assert!(out.contains("w:author=\"Alice\""), "{out}");
+ assert_eq!(count(&out, "<w:b/>"), 1, "{out}");
+ let r = s.state(fonts());
+ assert!(r.format.revision);
+ // A second change keeps the first record (the formatting before both).
+ run(
+ &mut s,
+ EditOp::SetFormat {
+ patch: RunPatch {
+ color: Some(Some("FF0000".into())),
+ ..RunPatch::default()
+ },
+ },
+ );
+ let out = xml(&s);
+ assert_eq!(count(&out, "<w:rPrChange"), 1, "{out}");
+ // Rejecting restores the plain text.
+ run(&mut s, EditOp::RejectChanges { all: true });
+ let out = xml(&s);
+ assert!(
+ !out.contains("rPrChange") && !out.contains("<w:b/>"),
+ "{out}"
+ );
+ assert!(!out.contains("FF0000"), "{out}");
+ assert_eq!(texts(&s), vec!["Pay the Seller"]);
+}
+
+#[test]
+fn formatting_new_text_records_nothing() {
+ let mut s = tracked(&p("Hello"));
+ caret_at(&mut s, 0, 5);
+ type_text(&mut s, " world");
+ select(&mut s, (0, 6), (0, 11));
+ run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Italic,
+ },
+ );
+ let out = xml(&s);
+ assert!(!out.contains("rPrChange"), "{out}");
+ assert!(out.contains("<w:i/>"), "{out}");
+}
+
+fn align(s: &mut Session, a: Alignment) {
+ run(
+ s,
+ EditOp::SetParagraph {
+ patch: ParaPatch {
+ align: Some(a),
+ ..ParaPatch::default()
+ },
+ },
+ );
+}
+
+#[test]
+fn paragraph_formatting_while_tracking_is_recorded_and_can_be_rejected() {
+ let mut s = tracked(&p("Recitals"));
+ caret_at(&mut s, 0, 3);
+ align(&mut s, Alignment::Center);
+ let out = xml(&s);
+ assert_eq!(count(&out, "<w:pPrChange"), 1, "{out}");
+ assert!(out.contains(r#"<w:jc w:val="center"/>"#), "{out}");
+ // Accepting keeps the new alignment and drops the record.
+ run(&mut s, EditOp::AcceptChanges { all: true });
+ let out = xml(&s);
+ assert!(!out.contains("pPrChange"), "{out}");
+ assert!(out.contains(r#"<w:jc w:val="center"/>"#), "{out}");
+ // Two more changes keep one record; rejecting the change at the caret
+ // goes back to centered.
+ align(&mut s, Alignment::Right);
+ align(&mut s, Alignment::Justify);
+ assert_eq!(count(&xml(&s), "<w:pPrChange"), 1);
+ assert!(s.state(fonts()).format.revision);
+ run(&mut s, EditOp::RejectChanges { all: false });
+ let out = xml(&s);
+ assert!(!out.contains("pPrChange"), "{out}");
+ assert!(out.contains(r#"<w:jc w:val="center"/>"#), "{out}");
+}
+
+#[test]
+fn formatting_changed_back_leaves_no_change() {
+ let mut s = tracked(&p("Pay the Seller"));
+ select(&mut s, (0, 8), (0, 14));
+ for _ in 0..2 {
+ run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Bold,
+ },
+ );
+ }
+ let out = xml(&s);
+ assert!(
+ !out.contains("rPrChange") && !out.contains("<w:b/>"),
+ "{out}"
+ );
+ for _ in 0..2 {
+ run(
+ &mut s,
+ EditOp::ToggleList {
+ kind: ListKind::Bullet,
+ },
+ );
+ }
+ let out = xml(&s);
+ assert!(
+ !out.contains("pPrChange") && !out.contains("numPr"),
+ "{out}"
+ );
+}
+
+#[test]
+fn list_changes_in_new_paragraphs_record_nothing() {
+ let mut s = tracked(&p("Terms"));
+ caret_at(&mut s, 0, 5);
+ run(&mut s, EditOp::InsertParagraph);
+ type_text(&mut s, "Price");
+ // The first paragraph's mark is the new one.
+ caret_at(&mut s, 0, 2);
+ run(
+ &mut s,
+ EditOp::ToggleList {
+ kind: ListKind::Number,
+ },
+ );
+ let out = xml(&s);
+ assert!(out.contains("numPr") && !out.contains("pPrChange"), "{out}");
+}
+
+#[test]
+fn replacing_an_attribute_leaves_others_with_the_same_value() {
+ let tag = r#"<w:footnoteReference w:customMarkFollows="1" w:id="1"/>"#;
+ assert_eq!(
+ super::with_attribute(tag, "id", "7").as_deref(),
+ Some(r#"<w:footnoteReference w:customMarkFollows="1" w:id="7"/>"#)
+ );
+ assert_eq!(super::attribute(tag, "id").as_deref(), Some("1"));
+ // A longer name ending in the same letters is not the attribute.
+ let para = r#"<w:p w14:paraId="1" w:id='2'>"#;
+ assert_eq!(
+ super::with_attribute(para, "id", "3").as_deref(),
+ Some(r#"<w:p w14:paraId="1" w:id='3'>"#)
+ );
+ assert_eq!(super::with_attribute("<w:b/>", "id", "3"), None);
+}
diff --git a/crates/docx_engine/src/edit/table.rs b/crates/docx_engine/src/edit/table.rs
new file mode 100644
index 0000000000..e1c5ca700a
--- /dev/null
+++ b/crates/docx_engine/src/edit/table.rs
@@ -0,0 +1,469 @@
+//! Tables: inserting them, and adding or removing rows and columns.
+
+use super::Pos;
+use super::text;
+use super::txn::Txn;
+use super::xmledit::{Element, TBLPR_ORDER, TCPR_ORDER, split_siblings};
+use crate::model::block::{Block, BlockId, BlockKind};
+use crate::xml::SnippetContext;
+
+fn q(w: &str, l: &str) -> String {
+ if w.is_empty() {
+ l.to_owned()
+ } else {
+ format!("{w}:{l}")
+ }
+}
+
+/// Table properties for a new table: the "Table Grid" style when the
+/// document has it, single borders otherwise.
+fn table_props(w: &str, grid_style: Option<&str>, cols: &[i64]) -> String {
+ let mut tbl_pr = format!("<{}>", q(w, "tblPr"));
+ if let Some(style) = grid_style {
+ tbl_pr.push_str(&format!(
+ "<{} {}=\"{style}\"/>",
+ q(w, "tblStyle"),
+ q(w, "val")
+ ));
+ }
+ tbl_pr.push_str(&format!(
+ "<{} {}=\"0\" {}=\"auto\"/>",
+ q(w, "tblW"),
+ q(w, "w"),
+ q(w, "type")
+ ));
+ if grid_style.is_none() {
+ tbl_pr.push_str(&format!("<{}>", q(w, "tblBorders")));
+ for side in ["top", "left", "bottom", "right", "insideH", "insideV"] {
+ tbl_pr.push_str(&format!(
+ "<{} {}=\"single\" {}=\"4\" {}=\"0\" {}=\"auto\"/>",
+ q(w, side),
+ q(w, "val"),
+ q(w, "sz"),
+ q(w, "space"),
+ q(w, "color")
+ ));
+ }
+ tbl_pr.push_str(&format!("</{}>", q(w, "tblBorders")));
+ }
+ tbl_pr.push_str(&format!(
+ "<{} {}=\"04A0\" {}=\"1\" {}=\"0\" {}=\"1\" {}=\"0\" {}=\"0\" {}=\"1\"/>",
+ q(w, "tblLook"),
+ q(w, "val"),
+ q(w, "firstRow"),
+ q(w, "lastRow"),
+ q(w, "firstColumn"),
+ q(w, "lastColumn"),
+ q(w, "noHBand"),
+ q(w, "noVBand")
+ ));
+ tbl_pr.push_str(&format!("</{}>", q(w, "tblPr")));
+ tbl_pr.push_str(&grid_xml(w, cols));
+ tbl_pr
+}
+
+fn grid_xml(w: &str, cols: &[i64]) -> String {
+ let mut s = format!("<{}>", q(w, "tblGrid"));
+ for c in cols {
+ s.push_str(&format!("<{} {}=\"{c}\"/>", q(w, "gridCol"), q(w, "w")));
+ }
+ s.push_str(&format!("</{}>", q(w, "tblGrid")));
+ s
+}
+
+fn cell_props(w: &str, width: i64) -> String {
+ format!(
+ "<{tcPr}><{tcW} {w_a}=\"{width}\" {type_a}=\"dxa\"/></{tcPr}>",
+ tcPr = q(w, "tcPr"),
+ tcW = q(w, "tcW"),
+ w_a = q(w, "w"),
+ type_a = q(w, "type")
+ )
+}
+
+/// Inserts a `rows` × `cols` table at `at` (splitting the paragraph when
+/// the caret is inside it) spanning `width` twips. Returns the first cell's
+/// position.
+pub(super) fn insert_table(
+ txn: &mut Txn<'_>,
+ at: &Pos,
+ rows: usize,
+ cols: usize,
+ width: i64,
+ grid_style: Option<&str>,
+) -> Option<Pos> {
+ let rows = rows.clamp(1, 200);
+ let cols = cols.clamp(1, 63);
+ let w = txn.doc.w_prefix().to_owned();
+ let p = txn.get(&at.block)?.clone();
+ let len = p.content.len();
+ // Where the table goes: before the paragraph at its start, after it
+ // at its end, between its halves in the middle.
+ let (parent, after) = if at.offset == 0 && len > 0 {
+ let prev = {
+ let kids = txn.story().children(p.parent.as_ref());
+ let i = kids.iter().position(|k| *k == p.id)?;
+ i.checked_sub(1).map(|j| kids[j].clone())
+ };
+ (p.parent.clone(), prev)
+ } else if at.offset >= len {
+ (p.parent.clone(), Some(p.id.clone()))
+ } else {
+ text::split(txn, at)?;
+ (p.parent.clone(), Some(p.id.clone()))
+ };
+ let col_w = (width / cols as i64).max(200);
+ let grid: Vec<i64> = vec![col_w; cols];
+ let order = txn.story().key_after(parent.as_ref(), after.as_ref());
+ let table_id = txn.new_id();
+ let mut table = Block::new(table_id.clone(), BlockKind::Table, parent.clone(), order);
+ table.props = table_props(&w, grid_style, &grid);
+ txn.insert(table);
+ let row_keys = crate::model::block::initial_keys(rows);
+ let cell_keys = crate::model::block::initial_keys(cols);
+ let mut first: Option<BlockId> = None;
+ for rk in row_keys {
+ let row_id = txn.new_id();
+ txn.insert(Block::new(
+ row_id.clone(),
+ BlockKind::Row,
+ Some(table_id.clone()),
+ rk,
+ ));
+ for ck in &cell_keys {
+ let cell_id = txn.new_id();
+ let mut cell = Block::new(
+ cell_id.clone(),
+ BlockKind::Cell,
+ Some(row_id.clone()),
+ ck.clone(),
+ );
+ cell.props = cell_props(&w, col_w);
+ txn.insert(cell);
+ let para_id = txn.new_id();
+ let key = crate::model::block::initial_keys(1).remove(0);
+ txn.insert(Block::new(
+ para_id.clone(),
+ BlockKind::Paragraph,
+ Some(cell_id),
+ key,
+ ));
+ first.get_or_insert(para_id);
+ }
+ }
+ // A table never ends its container: a paragraph follows it.
+ let kids = txn.story().children(parent.as_ref()).to_vec();
+ if kids.last() == Some(&table_id) {
+ let order = txn.story().key_after(parent.as_ref(), Some(&table_id));
+ let id = txn.new_id();
+ txn.insert(Block::new(id, BlockKind::Paragraph, parent.clone(), order));
+ }
+ first.map(|b| Pos::new(b, 0))
+}
+
+/// The cell, row and table around a paragraph.
+pub(super) fn enclosing(txn: &Txn<'_>, para: &BlockId) -> Option<(BlockId, BlockId, BlockId)> {
+ let mut at = txn.get(para)?.parent.clone();
+ while let Some(id) = at {
+ let b = txn.get(&id)?;
+ if b.kind == BlockKind::Cell {
+ let row = b.parent.clone()?;
+ let table = txn.get(&row)?.parent.clone()?;
+ return Some((id, row, table));
+ }
+ at = b.parent.clone();
+ }
+ None
+}
+
+/// An empty copy of a cell (its properties without merge markers, one
+/// paragraph with the first paragraph's properties).
+fn empty_cell_like(txn: &mut Txn<'_>, cell: &BlockId, row: &BlockId, order: String) -> BlockId {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = std::sync::Arc::clone(txn.doc.decls());
+ let props = txn.get(cell).map(|c| c.props.clone()).unwrap_or_default();
+ let mut e = Element::open(&props, "tcPr", &w, &decls, TCPR_ORDER);
+ e.set("vMerge", None);
+ e.set("hMerge", None);
+ let first_ppr = txn
+ .story()
+ .children(Some(cell))
+ .iter()
+ .filter_map(|k| txn.get(k))
+ .find(|b| b.kind == BlockKind::Paragraph)
+ .map(|b| b.props.clone())
+ .unwrap_or_default();
+ let id = txn.new_id();
+ let mut c = Block::new(id.clone(), BlockKind::Cell, Some(row.clone()), order);
+ c.props = e.finish(true);
+ txn.insert(c);
+ let pid = txn.new_id();
+ let mut p = Block::new(
+ pid,
+ BlockKind::Paragraph,
+ Some(id.clone()),
+ crate::model::block::initial_keys(1).remove(0),
+ );
+ p.props = first_ppr;
+ txn.insert(p);
+ id
+}
+
+/// Inserts a row above or below the one holding `para`; returns its first
+/// paragraph.
+pub(super) fn insert_row(txn: &mut Txn<'_>, para: &BlockId, below: bool) -> Option<Pos> {
+ let (_, row, table) = enclosing(txn, para)?;
+ let order = if below {
+ txn.story().key_after(Some(&table), Some(&row))
+ } else {
+ txn.story().key_before(Some(&table), &row)
+ };
+ let source = txn.get(&row)?.clone();
+ let id = txn.new_id();
+ let mut r = Block::new(id.clone(), BlockKind::Row, Some(table.clone()), order);
+ r.props = source.props.clone();
+ r.attrs = text::strip_ids(&source.attrs);
+ txn.insert(r);
+ let cells: Vec<BlockId> = txn.story().children(Some(&row)).to_vec();
+ let keys = crate::model::block::initial_keys(cells.len());
+ for (c, k) in cells.iter().zip(keys) {
+ empty_cell_like(txn, c, &id, k);
+ }
+ let first_cell = txn.story().children(Some(&id)).first().cloned()?;
+ let p = txn.story().children(Some(&first_cell)).first().cloned()?;
+ Some(Pos::new(p, 0))
+}
+
+/// Removes the row holding `para` (the whole table when it is the last).
+/// Returns where the caret goes.
+pub(super) fn delete_row(txn: &mut Txn<'_>, para: &BlockId) -> Option<Pos> {
+ let (_, row, table) = enclosing(txn, para)?;
+ let rows: Vec<BlockId> = txn.story().children(Some(&table)).to_vec();
+ if rows.len() <= 1 {
+ return delete_table(txn, para);
+ }
+ let i = rows.iter().position(|r| *r == row)?;
+ let next = rows
+ .get(i + 1)
+ .or_else(|| i.checked_sub(1).and_then(|j| rows.get(j)))
+ .cloned()?;
+ txn.remove(&row);
+ let cell = txn.story().children(Some(&next)).first().cloned()?;
+ let p = txn.story().children(Some(&cell)).first().cloned()?;
+ Some(Pos::new(p, 0))
+}
+
+/// Removes the table holding `para`; the caret goes to the block after it.
+pub(super) fn delete_table(txn: &mut Txn<'_>, para: &BlockId) -> Option<Pos> {
+ let (_, _, table) = enclosing(txn, para)?;
+ let parent = txn.get(&table)?.parent.clone();
+ let kids: Vec<BlockId> = txn.story().children(parent.as_ref()).to_vec();
+ let i = kids.iter().position(|k| *k == table)?;
+ txn.remove(&table);
+ // The paragraph after the table, or before it, or a new one.
+ let near = kids
+ .get(i + 1)
+ .into_iter()
+ .chain(i.checked_sub(1).and_then(|j| kids.get(j)))
+ .find(|k| txn.get(k).is_some_and(|b| b.kind == BlockKind::Paragraph))
+ .cloned();
+ let p = match near {
+ Some(p) => p,
+ None => {
+ let order = txn.story().key_after(parent.as_ref(), None);
+ let id = txn.new_id();
+ txn.insert(Block::new(id.clone(), BlockKind::Paragraph, parent, order));
+ id
+ }
+ };
+ Some(Pos::new(p, 0))
+}
+
+/// The table's grid column widths and the rest of its properties.
+fn grid(txn: &Txn<'_>, table: &BlockId) -> (Vec<i64>, Vec<super::xmledit::Child>) {
+ let decls = txn.doc.decls();
+ let props = txn.get(table).map(|t| t.props.clone()).unwrap_or_default();
+ let parts = split_siblings(&props, decls);
+ let mut cols = Vec::new();
+ if let Some(g) = parts.iter().find(|c| c.local() == "tblGrid")
+ && let Ok(t) = SnippetContext::new(decls).parse(&g.xml)
+ {
+ for c in t.children(t.root()) {
+ cols.push(
+ t.w_attr(c, "w")
+ .and_then(crate::xml::parse_int)
+ .unwrap_or(0),
+ );
+ }
+ }
+ (cols, parts)
+}
+
+fn set_grid(txn: &mut Txn<'_>, table: &BlockId, cols: &[i64], parts: Vec<super::xmledit::Child>) {
+ let w = txn.doc.w_prefix().to_owned();
+ let mut out = String::new();
+ let mut wrote = false;
+ for p in parts {
+ if p.local() == "tblGrid" {
+ out.push_str(&grid_xml(&w, cols));
+ wrote = true;
+ } else {
+ out.push_str(&p.xml);
+ }
+ }
+ if !wrote {
+ out.push_str(&grid_xml(&w, cols));
+ }
+ if let Some(t) = txn.block_mut(table) {
+ t.props = out;
+ }
+}
+
+/// Column index of a cell (counting spans).
+fn column_of(txn: &Txn<'_>, row: &BlockId, cell: &BlockId) -> usize {
+ let decls = txn.doc.decls();
+ let mut col = 0;
+ for c in txn.story().children(Some(row)) {
+ if c == cell {
+ return col;
+ }
+ let span = txn
+ .get(c)
+ .and_then(|b| SnippetContext::new(decls).parse(&b.props).ok())
+ .and_then(|t| {
+ t.w_child(t.root(), "gridSpan")
+ .and_then(|g| t.val(g))
+ .and_then(crate::xml::parse_int)
+ })
+ .unwrap_or(1)
+ .max(1) as usize;
+ col += span;
+ }
+ col
+}
+
+/// The cell of `row` covering grid column `col`.
+fn cell_at(txn: &Txn<'_>, row: &BlockId, col: usize) -> Option<BlockId> {
+ let cells: Vec<BlockId> = txn.story().children(Some(row)).to_vec();
+ let mut best = None;
+ for c in cells {
+ if column_of(txn, row, &c) <= col {
+ best = Some(c);
+ }
+ }
+ best
+}
+
+/// Inserts a column left or right of the one holding `para`, narrowing the
+/// others so the table keeps its width.
+pub(super) fn insert_column(txn: &mut Txn<'_>, para: &BlockId, right: bool) -> Option<Pos> {
+ let (cell, row, table) = enclosing(txn, para)?;
+ let col = column_of(txn, &row, &cell);
+ let (mut cols, parts) = grid(txn, &table);
+ let total: i64 = cols.iter().sum();
+ let new_w = cols.get(col).copied().unwrap_or(1440).max(400);
+ let at = if right { col + 1 } else { col };
+ cols.insert(at.min(cols.len()), new_w);
+ if total > 0 {
+ let sum: i64 = cols.iter().sum();
+ for c in &mut cols {
+ *c = (*c * total / sum).max(200);
+ }
+ }
+ let rows: Vec<BlockId> = txn.story().children(Some(&table)).to_vec();
+ let mut result = None;
+ for r in rows {
+ let Some(source) = cell_at(txn, &r, col) else {
+ continue;
+ };
+ let order = if right {
+ txn.story().key_after(Some(&r), Some(&source))
+ } else {
+ txn.story().key_before(Some(&r), &source)
+ };
+ let id = empty_cell_like(txn, &source, &r, order);
+ if r == row {
+ let p = txn.story().children(Some(&id)).first().cloned();
+ result = p.map(|p| Pos::new(p, 0));
+ }
+ }
+ resize_cells(txn, &table, &cols);
+ set_grid(txn, &table, &cols, parts);
+ result
+}
+
+/// Removes the column holding `para` (the table when it is the last).
+pub(super) fn delete_column(txn: &mut Txn<'_>, para: &BlockId) -> Option<Pos> {
+ let (cell, row, table) = enclosing(txn, para)?;
+ let col = column_of(txn, &row, &cell);
+ let (mut cols, parts) = grid(txn, &table);
+ if cols.len() <= 1 || txn.story().children(Some(&row)).len() <= 1 {
+ return delete_table(txn, para);
+ }
+ let removed_w = if col < cols.len() {
+ cols.remove(col)
+ } else {
+ 0
+ };
+ let total: i64 = cols.iter().sum();
+ if total > 0 {
+ for c in &mut cols {
+ *c += removed_w * *c / total;
+ }
+ }
+ let rows: Vec<BlockId> = txn.story().children(Some(&table)).to_vec();
+ for r in &rows {
+ if let Some(c) = cell_at(txn, r, col)
+ && txn.story().children(Some(r)).len() > 1
+ {
+ txn.remove(&c);
+ }
+ }
+ resize_cells(txn, &table, &cols);
+ set_grid(txn, &table, &cols, parts);
+ let target = cell_at(txn, &row, col.saturating_sub(1))?;
+ let p = txn.story().children(Some(&target)).first().cloned()?;
+ Some(Pos::new(p, 0))
+}
+
+/// Sets each cell's width from the grid.
+fn resize_cells(txn: &mut Txn<'_>, table: &BlockId, cols: &[i64]) {
+ let w = txn.doc.w_prefix().to_owned();
+ let decls = std::sync::Arc::clone(txn.doc.decls());
+ let rows: Vec<BlockId> = txn.story().children(Some(table)).to_vec();
+ for r in rows {
+ let cells: Vec<BlockId> = txn.story().children(Some(&r)).to_vec();
+ let mut col = 0;
+ for c in cells {
+ let props = txn.get(&c).map(|b| b.props.clone()).unwrap_or_default();
+ let span = SnippetContext::new(&decls)
+ .parse(&props)
+ .ok()
+ .and_then(|t| {
+ t.w_child(t.root(), "gridSpan")
+ .and_then(|g| t.val(g))
+ .and_then(crate::xml::parse_int)
+ })
+ .unwrap_or(1)
+ .max(1) as usize;
+ let width: i64 = cols.iter().skip(col).take(span).sum();
+ col += span;
+ let mut e = Element::open(&props, "tcPr", &w, &decls, TCPR_ORDER);
+ e.set_attrs(
+ "tcW",
+ &[
+ ("w", Some(width.to_string())),
+ ("type", Some("dxa".to_owned())),
+ ],
+ &decls,
+ );
+ let xml = e.finish(false);
+ if xml != props
+ && let Some(b) = txn.block_mut(&c)
+ {
+ b.props = xml;
+ }
+ }
+ }
+ let _ = TBLPR_ORDER;
+}
diff --git a/crates/docx_engine/src/edit/test.rs b/crates/docx_engine/src/edit/test.rs
new file mode 100644
index 0000000000..adb30ea070
--- /dev/null
+++ b/crates/docx_engine/src/edit/test.rs
@@ -0,0 +1,1271 @@
+use super::test_util::*;
+use super::*;
+use crate::model::content::{Content, DeltaOp, Span};
+use crate::test_support::{NS, Parts, fonts};
+
+#[test]
+fn typing_inserts_text_and_reports_a_delta() {
+ let mut s = open(&p("Hello"));
+ caret_at(&mut s, 0, 5);
+ let r = type_text(&mut s, " world");
+ assert_eq!(texts(&s), vec!["Hello world"]);
+ assert_eq!(r.selection.focus.offset, 11);
+ assert!(r.changed);
+ match &r.changes[..] {
+ [Change::Text { delta, .. }] => {
+ assert_eq!(delta.len(), 2, "{delta:?}");
+ assert!(matches!(delta[0], DeltaOp::Retain { retain: 5, .. }));
+ assert!(matches!(&delta[1], DeltaOp::Insert { insert, .. } if insert == " world"));
+ }
+ other => panic!("{other:?}"),
+ }
+ // The typed text has the formatting of the text before it.
+ let b = s.document().body().get(&para(&s, 0)).unwrap();
+ assert_eq!(b.content.spans().len(), 1);
+ assert!(r.caret.is_some());
+}
+
+#[test]
+fn enter_splits_and_backspace_joins() {
+ let mut s = open(&p("Hello world"));
+ caret_at(&mut s, 0, 5);
+ let first = para(&s, 0);
+ let r = run(&mut s, EditOp::InsertParagraph);
+ assert_eq!(texts(&s), vec!["Hello", " world"]);
+ // The first half keeps the paragraph's id.
+ assert_eq!(para(&s, 0), first);
+ assert_eq!(r.selection.focus.offset, 0);
+ assert_eq!(r.selection.focus.block, para(&s, 1));
+ assert!(r.changes.iter().any(|c| matches!(c, Change::Block { .. })));
+ assert!(r.changes.iter().any(|c| matches!(c, Change::Text { .. })));
+ let r = run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ assert_eq!(texts(&s), vec!["Hello world"]);
+ assert_eq!(r.selection.focus, Pos::new(first.clone(), 5));
+ assert!(r.changes.iter().any(|c| matches!(c, Change::Remove { .. })));
+}
+
+#[test]
+fn enter_at_the_start_keeps_the_text_paragraph() {
+ let mut s = open(&p("Text"));
+ let id = para(&s, 0);
+ caret_at(&mut s, 0, 0);
+ run(&mut s, EditOp::InsertParagraph);
+ assert_eq!(texts(&s), vec!["", "Text"]);
+ assert_eq!(para(&s, 1), id);
+ assert_eq!(s.selection().focus, Pos::new(id, 0));
+}
+
+#[test]
+fn deleting_across_paragraphs_joins_the_ends() {
+ let mut s = open(&format!("{}{}{}", p("One two"), p("Three"), p("Four five")));
+ select(&mut s, (0, 3), (2, 4));
+ run(
+ &mut s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+ assert_eq!(texts(&s), vec!["One five"]);
+ assert_eq!(s.selection().focus.offset, 3);
+}
+
+#[test]
+fn typing_over_a_selection_replaces_it() {
+ let mut s = open(&format!("{}{}", p("abc"), p("def")));
+ select(&mut s, (1, 2), (0, 1));
+ type_text(&mut s, "X");
+ assert_eq!(texts(&s), vec!["aXf"]);
+}
+
+#[test]
+fn deleting_into_a_table_empties_covered_cells() {
+ let cell = |t: &str| format!("<w:tc>{}</w:tc>", p(t));
+ let body = format!(
+ "{}<w:tbl><w:tblGrid><w:gridCol w:w=\"2000\"/><w:gridCol w:w=\"2000\"/></w:tblGrid><w:tr>{}{}</w:tr><w:tr>{}{}</w:tr></w:tbl>{}",
+ p("Before"),
+ cell("A1"),
+ cell("B1"),
+ cell("A2"),
+ cell("B2"),
+ p("After")
+ );
+ let mut s = open(&body);
+ // From inside "Before" to the middle of B2.
+ select(&mut s, (0, 3), (4, 1));
+ run(
+ &mut s,
+ EditOp::Delete {
+ forward: true,
+ unit: Unit::Char,
+ },
+ );
+ // The fully covered first row goes; the covered cell of the second is emptied.
+ assert_eq!(texts(&s), vec!["Bef", "", "2", "After"]);
+ let rows = s
+ .document()
+ .body()
+ .blocks()
+ .filter(|b| b.kind == BlockKind::Row)
+ .count();
+ assert_eq!(rows, 1);
+}
+
+#[test]
+fn a_whole_table_in_the_range_goes() {
+ let body = format!(
+ "{}<w:tbl><w:tr><w:tc>{}</w:tc></w:tr></w:tbl>{}",
+ p("Before"),
+ p("Cell"),
+ p("After")
+ );
+ let mut s = open(&body);
+ select(&mut s, (0, 2), (2, 2));
+ type_text(&mut s, "-");
+ assert_eq!(texts(&s), vec!["Be-ter"]);
+ assert!(
+ s.document()
+ .body()
+ .blocks()
+ .all(|b| b.kind == BlockKind::Paragraph)
+ );
+}
+
+#[test]
+fn toggling_bold_sets_and_clears_direct_formatting() {
+ let mut s = open(&p("Hello world"));
+ select(&mut s, (0, 0), (0, 5));
+ let r = run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Bold,
+ },
+ );
+ assert!(r.format.bold);
+ let b = s.document().body().get(&para(&s, 0)).unwrap();
+ assert_eq!(b.content.spans().len(), 2);
+ assert_eq!(b.content.spans()[0].attrs.get("r:w:b"), Some("<w:b/>"));
+ assert_eq!(b.content.spans()[0].attrs.get("r:w:bCs"), Some("<w:bCs/>"));
+ // Only attributes changed: the delta retains with attributes.
+ match &r.changes[..] {
+ [Change::Text { delta, .. }] => {
+ assert!(
+ matches!(&delta[0], DeltaOp::Retain { retain: 5, attributes } if attributes.contains_key("r:w:b"))
+ );
+ }
+ other => panic!("{other:?}"),
+ }
+ let r = run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Bold,
+ },
+ );
+ assert!(!r.format.bold);
+ let b = s.document().body().get(&para(&s, 0)).unwrap();
+ assert_eq!(b.content.spans().len(), 1);
+}
+
+#[test]
+fn toggling_off_style_bold_writes_an_explicit_off() {
+ let styles = r#"<w:style w:type="paragraph" w:styleId="Strong"><w:name w:val="Strong"/><w:rPr><w:b/></w:rPr></w:style>"#;
+ let body = r#"<w:p><w:pPr><w:pStyle w:val="Strong"/></w:pPr><w:r><w:t>Bold</w:t></w:r></w:p>"#;
+ let mut s = open_with(
+ body,
+ &Parts {
+ styles: Some(styles),
+ ..Parts::default()
+ },
+ );
+ select(&mut s, (0, 0), (0, 4));
+ let r = run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Bold,
+ },
+ );
+ assert!(!r.format.bold);
+ let b = s.document().body().get(&para(&s, 0)).unwrap();
+ assert_eq!(
+ b.content.spans()[0].attrs.get("r:w:b"),
+ Some(r#"<w:b w:val="0"/>"#)
+ );
+}
+
+#[test]
+fn formatting_at_a_caret_applies_to_typed_text() {
+ let mut s = open(&p("ab"));
+ caret_at(&mut s, 0, 1);
+ let r = run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Italic,
+ },
+ );
+ assert!(r.format.italic);
+ assert!(!r.changed);
+ type_text(&mut s, "X");
+ let b = s.document().body().get(&para(&s, 0)).unwrap();
+ let spans: Vec<(&str, bool)> = b
+ .content
+ .spans()
+ .iter()
+ .map(|sp| (sp.text.as_str(), sp.attrs.has("r:w:i")))
+ .collect();
+ assert_eq!(spans, vec![("a", false), ("X", true), ("b", false)]);
+}
+
+#[test]
+fn set_format_and_paragraph_properties() {
+ let mut s = open(&p("Text"));
+ select(&mut s, (0, 0), (0, 4));
+ let r = run(
+ &mut s,
+ EditOp::SetFormat {
+ patch: RunPatch {
+ size: Some(Some(14.0)),
+ color: Some(Some("#ff0000".into())),
+ font: Some(Some("Arial".into())),
+ highlight: None,
+ },
+ },
+ );
+ assert_eq!(r.format.size, Some(14.0));
+ assert_eq!(r.format.color.as_deref(), Some("FF0000"));
+ assert_eq!(r.format.font.as_deref(), Some("Arial"));
+ let r = run(
+ &mut s,
+ EditOp::SetParagraph {
+ patch: ParaPatch {
+ align: Some(Alignment::Center),
+ space_after: Some(12.0),
+ ..ParaPatch::default()
+ },
+ },
+ );
+ assert_eq!(r.format.align, Some(Alignment::Center));
+ let b = s.document().body().get(&para(&s, 0)).unwrap();
+ assert_eq!(
+ b.props,
+ r#"<w:pPr><w:spacing w:after="240"/><w:jc w:val="center"/></w:pPr>"#
+ );
+ assert!(
+ r.changes
+ .iter()
+ .any(|c| matches!(c, Change::Fields { fields, .. } if fields.contains_key("x")))
+ );
+}
+
+#[test]
+fn json_operations_parse() {
+ let ops: Vec<EditOp> = serde_json::from_str(
+ r#"[{"op":"insertText","text":"a"},{"op":"move","unit":"word","forward":true,"extend":true},
+ {"op":"setFormat","size":12,"color":null},{"op":"toggleFormat","format":"bold"},
+ {"op":"setParagraph","align":"justify","lineSpacing":{"rule":"auto","value":1.5}},
+ {"op":"delete","forward":false},{"op":"insertBreak","kind":"page"}]"#,
+ )
+ .unwrap();
+ assert_eq!(ops.len(), 7);
+ match &ops[2] {
+ EditOp::SetFormat { patch } => {
+ assert_eq!(patch.size, Some(Some(12.0)));
+ assert_eq!(patch.color, Some(None));
+ assert_eq!(patch.font, None);
+ }
+ other => panic!("{other:?}"),
+ }
+}
+
+#[test]
+fn undo_and_redo_restore_the_document() {
+ let mut s = open(&p("Hello"));
+ caret_at(&mut s, 0, 5);
+ type_text(&mut s, " a");
+ type_text(&mut s, "b");
+ run(&mut s, EditOp::InsertParagraph);
+ type_text(&mut s, "Next");
+ assert_eq!(texts(&s), vec!["Hello ab", "Next"]);
+ s.undo(fonts()).unwrap();
+ assert_eq!(texts(&s), vec!["Hello ab", ""]);
+ s.undo(fonts()).unwrap();
+ assert_eq!(texts(&s), vec!["Hello ab"]);
+ // Typing merged into one step.
+ let r = s.undo(fonts()).unwrap();
+ assert_eq!(texts(&s), vec!["Hello"]);
+ assert_eq!(r.selection.focus.offset, 5);
+ assert!(s.undo(fonts()).is_none());
+ s.redo(fonts()).unwrap();
+ s.redo(fonts()).unwrap();
+ assert_eq!(texts(&s), vec!["Hello ab", ""]);
+ s.redo(fonts()).unwrap();
+ assert_eq!(texts(&s), vec!["Hello ab", "Next"]);
+}
+
+#[test]
+fn caret_geometry_and_hit_testing_agree() {
+ let mut s = open(&p("The quick brown fox jumps over the lazy dog."));
+ let block = para(&s, 0);
+ let mut last_x = -1.0;
+ for offset in [0, 4, 10, 20, 44] {
+ let c = s
+ .caret_at(&Pos::new(block.clone(), offset), fonts())
+ .unwrap();
+ assert!(c.x > last_x, "offset {offset}: {c:?}");
+ last_x = c.x;
+ assert_eq!(c.page, 0);
+ let hit = s
+ .hit_test(0, c.x + 0.5, c.y + c.height / 2.0, fonts())
+ .unwrap();
+ assert_eq!(hit.offset, offset);
+ assert_eq!(hit.block, block);
+ }
+}
+
+#[test]
+fn moving_by_characters_words_and_lines() {
+ let long = "word ".repeat(60);
+ let mut s = open(&format!("{}{}", p("ab cd"), p(long.trim_end())));
+ caret_at(&mut s, 0, 0);
+ let mv = |s: &mut Session, unit: Unit, forward: bool| {
+ run(
+ s,
+ EditOp::Move {
+ unit,
+ forward,
+ extend: false,
+ visual: false,
+ },
+ )
+ .selection
+ .focus
+ };
+ assert_eq!(mv(&mut s, Unit::Char, true).offset, 1);
+ assert_eq!(mv(&mut s, Unit::Word, true).offset, 3);
+ assert_eq!(mv(&mut s, Unit::LineBoundary, true).offset, 5);
+ // Past the end of the paragraph into the next.
+ let next = mv(&mut s, Unit::Char, true);
+ assert_eq!(next, Pos::new(para(&s, 1), 0));
+ // Down into the second line of the long paragraph.
+ let down = mv(&mut s, Unit::Line, true);
+ assert_eq!(down.block, para(&s, 1));
+ assert!(down.offset > 0, "{down:?}");
+ let up = mv(&mut s, Unit::Line, false);
+ assert_eq!(up.offset, 0);
+ assert_eq!(mv(&mut s, Unit::Char, false), Pos::new(para(&s, 0), 5));
+ // Extending keeps the anchor.
+ let r = run(
+ &mut s,
+ EditOp::Move {
+ unit: Unit::Word,
+ forward: false,
+ extend: true,
+ visual: false,
+ },
+ );
+ assert_eq!(r.selection.anchor.offset, 5);
+ assert_eq!(r.selection.focus.offset, 3);
+ assert!(!r.rects.is_empty());
+}
+
+#[test]
+fn word_and_paragraph_selection() {
+ let mut s = open(&p("Hello brave world"));
+ let block = para(&s, 0);
+ let r = run(
+ &mut s,
+ EditOp::SelectWord {
+ at: Pos::new(block.clone(), 8),
+ },
+ );
+ assert_eq!(
+ (r.selection.anchor.offset, r.selection.focus.offset),
+ (6, 11)
+ );
+ let r = run(
+ &mut s,
+ EditOp::SelectParagraph {
+ at: Pos::new(block, 3),
+ },
+ );
+ assert_eq!(
+ (r.selection.anchor.offset, r.selection.focus.offset),
+ (0, 17)
+ );
+}
+
+#[test]
+fn enter_on_an_empty_list_item_ends_the_list() {
+ let numbering = r#"<w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/></w:lvl></w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>"#;
+ let body = r#"<w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr><w:r><w:t>Item</w:t></w:r></w:p>"#;
+ let mut s = open_with(
+ body,
+ &Parts {
+ numbering: Some(numbering),
+ ..Parts::default()
+ },
+ );
+ caret_at(&mut s, 0, 4);
+ let r = run(&mut s, EditOp::InsertParagraph);
+ assert!(r.format.list);
+ let r = run(&mut s, EditOp::InsertParagraph);
+ assert!(!r.format.list);
+ assert_eq!(texts(&s), vec!["Item", ""]);
+}
+
+#[test]
+fn page_breaks_add_a_page() {
+ let mut s = open(&p("Before"));
+ caret_at(&mut s, 0, 6);
+ let r = run(
+ &mut s,
+ EditOp::InsertBreak {
+ kind: BreakKind::Page,
+ },
+ );
+ type_text(&mut s, "After");
+ assert_eq!(s.pages(fonts()).len(), 2);
+ assert!(r.pages.is_some());
+}
+
+#[test]
+fn page_fingerprints_change_only_where_content_changed() {
+ let mut paras = String::new();
+ for i in 0..80 {
+ paras.push_str(&p(&format!(
+ "Paragraph number {i} with some text to fill the line."
+ )));
+ }
+ let mut s = open(&paras);
+ let before = s.pages(fonts());
+ assert!(before.len() >= 2);
+ caret_at(&mut s, 0, 0);
+ let r = type_text(&mut s, "x");
+ let after = r.pages.expect("relaid");
+ assert_eq!(after.len(), before.len());
+ assert_ne!(before[0].fingerprint, after[0].fingerprint);
+ assert_eq!(before.last(), after.last());
+}
+
+#[test]
+fn edits_save_and_reopen() {
+ let mut s = open(&p("Hello"));
+ caret_at(&mut s, 0, 5);
+ type_text(&mut s, " world");
+ run(&mut s, EditOp::InsertParagraph);
+ type_text(&mut s, "Second");
+ select(&mut s, (1, 0), (1, 6));
+ run(
+ &mut s,
+ EditOp::ToggleFormat {
+ format: Toggle::Bold,
+ },
+ );
+ let bytes = s.save().unwrap();
+ let doc = Document::open(bytes).unwrap();
+ let t: Vec<String> = doc
+ .body()
+ .paragraphs()
+ .iter()
+ .map(|id| doc.body().get(id).unwrap().content.text())
+ .collect();
+ assert_eq!(t, vec!["Hello world", "Second"]);
+ let second = doc.body().get(&doc.body().paragraphs()[1]).unwrap();
+ assert!(second.content.spans()[0].attrs.has("r:w:b"));
+ let xml = doc.document_xml();
+ assert!(
+ xml.contains(
+ NS.split_whitespace()
+ .next()
+ .unwrap()
+ .split('=')
+ .next()
+ .unwrap()
+ )
+ );
+}
+
+/// Deterministic pseudo-random numbers.
+struct Rng(u64);
+
+impl Rng {
+ fn next(&mut self, n: usize) -> usize {
+ self.0 = self
+ .0
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ ((self.0 >> 33) as usize) % n.max(1)
+ }
+}
+
+#[test]
+fn content_deltas_reproduce_random_edits() {
+ let mut rng = Rng(7);
+ let attrs = [
+ Attrs::empty(),
+ Attrs::from_pairs([("r:w:b", "<w:b/>")]),
+ Attrs::from_pairs([("r:w:i", "<w:i/>")]),
+ Attrs::from_pairs([("r:w:b", "<w:b/>"), ("r:w:i", "<w:i/>")]),
+ ];
+ let words = ["alpha", " ", "βeta", "😀", "x", "\t", "longer text"];
+ for _ in 0..300 {
+ let mut before = Content::new();
+ for _ in 0..rng.next(6) {
+ before.push(
+ words[rng.next(words.len())],
+ attrs[rng.next(attrs.len())].clone(),
+ );
+ }
+ let mut after = before.clone();
+ for _ in 0..1 + rng.next(3) {
+ let len = after.len();
+ let at = rng.next(len + 1);
+ // Keep offsets on character boundaries.
+ let at = crate::model::content::utf16_len(
+ &after.text()[..crate::model::content::byte_at(&after.text(), at)],
+ );
+ match rng.next(3) {
+ 0 => after.insert(
+ at,
+ words[rng.next(words.len())],
+ attrs[rng.next(attrs.len())].clone(),
+ ),
+ 1 => {
+ let end = (at + rng.next(6)).min(len);
+ let end = crate::model::content::utf16_len(
+ &after.text()[..crate::model::content::byte_at(&after.text(), end)],
+ );
+ after.delete(at, end.max(at));
+ }
+ _ => {
+ let end = (at + rng.next(8)).min(len);
+ let end = crate::model::content::utf16_len(
+ &after.text()[..crate::model::content::byte_at(&after.text(), end)],
+ );
+ let a = attrs[rng.next(attrs.len())].clone();
+ after.map_attrs(at, end.max(at), |_| a.clone());
+ }
+ }
+ }
+ let delta = content_delta(&before, &after);
+ let mut applied = before.clone();
+ applied.apply_delta(&delta);
+ assert_eq!(applied, after, "delta {delta:?}");
+ // The delta survives JSON.
+ let json = serde_json::to_string(&delta).unwrap();
+ let back: Vec<DeltaOp> = serde_json::from_str(&json).unwrap();
+ assert_eq!(back, delta);
+ }
+ let _ = Span {
+ text: String::new(),
+ attrs: Attrs::empty(),
+ };
+}
+
+#[test]
+fn lists_toggle_on_and_off_and_create_the_numbering_part() {
+ let mut s = open(&format!("{}{}{}", p("One"), p("Two"), p("Three")));
+ select(&mut s, (0, 0), (1, 1));
+ let r = run(
+ &mut s,
+ EditOp::ToggleList {
+ kind: ListKind::Bullet,
+ },
+ );
+ assert!(r.format.list);
+ // The new part reaches the shared maps: its XML, relationship and type.
+ assert!(r.changes.iter().any(|c| matches!(c, Change::Entry { container, key, .. } if container == "wordParts" && key == "/word/numbering.xml")));
+ assert!(r.changes.iter().any(|c| matches!(c, Change::Entry { container, value: Some(v), .. } if container == "wordRels" && v.contains("numbering"))));
+ assert!(r.changes.iter().any(|c| matches!(c, Change::Entry { container, key, .. } if container == "wordTypes" && key.contains("numbering"))));
+ let kinds = s.list_kinds(&s.document().body().paragraphs());
+ assert!(kinds[0].is_some_and(|(k, _, _)| k == ListKind::Bullet));
+ assert!(kinds[1].is_some());
+ assert!(kinds[2].is_none());
+ // A numbered list started separately on the third paragraph.
+ select(&mut s, (2, 0), (2, 0));
+ run(
+ &mut s,
+ EditOp::ToggleList {
+ kind: ListKind::Number,
+ },
+ );
+ let kinds = s.list_kinds(&s.document().body().paragraphs());
+ assert!(kinds[2].is_some_and(|(k, _, _)| k == ListKind::Number));
+ // Off again.
+ select(&mut s, (0, 0), (1, 0));
+ let r = run(
+ &mut s,
+ EditOp::ToggleList {
+ kind: ListKind::Bullet,
+ },
+ );
+ assert!(!r.format.list);
+ let kinds = s.list_kinds(&s.document().body().paragraphs());
+ assert!(kinds[0].is_none() && kinds[1].is_none());
+ // Saved and reopened, the numbering part is valid.
+ let doc = Document::open(s.save().unwrap()).unwrap();
+ assert!(doc.parts().numbering.num_ids().count() >= 2);
+}
+
+#[test]
+fn numbered_items_continue_the_list_before_them() {
+ let mut s = open(&format!("{}{}", p("First"), p("Second")));
+ caret_at(&mut s, 0, 0);
+ run(
+ &mut s,
+ EditOp::ToggleList {
+ kind: ListKind::Number,
+ },
+ );
+ caret_at(&mut s, 1, 0);
+ run(
+ &mut s,
+ EditOp::ToggleList {
+ kind: ListKind::Number,
+ },
+ );
+ let kinds = s.list_kinds(&s.document().body().paragraphs());
+ let (a, b) = (kinds[0].unwrap(), kinds[1].unwrap());
+ assert_eq!(a.1, b.1, "same list instance");
+ // Tab-style indent moves the item a level down.
+ run(&mut s, EditOp::Indent { forward: true });
+ let kinds = s.list_kinds(&s.document().body().paragraphs());
+ assert_eq!(kinds[1].unwrap().2, 1);
+ // The labels lay out as 1. and a.
+ let layout = s.layout(fonts());
+ let labels: Vec<String> = layout.pages[0]
+ .items
+ .iter()
+ .filter_map(|i| match i {
+ crate::layout::Item::Line(l) => Some(l),
+ _ => None,
+ })
+ .map(|l| {
+ let pb = &l.para;
+ pb.inline.clusters[..pb.inline.label_len]
+ .iter()
+ .map(|c| c.ch)
+ .filter(|c| !c.is_whitespace() && *c != '\t')
+ .collect()
+ })
+ .collect();
+ assert_eq!(labels, vec!["1.", "a."]);
+}
+
+#[test]
+fn tables_insert_and_change_shape() {
+ let mut s = open(&p("Before"));
+ caret_at(&mut s, 0, 6);
+ let r = run(&mut s, EditOp::InsertTable { rows: 2, cols: 3 });
+ let count =
+ |s: &Session, k: BlockKind| s.document().body().blocks().filter(|b| b.kind == k).count();
+ assert_eq!(count(&s, BlockKind::Table), 1);
+ assert_eq!(count(&s, BlockKind::Row), 2);
+ assert_eq!(count(&s, BlockKind::Cell), 6);
+ // The caret is in the first cell, and a paragraph follows the table.
+ let first_cell = r.selection.focus.block.clone();
+ type_text(&mut s, "A1");
+ assert_eq!(
+ s.document().body().get(&first_cell).unwrap().content.text(),
+ "A1"
+ );
+ let top = s.document().body().children(None).to_vec();
+ assert_eq!(top.len(), 3);
+ assert_eq!(
+ s.document().body().get(&top[2]).unwrap().kind,
+ BlockKind::Paragraph
+ );
+ run(&mut s, EditOp::InsertRow { below: true });
+ assert_eq!(count(&s, BlockKind::Row), 3);
+ run(&mut s, EditOp::InsertColumn { right: true });
+ assert_eq!(count(&s, BlockKind::Cell), 12);
+ run(&mut s, EditOp::DeleteColumn);
+ assert_eq!(count(&s, BlockKind::Cell), 9);
+ run(&mut s, EditOp::DeleteRow);
+ assert_eq!(count(&s, BlockKind::Row), 2);
+ // It lays out and saves.
+ assert_eq!(s.pages(fonts()).len(), 1);
+ let doc = Document::open(s.save().unwrap()).unwrap();
+ assert_eq!(
+ doc.body()
+ .blocks()
+ .filter(|b| b.kind == BlockKind::Cell)
+ .count(),
+ 6
+ );
+ run(&mut s, EditOp::DeleteTable);
+ assert_eq!(count(&s, BlockKind::Table), 0);
+}
+
+#[test]
+fn typing_reports_a_band_around_the_changed_lines() {
+ let mut paras = String::new();
+ for i in 0..30 {
+ paras.push_str(&p(&format!("Paragraph {i} with some text.")));
+ }
+ let mut s = open(&paras);
+ s.pages(fonts());
+ caret_at(&mut s, 3, 0);
+ let r = type_text(&mut s, "x");
+ assert_eq!(r.bands.len(), 1, "{:?}", r.bands);
+ let band = r.bands[0];
+ let caret = r.caret.unwrap();
+ assert_eq!(band.page, 0);
+ assert!(band.top <= caret.y && band.bottom >= caret.y + caret.height);
+ assert!(band.bottom - band.top < 40.0, "{band:?}");
+}
+
+#[test]
+fn selected_text_joins_paragraphs() {
+ let mut s = open(&format!("{}{}", p("Hello world"), p("Second line")));
+ select(&mut s, (0, 6), (1, 6));
+ assert_eq!(s.selected_text(), "world\nSecond");
+}
+
+#[test]
+#[ignore = "timing probe over a long document; run with --ignored --nocapture"]
+fn zz_typing_profile() {
+ // About sixty pages of contract-like paragraphs.
+ let clause = "The Receiving Party shall hold the Disclosing Party's Confidential \
+ Information in strict confidence and shall not disclose it to any third party \
+ except to its Representatives who need to know it for the Purpose.";
+ let body: String = (0..600).map(|i| p(&format!("{i}. {clause}"))).collect();
+ let mut s = open(&body);
+ let t = std::time::Instant::now();
+ let pages = s.pages(fonts()).len();
+ eprintln!("first layout {:?} ({pages} pages)", t.elapsed());
+ let target = s.document().body().paragraphs()[20].clone();
+ s.apply(
+ &[EditOp::Select {
+ anchor: Pos::new(target.clone(), 3),
+ focus: Pos::new(target, 3),
+ }],
+ None,
+ fonts(),
+ )
+ .unwrap();
+ for i in 0..5 {
+ let t = std::time::Instant::now();
+ let r = s
+ .apply(
+ &[EditOp::InsertText { text: "x".into() }],
+ Some("typing"),
+ fonts(),
+ )
+ .unwrap();
+ let total = t.elapsed();
+ let t2 = std::time::Instant::now();
+ let json = serde_json::to_string(&r).unwrap();
+ eprintln!(
+ "keystroke {i}: apply {total:?}, json {:?} ({} bytes)",
+ t2.elapsed(),
+ json.len()
+ );
+ }
+ // Layout alone.
+ let t = std::time::Instant::now();
+ let cache = crate::layout::LayoutCache::new();
+ s.document()
+ .layout_cached(fonts(), &crate::layout::LayoutOptions::default(), &cache);
+ eprintln!("cold layout {:?}", t.elapsed());
+ let t = std::time::Instant::now();
+ s.document()
+ .layout_cached(fonts(), &crate::layout::LayoutOptions::default(), &cache);
+ eprintln!("warm layout {:?}", t.elapsed());
+}
+
+const WITH_HEADER: &str = r#"<w:p><w:r><w:t>Body text</w:t></w:r></w:p><w:sectPr><w:headerReference w:type="default" r:id="rIdH1"/><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720" w:gutter="0"/></w:sectPr>"#;
+
+fn header_texts(doc: &Document) -> Vec<String> {
+ let part = doc.part_story("/word/header1.xml").expect("header part");
+ part.story
+ .paragraphs()
+ .iter()
+ .map(|id| part.story.get(id).unwrap().content.text())
+ .collect()
+}
+
+fn open_with_header() -> Session {
+ let header = p("Confidential");
+ open_with(
+ WITH_HEADER,
+ &Parts {
+ header: Some(&header),
+ ..Parts::default()
+ },
+ )
+}
+
+#[test]
+fn headers_are_edited_in_place_and_written_to_their_part() {
+ let mut s = open_with_header();
+ let pages = s.pages(fonts());
+ let area = pages[0].header.clone().expect("header area");
+ assert!(area.editable);
+ assert!(area.bottom >= 72.0 - 0.1, "{area:?}");
+ // Header blocks have ids of their own.
+ let header_id = s
+ .document()
+ .part_story("/word/header1.xml")
+ .unwrap()
+ .story
+ .paragraphs()[0]
+ .clone();
+ assert!(header_id.as_str().starts_with("word/header1.xml#"));
+
+ let r = run(
+ &mut s,
+ EditOp::EnterStory {
+ page: 0,
+ x: 300.0,
+ y: 42.0,
+ },
+ );
+ assert_eq!(r.story.kind, StoryKind::Header);
+ assert_eq!(r.story.page, Some(0));
+ assert_eq!(r.selection.focus.block, header_id);
+ run(
+ &mut s,
+ EditOp::Move {
+ unit: Unit::Document,
+ forward: true,
+ extend: false,
+ visual: false,
+ },
+ );
+ let r = type_text(&mut s, " draft");
+ // Shared as the part's XML, not as body blocks.
+ assert!(
+ r.changes.iter().any(|c| matches!(
+ c,
+ Change::Entry { container, key, value: Some(v) }
+ if container == "wordParts" && key.ends_with("header1.xml") && v.contains("Confidential draft")
+ )),
+ "{:?}",
+ r.changes
+ );
+ assert!(!r.changes.iter().any(|c| matches!(c, Change::Text { .. })));
+ let caret = r.caret.expect("caret");
+ assert_eq!(caret.page, 0);
+ assert!(caret.y < 72.0, "{caret:?}");
+ assert_eq!(header_texts(s.document()), vec!["Confidential draft"]);
+ assert_eq!(texts(&s), vec!["Body text"]);
+
+ // Back to the body, where the caret was.
+ let r = run(&mut s, EditOp::ExitStory);
+ assert_eq!(r.story.kind, StoryKind::Body);
+ assert_eq!(r.selection.focus.block, para(&s, 0));
+
+ // The saved file has the new header.
+ let saved = Document::open(s.document().save().unwrap()).unwrap();
+ assert_eq!(header_texts(&saved), vec!["Confidential draft"]);
+ assert_eq!(
+ saved
+ .body()
+ .paragraphs()
+ .iter()
+ .map(|id| saved.body().get(id).unwrap().content.text())
+ .collect::<Vec<_>>(),
+ vec!["Body text"]
+ );
+
+ // Undo goes back into the header and removes the typing.
+ let r = s.undo(fonts()).unwrap();
+ assert_eq!(r.story.kind, StoryKind::Header);
+ assert_eq!(header_texts(s.document()), vec!["Confidential"]);
+ s.redo(fonts()).unwrap();
+ assert_eq!(header_texts(s.document()), vec!["Confidential draft"]);
+}
+
+#[test]
+fn double_clicking_the_body_leaves_the_header() {
+ let mut s = open_with_header();
+ run(
+ &mut s,
+ EditOp::EnterStory {
+ page: 0,
+ x: 300.0,
+ y: 42.0,
+ },
+ );
+ // Enter splits the header paragraph within the header.
+ run(&mut s, EditOp::InsertParagraph);
+ assert_eq!(header_texts(s.document()).len(), 2);
+ assert_eq!(texts(&s), vec!["Body text"]);
+ let r = run(
+ &mut s,
+ EditOp::EnterStory {
+ page: 0,
+ x: 100.0,
+ y: 80.0,
+ },
+ );
+ assert_eq!(r.story.kind, StoryKind::Body);
+ assert_eq!(r.selection.focus.block, para(&s, 0));
+}
+
+#[test]
+fn a_remote_header_change_keeps_the_caret_in_the_header() {
+ let mut s = open_with_header();
+ run(
+ &mut s,
+ EditOp::EnterStory {
+ page: 0,
+ x: 300.0,
+ y: 42.0,
+ },
+ );
+ run(
+ &mut s,
+ EditOp::Move {
+ unit: Unit::Document,
+ forward: true,
+ extend: false,
+ visual: false,
+ },
+ );
+ // Another peer rewrites the header part.
+ let xml = format!(
+ r#"<w:hdr {NS}><w:p><w:r><w:t>Privileged</w:t></w:r></w:p><w:p><w:r><w:t>Second</w:t></w:r></w:p></w:hdr>"#
+ );
+ let r = s
+ .apply_remote(
+ &[RemoteChange::Entry {
+ container: "wordParts".to_owned(),
+ key: "/word/header1.xml".to_owned(),
+ value: Some(xml),
+ }],
+ fonts(),
+ )
+ .unwrap();
+ assert_eq!(header_texts(s.document()), vec!["Privileged", "Second"]);
+ assert_eq!(r.story.kind, StoryKind::Header);
+ let first = s
+ .document()
+ .part_story("/word/header1.xml")
+ .unwrap()
+ .story
+ .paragraphs()[0]
+ .clone();
+ assert_eq!(r.selection.focus.block, first);
+ // Typing continues in the header.
+ type_text(&mut s, "!");
+ assert_eq!(
+ header_texts(s.document())[0]
+ .chars()
+ .filter(|c| *c == '!')
+ .count(),
+ 1
+ );
+}
+
+#[test]
+fn remote_text_at_the_caret_keeps_the_typists_place() {
+ use crate::model::content::DeltaOp;
+ // This session typed " " after "X"; meanwhile another person typed
+ // " [two]" at the same spot, which the shared text put first.
+ let mut s = open(&p("X"));
+ caret_at(&mut s, 0, 1);
+ type_text(&mut s, " ");
+ let id = para(&s, 0);
+ let mut record = BlockRecord::of(s.document().body().get(&id).unwrap());
+ let mut shared = Content::from_delta(record.t.as_deref().unwrap());
+ shared.insert(1, " [two]", Default::default());
+ record.t = Some(shared.to_delta());
+ let insert = |at: usize, text: &str| {
+ vec![
+ DeltaOp::Retain {
+ retain: at,
+ attributes: Default::default(),
+ },
+ DeltaOp::Insert {
+ insert: text.to_owned(),
+ attributes: Default::default(),
+ },
+ ]
+ };
+ let r = s
+ .apply_remote(
+ &[RemoteChange::Block {
+ block: record.clone(),
+ deltas: vec![insert(1, " [two]")],
+ }],
+ fonts(),
+ )
+ .unwrap();
+ // The caret stays after this person's own space, at the end.
+ assert_eq!(texts(&s), vec!["X [two] "]);
+ assert_eq!(r.selection.focus.offset, 8);
+ // Comparing texts alone would have put it inside the other's text.
+ let mut s2 = open(&p("X"));
+ caret_at(&mut s2, 0, 1);
+ type_text(&mut s2, " ");
+ let mut record2 = BlockRecord::of(s2.document().body().get(&para(&s2, 0)).unwrap());
+ record2.t = record.t.clone();
+ let r2 = s2
+ .apply_remote(
+ &[RemoteChange::Block {
+ block: record2,
+ deltas: Vec::new(),
+ }],
+ fonts(),
+ )
+ .unwrap();
+ assert_eq!(r2.selection.focus.offset, 2);
+ // Deltas that do not fit the text are ignored.
+ let mut s3 = open(&p("X"));
+ caret_at(&mut s3, 0, 1);
+ type_text(&mut s3, " ");
+ let mut record3 = BlockRecord::of(s3.document().body().get(&para(&s3, 0)).unwrap());
+ record3.t = record.t.clone();
+ let r3 = s3
+ .apply_remote(
+ &[RemoteChange::Block {
+ block: record3,
+ deltas: vec![insert(5, "zzz")],
+ }],
+ fonts(),
+ )
+ .unwrap();
+ assert_eq!(r3.selection.focus.offset, 2);
+}
+
+#[test]
+fn carets_and_selections_in_right_to_left_text() {
+ // "shalom" in a right-to-left paragraph.
+ let mut s = open(
+ r#"<w:p><w:pPr><w:bidi/></w:pPr><w:r><w:rPr><w:rtl/></w:rPr><w:t>שלום</w:t></w:r></w:p>"#,
+ );
+ let block = para(&s, 0);
+ let caret = |s: &mut Session, offset: usize| {
+ s.caret_at(&Pos::new(block.clone(), offset), fonts())
+ .unwrap()
+ .x
+ };
+ // The text starts at the right margin (612 - 72) and runs leftwards.
+ let start = caret(&mut s, 0);
+ let middle = caret(&mut s, 2);
+ let end = caret(&mut s, 4);
+ assert!((start - 540.0).abs() < 1.0, "{start}");
+ assert!(end < middle && middle < start, "{end} {middle} {start}");
+ // A click just left of the right edge lands before the first letter.
+ let hit = s.hit_test(0, start - 1.0, 80.0, fonts()).unwrap();
+ assert_eq!(hit.offset, 0);
+ let hit = s.hit_test(0, end + 1.0, 80.0, fonts()).unwrap();
+ assert_eq!(hit.offset, 4);
+ // The first two letters are selected on the right.
+ let rects = s.range_rects(
+ &Pos::new(block.clone(), 0),
+ &Pos::new(block.clone(), 2),
+ fonts(),
+ );
+ assert_eq!(rects.len(), 1);
+ let r = &rects[0];
+ assert!((r.x - middle).abs() < 0.5 && (r.x + r.w - start).abs() < 0.5);
+}
+
+#[test]
+fn arrow_keys_move_visually_in_right_to_left_text() {
+ let mut s = open(
+ r#"<w:p><w:pPr><w:bidi/></w:pPr><w:r><w:rPr><w:rtl/></w:rPr><w:t>שלום</w:t></w:r></w:p>"#,
+ );
+ caret_at(&mut s, 0, 1);
+ let arrow = |s: &mut Session, right: bool| {
+ run(
+ s,
+ EditOp::Move {
+ unit: Unit::Char,
+ forward: right,
+ extend: false,
+ visual: true,
+ },
+ );
+ s.selection().focus.offset
+ };
+ // Left goes on through the text, right goes back.
+ assert_eq!(arrow(&mut s, false), 2);
+ assert_eq!(arrow(&mut s, true), 1);
+}
+
+#[test]
+fn format_state_reports_highlight_spacing_and_tables() {
+ let mut s = open(&format!(
+ r#"<w:p><w:pPr><w:spacing w:line="360" w:lineRule="auto"/></w:pPr><w:r><w:rPr><w:highlight w:val="yellow"/></w:rPr><w:t>marked</w:t></w:r></w:p><w:tbl><w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid><w:tr><w:tc>{}</w:tc></w:tr></w:tbl>{}"#,
+ p("cell"),
+ p("after")
+ ));
+ caret_at(&mut s, 0, 2);
+ let f = s.state(fonts()).format;
+ assert_eq!(f.highlight.as_deref(), Some("yellow"));
+ assert_eq!(f.line_spacing, Some(1.5));
+ assert!(!f.table);
+ caret_at(&mut s, 1, 1);
+ let f = s.state(fonts()).format;
+ assert!(f.table);
+ assert_eq!(f.highlight, None);
+ assert_eq!(f.line_spacing, Some(1.0));
+}
+
+const WITH_FOOTNOTE: &str = r#"<w:p><w:r><w:t>Body text</w:t></w:r><w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:footnoteReference w:id="1"/></w:r></w:p>"#;
+
+const FOOTNOTES: &str = r#"<w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote><w:footnote w:type="continuationSeparator" w:id="0"><w:p><w:r><w:continuationSeparator/></w:r></w:p></w:footnote><w:footnote w:id="1"><w:p><w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> See the Agreement.</w:t></w:r></w:p></w:footnote>"#;
+
+fn open_with_footnote() -> Session {
+ open_with(
+ WITH_FOOTNOTE,
+ &Parts {
+ footnotes: Some(FOOTNOTES),
+ ..Parts::default()
+ },
+ )
+}
+
+/// The text of footnote 1 (its reference mark is an object character).
+fn note_text(doc: &Document) -> Vec<String> {
+ let note = &doc.footnotes().by_id[&1];
+ note.story
+ .paragraphs()
+ .iter()
+ .map(|id| {
+ note.story
+ .get(id)
+ .unwrap()
+ .content
+ .text()
+ .replace('\u{FFFC}', "^")
+ })
+ .collect()
+}
+
+fn enter_note(s: &mut Session) -> EditResult {
+ let area = s.pages(fonts())[0].notes.clone().expect("notes area");
+ run(
+ s,
+ EditOp::EnterStory {
+ page: 0,
+ x: 150.0,
+ y: (area.top + area.bottom) / 2.0,
+ },
+ )
+}
+
+#[test]
+fn footnotes_are_edited_in_place_and_written_to_their_part() {
+ let mut s = open_with_footnote();
+ let area = s.pages(fonts())[0].notes.clone().expect("notes area");
+ assert!(area.top > 600.0, "{area:?}");
+ let r = enter_note(&mut s);
+ assert_eq!(r.story.kind, StoryKind::Footnote);
+ assert_eq!(r.story.page, Some(0));
+ let note_para = s.document().footnotes().by_id[&1].story.paragraphs()[0].clone();
+ assert_eq!(r.selection.focus.block, note_para);
+ run(
+ &mut s,
+ EditOp::Move {
+ unit: Unit::Document,
+ forward: true,
+ extend: false,
+ visual: false,
+ },
+ );
+ let r = type_text(&mut s, " Exhibit A.");
+ // Shared as the note's XML, not the whole notes part.
+ assert!(
+ matches!(
+ &r.changes[..],
+ [Change::Entry { container, key, value: Some(v) }]
+ if container == "wordParts" && key == "/word/footnotes.xml|1"
+ && v.contains("See the Agreement. Exhibit A.")
+ ),
+ "{:?}",
+ r.changes
+ );
+ let caret = r.caret.expect("caret");
+ assert!(caret.y > 600.0, "{caret:?}");
+ assert_eq!(
+ note_text(s.document()),
+ vec!["^ See the Agreement. Exhibit A."]
+ );
+ assert_eq!(texts(&s), vec!["Body text\u{FFFC}"]);
+
+ // Back to the body, where the caret was.
+ let r = run(&mut s, EditOp::ExitStory);
+ assert_eq!(r.story.kind, StoryKind::Body);
+
+ // The saved file has the new note, and the separators.
+ let saved = Document::open(s.document().save().unwrap()).unwrap();
+ assert_eq!(note_text(&saved), vec!["^ See the Agreement. Exhibit A."]);
+ assert_eq!(saved.footnotes().by_id[&-1].kind, "separator");
+ assert_eq!(saved.footnotes().by_id[&0].kind, "continuationSeparator");
+
+ // Undo goes back into the note.
+ let r = s.undo(fonts()).unwrap();
+ assert_eq!(r.story.kind, StoryKind::Footnote);
+ assert_eq!(note_text(s.document()), vec!["^ See the Agreement."]);
+}
+
+#[test]
+fn clicking_the_body_leaves_a_note_and_enter_splits_it() {
+ let mut s = open_with_footnote();
+ enter_note(&mut s);
+ // Entering the note it is in keeps the selection.
+ run(
+ &mut s,
+ EditOp::Move {
+ unit: Unit::Document,
+ forward: true,
+ extend: false,
+ visual: false,
+ },
+ );
+ let at = s.selection().clone();
+ let r = enter_note(&mut s);
+ assert_eq!(r.selection, at);
+ run(&mut s, EditOp::InsertParagraph);
+ type_text(&mut s, "Second");
+ assert_eq!(
+ note_text(s.document()),
+ vec!["^ See the Agreement.", "Second"]
+ );
+ let r = run(
+ &mut s,
+ EditOp::EnterStory {
+ page: 0,
+ x: 100.0,
+ y: 80.0,
+ },
+ );
+ assert_eq!(r.story.kind, StoryKind::Body);
+ assert_eq!(texts(&s), vec!["Body text\u{FFFC}"]);
+}
+
+#[test]
+fn a_remote_note_change_keeps_the_caret_in_the_note() {
+ let mut s = open_with_footnote();
+ enter_note(&mut s);
+ let xml = format!(
+ r#"<w:footnotes {NS}>{}</w:footnotes>"#,
+ FOOTNOTES.replace("See the Agreement.", "See the Merger Agreement.")
+ );
+ let r = s
+ .apply_remote(
+ &[RemoteChange::Entry {
+ container: "wordParts".to_owned(),
+ key: "/word/footnotes.xml".to_owned(),
+ value: Some(xml),
+ }],
+ fonts(),
+ )
+ .unwrap();
+ assert_eq!(r.story.kind, StoryKind::Footnote);
+ assert_eq!(note_text(s.document()), vec!["^ See the Merger Agreement."]);
+ let first = s.document().footnotes().by_id[&1].story.paragraphs()[0].clone();
+ assert_eq!(r.selection.focus.block, first);
+ type_text(&mut s, "x");
+ assert!(note_text(s.document())[0].contains('x'));
+}
diff --git a/crates/docx_engine/src/edit/test_util.rs b/crates/docx_engine/src/edit/test_util.rs
new file mode 100644
index 0000000000..17a92d69a4
--- /dev/null
+++ b/crates/docx_engine/src/edit/test_util.rs
@@ -0,0 +1,65 @@
+//! Helpers shared by the editing tests.
+
+use super::*;
+use crate::test_support::{Parts, docx, fonts};
+
+pub(crate) fn open(body: &str) -> Session {
+ open_with(body, &Parts::default())
+}
+
+pub(crate) fn open_with(body: &str, parts: &Parts<'_>) -> Session {
+ let doc = Document::open(docx(body, parts)).expect("open");
+ Session::new(doc)
+}
+
+pub(crate) fn p(text: &str) -> String {
+ format!(r#"<w:p><w:r><w:t xml:space="preserve">{text}</w:t></w:r></w:p>"#)
+}
+
+pub(crate) fn texts(s: &Session) -> Vec<String> {
+ s.document()
+ .body()
+ .paragraphs()
+ .iter()
+ .map(|id| s.document().body().get(id).unwrap().content.text())
+ .collect()
+}
+
+pub(crate) fn para(s: &Session, i: usize) -> BlockId {
+ s.document().body().paragraphs()[i].clone()
+}
+
+pub(crate) fn caret_at(s: &mut Session, i: usize, offset: usize) {
+ let block = para(s, i);
+ s.apply(
+ &[EditOp::Select {
+ anchor: Pos::new(block.clone(), offset),
+ focus: Pos::new(block, offset),
+ }],
+ None,
+ fonts(),
+ )
+ .unwrap();
+}
+
+pub(crate) fn select(s: &mut Session, a: (usize, usize), f: (usize, usize)) {
+ let anchor = Pos::new(para(s, a.0), a.1);
+ let focus = Pos::new(para(s, f.0), f.1);
+ s.apply(&[EditOp::Select { anchor, focus }], None, fonts())
+ .unwrap();
+}
+
+pub(crate) fn run(s: &mut Session, op: EditOp) -> EditResult {
+ s.apply(&[op], None, fonts()).unwrap()
+}
+
+pub(crate) fn type_text(s: &mut Session, text: &str) -> EditResult {
+ s.apply(
+ &[EditOp::InsertText {
+ text: text.to_owned(),
+ }],
+ Some("typing"),
+ fonts(),
+ )
+ .unwrap()
+}
diff --git a/crates/docx_engine/src/edit/text.rs b/crates/docx_engine/src/edit/text.rs
new file mode 100644
index 0000000000..9bb1c67625
--- /dev/null
+++ b/crates/docx_engine/src/edit/text.rs
@@ -0,0 +1,479 @@
+//! Text edits on the block tree: typing, splitting and joining paragraphs,
+//! and deleting ranges that may span paragraphs, tables and cells.
+
+use super::Pos;
+use super::txn::Txn;
+use super::xmledit::{Element, PPR_ORDER};
+use crate::model::block::{Block, BlockId, BlockKind, Story};
+use crate::model::content::{Attrs, Content, Wrapper, encode_wrappers, key};
+use crate::xml::{SnippetContext, parse_on_off};
+use std::collections::HashMap;
+
+/// Wrappers that text typed next to them never joins: tracked changes
+/// (typing is recorded as the typist's own insertion, or not at all) and
+/// simple fields.
+fn never_extends(w: &Wrapper) -> bool {
+ matches!(
+ w.local(),
+ "ins" | "del" | "moveFrom" | "moveTo" | "fldSimple"
+ )
+}
+
+/// Run property keys that belong to a tracked change rather than to the
+/// text's formatting.
+fn is_revision_key(k: &str) -> bool {
+ let local = k
+ .strip_prefix(key::RUN_PROP)
+ .map(|q| q.rsplit(':').next().unwrap_or(q));
+ matches!(
+ local,
+ Some("ins" | "del" | "moveFrom" | "moveTo" | "rPrChange")
+ )
+}
+
+/// Run property attributes of a paragraph mark (its `w:pPr/w:rPr`).
+pub(super) fn mark_attrs(ppr: &str, w: &str, ctx: &SnippetContext) -> Attrs {
+ if ppr.is_empty() {
+ return Attrs::empty();
+ }
+ let Ok(tree) = ctx.parse(ppr) else {
+ return Attrs::empty();
+ };
+ let Some(rpr) = tree.w_child(tree.root(), "rPr") else {
+ return Attrs::empty();
+ };
+ let _ = w;
+ Attrs::from_pairs(
+ tree.children(rpr)
+ .map(|c| {
+ (
+ format!("{}{}", key::RUN_PROP, tree.qname(c)),
+ tree.snippet(c),
+ )
+ })
+ .filter(|(k, _)| !is_revision_key(k)),
+ )
+}
+
+/// The formatting text typed at `offset` gets: the character before it
+/// (or after it at the paragraph start), staying inside wrappers only when
+/// the caret is inside them, and the paragraph mark's in an empty paragraph.
+pub(super) fn typing_attrs(block: &Block, offset: usize, w: &str, ctx: &SnippetContext) -> Attrs {
+ let content = &block.content;
+ if content.is_empty() {
+ return mark_attrs(&block.props, w, ctx);
+ }
+ let base = content.typing_attrs(offset);
+ let before = (offset > 0).then(|| content.attrs_at(offset - 1)).flatten();
+ let after = content.attrs_at(offset);
+ let stack_before = before.map(Attrs::wrappers).unwrap_or_default();
+ let stack_after = after.map(Attrs::wrappers).unwrap_or_default();
+ // Inside a wrapper only when both neighbours are in it.
+ let mut kept: Vec<Wrapper> = Vec::new();
+ let mut dropped_link = false;
+ let shared = if before.is_none() {
+ Vec::new()
+ } else {
+ stack_before
+ .iter()
+ .zip(stack_after.iter())
+ .take_while(|(a, b)| a == b)
+ .map(|(a, _)| a.clone())
+ .collect::<Vec<_>>()
+ };
+ for (i, wrapper) in stack_before.iter().enumerate() {
+ let inside = i < shared.len();
+ if inside && !never_extends(wrapper) {
+ kept.push(wrapper.clone());
+ } else if wrapper.local() == "hyperlink" {
+ dropped_link = true;
+ }
+ }
+ let mut attrs = base
+ .with(key::WRAP, encode_wrappers(&kept).as_deref())
+ .without(is_revision_key);
+ if dropped_link {
+ let style_key = format!("{}{}:rStyle", key::RUN_PROP, w);
+ if attrs
+ .get(&style_key)
+ .is_some_and(|v| v.contains("Hyperlink"))
+ {
+ attrs = attrs.with(&style_key, None);
+ }
+ }
+ attrs
+}
+
+/// The `w:sectPr` of a paragraph's properties.
+fn sect_pr(ppr: &str, w: &str, txn: &Txn<'_>) -> Option<String> {
+ if !ppr.contains("sectPr") {
+ return None;
+ }
+ let e = Element::open(ppr, "pPr", w, txn.doc.decls(), PPR_ORDER);
+ e.get("sectPr").map(str::to_owned)
+}
+
+fn set_sect_pr(ppr: &str, sect: Option<String>, w: &str, txn: &Txn<'_>) -> String {
+ if sect.is_none() && !ppr.contains("sectPr") {
+ return ppr.to_owned();
+ }
+ let mut e = Element::open(ppr, "pPr", w, txn.doc.decls(), PPR_ORDER);
+ e.set("sectPr", sect);
+ e.finish(true)
+}
+
+/// The style a paragraph after one of `style` gets (`w:next`).
+fn next_style(txn: &Txn<'_>, ppr: &str) -> Option<String> {
+ let styles = &txn.doc.parts().styles;
+ let ctx = SnippetContext::new(txn.doc.decls());
+ let id = (!ppr.is_empty())
+ .then(|| ctx.parse(ppr).ok())
+ .flatten()
+ .and_then(|t| {
+ t.w_child(t.root(), "pStyle")
+ .and_then(|s| t.val(s))
+ .map(str::to_owned)
+ })
+ .or_else(|| styles.default_paragraph_id().map(str::to_owned))?;
+ let style = styles.get(&id)?;
+ style.next.clone().filter(|n| *n != id)
+}
+
+/// Splits the paragraph at `at`. The paragraph keeps its id and the text
+/// before the split; a new paragraph after it takes the rest. Returns the
+/// start of the new paragraph.
+pub(super) fn split(txn: &mut Txn<'_>, at: &Pos) -> Option<Pos> {
+ let w = txn.doc.w_prefix().to_owned();
+ let p = txn.get(&at.block)?.clone();
+ if p.kind != BlockKind::Paragraph {
+ return None;
+ }
+ let len = p.content.len();
+ let offset = at.offset.min(len);
+ let new_id = txn.new_id();
+ let order = txn.story().key_after(p.parent.as_ref(), Some(&p.id));
+ let mut q = Block::new(
+ new_id.clone(),
+ BlockKind::Paragraph,
+ p.parent.clone(),
+ order,
+ );
+ q.attrs = strip_ids(&p.attrs);
+ // The section break belongs to the original paragraph mark, which now
+ // ends the second half.
+ let sect = sect_pr(&p.props, &w, txn);
+ let mut q_props = p.props.clone();
+ let mut p_props = set_sect_pr(&p.props, None, &w, txn);
+ if offset == len
+ && let Some(next) = next_style(txn, &p.props)
+ {
+ let mut e = Element::open(&q_props, "pPr", &w, txn.doc.decls(), PPR_ORDER);
+ e.set_val("pStyle", Some(&next));
+ // A heading's numbering does not carry over to body text.
+ if e.has("numPr") && !p.props.contains("numPr") {
+ e.set("numPr", None);
+ }
+ q_props = e.finish(true);
+ }
+ if offset == 0 && len > 0 {
+ // Enter at the start: an empty paragraph goes in front and the
+ // text keeps its paragraph (and id, so comments stay anchored).
+ let order = txn.story().key_before(p.parent.as_ref(), &p.id);
+ let mut e = Block::new(
+ new_id.clone(),
+ BlockKind::Paragraph,
+ p.parent.clone(),
+ order,
+ );
+ e.attrs = strip_ids(&p.attrs);
+ e.props = set_sect_pr(&p.props, None, &w, txn);
+ txn.insert(e);
+ return Some(Pos {
+ block: p.id.clone(),
+ offset: 0,
+ upstream: false,
+ });
+ }
+ if sect.is_some() {
+ q_props = set_sect_pr(&q_props, sect, &w, txn);
+ } else {
+ p_props = p.props.clone();
+ }
+ let block = txn.block_mut(&p.id)?;
+ let tail = block.content.split_off(offset);
+ block.props = p_props;
+ q.content = tail;
+ q.props = q_props;
+ txn.insert(q);
+ Some(Pos {
+ block: new_id,
+ offset: 0,
+ upstream: false,
+ })
+}
+
+/// Paragraph element attributes without per-paragraph identifiers that
+/// must stay unique (`w14:paraId`, `w14:textId`).
+pub(super) fn strip_ids(attrs: &str) -> String {
+ let mut out = String::with_capacity(attrs.len());
+ let mut rest = attrs;
+ while let Some(eq) = rest.find('=') {
+ let name_start = rest[..eq].rfind(char::is_whitespace).map_or(0, |i| i + 1);
+ let name = rest[name_start..eq].trim();
+ let quote_at = rest[eq + 1..].find(['"', '\'']).map(|i| eq + 1 + i);
+ let Some(q) = quote_at else {
+ break;
+ };
+ let quote = &rest[q..=q];
+ let Some(close) = rest[q + 1..].find(quote).map(|i| q + 1 + i) else {
+ break;
+ };
+ let local = name.rsplit(':').next().unwrap_or(name);
+ if !matches!(local, "paraId" | "textId") {
+ out.push(' ');
+ out.push_str(&rest[name_start..=close]);
+ }
+ rest = &rest[close + 1..];
+ }
+ out
+}
+
+/// Appends paragraph `b`'s content to paragraph `a` and removes `b`. The
+/// joined paragraph keeps `a`'s properties, except that `b`'s section
+/// break (if any) survives, since `b`'s mark ends the joined paragraph.
+pub(super) fn join(txn: &mut Txn<'_>, a: &BlockId, b: &BlockId) -> Option<Pos> {
+ let w = txn.doc.w_prefix().to_owned();
+ let second = txn.get(b)?.clone();
+ let first = txn.get(a)?.clone();
+ if first.kind != BlockKind::Paragraph || second.kind != BlockKind::Paragraph {
+ return None;
+ }
+ let caret = first.content.len();
+ let sect = sect_pr(&second.props, &w, txn);
+ let props = if sect.is_some() || first.props.contains("sectPr") {
+ set_sect_pr(&first.props, sect, &w, txn)
+ } else {
+ first.props.clone()
+ };
+ // Children of the second paragraph's container never exist (paragraphs
+ // have no children), so removing it is enough.
+ txn.remove(b);
+ let block = txn.block_mut(a)?;
+ block.content.insert_content(caret, &second.content);
+ block.props = props;
+ Some(Pos {
+ block: a.clone(),
+ offset: caret,
+ upstream: false,
+ })
+}
+
+/// Pre-order positions of every block and the last position inside each.
+fn doc_positions(story: &Story) -> HashMap<BlockId, (usize, usize)> {
+ fn go(
+ story: &Story,
+ parent: Option<&BlockId>,
+ n: &mut usize,
+ out: &mut HashMap<BlockId, (usize, usize)>,
+ ) {
+ for id in story.children(parent) {
+ let start = *n;
+ *n += 1;
+ go(story, Some(id), n, out);
+ out.insert(id.clone(), (start, *n - 1));
+ }
+ }
+ let mut out = HashMap::new();
+ let mut n = 0;
+ go(story, None, &mut n, &mut out);
+ out
+}
+
+/// Deletes everything between two positions (`from` before `to`). Blocks
+/// wholly inside the range go; table cells are emptied rather than removed;
+/// the end paragraphs are joined when they are siblings. Returns where the
+/// caret goes.
+pub(super) fn delete_range(txn: &mut Txn<'_>, from: &Pos, to: &Pos) -> Pos {
+ if from.block == to.block {
+ if let Some(b) = txn.block_mut(&from.block) {
+ let len = b.content.len();
+ b.content.delete(from.offset.min(len), to.offset.min(len));
+ }
+ return Pos {
+ upstream: false,
+ ..from.clone()
+ };
+ }
+ let positions = doc_positions(txn.story());
+ let (Some(&(a_at, _)), Some(&(b_at, _))) =
+ (positions.get(&from.block), positions.get(&to.block))
+ else {
+ return from.clone();
+ };
+ let covered = |id: &BlockId| {
+ positions
+ .get(id)
+ .is_some_and(|&(s, e)| s > a_at && e < b_at)
+ };
+ // Outermost covered blocks.
+ let mut roots: Vec<(usize, BlockId)> = Vec::new();
+ for b in txn.story().blocks() {
+ if !covered(&b.id) {
+ continue;
+ }
+ if b.parent.as_ref().is_some_and(covered) {
+ continue;
+ }
+ roots.push((positions[&b.id].0, b.id.clone()));
+ }
+ roots.sort();
+ for (_, id) in roots {
+ let Some(block) = txn.get(&id) else {
+ continue;
+ };
+ match block.kind {
+ BlockKind::Cell => clear_cell(txn, &id),
+ _ => {
+ let parent = block.parent.clone();
+ txn.remove(&id);
+ if let Some(p) = parent {
+ ensure_cell_paragraph(txn, &p);
+ }
+ }
+ }
+ }
+ // Trim the ends.
+ if let Some(b) = txn.block_mut(&from.block) {
+ let len = b.content.len();
+ b.content.delete(from.offset.min(len), len);
+ }
+ if let Some(b) = txn.block_mut(&to.block) {
+ let len = b.content.len();
+ b.content.delete(0, to.offset.min(len));
+ }
+ let same_parent = txn.get(&from.block).map(|b| b.parent.clone())
+ == txn.get(&to.block).map(|b| b.parent.clone());
+ if same_parent {
+ join(txn, &from.block, &to.block);
+ }
+ Pos {
+ upstream: false,
+ ..from.clone()
+ }
+}
+
+/// Empties a cell: its first paragraph stays (without text), the rest goes.
+fn clear_cell(txn: &mut Txn<'_>, cell: &BlockId) {
+ let kids: Vec<BlockId> = txn.story().children(Some(cell)).to_vec();
+ let keep = kids
+ .iter()
+ .find(|k| txn.get(k).is_some_and(|b| b.kind == BlockKind::Paragraph))
+ .cloned();
+ for k in &kids {
+ if Some(k) != keep.as_ref() {
+ txn.remove(k);
+ }
+ }
+ match keep {
+ Some(k) => {
+ if let Some(b) = txn.block_mut(&k) {
+ b.content = Content::new();
+ }
+ }
+ None => ensure_cell_paragraph(txn, cell),
+ }
+}
+
+/// A cell must hold at least one paragraph.
+pub(super) fn ensure_cell_paragraph(txn: &mut Txn<'_>, cell: &BlockId) {
+ let Some(c) = txn.get(cell) else {
+ return;
+ };
+ if c.kind != BlockKind::Cell {
+ return;
+ }
+ let has = txn
+ .story()
+ .children(Some(cell))
+ .iter()
+ .any(|k| txn.get(k).is_some_and(|b| b.kind == BlockKind::Paragraph));
+ if has {
+ return;
+ }
+ let last = txn.story().children(Some(cell)).last().cloned();
+ let order = txn.story().key_after(Some(cell), last.as_ref());
+ let id = txn.new_id();
+ txn.insert(Block::new(
+ id,
+ BlockKind::Paragraph,
+ Some(cell.clone()),
+ order,
+ ));
+}
+
+/// Splits the paragraph at `at`; while tracking, the paragraph mark this
+/// adds is recorded as inserted.
+pub(super) fn split_tracked(
+ txn: &mut Txn<'_>,
+ at: &Pos,
+ rev: Option<&super::revise::Revisor>,
+) -> Option<Pos> {
+ let pos = split(txn, at)?;
+ if let Some(r) = rev
+ && let Some(prev) = super::revise::previous_paragraph(txn, &pos.block)
+ {
+ super::revise::mark_inserted(txn, &prev, r);
+ }
+ Some(pos)
+}
+
+/// Inserts `text` at `at` with `attrs`; newlines start new paragraphs
+/// (recorded as inserted while tracking). Returns the position after it.
+pub(super) fn insert_text(
+ txn: &mut Txn<'_>,
+ at: &Pos,
+ text: &str,
+ attrs: &Attrs,
+ rev: Option<&super::revise::Revisor>,
+) -> Pos {
+ let text = text.replace("\r\n", "\n").replace('\r', "\n");
+ let mut pos = Pos {
+ upstream: false,
+ ..at.clone()
+ };
+ for (i, line) in text.split('\n').enumerate() {
+ if i > 0 {
+ match split_tracked(txn, &pos, rev) {
+ Some(p) => pos = p,
+ None => break,
+ }
+ }
+ if line.is_empty() {
+ continue;
+ }
+ let Some(b) = txn.block_mut(&pos.block) else {
+ break;
+ };
+ let offset = pos.offset.min(b.content.len());
+ b.content.insert(offset, line, attrs.clone());
+ pos.offset = offset + crate::model::content::utf16_len(line);
+ }
+ pos
+}
+
+/// Whether the paragraph has its own list numbering (`w:numPr` with a
+/// non-zero `w:numId` in its direct properties).
+pub(super) fn has_direct_numbering(ppr: &str) -> bool {
+ if !ppr.contains("numPr") {
+ return false;
+ }
+ !ppr.contains("w:numId w:val=\"0\"")
+}
+
+/// Whether a paragraph's on/off property `w:{local}` is directly on.
+#[allow(dead_code)]
+pub(super) fn direct_flag(ppr: &str, local: &str, ctx: &SnippetContext) -> Option<bool> {
+ let tree = ctx.parse(ppr).ok()?;
+ let c = tree.w_child(tree.root(), local)?;
+ Some(parse_on_off(tree.val(c)))
+}
diff --git a/crates/docx_engine/src/edit/txn.rs b/crates/docx_engine/src/edit/txn.rs
new file mode 100644
index 0000000000..e6bef502b8
--- /dev/null
+++ b/crates/docx_engine/src/edit/txn.rs
@@ -0,0 +1,455 @@
+//! Transactions: every change to the body goes through one, which keeps the
+//! blocks as they were before it first touched them. Comparing those with
+//! the blocks afterwards yields the collaborative changes (text deltas,
+//! changed fields, new and removed blocks) and the undo record.
+
+use crate::document::{Document, StoryTarget};
+use crate::model::block::{Block, BlockId, BlockKind, Story};
+use crate::model::content::{Content, DeltaOp, attr_delta};
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, HashMap};
+
+/// A block as the collaborative maps store it.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct BlockRecord {
+ /// Block id.
+ pub id: BlockId,
+ /// Kind code (`p`, `tbl`, `tr`, `tc`, `sdt`, `x`).
+ pub k: String,
+ /// Parent block id (empty at the top level).
+ pub p: String,
+ /// Position key among siblings.
+ pub o: String,
+ /// The element's attributes as written.
+ pub a: String,
+ /// Property elements (or the whole element for opaque blocks).
+ pub x: String,
+ /// Paragraph text as a delta of inserts (paragraphs only).
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub t: Option<Vec<DeltaOp>>,
+}
+
+impl BlockRecord {
+ /// The record of a block.
+ pub fn of(b: &Block) -> Self {
+ Self {
+ id: b.id.clone(),
+ k: b.kind.code().to_owned(),
+ p: b.parent
+ .as_ref()
+ .map_or_else(String::new, |p| p.as_str().to_owned()),
+ o: b.order.clone(),
+ a: b.attrs.clone(),
+ x: b.props.clone(),
+ t: (b.kind == BlockKind::Paragraph).then(|| b.content.to_delta()),
+ }
+ }
+
+ /// The block a record describes (`None` for an unknown kind).
+ pub fn to_block(&self) -> Option<Block> {
+ let kind = BlockKind::from_code(&self.k)?;
+ let parent = (!self.p.is_empty()).then(|| BlockId::new(&self.p));
+ let mut b = Block::new(self.id.clone(), kind, parent, self.o.clone());
+ b.attrs = self.a.clone();
+ b.props = self.x.clone();
+ if kind == BlockKind::Paragraph {
+ b.content = self
+ .t
+ .as_deref()
+ .map(Content::from_delta)
+ .unwrap_or_default();
+ }
+ Some(b)
+ }
+}
+
+/// One change to the collaborative state.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "t", rename_all = "camelCase")]
+pub enum Change {
+ /// A new block, or one replaced wholesale.
+ Block {
+ /// The block.
+ block: BlockRecord,
+ },
+ /// Fields of an existing block changed (`p`, `o`, `a`, `x`).
+ Fields {
+ /// Block id.
+ id: BlockId,
+ /// New values.
+ fields: BTreeMap<String, String>,
+ },
+ /// An existing paragraph's text changed.
+ Text {
+ /// Block id.
+ id: BlockId,
+ /// The change, as a rich-text delta.
+ delta: Vec<DeltaOp>,
+ },
+ /// A block was removed.
+ Remove {
+ /// Block id.
+ id: BlockId,
+ },
+ /// An entry of one of the flat maps (parts, relationships, content types).
+ Entry {
+ /// The map.
+ container: String,
+ /// The key.
+ key: String,
+ /// The new value (`None` deletes the entry).
+ value: Option<String>,
+ },
+}
+
+/// The delta that turns `before` into `after`: shared text at both ends is
+/// kept (with attribute changes), the middle is replaced.
+pub fn content_delta(before: &Content, after: &Content) -> Vec<DeltaOp> {
+ let a: Vec<char> = before.text().chars().collect();
+ let b: Vec<char> = after.text().chars().collect();
+ let mut prefix = 0;
+ while prefix < a.len() && prefix < b.len() && a[prefix] == b[prefix] {
+ prefix += 1;
+ }
+ let mut suffix = 0;
+ while suffix < a.len() - prefix
+ && suffix < b.len() - prefix
+ && a[a.len() - 1 - suffix] == b[b.len() - 1 - suffix]
+ {
+ suffix += 1;
+ }
+ let units = |cs: &[char]| cs.iter().map(|c| c.len_utf16()).sum::<usize>();
+ let p16 = units(&a[..prefix]);
+ let a_mid = units(&a[prefix..a.len() - suffix]);
+ let b_mid = units(&b[prefix..b.len() - suffix]);
+ let a_len = before.len();
+ let b_len = after.len();
+ let mut out: Vec<DeltaOp> = Vec::new();
+ let push = |op: DeltaOp, out: &mut Vec<DeltaOp>| match (out.last_mut(), op) {
+ (
+ Some(DeltaOp::Retain {
+ retain: r,
+ attributes: ra,
+ }),
+ DeltaOp::Retain { retain, attributes },
+ ) if *ra == attributes => *r += retain,
+ (_, op) => out.push(op),
+ };
+ // Attribute changes over the shared prefix.
+ let head = attr_delta(&before.slice(0, p16), &after.slice(0, p16));
+ let mut covered = 0;
+ for op in head {
+ if let DeltaOp::Retain { retain, .. } = &op {
+ covered += retain;
+ }
+ push(op, &mut out);
+ }
+ if covered < p16 {
+ push(
+ DeltaOp::Retain {
+ retain: p16 - covered,
+ attributes: BTreeMap::new(),
+ },
+ &mut out,
+ );
+ }
+ if a_mid > 0 {
+ push(DeltaOp::Delete { delete: a_mid }, &mut out);
+ }
+ if b_mid > 0 {
+ for op in after.slice(p16, p16 + b_mid).to_delta() {
+ push(op, &mut out);
+ }
+ }
+ let tail = attr_delta(
+ &before.slice(p16 + a_mid, a_len),
+ &after.slice(p16 + b_mid, b_len),
+ );
+ for op in tail {
+ push(op, &mut out);
+ }
+ // Trailing plain retains say nothing.
+ while matches!(out.last(), Some(DeltaOp::Retain { attributes, .. }) if attributes.is_empty()) {
+ out.pop();
+ }
+ debug_assert_eq!(
+ {
+ let mut c = before.clone();
+ c.apply_delta(&out);
+ c
+ },
+ *after
+ );
+ out
+}
+
+/// Changes that turn block `before` into `after` (both present).
+fn block_changes(before: &Block, after: &Block, out: &mut Vec<Change>) {
+ if before.kind != after.kind {
+ out.push(Change::Block {
+ block: BlockRecord::of(after),
+ });
+ return;
+ }
+ let mut fields = BTreeMap::new();
+ let parent = |b: &Block| {
+ b.parent
+ .as_ref()
+ .map_or_else(String::new, |p| p.as_str().to_owned())
+ };
+ if before.parent != after.parent {
+ fields.insert("p".to_owned(), parent(after));
+ }
+ if before.order != after.order {
+ fields.insert("o".to_owned(), after.order.clone());
+ }
+ if before.attrs != after.attrs {
+ fields.insert("a".to_owned(), after.attrs.clone());
+ }
+ if before.props != after.props {
+ fields.insert("x".to_owned(), after.props.clone());
+ }
+ if !fields.is_empty() {
+ out.push(Change::Fields {
+ id: after.id.clone(),
+ fields,
+ });
+ }
+ if after.kind == BlockKind::Paragraph && before.content != after.content {
+ let delta = content_delta(&before.content, &after.content);
+ if !delta.is_empty() {
+ out.push(Change::Text {
+ id: after.id.clone(),
+ delta,
+ });
+ }
+ }
+}
+
+/// Blocks as they were before a transaction and as it left them.
+#[derive(Clone, Debug, Default)]
+pub struct Step {
+ /// Pre-images (`None` = the block did not exist).
+ pub before: HashMap<BlockId, Option<Block>>,
+ /// Post-images.
+ pub after: HashMap<BlockId, Option<Block>>,
+ /// Ids in the order they were first touched.
+ pub order: Vec<BlockId>,
+ /// Flat-map entries the transaction wrote, with their previous values.
+ pub entries: Vec<(String, String, Option<String>, Option<String>)>,
+ /// The story the blocks belong to. Outside the body, blocks are shared
+ /// as their part's XML rather than one by one.
+ pub story: StoryTarget,
+}
+
+impl Step {
+ /// Whether the step changed nothing.
+ pub fn is_empty(&self) -> bool {
+ self.order
+ .iter()
+ .all(|id| same(self.before.get(id), self.after.get(id)))
+ && self.entries.iter().all(|(_, _, old, new)| old == new)
+ }
+
+ /// The collaborative changes of the step, parents before children.
+ pub fn changes(&self) -> Vec<Change> {
+ let mut out = Vec::new();
+ let blocks = if self.story == StoryTarget::Body {
+ &self.order[..]
+ } else {
+ &[]
+ };
+ for id in blocks {
+ let before = self.before.get(id).and_then(Option::as_ref);
+ let after = self.after.get(id).and_then(Option::as_ref);
+ match (before, after) {
+ (None, Some(b)) => out.push(Change::Block {
+ block: BlockRecord::of(b),
+ }),
+ (Some(_), None) => out.push(Change::Remove { id: id.clone() }),
+ (Some(a), Some(b)) => block_changes(a, b, &mut out),
+ (None, None) => {}
+ }
+ }
+ for (container, key, old, new) in &self.entries {
+ if old != new {
+ out.push(Change::Entry {
+ container: container.clone(),
+ key: key.clone(),
+ value: new.clone(),
+ });
+ }
+ }
+ out
+ }
+
+ /// The step that undoes this one.
+ pub fn inverse(&self) -> Step {
+ Step {
+ before: self.after.clone(),
+ after: self.before.clone(),
+ order: self.order.iter().rev().cloned().collect(),
+ entries: self
+ .entries
+ .iter()
+ .rev()
+ .map(|(c, k, old, new)| (c.clone(), k.clone(), new.clone(), old.clone()))
+ .collect(),
+ story: self.story.clone(),
+ }
+ }
+
+ /// Folds a later step into this one (typing runs merge into one undo step).
+ pub fn merge(&mut self, later: Step) {
+ if self.order.is_empty() && self.entries.is_empty() {
+ self.story = later.story.clone();
+ }
+ for id in later.order {
+ if !self.before.contains_key(&id) {
+ self.before
+ .insert(id.clone(), later.before.get(&id).cloned().flatten());
+ self.order.push(id.clone());
+ }
+ self.after
+ .insert(id.clone(), later.after.get(&id).cloned().flatten());
+ }
+ self.entries.extend(later.entries);
+ }
+}
+
+fn same(a: Option<&Option<Block>>, b: Option<&Option<Block>>) -> bool {
+ match (a.and_then(Option::as_ref), b.and_then(Option::as_ref)) {
+ (None, None) => true,
+ (Some(x), Some(y)) => {
+ x.kind == y.kind
+ && x.parent == y.parent
+ && x.order == y.order
+ && x.attrs == y.attrs
+ && x.props == y.props
+ && x.content == y.content
+ }
+ _ => false,
+ }
+}
+
+/// An open transaction on one of a document's stories.
+pub struct Txn<'d> {
+ /// The document.
+ pub doc: &'d mut Document,
+ step: Step,
+}
+
+impl<'d> Txn<'d> {
+ /// Starts a transaction on a story.
+ pub fn new(doc: &'d mut Document, story: &StoryTarget) -> Self {
+ let story = if doc.has_story(story) {
+ story.clone()
+ } else {
+ StoryTarget::Body
+ };
+ Self {
+ doc,
+ step: Step {
+ story,
+ ..Step::default()
+ },
+ }
+ }
+
+ /// The story being changed.
+ pub fn story(&self) -> &Story {
+ self.doc.story(&self.step.story)
+ }
+
+ fn story_mut(&mut self) -> &mut Story {
+ if self.step.story == StoryTarget::Body {
+ self.doc.body_dirty = true;
+ }
+ self.doc.story_mut(&self.step.story)
+ }
+
+ fn touch(&mut self, id: &BlockId) {
+ if !self.step.before.contains_key(id) {
+ let pre = self.story().get(id).cloned();
+ self.step.before.insert(id.clone(), pre);
+ self.step.order.push(id.clone());
+ }
+ }
+
+ /// A block (read-only).
+ pub fn get(&self, id: &BlockId) -> Option<&Block> {
+ self.story().get(id)
+ }
+
+ /// A block, for changing.
+ pub fn block_mut(&mut self, id: &BlockId) -> Option<&mut Block> {
+ if !self.story().contains(id) {
+ return None;
+ }
+ self.touch(id);
+ self.story_mut().get_mut(id)
+ }
+
+ /// Adds (or replaces) a block.
+ pub fn insert(&mut self, block: Block) {
+ self.touch(&block.id);
+ self.story_mut().insert(block);
+ }
+
+ /// Removes a block and everything inside it.
+ pub fn remove(&mut self, id: &BlockId) {
+ let mut ids = Vec::new();
+ self.story().walk_from(id, &mut |b| ids.push(b.id.clone()));
+ for i in &ids {
+ self.touch(i);
+ }
+ self.story_mut().remove(id);
+ }
+
+ /// A fresh block id.
+ pub fn new_id(&self) -> BlockId {
+ self.doc.next_block_id()
+ }
+
+ /// Ends the transaction. A header, footer or note is written back to
+ /// its part, which is how other peers receive the change.
+ pub fn finish(mut self) -> Step {
+ for id in &self.step.order {
+ let post = self.story().get(id).cloned();
+ self.step.after.insert(id.clone(), post);
+ }
+ if !self.step.order.is_empty() {
+ match &self.step.story {
+ StoryTarget::Body => {}
+ StoryTarget::Part(name) => self.doc.write_part_story(name),
+ StoryTarget::Note { endnote, id } => self.doc.write_notes(*endnote, Some(*id)),
+ }
+ }
+ self.step
+ }
+}
+
+/// Applies a step's post-images to a document (undo and redo).
+pub fn apply_step(doc: &mut Document, step: &Step) {
+ if !doc.has_story(&step.story) {
+ return;
+ }
+ let story = doc.story_mut(&step.story);
+ // Remove first (children before parents is handled by subtree removal),
+ // then insert parents before children so ordering keys resolve.
+ for id in step.order.iter().rev() {
+ if matches!(step.after.get(id), Some(None)) && story.contains(id) {
+ story.remove_one(id);
+ }
+ }
+ for id in &step.order {
+ if let Some(Some(b)) = step.after.get(id) {
+ story.insert(b.clone());
+ }
+ }
+ match &step.story {
+ StoryTarget::Body => doc.body_dirty = true,
+ StoryTarget::Part(name) => doc.write_part_story(name),
+ StoryTarget::Note { endnote, id } => doc.write_notes(*endnote, Some(*id)),
+ }
+}
diff --git a/crates/docx_engine/src/edit/xmledit.rs b/crates/docx_engine/src/edit/xmledit.rs
new file mode 100644
index 0000000000..ccb07f7899
--- /dev/null
+++ b/crates/docx_engine/src/edit/xmledit.rs
@@ -0,0 +1,400 @@
+//! Small edits to property elements kept as XML (`w:pPr`, `w:tcPr`,
+//! `w:tblPr`...): replacing, inserting and removing children in schema
+//! order, and changing attributes of empty children such as `w:spacing`.
+
+use crate::xml::{Decl, SnippetContext, escape_attr};
+
+/// Schema order of paragraph property children (CT_PPr).
+pub(crate) const PPR_ORDER: &[&str] = &[
+ "pStyle",
+ "keepNext",
+ "keepLines",
+ "pageBreakBefore",
+ "framePr",
+ "widowControl",
+ "numPr",
+ "suppressLineNumbers",
+ "pBdr",
+ "shd",
+ "tabs",
+ "suppressAutoHyphens",
+ "kinsoku",
+ "wordWrap",
+ "overflowPunct",
+ "topLinePunct",
+ "autoSpaceDE",
+ "autoSpaceDN",
+ "bidi",
+ "adjustRightInd",
+ "snapToGrid",
+ "spacing",
+ "ind",
+ "contextualSpacing",
+ "mirrorIndents",
+ "suppressOverlap",
+ "jc",
+ "textDirection",
+ "textAlignment",
+ "textboxTightWrap",
+ "outlineLvl",
+ "divId",
+ "cnfStyle",
+ "rPr",
+ "sectPr",
+ "pPrChange",
+];
+
+/// Schema order of table cell property children (CT_TcPr).
+pub(crate) const TCPR_ORDER: &[&str] = &[
+ "cnfStyle",
+ "tcW",
+ "gridSpan",
+ "hMerge",
+ "vMerge",
+ "tcBorders",
+ "shd",
+ "noWrap",
+ "tcMar",
+ "textDirection",
+ "tcFitText",
+ "vAlign",
+ "hideMark",
+ "headers",
+ "cellIns",
+ "cellDel",
+ "cellMerge",
+ "tcPrChange",
+];
+
+/// Schema order of table property children (CT_TblPr).
+pub(crate) const TBLPR_ORDER: &[&str] = &[
+ "tblStyle",
+ "tblpPr",
+ "tblOverlap",
+ "bidiVisual",
+ "tblStyleRowBandSize",
+ "tblStyleColBandSize",
+ "tblW",
+ "jc",
+ "tblCellSpacing",
+ "tblInd",
+ "tblBorders",
+ "shd",
+ "tblLayout",
+ "tblCellMar",
+ "tblLook",
+ "tblCaption",
+ "tblDescription",
+ "tblPrChange",
+];
+
+/// One child element: its qualified name and markup.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct Child {
+ pub qname: String,
+ pub xml: String,
+}
+
+impl Child {
+ /// The local name.
+ pub fn local(&self) -> &str {
+ self.qname.rsplit(':').next().unwrap_or(&self.qname)
+ }
+
+ /// The prefix (empty when unprefixed).
+ pub fn prefix(&self) -> &str {
+ self.qname.rsplit_once(':').map_or("", |(p, _)| p)
+ }
+}
+
+/// A property element opened for editing.
+#[derive(Clone, Debug)]
+pub(crate) struct Element {
+ /// Prefix of the WordprocessingML namespace.
+ w: String,
+ /// The element's start tag without the closing `>` or `/>`.
+ open: String,
+ /// The element's qualified name.
+ qname: String,
+ /// Children, in order.
+ pub children: Vec<Child>,
+ /// Text between children is dropped; property elements hold none.
+ order: &'static [&'static str],
+}
+
+fn qualify(w: &str, local: &str) -> String {
+ if w.is_empty() {
+ local.to_owned()
+ } else {
+ format!("{w}:{local}")
+ }
+}
+
+impl Element {
+ /// Opens `xml` (one element, or empty for a new `w:{local}` element).
+ pub fn open(
+ xml: &str,
+ local: &str,
+ w: &str,
+ decls: &[Decl],
+ order: &'static [&'static str],
+ ) -> Self {
+ let qname = qualify(w, local);
+ let empty = Self {
+ w: w.to_owned(),
+ open: format!("<{qname}"),
+ qname: qname.clone(),
+ children: Vec::new(),
+ order,
+ };
+ let xml = xml.trim();
+ if xml.is_empty() {
+ return empty;
+ }
+ let Ok(tree) = SnippetContext::new(decls).parse(xml) else {
+ return empty;
+ };
+ let root = tree.root();
+ let start = tree.start_tag(root);
+ let open = start
+ .trim_end_matches('>')
+ .trim_end_matches('/')
+ .trim_end()
+ .to_owned();
+ let children = tree
+ .children(root)
+ .map(|c| Child {
+ qname: tree.qname(c).to_owned(),
+ xml: tree.raw(c).to_owned(),
+ })
+ .collect();
+ Self {
+ w: w.to_owned(),
+ open,
+ qname: tree.qname(root).to_owned(),
+ children,
+ order,
+ }
+ }
+
+ fn is_w(&self, c: &Child, local: &str) -> bool {
+ c.local() == local && c.prefix() == self.w
+ }
+
+ /// The qualified name of a WordprocessingML child.
+ pub fn q(&self, local: &str) -> String {
+ qualify(&self.w, local)
+ }
+
+ /// The markup of child `w:{local}`.
+ pub fn get(&self, local: &str) -> Option<&str> {
+ self.children
+ .iter()
+ .find(|c| self.is_w(c, local))
+ .map(|c| c.xml.as_str())
+ }
+
+ /// Whether child `w:{local}` exists.
+ pub fn has(&self, local: &str) -> bool {
+ self.get(local).is_some()
+ }
+
+ fn rank(&self, c: &Child) -> Option<usize> {
+ if c.prefix() != self.w {
+ return None;
+ }
+ self.order.iter().position(|n| *n == c.local())
+ }
+
+ /// Replaces child `w:{local}` with `xml`, inserts it in schema order, or
+ /// removes it (`None`).
+ pub fn set(&mut self, local: &str, xml: Option<String>) {
+ let at = self.children.iter().position(|c| self.is_w(c, local));
+ match (at, xml) {
+ (Some(i), Some(xml)) => self.children[i].xml = xml,
+ (Some(i), None) => {
+ self.children.remove(i);
+ }
+ (None, Some(xml)) => {
+ let rank = self.order.iter().position(|n| *n == local);
+ let at = rank.map_or(self.children.len(), |r| {
+ self.children
+ .iter()
+ .position(|c| self.rank(c).is_some_and(|cr| cr > r))
+ .unwrap_or(self.children.len())
+ });
+ let qname = self.q(local);
+ self.children.insert(at, Child { qname, xml });
+ }
+ (None, None) => {}
+ }
+ }
+
+ /// Sets `w:{local}` to an empty element with a `w:val`.
+ pub fn set_val(&mut self, local: &str, val: Option<&str>) {
+ let xml = val.map(|v| {
+ let mut s = format!("<{} {}=\"", self.q(local), self.q("val"));
+ escape_attr(&mut s, v);
+ s.push_str("\"/>");
+ s
+ });
+ self.set(local, xml);
+ }
+
+ /// Sets an on/off property: present (`true`), `w:val="0"` (`false`) or
+ /// absent (`None`).
+ pub fn set_flag(&mut self, local: &str, on: Option<bool>) {
+ match on {
+ Some(true) => {
+ let xml = format!("<{}/>", self.q(local));
+ self.set(local, Some(xml));
+ }
+ Some(false) => self.set_val(local, Some("0")),
+ None => self.set(local, None),
+ }
+ }
+
+ /// Attributes of an empty child, as (qualified name, value).
+ pub fn attrs_of(&self, local: &str, decls: &[Decl]) -> Vec<(String, String)> {
+ let Some(xml) = self.get(local) else {
+ return Vec::new();
+ };
+ let Ok(tree) = SnippetContext::new(decls).parse(xml) else {
+ return Vec::new();
+ };
+ tree.attrs(tree.root())
+ .iter()
+ .map(|a| (a.qname.to_string(), a.value.to_string()))
+ .collect()
+ }
+
+ /// Sets (or removes) attributes `w:{name}` of the empty child
+ /// `w:{local}`, creating it when needed and removing it when no
+ /// attributes are left.
+ pub fn set_attrs(&mut self, local: &str, changes: &[(&str, Option<String>)], decls: &[Decl]) {
+ let mut attrs = self.attrs_of(local, decls);
+ for (name, value) in changes {
+ let q = self.q(name);
+ match value {
+ Some(v) => match attrs.iter_mut().find(|(k, _)| *k == q) {
+ Some(slot) => slot.1 = v.clone(),
+ None => attrs.push((q, v.clone())),
+ },
+ None => attrs.retain(|(k, _)| *k != q),
+ }
+ }
+ if attrs.is_empty() {
+ self.set(local, None);
+ return;
+ }
+ let mut xml = format!("<{}", self.q(local));
+ for (k, v) in &attrs {
+ xml.push(' ');
+ xml.push_str(k);
+ xml.push_str("=\"");
+ escape_attr(&mut xml, v);
+ xml.push('"');
+ }
+ xml.push_str("/>");
+ self.set(local, Some(xml));
+ }
+
+ /// Whether the element has no children and no attributes (namespace
+ /// declarations aside).
+ pub fn is_empty(&self) -> bool {
+ self.children.is_empty()
+ && self.open[self.qname.len() + 1..]
+ .split_whitespace()
+ .all(|t| t.starts_with("xmlns"))
+ }
+
+ /// The element's markup (empty when it has nothing to say and `drop_empty`).
+ pub fn finish(&self, drop_empty: bool) -> String {
+ if drop_empty && self.is_empty() {
+ return String::new();
+ }
+ if self.children.is_empty() {
+ return format!("{}/>", self.open);
+ }
+ let mut out = String::with_capacity(
+ self.open.len() + self.children.iter().map(|c| c.xml.len()).sum::<usize>() + 32,
+ );
+ out.push_str(&self.open);
+ out.push('>');
+ for c in &self.children {
+ out.push_str(&c.xml);
+ }
+ out.push_str("</");
+ out.push_str(&self.qname);
+ out.push('>');
+ out
+ }
+}
+
+/// Splits concatenated sibling elements (a table's `w:tblPr` + `w:tblGrid`,
+/// a row's `w:tblPrEx` + `w:trPr`) into (qualified name, markup) pairs.
+pub(crate) fn split_siblings(xml: &str, decls: &[Decl]) -> Vec<Child> {
+ if xml.trim().is_empty() {
+ return Vec::new();
+ }
+ let Ok((tree, kids)) = SnippetContext::new(decls).parse_many(xml) else {
+ return Vec::new();
+ };
+ kids.into_iter()
+ .map(|k| Child {
+ qname: tree.qname(k).to_owned(),
+ xml: tree.raw(k).to_owned(),
+ })
+ .collect()
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ fn decls() -> Vec<Decl> {
+ vec![Decl {
+ prefix: "w".into(),
+ uri: "http://schemas.openxmlformats.org/wordprocessingml/2006/main".into(),
+ }]
+ }
+
+ #[test]
+ fn inserts_in_schema_order_and_edits_attributes() {
+ let d = decls();
+ let mut e = Element::open(
+ r#"<w:pPr><w:pStyle w:val="Body"/><w:jc w:val="left"/></w:pPr>"#,
+ "pPr",
+ "w",
+ &d,
+ PPR_ORDER,
+ );
+ e.set_val("jc", Some("center"));
+ e.set_attrs("spacing", &[("after", Some("120".into()))], &d);
+ e.set_flag("keepNext", Some(true));
+ assert_eq!(
+ e.finish(true),
+ r#"<w:pPr><w:pStyle w:val="Body"/><w:keepNext/><w:spacing w:after="120"/><w:jc w:val="center"/></w:pPr>"#
+ );
+ e.set_attrs("spacing", &[("after", None)], &d);
+ e.set("pStyle", None);
+ e.set("keepNext", None);
+ e.set("jc", None);
+ assert_eq!(e.finish(true), "");
+ }
+
+ #[test]
+ fn opens_empty_and_self_closing() {
+ let d = decls();
+ let mut e = Element::open("", "pPr", "w", &d, PPR_ORDER);
+ assert!(e.is_empty());
+ e.set_val("pStyle", Some("Heading1"));
+ assert_eq!(
+ e.finish(true),
+ r#"<w:pPr><w:pStyle w:val="Heading1"/></w:pPr>"#
+ );
+ let e = Element::open(r#"<w:tcPr/>"#, "tcPr", "w", &d, TCPR_ORDER);
+ assert!(e.children.is_empty());
+ assert_eq!(e.finish(false), "<w:tcPr/>");
+ }
+}
diff --git a/crates/docx_engine/src/error.rs b/crates/docx_engine/src/error.rs
new file mode 100644
index 0000000000..b85187089e
--- /dev/null
+++ b/crates/docx_engine/src/error.rs
@@ -0,0 +1,35 @@
+//! Error type shared by every engine module.
+
+/// Everything that can go wrong while reading, laying out, editing, or saving.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+ /// The package container (ZIP, OPC) failed; see the source error.
+ #[error(transparent)]
+ Package(#[from] pptx_engine::Error),
+ /// An XML part is not well-formed.
+ #[error("invalid xml in {part}: {message}")]
+ Xml {
+ /// The part being parsed.
+ part: String,
+ /// What was wrong.
+ message: String,
+ },
+ /// A required part is missing.
+ #[error("missing part: {0}")]
+ MissingPart(String),
+ /// The package is not a WordprocessingML document.
+ #[error("not a Word document: {0}")]
+ NotWord(String),
+ /// An edit operation was rejected.
+ #[error("invalid edit: {0}")]
+ InvalidEdit(String),
+ /// A referenced block or position does not exist.
+ #[error("not found: {0}")]
+ NotFound(String),
+ /// Shared collaborative state could not be read.
+ #[error("invalid collaborative state: {0}")]
+ Collab(String),
+}
+
+/// Convenience alias for engine results.
+pub type Result<T> = std::result::Result<T, Error>;
diff --git a/crates/docx_engine/src/hash.rs b/crates/docx_engine/src/hash.rs
new file mode 100644
index 0000000000..44a4b00ad6
--- /dev/null
+++ b/crates/docx_engine/src/hash.rs
@@ -0,0 +1,76 @@
+//! A fast, non-cryptographic hasher for the engine's in-memory maps (the
+//! "Fx" hash rustc uses). Layout looks up thousands of cached paragraphs,
+//! formats and blocks per pass; SipHash's flood resistance buys nothing
+//! there and costs a quarter of a relayout.
+
+use std::collections::HashMap;
+use std::hash::{BuildHasherDefault, Hasher};
+
+/// The Fx hasher.
+#[derive(Clone, Copy, Default)]
+pub struct FxHasher {
+ hash: u64,
+}
+
+const SEED: u64 = 0x51_7c_c1_b7_27_22_0a_95;
+
+impl FxHasher {
+ #[inline]
+ fn add(&mut self, word: u64) {
+ self.hash = (self.hash.rotate_left(5) ^ word).wrapping_mul(SEED);
+ }
+}
+
+impl Hasher for FxHasher {
+ #[inline]
+ fn write(&mut self, bytes: &[u8]) {
+ let mut chunks = bytes.chunks_exact(8);
+ for chunk in &mut chunks {
+ let mut word = [0u8; 8];
+ word.copy_from_slice(chunk);
+ self.add(u64::from_le_bytes(word));
+ }
+ let rest = chunks.remainder();
+ if !rest.is_empty() {
+ let mut word = [0u8; 8];
+ word[..rest.len()].copy_from_slice(rest);
+ self.add(u64::from_le_bytes(word) ^ ((rest.len() as u64) << 56));
+ }
+ }
+
+ #[inline]
+ fn write_u8(&mut self, i: u8) {
+ self.add(u64::from(i));
+ }
+
+ #[inline]
+ fn write_u16(&mut self, i: u16) {
+ self.add(u64::from(i));
+ }
+
+ #[inline]
+ fn write_u32(&mut self, i: u32) {
+ self.add(u64::from(i));
+ }
+
+ #[inline]
+ fn write_u64(&mut self, i: u64) {
+ self.add(i);
+ }
+
+ #[inline]
+ fn write_usize(&mut self, i: usize) {
+ self.add(i as u64);
+ }
+
+ #[inline]
+ fn finish(&self) -> u64 {
+ self.hash
+ }
+}
+
+/// Builds [`FxHasher`]s.
+pub type FxBuild = BuildHasherDefault<FxHasher>;
+
+/// A `HashMap` with the Fx hash.
+pub type FxMap<K, V> = HashMap<K, V, FxBuild>;
diff --git a/crates/docx_engine/src/layout.rs b/crates/docx_engine/src/layout.rs
new file mode 100644
index 0000000000..2487bc19dc
--- /dev/null
+++ b/crates/docx_engine/src/layout.rs
@@ -0,0 +1,412 @@
+//! Paginated layout.
+//!
+//! [`Document::layout`] turns the document into pages of placed items:
+//! lines of text, shading and borders, drawings. Paragraphs are measured
+//! into clusters ([`inline`]), broken into lines ([`lines`]), and flowed into
+//! columns and pages ([`flow`]) with Word's rules for spacing, keeping lines
+//! together, widows and orphans, sections, headers, footers and notes.
+
+pub mod bidi;
+pub mod drawing;
+mod flow;
+pub mod fonts;
+pub mod format;
+pub mod inline;
+pub mod lines;
+mod table;
+
+use crate::document::Document;
+use crate::model::block::BlockId;
+use crate::model::props::Border;
+use format::ParaFormat;
+use inline::Inline;
+use lines::Lines;
+use pptx_engine::font::FontDb;
+use pptx_engine::model::color::Rgba;
+use pptx_engine::path::Rect;
+use std::sync::{Arc, Mutex};
+
+pub use flow::LayoutOptions;
+
+/// Which story a paragraph belongs to.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub enum StoryRef {
+ /// The body.
+ Body,
+ /// A header or footer part.
+ Part(String),
+ /// A footnote.
+ Footnote(i64),
+ /// An endnote.
+ Endnote(i64),
+ /// A text box inside a drawing (anchor paragraph and drawing index).
+ TextBox(BlockId, u16),
+}
+
+/// A laid-out paragraph, shared by the lines that show it.
+#[derive(Debug)]
+pub struct ParaBox {
+ /// The story.
+ pub story: StoryRef,
+ /// The paragraph block.
+ pub block: BlockId,
+ /// Its clusters.
+ pub inline: Inline,
+ /// Its lines.
+ pub lines: Lines,
+ /// Its formatting.
+ pub format: Arc<ParaFormat>,
+}
+
+/// A line placed on a page.
+#[derive(Clone, Debug)]
+pub struct PlacedLine {
+ /// The paragraph.
+ pub para: Arc<ParaBox>,
+ /// Line index within the paragraph.
+ pub line: usize,
+ /// Page x of the paragraph's text area left edge.
+ pub x: f32,
+ /// Page y of the line's top.
+ pub y: f32,
+ /// Clip rectangle (cells with an exact height).
+ pub clip: Option<Rect>,
+}
+
+impl PlacedLine {
+ /// The line.
+ pub fn line(&self) -> &lines::Line {
+ &self.para.lines.lines[self.line]
+ }
+
+ /// Page y of the baseline.
+ pub fn baseline(&self) -> f32 {
+ self.y + self.line().baseline
+ }
+}
+
+/// A drawing placed on a page.
+#[derive(Clone, Debug)]
+pub struct PlacedDrawing {
+ /// The drawing.
+ pub drawing: Arc<drawing::Drawing>,
+ /// Its box on the page (without effect extents).
+ pub rect: Rect,
+ /// Story of the paragraph that holds it (for part relationships).
+ pub story: StoryRef,
+}
+
+/// Something drawn on a page.
+#[derive(Clone, Debug)]
+pub enum Item {
+ /// A line of text.
+ Line(PlacedLine),
+ /// A filled rectangle (shading).
+ Fill {
+ /// Area.
+ rect: Rect,
+ /// Color.
+ color: Rgba,
+ },
+ /// A border segment from (x0, y0) to (x1, y1).
+ Rule {
+ /// Start x.
+ x0: f32,
+ /// Start y.
+ y0: f32,
+ /// End x.
+ x1: f32,
+ /// End y.
+ y1: f32,
+ /// Border style.
+ border: Border,
+ },
+ /// A drawing.
+ Drawing(PlacedDrawing),
+ /// A line number in the margin.
+ LineNumber {
+ /// Text.
+ text: String,
+ /// Right edge x.
+ right: f32,
+ /// Baseline y.
+ baseline: f32,
+ /// Font size.
+ size: f32,
+ /// Font family.
+ font: String,
+ },
+}
+
+/// One page.
+#[derive(Clone, Debug)]
+pub struct Page {
+ /// Width (points).
+ pub width: f32,
+ /// Height (points).
+ pub height: f32,
+ /// Section index.
+ pub section: usize,
+ /// Displayed page number.
+ pub number: i64,
+ /// Items behind the text (floats behind, page borders).
+ pub behind: Vec<Item>,
+ /// Body, headers, footers and notes.
+ pub items: Vec<Item>,
+ /// Items in front of the text.
+ pub front: Vec<Item>,
+ /// The body text area (for editors).
+ pub body: Rect,
+ /// The header area, above the body.
+ pub header: Option<Chrome>,
+ /// The footer area, below the body.
+ pub footer: Option<Chrome>,
+}
+
+/// A page's header or footer area, for editors.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Chrome {
+ /// The part shown there (`None` when the section has none for the page).
+ pub part: Option<String>,
+ /// Top (points).
+ pub top: f32,
+ /// Bottom (points).
+ pub bottom: f32,
+}
+
+impl Page {
+ /// Every item in paint order.
+ pub fn all_items(&self) -> impl Iterator<Item = &Item> {
+ self.behind.iter().chain(&self.items).chain(&self.front)
+ }
+
+ /// Placed lines of one story.
+ pub fn lines_of<'a>(
+ &'a self,
+ story: &'a StoryRef,
+ ) -> impl Iterator<Item = &'a PlacedLine> + 'a {
+ self.items.iter().filter_map(move |i| match i {
+ Item::Line(l) if &l.para.story == story => Some(l),
+ _ => None,
+ })
+ }
+}
+
+/// A laid-out document.
+#[derive(Clone, Debug, Default)]
+pub struct Layout {
+ /// The pages.
+ pub pages: Vec<Page>,
+}
+
+/// What a measured paragraph depends on besides its own content.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ParaKey {
+ pub version: u64,
+ pub generation: u64,
+ pub width: u32,
+ pub table: u64,
+ pub label: Option<(String, String)>,
+ pub grid: u32,
+ pub origin: u32,
+ pub markup: bool,
+ pub note_number: Option<String>,
+}
+
+#[derive(Debug)]
+struct Cached {
+ key: ParaKey,
+ pb: Arc<ParaBox>,
+ epoch: u64,
+}
+
+/// Laid out paragraphs by story and block.
+type ParaBoxes = crate::hash::FxMap<(StoryRef, BlockId), Vec<Cached>>;
+
+/// Paragraph measurements kept between layouts, so laying out again after
+/// an edit re-measures only the paragraphs the edit touched.
+#[derive(Debug, Default)]
+pub struct LayoutCache {
+ /// Per paragraph, the boxes of its last pass: a few, since one pass can
+ /// lay a paragraph out more than once (a table cell measured for the
+ /// column widths, then laid out at its width).
+ paras: Mutex<(u64, ParaBoxes)>,
+ /// Paragraphs showing page fields, by the values they show (a footer's
+ /// page number on every page).
+ dynamic: Mutex<crate::hash::FxMap<(StoryRef, BlockId, u64), Cached>>,
+ /// Laid-out tables.
+ tables: flow::TableCache,
+ /// The body's list labels and note numbers.
+ numbers: flow::NumbersCache,
+ /// Resolved formats of one style sheet generation.
+ formats: Mutex<Option<(u64, Arc<format::FormatCache>)>>,
+ /// Page count of the last layout (the first guess for page-count fields).
+ pages: Mutex<Option<usize>>,
+}
+
+impl LayoutCache {
+ /// An empty cache.
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub(crate) fn get(
+ &self,
+ story: &StoryRef,
+ block: &BlockId,
+ key: &ParaKey,
+ ) -> Option<Arc<ParaBox>> {
+ let mut guard = self.paras.lock().unwrap_or_else(|e| e.into_inner());
+ let epoch = guard.0;
+ let hit = guard
+ .1
+ .get_mut(&(story.clone(), block.clone()))?
+ .iter_mut()
+ .find(|c| c.key == *key)?;
+ hit.epoch = epoch;
+ Some(Arc::clone(&hit.pb))
+ }
+
+ pub(crate) fn put(&self, story: &StoryRef, block: &BlockId, key: ParaKey, pb: Arc<ParaBox>) {
+ /// Boxes kept per paragraph.
+ const KEEP: usize = 4;
+ let mut guard = self.paras.lock().unwrap_or_else(|e| e.into_inner());
+ let epoch = guard.0;
+ let list = guard.1.entry((story.clone(), block.clone())).or_default();
+ list.retain(|c| c.key != key);
+ if list.len() >= KEEP {
+ // The least recently used goes.
+ if let Some(oldest) = (0..list.len()).min_by_key(|&i| list[i].epoch) {
+ list.remove(oldest);
+ }
+ }
+ list.push(Cached { key, pb, epoch });
+ }
+
+ /// A paragraph with page fields, as laid out for these field values.
+ pub(crate) fn get_dynamic(
+ &self,
+ story: &StoryRef,
+ block: &BlockId,
+ fields: u64,
+ key: &ParaKey,
+ ) -> Option<Arc<ParaBox>> {
+ let epoch = self.paras.lock().unwrap_or_else(|e| e.into_inner()).0;
+ let mut guard = self.dynamic.lock().unwrap_or_else(|e| e.into_inner());
+ let hit = guard.get_mut(&(story.clone(), block.clone(), fields))?;
+ if hit.key != *key {
+ return None;
+ }
+ hit.epoch = epoch;
+ Some(Arc::clone(&hit.pb))
+ }
+
+ pub(crate) fn put_dynamic(
+ &self,
+ story: &StoryRef,
+ block: &BlockId,
+ fields: u64,
+ key: ParaKey,
+ pb: Arc<ParaBox>,
+ ) {
+ let epoch = self.paras.lock().unwrap_or_else(|e| e.into_inner()).0;
+ self.dynamic
+ .lock()
+ .unwrap_or_else(|e| e.into_inner())
+ .insert(
+ (story.clone(), block.clone(), fields),
+ Cached { key, pb, epoch },
+ );
+ }
+
+ /// Starts a layout pass.
+ pub(crate) fn begin(&self) {
+ let mut guard = self.paras.lock().unwrap_or_else(|e| e.into_inner());
+ guard.0 += 1;
+ }
+
+ /// The current layout pass.
+ pub(crate) fn epoch(&self) -> u64 {
+ self.paras.lock().unwrap_or_else(|e| e.into_inner()).0
+ }
+
+ /// Ends a layout pass, dropping the paragraphs and tables it did not
+ /// use, unless something else still holds them (a cached table holds
+ /// its paragraphs, a layout the lines it shows).
+ pub(crate) fn end(&self) {
+ let mut guard = self.paras.lock().unwrap_or_else(|e| e.into_inner());
+ let epoch = guard.0;
+ let keep = |c: &Cached| c.epoch == epoch || Arc::strong_count(&c.pb) > 1;
+ guard.1.retain(|_, list| {
+ list.retain(keep);
+ !list.is_empty()
+ });
+ drop(guard);
+ self.dynamic
+ .lock()
+ .unwrap_or_else(|e| e.into_inner())
+ .retain(|_, c| keep(c));
+ self.tables.end(epoch);
+ }
+
+ /// The format cache for a style sheet generation.
+ pub(crate) fn formats(&self, generation: u64) -> Arc<format::FormatCache> {
+ let mut guard = self.formats.lock().unwrap_or_else(|e| e.into_inner());
+ match &*guard {
+ Some((g, cache)) if *g == generation => Arc::clone(cache),
+ _ => {
+ let cache = Arc::new(format::FormatCache::default());
+ *guard = Some((generation, Arc::clone(&cache)));
+ cache
+ }
+ }
+ }
+
+ /// The last layout's page count.
+ pub(crate) fn last_pages(&self) -> Option<usize> {
+ *self.pages.lock().unwrap_or_else(|e| e.into_inner())
+ }
+
+ pub(crate) fn set_last_pages(&self, pages: usize) {
+ *self.pages.lock().unwrap_or_else(|e| e.into_inner()) = Some(pages);
+ }
+
+ /// Number of cached paragraphs.
+ pub fn len(&self) -> usize {
+ self.paras.lock().map_or(0, |g| g.1.len())
+ }
+
+ /// Whether nothing is cached.
+ pub fn is_empty(&self) -> bool {
+ self.len() == 0
+ }
+}
+
+impl Document {
+ /// Lays the document out into pages.
+ pub fn layout(&self, fonts: &FontDb) -> Layout {
+ self.layout_with(fonts, &LayoutOptions::default())
+ }
+
+ /// Lays the document out with options.
+ pub fn layout_with(&self, fonts: &FontDb, options: &LayoutOptions) -> Layout {
+ flow::layout(self, fonts, options, None)
+ }
+
+ /// Lays the document out, reusing paragraph measurements from `cache`
+ /// (and leaving this layout's in it).
+ pub fn layout_cached(
+ &self,
+ fonts: &FontDb,
+ options: &LayoutOptions,
+ cache: &LayoutCache,
+ ) -> Layout {
+ cache.begin();
+ let layout = flow::layout(self, fonts, options, Some(cache));
+ cache.end();
+ layout
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/layout/bidi.rs b/crates/docx_engine/src/layout/bidi.rs
new file mode 100644
index 0000000000..4f5b2ad9d4
--- /dev/null
+++ b/crates/docx_engine/src/layout/bidi.rs
@@ -0,0 +1,446 @@
+//! Bidirectional text: embedding levels from the Unicode Bidirectional
+//! Algorithm (UAX #9) and the visual order of a line.
+//!
+//! A paragraph's direction comes from `w:bidi`; Word marks runs typed
+//! right to left with `w:rtl`, and their spaces and punctuation then read
+//! right to left where the algorithm would otherwise fall back to the
+//! paragraph's direction. Explicit embedding and isolate characters are
+//! not interpreted (Word documents express direction through properties).
+
+/// Bidirectional character types (UAX #9 Table 4), without the explicit
+/// formatting types.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Class {
+ /// Left to right.
+ L,
+ /// Right to left (Hebrew).
+ R,
+ /// Arabic letter.
+ Al,
+ /// European number.
+ En,
+ /// European number separator (`+`, `-`).
+ Es,
+ /// European number terminator (`#`, `$`, `%`...).
+ Et,
+ /// Arabic number.
+ An,
+ /// Common number separator (`,`, `.`, `/`, `:`).
+ Cs,
+ /// Non-spacing mark.
+ Nsm,
+ /// Boundary neutral (zero-width and control characters).
+ Bn,
+ /// Paragraph separator.
+ B,
+ /// Segment separator (tab).
+ S,
+ /// Whitespace.
+ Ws,
+ /// Other neutral.
+ On,
+}
+
+/// The bidirectional type of a character.
+pub fn class(c: char) -> Class {
+ use Class::*;
+ let u = c as u32;
+ match u {
+ 0x0030..=0x0039
+ | 0x00B2
+ | 0x00B3
+ | 0x00B9
+ | 0x06F0..=0x06F9
+ | 0x2070
+ | 0x2074..=0x2079
+ | 0x2080..=0x2089
+ | 0x2488..=0x249B
+ | 0xFF10..=0xFF19 => En,
+ 0x002B | 0x002D | 0x207A | 0x207B | 0x208A | 0x208B | 0x2212 | 0xFB29 | 0xFE62 | 0xFE63
+ | 0xFF0B | 0xFF0D => Es,
+ 0x0023..=0x0025
+ | 0x00A2..=0x00A5
+ | 0x00B0
+ | 0x00B1
+ | 0x0609
+ | 0x060A
+ | 0x066A
+ | 0x09F2
+ | 0x09F3
+ | 0x0E3F
+ | 0x17DB
+ | 0x2030..=0x2034
+ | 0x20A0..=0x20CF
+ | 0x212E
+ | 0x2213
+ | 0xFE5F
+ | 0xFE69
+ | 0xFE6A
+ | 0xFF03..=0xFF05
+ | 0xFFE0
+ | 0xFFE1
+ | 0xFFE5
+ | 0xFFE6 => Et,
+ 0x0600..=0x0605 | 0x0660..=0x0669 | 0x066B | 0x066C | 0x06DD | 0x0890 | 0x0891 | 0x08E2 => {
+ An
+ }
+ 0x002C | 0x002E | 0x002F | 0x003A | 0x00A0 | 0x060C | 0x202F | 0x2044 | 0xFE50 | 0xFE52
+ | 0xFE55 | 0xFF0C | 0xFF0E | 0xFF0F | 0xFF1A => Cs,
+ 0x0009 | 0x000B | 0x001F => S,
+ 0x000A | 0x000D | 0x001C..=0x001E | 0x0085 | 0x2029 => B,
+ 0x000C | 0x0020 | 0x1680 | 0x2000..=0x200A | 0x2028 | 0x205F | 0x3000 => Ws,
+ 0x0000..=0x0008
+ | 0x000E..=0x001B
+ | 0x007F..=0x0084
+ | 0x0086..=0x009F
+ | 0x00AD
+ | 0x180E
+ | 0x200B..=0x200D
+ | 0x202A..=0x202E
+ | 0x2060..=0x2069
+ | 0x206A..=0x206F
+ | 0xFEFF => Bn,
+ 0x200E => L,
+ 0x200F => R,
+ 0x061C => Al,
+ // Combining marks.
+ 0x0300..=0x036F
+ | 0x0483..=0x0489
+ | 0x0591..=0x05BD
+ | 0x05BF
+ | 0x05C1
+ | 0x05C2
+ | 0x05C4
+ | 0x05C5
+ | 0x05C7
+ | 0x0610..=0x061A
+ | 0x064B..=0x065F
+ | 0x0670
+ | 0x06D6..=0x06DC
+ | 0x06DF..=0x06E4
+ | 0x06E7
+ | 0x06E8
+ | 0x06EA..=0x06ED
+ | 0x0711
+ | 0x0730..=0x074A
+ | 0x07A6..=0x07B0
+ | 0x07EB..=0x07F3
+ | 0x0816..=0x0819
+ | 0x081B..=0x0823
+ | 0x0825..=0x0827
+ | 0x0829..=0x082D
+ | 0x0859..=0x085B
+ | 0x08D3..=0x08E1
+ | 0x08E3..=0x0902
+ | 0x1AB0..=0x1AFF
+ | 0x1DC0..=0x1DFF
+ | 0x20D0..=0x20F0
+ | 0xFB1E
+ | 0xFE00..=0xFE0F
+ | 0xFE20..=0xFE2F => Nsm,
+ // Hebrew, Samaritan, Mandaic, NKo and other right-to-left scripts.
+ 0x0590..=0x05FF
+ | 0x07C0..=0x085F
+ | 0xFB1D..=0xFB4F
+ | 0x10800..=0x10FFF
+ | 0x1E800..=0x1EDFF => R,
+ // Arabic, Syriac, Thaana and their presentation forms.
+ 0x0600..=0x07BF
+ | 0x0860..=0x08FF
+ | 0xFB50..=0xFD3D
+ | 0xFD40..=0xFDFF
+ | 0xFE70..=0xFEFE
+ | 0x1EE00..=0x1EEFF => Al,
+ // ASCII and Latin-1 punctuation and symbols.
+ 0x0021
+ | 0x0022
+ | 0x0026..=0x002A
+ | 0x003B..=0x0040
+ | 0x005B..=0x0060
+ | 0x007B..=0x007E
+ | 0x00A1
+ | 0x00A6..=0x00A9
+ | 0x00AB
+ | 0x00AC
+ | 0x00AE
+ | 0x00AF
+ | 0x00B4
+ | 0x00B6..=0x00B8
+ | 0x00BB..=0x00BF
+ | 0x00D7
+ | 0x00F7 => On,
+ // General punctuation, symbols, arrows, math, shapes and CJK
+ // punctuation (letter-like symbols aside).
+ 0x2010..=0x2027
+ | 0x2035..=0x2043
+ | 0x2045..=0x205E
+ | 0x2190..=0x2211
+ | 0x2214..=0x2335
+ | 0x237B..=0x2394
+ | 0x2396..=0x2487
+ | 0x24EA..=0x26AB
+ | 0x26AD..=0x27FF
+ | 0x2900..=0x2B73
+ | 0x3001..=0x3004
+ | 0x3008..=0x3020
+ | 0xFD3E
+ | 0xFD3F
+ | 0xFE10..=0xFE19
+ | 0xFE30..=0xFE4F
+ | 0xFE51
+ | 0xFE54
+ | 0xFE56..=0xFE5E
+ | 0xFE60
+ | 0xFE61
+ | 0xFE64..=0xFE68
+ | 0xFE6B
+ | 0xFF01
+ | 0xFF02
+ | 0xFF06..=0xFF0A
+ | 0xFF1B..=0xFF20
+ | 0xFF3B..=0xFF40
+ | 0xFF5B..=0xFF65
+ | 0xFFE2..=0xFFE4
+ | 0xFFE8..=0xFFEE => On,
+ _ => L,
+ }
+}
+
+/// The glyph a character shows at a right-to-left level (paired brackets
+/// and other mirrored characters), if it changes.
+pub fn mirror(c: char) -> Option<char> {
+ const PAIRS: &[(char, char)] = &[
+ ('(', ')'),
+ ('<', '>'),
+ ('[', ']'),
+ ('{', '}'),
+ ('\u{00AB}', '\u{00BB}'),
+ ('\u{2039}', '\u{203A}'),
+ ('\u{2045}', '\u{2046}'),
+ ('\u{207D}', '\u{207E}'),
+ ('\u{208D}', '\u{208E}'),
+ ('\u{2208}', '\u{220B}'),
+ ('\u{2264}', '\u{2265}'),
+ ('\u{226A}', '\u{226B}'),
+ ('\u{2282}', '\u{2283}'),
+ ('\u{2286}', '\u{2287}'),
+ ('\u{2329}', '\u{232A}'),
+ ('\u{27E8}', '\u{27E9}'),
+ ('\u{27E6}', '\u{27E7}'),
+ ('\u{3008}', '\u{3009}'),
+ ('\u{300A}', '\u{300B}'),
+ ('\u{300C}', '\u{300D}'),
+ ('\u{300E}', '\u{300F}'),
+ ('\u{3010}', '\u{3011}'),
+ ('\u{3014}', '\u{3015}'),
+ ('\u{FF08}', '\u{FF09}'),
+ ('\u{FF3B}', '\u{FF3D}'),
+ ('\u{FF5B}', '\u{FF5D}'),
+ ];
+ PAIRS.iter().find_map(|&(a, b)| {
+ if c == a {
+ Some(b)
+ } else if c == b {
+ Some(a)
+ } else {
+ None
+ }
+ })
+}
+
+/// Whether text of these types needs bidirectional processing in a
+/// paragraph of the given direction.
+pub fn needed(classes: &[Class], rtl_paragraph: bool) -> bool {
+ rtl_paragraph
+ || classes
+ .iter()
+ .any(|c| matches!(c, Class::R | Class::Al | Class::An))
+}
+
+/// Strong direction for neutral resolution: L, R (numbers count as R).
+fn strong(c: Class) -> Option<bool> {
+ match c {
+ Class::L => Some(false),
+ Class::R | Class::Al | Class::En | Class::An => Some(true),
+ _ => None,
+ }
+}
+
+/// Resolves the embedding level of each character of a paragraph:
+/// `classes` from [`class`], `rtl_runs[i]` when the character's run is
+/// marked right to left, `base` the paragraph level (0 or 1). As in Word,
+/// a separator in a right-to-left run does not join the numbers around
+/// it: `78/265` reads as two numbers, right to left.
+pub fn levels(classes: &[Class], rtl_runs: &[bool], base: u8) -> Vec<u8> {
+ use Class::*;
+ let n = classes.len();
+ let sos = if base % 2 == 1 { R } else { L };
+ let mut t: Vec<Class> = classes.to_vec();
+ // W1: marks (and boundary neutrals) take the type before them.
+ let mut prev = sos;
+ for c in t.iter_mut() {
+ if matches!(*c, Nsm | Bn) {
+ *c = prev;
+ }
+ prev = *c;
+ }
+ // W2: European numbers after Arabic letters are Arabic numbers.
+ let mut last_strong = sos;
+ for c in t.iter_mut() {
+ match *c {
+ L | R | Al => last_strong = *c,
+ En if last_strong == Al => *c = An,
+ _ => {}
+ }
+ }
+ // W3.
+ for c in t.iter_mut() {
+ if *c == Al {
+ *c = R;
+ }
+ }
+ // W4: a single separator between two numbers of a kind joins them.
+ for i in 1..n.saturating_sub(1) {
+ if rtl_runs.get(i).copied().unwrap_or(false) {
+ continue;
+ }
+ let (a, b) = (t[i - 1], t[i + 1]);
+ match t[i] {
+ Es if a == En && b == En => t[i] = En,
+ Cs if a == En && b == En => t[i] = En,
+ Cs if a == An && b == An => t[i] = An,
+ _ => {}
+ }
+ }
+ // W5: terminators next to European numbers are part of them.
+ let mut i = 0;
+ while i < n {
+ if t[i] != Et {
+ i += 1;
+ continue;
+ }
+ let start = i;
+ while i < n && t[i] == Et {
+ i += 1;
+ }
+ let touches = (start > 0 && t[start - 1] == En) || (i < n && t[i] == En);
+ if touches {
+ for c in &mut t[start..i] {
+ *c = En;
+ }
+ }
+ }
+ // W6: other separators and terminators are neutral.
+ for c in t.iter_mut() {
+ if matches!(*c, Es | Et | Cs) {
+ *c = On;
+ }
+ }
+ // W7: European numbers in left-to-right text are left to right.
+ let mut last_strong = sos;
+ for c in t.iter_mut() {
+ match *c {
+ L | R => last_strong = *c,
+ En if last_strong == L => *c = L,
+ _ => {}
+ }
+ }
+ // N1, N2: neutrals between text of one direction take it; others the
+ // paragraph's (right to left in runs marked so).
+ let mut i = 0;
+ while i < n {
+ if !matches!(t[i], B | S | Ws | On) {
+ i += 1;
+ continue;
+ }
+ let start = i;
+ while i < n && matches!(t[i], B | S | Ws | On) {
+ i += 1;
+ }
+ let before = (0..start)
+ .rev()
+ .find_map(|k| strong(t[k]))
+ .unwrap_or(base % 2 == 1);
+ let after = (i..n).find_map(|k| strong(t[k])).unwrap_or(base % 2 == 1);
+ for (k, c) in t.iter_mut().enumerate().take(i).skip(start) {
+ let rtl = if before == after {
+ before
+ } else {
+ base % 2 == 1 || rtl_runs.get(k).copied().unwrap_or(false)
+ };
+ *c = if rtl { R } else { L };
+ }
+ }
+ // I1, I2.
+ let mut out: Vec<u8> = t
+ .iter()
+ .map(|c| match (base % 2 == 1, c) {
+ (false, R) => base + 1,
+ (false, An | En) => base + 2,
+ (true, L | En | An) => base + 1,
+ _ => base,
+ })
+ .collect();
+ // L1: tabs and the whitespace before them (and at the paragraph's end)
+ // are at the paragraph's level.
+ let mut reset = true;
+ for k in (0..n).rev() {
+ match classes[k] {
+ S | B => {
+ out[k] = base;
+ reset = true;
+ }
+ Ws | Bn if reset => out[k] = base,
+ _ => reset = false,
+ }
+ }
+ out
+}
+
+/// Puts one line in visual order. `x` and `adv` give the line's clusters
+/// in logical order as laid out left to right; `levels` their embedding
+/// levels. Every run at or above each level, from the highest down to 1,
+/// is mirrored within its extent; a right-to-left paragraph's whole line
+/// is mirrored within `area` (the text area), so the paragraph's start
+/// lands on its right.
+pub fn reorder(x: &mut [f32], adv: &[f32], levels: &[u8], base: u8, area: (f32, f32)) {
+ let n = x.len().min(adv.len()).min(levels.len());
+ let Some(&max) = levels[..n].iter().max() else {
+ return;
+ };
+ let mut order: Vec<usize> = (0..n).collect();
+ let mut lowest = 1;
+ if base % 2 == 1 {
+ for i in 0..n {
+ x[i] = area.0 + area.1 - (x[i] + adv[i]);
+ }
+ order.reverse();
+ lowest = 2;
+ }
+ for level in (lowest..=max).rev() {
+ let mut k = 0;
+ while k < n {
+ if levels[order[k]] < level {
+ k += 1;
+ continue;
+ }
+ let start = k;
+ while k < n && levels[order[k]] >= level {
+ k += 1;
+ }
+ let run = &order[start..k];
+ let left = run.iter().map(|&i| x[i]).fold(f32::INFINITY, f32::min);
+ let right = run
+ .iter()
+ .map(|&i| x[i] + adv[i])
+ .fold(f32::NEG_INFINITY, f32::max);
+ for &i in run {
+ x[i] = left + right - (x[i] + adv[i]);
+ }
+ order[start..k].reverse();
+ }
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/layout/bidi/test.rs b/crates/docx_engine/src/layout/bidi/test.rs
new file mode 100644
index 0000000000..6c28adf45f
--- /dev/null
+++ b/crates/docx_engine/src/layout/bidi/test.rs
@@ -0,0 +1,111 @@
+use super::*;
+
+fn levels_of(text: &str, base: u8) -> Vec<u8> {
+ let classes: Vec<Class> = text.chars().map(class).collect();
+ levels(&classes, &vec![false; classes.len()], base)
+}
+
+/// The text in visual order (left to right), one cluster per character
+/// of width 1.
+fn visual(text: &str, base: u8) -> String {
+ let chars: Vec<char> = text.chars().collect();
+ let lv = levels_of(text, base);
+ let mut x: Vec<f32> = (0..chars.len()).map(|i| i as f32).collect();
+ let adv = vec![1.0; chars.len()];
+ reorder(&mut x, &adv, &lv, base, (0.0, chars.len() as f32));
+ let mut order: Vec<usize> = (0..chars.len()).collect();
+ order.sort_by(|&a, &b| x[a].total_cmp(&x[b]));
+ order
+ .iter()
+ .map(|&i| {
+ let c = chars[i];
+ if lv[i] % 2 == 1 {
+ mirror(c).unwrap_or(c)
+ } else {
+ c
+ }
+ })
+ .collect()
+}
+
+#[test]
+fn classes_of_common_characters() {
+ assert_eq!(class('a'), Class::L);
+ assert_eq!(class('\u{05D0}'), Class::R);
+ assert_eq!(class('\u{0628}'), Class::Al);
+ assert_eq!(class('\u{0661}'), Class::An);
+ assert_eq!(class('7'), Class::En);
+ assert_eq!(class(','), Class::Cs);
+ assert_eq!(class('%'), Class::Et);
+ assert_eq!(class(' '), Class::Ws);
+ assert_eq!(class('\t'), Class::S);
+ assert_eq!(class('('), Class::On);
+ assert_eq!(class('\u{064E}'), Class::Nsm);
+}
+
+#[test]
+fn hebrew_reads_right_to_left_with_numbers_left_to_right() {
+ // Letters stand for Hebrew: A = alef, B = bet, ...
+ let he = |s: &str| {
+ s.chars()
+ .map(|c| match c {
+ 'A'..='Z' => char::from_u32(0x05D0 + (c as u32 - 'A' as u32)).unwrap(),
+ c => c,
+ })
+ .collect::<String>()
+ };
+ // Right-to-left paragraph: words in reverse order, 123 stays.
+ assert_eq!(visual(&he("AB 123 CD"), 1), he("DC 123 BA"));
+ // English inside a right-to-left paragraph keeps its order.
+ assert_eq!(visual(&he("AB word CD"), 1), he("DC word BA"));
+ // Hebrew inside an English paragraph.
+ assert_eq!(visual(&he("go AB now"), 0), he("go BA now"));
+ // Brackets mirror in right-to-left text.
+ assert_eq!(visual(&he("A (B) C"), 1), he("C (B) A"));
+}
+
+#[test]
+fn european_numbers_after_arabic_letters_are_arabic_numbers() {
+ let lv = levels_of("\u{0628} 12", 0);
+ // The digits are numbers at level 2 inside the right-to-left run.
+ assert_eq!(lv, vec![1, 1, 2, 2]);
+ // After a Latin letter they are left to right, with the space between.
+ let lv = levels_of("a 12", 1);
+ assert_eq!(lv, vec![2, 2, 2, 2]);
+}
+
+#[test]
+fn tabs_and_trailing_spaces_take_the_paragraph_level() {
+ let lv = levels_of("\u{05D0}\u{05D1} \tx ", 0);
+ assert_eq!(lv, vec![1, 1, 0, 0, 0, 0]);
+}
+
+#[test]
+fn right_to_left_lines_start_at_the_area_right() {
+ // Two clusters of width 2 in an area 10 wide, in a right-to-left
+ // paragraph: the first sits at the right edge.
+ let mut x = vec![0.0, 2.0];
+ reorder(&mut x, &[2.0, 2.0], &[1, 1], 1, (0.0, 10.0));
+ assert_eq!(x, vec![8.0, 6.0]);
+}
+
+#[test]
+fn neutrals_in_right_to_left_runs_read_right_to_left() {
+ // "a b" in a left-to-right paragraph: the space is between two
+ // left-to-right letters either way.
+ let classes: Vec<Class> = "a (\u{05D0}".chars().map(class).collect();
+ let plain = levels(&classes, &[false; 4], 0);
+ let rtl = levels(&classes, &[false, true, true, true], 0);
+ assert_eq!(plain, vec![0, 0, 0, 1]);
+ assert_eq!(rtl, vec![0, 1, 1, 1]);
+}
+
+#[test]
+fn separators_in_right_to_left_runs_split_numbers() {
+ let classes: Vec<Class> = "78/265".chars().map(class).collect();
+ // In a left-to-right run: one number.
+ assert_eq!(levels(&classes, &[false; 6], 1), vec![2; 6]);
+ // In a right-to-left run (as Word shows dates and references there):
+ // two numbers read right to left, the slash between them.
+ assert_eq!(levels(&classes, &[true; 6], 1), vec![2, 2, 1, 2, 2, 2]);
+}
diff --git a/crates/docx_engine/src/layout/drawing.rs b/crates/docx_engine/src/layout/drawing.rs
new file mode 100644
index 0000000000..c45ef0b115
--- /dev/null
+++ b/crates/docx_engine/src/layout/drawing.rs
@@ -0,0 +1,527 @@
+//! Drawings in runs: pictures, shapes, text boxes, charts (DrawingML in
+//! `w:drawing`, VML in `w:pict`/`w:object`), their size and placement.
+
+use crate::units::{emu, twips};
+use crate::xml::{NodeId, Ns, SnippetContext, XmlTree, parse_int, parse_on_off};
+use std::sync::Arc;
+
+/// What a horizontal or vertical position is relative to.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum RelFrom {
+ /// The page edge.
+ Page,
+ /// The margin (text area).
+ Margin,
+ /// The column.
+ Column,
+ /// The anchoring character / paragraph / line.
+ Text,
+ /// The left/top margin area.
+ LeftMargin,
+ /// The right/bottom margin area.
+ RightMargin,
+ /// Inside margin (mirrored pages).
+ InsideMargin,
+ /// Outside margin.
+ OutsideMargin,
+}
+
+/// Position along one axis.
+#[derive(Clone, Debug, PartialEq)]
+pub struct AxisPos {
+ /// Relative to.
+ pub from: RelFrom,
+ /// Alignment keyword (`left`, `center`, `right`, `top`, `bottom`, `inside`...).
+ pub align: Option<String>,
+ /// Offset in points.
+ pub offset: f32,
+ /// For vertical positions relative to text: relative to the line (else paragraph).
+ pub line: bool,
+}
+
+/// How text wraps around a floating object.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Wrap {
+ /// No wrapping: in front of or behind text.
+ None,
+ /// Text flows around the bounding box.
+ Square,
+ /// Text flows around the outline (treated as the box).
+ Tight,
+ /// Text above and below only.
+ TopAndBottom,
+}
+
+/// Placement of a floating (anchored) drawing.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Anchor {
+ /// Horizontal position.
+ pub h: AxisPos,
+ /// Vertical position.
+ pub v: AxisPos,
+ /// Text wrapping.
+ pub wrap: Wrap,
+ /// Which sides text may wrap on (`bothSides`, `left`, `right`, `largest`).
+ pub wrap_side: String,
+ /// Behind the text.
+ pub behind: bool,
+ /// Distance from text: top, bottom, left, right (points).
+ pub dist: [f32; 4],
+ /// Z-order.
+ pub z: i64,
+ /// Positioned within the table cell holding its anchor (rather than
+ /// the page's column) when it is in one.
+ pub in_cell: bool,
+}
+
+/// What a drawing shows.
+#[derive(Clone, Debug, PartialEq)]
+pub enum Graphic {
+ /// A picture (relationship id of the image).
+ Picture,
+ /// A shape (possibly with a text box).
+ Shape,
+ /// A group of shapes and pictures.
+ Group,
+ /// A chart (relationship id of the chart part).
+ Chart(String),
+ /// Something else (SmartArt, ink...): drawn from its fallback, if any.
+ Other,
+}
+
+/// A drawing found in a run.
+#[derive(Clone, Debug)]
+pub struct Drawing {
+ /// Width (points).
+ pub width: f32,
+ /// Height (points).
+ pub height: f32,
+ /// Extra space for effects: left, top, right, bottom (points).
+ pub effect: [f32; 4],
+ /// Placement when floating.
+ pub anchor: Option<Anchor>,
+ /// Content kind.
+ pub graphic: Graphic,
+ /// The parsed XML of the object.
+ pub tree: Arc<XmlTree>,
+ /// The element holding the graphic (`wp:inline`/`wp:anchor`, or the VML shape).
+ pub node: NodeId,
+ /// VML rather than DrawingML.
+ pub vml: bool,
+}
+
+/// Where text goes vertically in a text box.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TextAnchor {
+ /// At the top.
+ Top,
+ /// Centered.
+ Middle,
+ /// At the bottom.
+ Bottom,
+}
+
+/// The text of a shape: its content and where it goes in the shape.
+#[derive(Clone, Copy, Debug)]
+pub struct TextBox {
+ /// The `w:txbxContent` element (in the drawing's tree).
+ pub content: NodeId,
+ /// Distances of the text from the shape's edges: left, top, right,
+ /// bottom (points).
+ pub insets: [f32; 4],
+ /// Vertical placement of the text.
+ pub anchor: TextAnchor,
+}
+
+/// Default text box insets: 0.1in left and right, 0.05in top and bottom.
+const TEXT_INSETS: [f32; 4] = [7.2, 3.6, 7.2, 3.6];
+
+impl Drawing {
+ /// The text box of a shape (not of a shape in a group), if it holds
+ /// text.
+ pub fn text_box(&self) -> Option<TextBox> {
+ let t = &self.tree;
+ if self.graphic != Graphic::Shape {
+ return None;
+ }
+ if self.vml {
+ let tb = t.children(self.node).find(|&c| t.is(c, Ns::V, "textbox"))?;
+ let content = t.children(tb).find(|&c| t.is_w(c, "txbxContent"))?;
+ let mut insets = TEXT_INSETS;
+ if let Some(v) = t.attr(tb, Ns::NONE, "inset") {
+ for (i, part) in v.split(',').take(4).enumerate() {
+ if let Some(len) = css_length(part) {
+ insets[i] = len;
+ }
+ }
+ }
+ let style = t.attr(self.node, Ns::NONE, "style").unwrap_or("");
+ let anchor = match css_prop(style, "v-text-anchor") {
+ Some(a) if a.starts_with("middle") => TextAnchor::Middle,
+ Some(a) if a.starts_with("bottom") => TextAnchor::Bottom,
+ _ => TextAnchor::Top,
+ };
+ return Some(TextBox {
+ content,
+ insets,
+ anchor,
+ });
+ }
+ let wsp = t
+ .descendants(self.node)
+ .into_iter()
+ .find(|&d| t.is(d, Ns::WPS, "wsp"))?;
+ let content = t
+ .child(wsp, Ns::WPS, "txbx")
+ .and_then(|tb| t.children(tb).find(|&c| t.is_w(c, "txbxContent")))?;
+ let body = t.child(wsp, Ns::WPS, "bodyPr");
+ let inset = |name: &str, default: f32| {
+ body.and_then(|b| t.attr(b, Ns::NONE, name))
+ .and_then(parse_int)
+ .map_or(default, emu)
+ };
+ let insets = [
+ inset("lIns", TEXT_INSETS[0]),
+ inset("tIns", TEXT_INSETS[1]),
+ inset("rIns", TEXT_INSETS[2]),
+ inset("bIns", TEXT_INSETS[3]),
+ ];
+ let anchor = match body.and_then(|b| t.attr(b, Ns::NONE, "anchor")) {
+ Some("ctr") => TextAnchor::Middle,
+ Some("b") => TextAnchor::Bottom,
+ _ => TextAnchor::Top,
+ };
+ Some(TextBox {
+ content,
+ insets,
+ anchor,
+ })
+ }
+}
+
+fn rel_from(v: Option<&str>) -> RelFrom {
+ match v.unwrap_or("column") {
+ "page" => RelFrom::Page,
+ "margin" => RelFrom::Margin,
+ "column" => RelFrom::Column,
+ "leftMargin" | "topMargin" => RelFrom::LeftMargin,
+ "rightMargin" | "bottomMargin" => RelFrom::RightMargin,
+ "insideMargin" => RelFrom::InsideMargin,
+ "outsideMargin" => RelFrom::OutsideMargin,
+ _ => RelFrom::Text,
+ }
+}
+
+fn read_axis(t: &XmlTree, n: Option<NodeId>, vertical: bool) -> AxisPos {
+ let Some(n) = n else {
+ return AxisPos {
+ from: RelFrom::Text,
+ align: None,
+ offset: 0.0,
+ line: false,
+ };
+ };
+ let from_attr = t.attr(n, Ns::NONE, "relativeFrom");
+ let line = vertical && from_attr == Some("line");
+ let align = t
+ .child(n, Ns::WP, "align")
+ .map(|a| t.text(a).trim().to_owned());
+ let offset = t
+ .child(n, Ns::WP, "posOffset")
+ .and_then(|o| parse_int(&t.text(o)))
+ .map_or(0.0, emu);
+ AxisPos {
+ from: rel_from(from_attr),
+ align,
+ offset,
+ line,
+ }
+}
+
+/// The supported branch of an `mc:AlternateContent`, or its fallback.
+pub fn alternate_choice(t: &XmlTree, ac: NodeId) -> Option<NodeId> {
+ const UNDERSTOOD: &[&str] = &[
+ "wps", "wpg", "wp14", "w14", "w15", "a14", "wpc", "v", "o", "c14", "w10",
+ ];
+ for c in t.children(ac) {
+ if t.is(c, Ns::MC, "Choice") {
+ let requires = t.attr(c, Ns::NONE, "Requires").unwrap_or("");
+ if requires.split_whitespace().all(|r| UNDERSTOOD.contains(&r)) {
+ return Some(c);
+ }
+ } else if t.is(c, Ns::MC, "Fallback") {
+ return Some(c);
+ }
+ }
+ None
+}
+
+/// Parses a length in a VML `style` (`width:72pt;height:1in`) to points.
+pub fn css_length(v: &str) -> Option<f32> {
+ let v = v.trim();
+ let (num, unit) = v
+ .find(|c: char| c.is_ascii_alphabetic() || c == '%')
+ .map_or((v, ""), |i| (&v[..i], &v[i..]));
+ let n: f32 = num.trim().parse().ok()?;
+ Some(match unit {
+ "pt" | "" => n,
+ "in" => n * 72.0,
+ "cm" => n * 72.0 / 2.54,
+ "mm" => n * 72.0 / 25.4,
+ "px" => n * 0.75,
+ "pc" => n * 12.0,
+ "emu" => n / 12_700.0,
+ _ => return None,
+ })
+}
+
+/// Reads one property from a VML `style` attribute.
+pub fn css_prop<'a>(style: &'a str, name: &str) -> Option<&'a str> {
+ style.split(';').find_map(|decl| {
+ let (k, v) = decl.split_once(':')?;
+ (k.trim().eq_ignore_ascii_case(name)).then_some(v.trim())
+ })
+}
+
+/// Parses a run object (`w:drawing`, `w:pict`, `w:object`,
+/// `mc:AlternateContent`) into a drawing, if it is one.
+pub fn parse_drawing(xml: &str, snippets: &SnippetContext) -> Option<Drawing> {
+ let tree = Arc::new(snippets.parse(xml).ok()?);
+ let root = tree.root();
+ find_drawing(&tree, root)
+}
+
+fn find_drawing(t: &Arc<XmlTree>, n: NodeId) -> Option<Drawing> {
+ if t.is(n, Ns::MC, "AlternateContent") {
+ let branch = alternate_choice(t, n)?;
+ return t.children(branch).find_map(|c| find_drawing(t, c));
+ }
+ if t.is_w(n, "drawing") {
+ let holder = t
+ .children(n)
+ .find(|&c| t.is(c, Ns::WP, "inline") || t.is(c, Ns::WP, "anchor"))?;
+ return drawingml(t, holder);
+ }
+ if t.is_w(n, "pict") || t.is_w(n, "object") {
+ // The first VML shape with a size.
+ let shape = t.descendants(n).into_iter().find(|&d| {
+ t.ns(d) == Ns::V
+ && matches!(
+ t.local(d),
+ "shape" | "rect" | "roundrect" | "oval" | "line" | "group" | "image"
+ )
+ })?;
+ return vml(t, n, shape);
+ }
+ None
+}
+
+fn drawingml(t: &Arc<XmlTree>, holder: NodeId) -> Option<Drawing> {
+ let inline = t.is(holder, Ns::WP, "inline");
+ let extent = t.child(holder, Ns::WP, "extent")?;
+ let cx = t
+ .attr(extent, Ns::NONE, "cx")
+ .and_then(parse_int)
+ .unwrap_or(0);
+ let cy = t
+ .attr(extent, Ns::NONE, "cy")
+ .and_then(parse_int)
+ .unwrap_or(0);
+ let effect = t
+ .child(holder, Ns::WP, "effectExtent")
+ .map_or([0.0; 4], |e| {
+ let v = |n: &str| t.attr(e, Ns::NONE, n).and_then(parse_int).map_or(0.0, emu);
+ [v("l"), v("t"), v("r"), v("b")]
+ });
+ let graphic_data = t
+ .child(holder, Ns::A, "graphic")
+ .and_then(|g| t.child(g, Ns::A, "graphicData"));
+ let uri = graphic_data
+ .and_then(|g| t.attr(g, Ns::NONE, "uri"))
+ .unwrap_or("");
+ let graphic = if uri.ends_with("/picture") {
+ Graphic::Picture
+ } else if uri.ends_with("wordprocessingShape") {
+ Graphic::Shape
+ } else if uri.ends_with("wordprocessingGroup") || uri.ends_with("wordprocessingCanvas") {
+ Graphic::Group
+ } else if uri.ends_with("/chart") {
+ graphic_data
+ .and_then(|g| t.child(g, Ns::C, "chart"))
+ .and_then(|c| t.attr(c, Ns::R, "id"))
+ .map_or(Graphic::Other, |id| Graphic::Chart(id.to_owned()))
+ } else {
+ Graphic::Other
+ };
+ let anchor = (!inline).then(|| {
+ let dist = |n: &str| {
+ t.attr(holder, Ns::NONE, n)
+ .and_then(parse_int)
+ .map_or(0.0, emu)
+ };
+ let wrap_el = t
+ .children(holder)
+ .find(|&c| t.ns(c) == Ns::WP && t.local(c).starts_with("wrap"));
+ let wrap = match wrap_el.map(|w| t.local(w)) {
+ Some("wrapSquare") => Wrap::Square,
+ Some("wrapTight") | Some("wrapThrough") => Wrap::Tight,
+ Some("wrapTopAndBottom") => Wrap::TopAndBottom,
+ _ => Wrap::None,
+ };
+ let simple = t
+ .attr(holder, Ns::NONE, "simplePos")
+ .is_some_and(|v| parse_on_off(Some(v)));
+ let (h, v) = if simple {
+ let sp = t.child(holder, Ns::WP, "simplePos");
+ let x = sp
+ .and_then(|s| t.attr(s, Ns::NONE, "x"))
+ .and_then(parse_int)
+ .map_or(0.0, emu);
+ let y = sp
+ .and_then(|s| t.attr(s, Ns::NONE, "y"))
+ .and_then(parse_int)
+ .map_or(0.0, emu);
+ (
+ AxisPos {
+ from: RelFrom::Page,
+ align: None,
+ offset: x,
+ line: false,
+ },
+ AxisPos {
+ from: RelFrom::Page,
+ align: None,
+ offset: y,
+ line: false,
+ },
+ )
+ } else {
+ (
+ read_axis(t, t.child(holder, Ns::WP, "positionH"), false),
+ read_axis(t, t.child(holder, Ns::WP, "positionV"), true),
+ )
+ };
+ Anchor {
+ h,
+ v,
+ wrap,
+ wrap_side: wrap_el
+ .and_then(|w| t.attr(w, Ns::NONE, "wrapText"))
+ .unwrap_or("bothSides")
+ .to_owned(),
+ behind: t
+ .attr(holder, Ns::NONE, "behindDoc")
+ .is_some_and(|v| parse_on_off(Some(v))),
+ dist: [dist("distT"), dist("distB"), dist("distL"), dist("distR")],
+ z: t.attr(holder, Ns::NONE, "relativeHeight")
+ .and_then(parse_int)
+ .unwrap_or(0),
+ in_cell: t
+ .attr(holder, Ns::NONE, "layoutInCell")
+ .is_none_or(|v| parse_on_off(Some(v))),
+ }
+ });
+ Some(Drawing {
+ width: emu(cx),
+ height: emu(cy),
+ effect,
+ anchor,
+ graphic,
+ tree: Arc::clone(t),
+ node: holder,
+ vml: false,
+ })
+}
+
+fn vml(t: &Arc<XmlTree>, object: NodeId, shape: NodeId) -> Option<Drawing> {
+ let style = t.attr(shape, Ns::NONE, "style").unwrap_or("");
+ let mut width = css_prop(style, "width").and_then(css_length);
+ let mut height = css_prop(style, "height").and_then(css_length);
+ if t.is_w(object, "object") {
+ // OLE objects record their natural size in twips.
+ if let Some(w) = t.w_attr(object, "dxaOrig").and_then(parse_int) {
+ width = width.or(Some(twips(w)));
+ }
+ if let Some(h) = t.w_attr(object, "dyaOrig").and_then(parse_int) {
+ height = height.or(Some(twips(h)));
+ }
+ }
+ let (width, height) = (width?, height?);
+ let absolute = css_prop(style, "position").is_some_and(|p| p.eq_ignore_ascii_case("absolute"));
+ let anchor = absolute.then(|| {
+ let left = css_prop(style, "margin-left")
+ .or_else(|| css_prop(style, "left"))
+ .and_then(css_length)
+ .unwrap_or(0.0);
+ let top = css_prop(style, "margin-top")
+ .or_else(|| css_prop(style, "top"))
+ .and_then(css_length)
+ .unwrap_or(0.0);
+ let h_from = match css_prop(style, "mso-position-horizontal-relative") {
+ Some("page") => RelFrom::Page,
+ Some("margin") => RelFrom::Margin,
+ Some("char") | Some("text") => RelFrom::Text,
+ _ => RelFrom::Column,
+ };
+ let v_from = match css_prop(style, "mso-position-vertical-relative") {
+ Some("page") => RelFrom::Page,
+ Some("margin") => RelFrom::Margin,
+ Some("line") => RelFrom::Text,
+ _ => RelFrom::Text,
+ };
+ let wrap = t
+ .descendants(shape)
+ .into_iter()
+ .find(|&d| t.is(d, Ns::W10, "wrap"))
+ .and_then(|w| t.attr(w, Ns::NONE, "type"))
+ .map_or(Wrap::None, |ty| match ty {
+ "square" => Wrap::Square,
+ "tight" | "through" => Wrap::Tight,
+ "topAndBottom" => Wrap::TopAndBottom,
+ _ => Wrap::None,
+ });
+ let z = css_prop(style, "z-index")
+ .and_then(|z| z.trim().parse::<i64>().ok())
+ .unwrap_or(0);
+ Anchor {
+ h: AxisPos {
+ from: h_from,
+ align: css_prop(style, "mso-position-horizontal").map(str::to_owned),
+ offset: left,
+ line: false,
+ },
+ v: AxisPos {
+ from: v_from,
+ align: css_prop(style, "mso-position-vertical").map(str::to_owned),
+ offset: top,
+ line: false,
+ },
+ wrap,
+ wrap_side: "bothSides".into(),
+ behind: z < 0,
+ dist: [0.0; 4],
+ z,
+ in_cell: t
+ .attr(shape, Ns::O, "allowincell")
+ .is_none_or(|v| parse_on_off(Some(v))),
+ }
+ });
+ let has_image = t
+ .descendants(shape)
+ .into_iter()
+ .any(|d| t.is(d, Ns::V, "imagedata"));
+ Some(Drawing {
+ width,
+ height,
+ effect: [0.0; 4],
+ anchor,
+ graphic: if has_image {
+ Graphic::Picture
+ } else {
+ Graphic::Shape
+ },
+ tree: Arc::clone(t),
+ node: shape,
+ vml: true,
+ })
+}
diff --git a/crates/docx_engine/src/layout/flow.rs b/crates/docx_engine/src/layout/flow.rs
new file mode 100644
index 0000000000..ba8ac9f5e4
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow.rs
@@ -0,0 +1,246 @@
+//! Flowing the body into pages and columns.
+
+mod anchors;
+mod body;
+mod frames;
+mod numbers;
+mod split;
+mod stack;
+mod textbox;
+
+use super::fonts::Fonts;
+use super::format::{Formats, TableCtx};
+use super::{Item, Layout};
+use crate::document::{Document, rel_kind};
+use crate::model::block::{Block, BlockId, BlockKind, Story};
+use crate::model::numbering::{Counters, Label};
+use crate::model::props::RunProps;
+use crate::model::section::{HeaderRefs, Section};
+use numbers::{Labels, NoteNumbers};
+use pptx_engine::font::FontDb;
+use std::sync::Arc;
+
+pub(super) use numbers::NumbersCache;
+pub(super) use stack::TableCache;
+
+/// Layout choices.
+#[derive(Clone, Debug)]
+pub struct LayoutOptions {
+ /// Show tracked changes inline (else the document as if accepted).
+ pub markup: bool,
+ /// Keep a paragraph's space before when it lands at the top of a page
+ /// after a natural page break (Word drops it: off by default).
+ pub space_before_at_page_top: bool,
+}
+
+impl Default for LayoutOptions {
+ fn default() -> Self {
+ Self {
+ markup: true,
+ space_before_at_page_top: false,
+ }
+ }
+}
+
+/// Everything layout reads.
+pub(super) struct Env<'a> {
+ pub doc: &'a Document,
+ pub formats: Formats<'a>,
+ pub fonts: Fonts<'a>,
+ pub options: &'a LayoutOptions,
+ /// Displayed note numbers by (endnote, id).
+ pub note_numbers: Arc<NoteNumbers>,
+ /// List labels of numbered paragraphs.
+ pub labels: Arc<Labels>,
+ /// Measurements kept between layouts.
+ pub cache: Option<&'a super::LayoutCache>,
+}
+
+impl<'a> Env<'a> {
+ fn new(
+ doc: &'a Document,
+ fonts: &'a FontDb,
+ options: &'a LayoutOptions,
+ cache: Option<&'a super::LayoutCache>,
+ ) -> Self {
+ let parts = doc.parts();
+ let mut formats = Formats::new(
+ &parts.styles,
+ &parts.numbering,
+ &parts.settings,
+ &parts.theme,
+ doc.decls(),
+ );
+ if let Some(c) = cache {
+ formats = formats.with_cache(c.formats(doc.generation));
+ }
+ Env {
+ doc,
+ formats,
+ fonts: Fonts::new(fonts),
+ options,
+ note_numbers: Arc::default(),
+ labels: Arc::default(),
+ cache,
+ }
+ }
+
+ /// Numbers notes in order of reference and computes list labels.
+ fn prepare(&mut self) {
+ let cache = self.cache.map(|c| &c.numbers);
+ (self.labels, self.note_numbers) = numbers::count(self.doc, &self.formats, cache);
+ }
+
+ /// The list label of a paragraph outside the body (headers, footers,
+ /// notes), counted on its own.
+ fn story_label(&self, block: &Block, table: &TableCtx) -> Option<(Label, RunProps)> {
+ let fmt = self.formats.paragraph(&block.props, table);
+ let (num_id, ilvl) = fmt.props.num?;
+ if fmt.mark.vanish {
+ return None;
+ }
+ let label =
+ Counters::default().next(self.formats.numbering, self.formats.styles, num_id, ilvl)?;
+ let props = self.formats.label_props(&fmt, &label);
+ Some((label, props))
+ }
+
+ /// The part a section's header/footer reference points to.
+ fn hf_part(&self, rid: &str) -> Option<String> {
+ let rels = self.doc.main_rels();
+ rels.get(rid)
+ .filter(|r| matches!(rel_kind(&r.rel_type), "header" | "footer"))
+ .map(|r| rels.resolve(r))
+ }
+}
+
+fn note_id(xml: &str) -> Option<i64> {
+ let i = xml
+ .find(":id=\"")
+ .map(|i| i + 5)
+ .or_else(|| xml.find(" id=\"").map(|i| i + 5))?;
+ let rest = &xml[i..];
+ let end = rest.find('"')?;
+ crate::xml::parse_int(&rest[..end])
+}
+
+/// Body blocks in flow order, with content controls opened up.
+pub(super) fn flow_blocks<'s>(
+ story: &'s Story,
+ parent: Option<&BlockId>,
+ out: &mut Vec<&'s Block>,
+) {
+ for id in story.children(parent) {
+ let Some(b) = story.get(id) else {
+ continue;
+ };
+ match b.kind {
+ BlockKind::Paragraph | BlockKind::Table => out.push(b),
+ BlockKind::Container => flow_blocks(story, Some(id), out),
+ BlockKind::Row | BlockKind::Cell | BlockKind::Opaque => {}
+ }
+ }
+}
+
+/// Header and footer references with inheritance from earlier sections.
+fn effective_refs(sections: &[Section]) -> Vec<(HeaderRefs, HeaderRefs)> {
+ let mut out: Vec<(HeaderRefs, HeaderRefs)> = Vec::with_capacity(sections.len());
+ let mut last = (HeaderRefs::default(), HeaderRefs::default());
+ for s in sections {
+ let merge = |own: &HeaderRefs, prev: &HeaderRefs| HeaderRefs {
+ default: own.default.clone().or_else(|| prev.default.clone()),
+ first: own.first.clone().or_else(|| prev.first.clone()),
+ even: own.even.clone().or_else(|| prev.even.clone()),
+ };
+ last = (merge(&s.headers, &last.0), merge(&s.footers, &last.1));
+ out.push(last.clone());
+ }
+ out
+}
+
+/// Lays out a document.
+pub(super) fn layout(
+ doc: &Document,
+ fonts: &FontDb,
+ options: &LayoutOptions,
+ cache: Option<&super::LayoutCache>,
+) -> Layout {
+ let mut env = Env::new(doc, fonts, options, cache);
+ env.prepare();
+ let mut blocks: Vec<&Block> = Vec::new();
+ flow_blocks(&doc.body, None, &mut blocks);
+ // Sections: each paragraph carrying a sectPr closes one.
+ let mut sections: Vec<Section> = Vec::new();
+ let mut section_of: Vec<usize> = Vec::with_capacity(blocks.len());
+ for b in &blocks {
+ section_of.push(sections.len());
+ if b.kind == BlockKind::Paragraph
+ && let Some(s) = env
+ .formats
+ .paragraph(&b.props, &TableCtx::default())
+ .section
+ .clone()
+ {
+ sections.push(s);
+ }
+ }
+ sections.push(doc.final_section());
+ let refs = effective_refs(&sections);
+ // Page-count fields need the page count: lay out again when the first
+ // pass's guess (the last layout's count) was wrong.
+ let mut total = cache.and_then(|c| c.last_pages()).unwrap_or(1) as i64;
+ let mut pages = Vec::new();
+ for _ in 0..3 {
+ let mut flow = body::Flow::new(&env, sections.clone(), refs.clone(), total);
+ flow.run(&blocks, &section_of);
+ pages = flow.finish();
+ let count = pages.len() as i64;
+ if count == total {
+ break;
+ }
+ total = count;
+ }
+ if let Some(c) = cache {
+ c.set_last_pages(pages.len());
+ }
+ Layout { pages }
+}
+
+/// Offsets every item by (dx, dy).
+pub(super) fn offset_items(items: &mut [Item], dx: f32, dy: f32) {
+ for item in items {
+ match item {
+ Item::Line(l) => {
+ l.x += dx;
+ l.y += dy;
+ if let Some(c) = &mut l.clip {
+ c.x += dx;
+ c.y += dy;
+ }
+ }
+ Item::Fill { rect, .. } => {
+ rect.x += dx;
+ rect.y += dy;
+ }
+ Item::Rule { x0, y0, x1, y1, .. } => {
+ *x0 += dx;
+ *x1 += dx;
+ *y0 += dy;
+ *y1 += dy;
+ }
+ Item::Drawing(d) => {
+ d.rect.x += dx;
+ d.rect.y += dy;
+ }
+ Item::LineNumber {
+ right, baseline, ..
+ } => {
+ *right += dx;
+ *baseline += dy;
+ }
+ }
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/layout/flow/anchors.rs b/crates/docx_engine/src/layout/flow/anchors.rs
new file mode 100644
index 0000000000..346a891b5e
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/anchors.rs
@@ -0,0 +1,69 @@
+//! Positions floating drawings on their page.
+
+use super::super::drawing::RelFrom;
+use super::stack::PendingAnchor;
+use pptx_engine::path::Rect;
+
+/// The page geometry floating drawings are positioned against.
+#[derive(Clone, Copy, Debug)]
+pub struct PageGeom {
+ /// Page width.
+ pub width: f32,
+ /// Page height.
+ pub height: f32,
+ /// Left margin.
+ pub left: f32,
+ /// Right margin.
+ pub right: f32,
+ /// Top margin.
+ pub top: f32,
+ /// Bottom margin.
+ pub bottom: f32,
+ /// Column left edge.
+ pub col_left: f32,
+ /// Column width.
+ pub col_width: f32,
+}
+
+/// The rectangle a floating drawing occupies on the page.
+pub fn resolve(a: &PendingAnchor, g: &PageGeom) -> Option<Rect> {
+ let d = &a.drawing;
+ let anchor = d.anchor.as_ref()?;
+ let (w, h) = (d.width, d.height);
+ let (x0, span) = match anchor.h.from {
+ RelFrom::Page => (0.0, g.width),
+ RelFrom::Margin => (g.left, g.width - g.left - g.right),
+ RelFrom::Column => a.cell.unwrap_or((g.col_left, g.col_width)),
+ RelFrom::Text => (a.char_x, 0.0),
+ RelFrom::LeftMargin | RelFrom::InsideMargin => (0.0, g.left),
+ RelFrom::RightMargin | RelFrom::OutsideMargin => (g.width - g.right, g.right),
+ };
+ let x = match anchor.h.align.as_deref() {
+ Some("center") => x0 + (span - w) / 2.0,
+ Some("right" | "outside") => x0 + span - w,
+ Some("left" | "inside") => x0,
+ _ => x0 + anchor.h.offset,
+ };
+ let (y0, vspan) = match anchor.v.from {
+ RelFrom::Page => (0.0, g.height),
+ RelFrom::Margin => (g.top, g.height - g.top - g.bottom),
+ RelFrom::Column => (g.top, g.height - g.top - g.bottom),
+ RelFrom::Text => (
+ if anchor.v.line {
+ a.line_top
+ } else {
+ a.para_top
+ },
+ 0.0,
+ ),
+ RelFrom::LeftMargin | RelFrom::InsideMargin => (0.0, g.top),
+ RelFrom::RightMargin | RelFrom::OutsideMargin => (g.height - g.bottom, g.bottom),
+ };
+ let y = match anchor.v.align.as_deref() {
+ Some("center") => y0 + (vspan - h) / 2.0,
+ Some("bottom" | "outside") => y0 + vspan - h,
+ Some("top" | "inside") => y0,
+ _ => y0 + anchor.v.offset,
+ };
+ Some(Rect::from_xywh(x, y, w, h))
+}
diff --git a/crates/docx_engine/src/layout/flow/body.rs b/crates/docx_engine/src/layout/flow/body.rs
new file mode 100644
index 0000000000..f666b1f7d5
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/body.rs
@@ -0,0 +1,578 @@
+//! The body paginator: sections, columns, pages, keep rules, notes.
+
+mod floats;
+mod notes;
+mod paragraphs;
+mod tables;
+
+use super::super::inline::{FieldValues, Kind};
+use super::super::{Chrome, Item, Page, ParaBox, StoryRef};
+use super::anchors::PageGeom;
+use super::stack::{ParaCtx, PrevPara, Stack, StackCtx, para_box, stack_story};
+use super::{Env, offset_items};
+use crate::model::block::{Block, BlockId, BlockKind};
+use crate::model::section::{HeaderRefs, PageVAlign, Section, SectionStart};
+use floats::{Band, OnPage, place_anchors, place_frames};
+use pptx_engine::path::Rect;
+use std::sync::Arc;
+
+const EPS: f32 = 0.01;
+
+/// Columns this close in width take the same line breaks.
+const COLUMN_SLACK: f32 = 0.5;
+
+/// Default distance of line numbers from the text.
+const LINE_NUMBER_DISTANCE: f32 = 18.0;
+
+/// The compatibility mode of Word 2013 and later.
+const MODERN_COMPAT: u32 = 15;
+
+struct Cur {
+ page: Page,
+ sect: usize,
+ col: usize,
+ top: f32,
+ bottom: f32,
+ y: f32,
+ body: Vec<Item>,
+ behind: Vec<Item>,
+ front: Vec<Item>,
+ chrome: Vec<Item>,
+ notes: Vec<i64>,
+ notes_height: f32,
+ placed_any: bool,
+ hard: bool,
+ line_on_page: u32,
+ /// Stretches of the page that body text skips (floats that allow no
+ /// text beside them).
+ bands: Vec<Band>,
+ /// Where the columns of the current section start on this page (below
+ /// what earlier sections left on it).
+ sect_top: f32,
+ /// The lowest point the current section's columns reached on this page.
+ sect_bottom: f32,
+}
+
+pub(in crate::layout) struct Flow<'e, 'a> {
+ env: &'e Env<'a>,
+ sections: Vec<Section>,
+ refs: Vec<(HeaderRefs, HeaderRefs)>,
+ pages: Vec<Page>,
+ cur: Option<Cur>,
+ page_number: i64,
+ section_started: Vec<bool>,
+ prev: Option<PrevPara>,
+ line_no: u32,
+ boxes: crate::hash::FxMap<BlockId, Arc<ParaBox>>,
+ note_stacks: crate::hash::FxMap<i64, Stack>,
+ separator: Option<Stack>,
+ /// Height of the footnote continuation notice, once measured.
+ notice: Option<f32>,
+ total_pages: i64,
+}
+
+impl<'e, 'a> Flow<'e, 'a> {
+ pub fn new(
+ env: &'e Env<'a>,
+ sections: Vec<Section>,
+ refs: Vec<(HeaderRefs, HeaderRefs)>,
+ total_pages: i64,
+ ) -> Self {
+ let n = sections.len();
+ Self {
+ env,
+ sections,
+ refs,
+ pages: Vec::new(),
+ cur: None,
+ page_number: 0,
+ section_started: vec![false; n],
+ prev: None,
+ line_no: 0,
+ boxes: crate::hash::FxMap::default(),
+ note_stacks: crate::hash::FxMap::default(),
+ separator: None,
+ notice: None,
+ total_pages,
+ }
+ }
+
+ /// Whether paragraph spacing adds up (Word 2003) instead of collapsing.
+ fn sum_spacing(&self) -> bool {
+ !self.env.doc.parts().settings.html_auto_spacing
+ }
+
+ fn section(&self) -> &Section {
+ let s = self.cur.as_ref().map_or(0, |c| c.sect);
+ &self.sections[s.min(self.sections.len() - 1)]
+ }
+
+ fn col_geom(&self) -> (f32, f32) {
+ let s = self.section();
+ let col = self
+ .cur
+ .as_ref()
+ .map_or(0, |c| c.col)
+ .min(s.columns.len().saturating_sub(1));
+ let mut x = s.left + s.gutter;
+ for c in &s.columns[..col] {
+ x += c.width + c.space;
+ }
+ (x, s.columns.get(col).map_or(s.text_width(), |c| c.width))
+ }
+
+ fn page_geom(&self) -> PageGeom {
+ let s = self.section();
+ let (col_left, col_width) = self.col_geom();
+ PageGeom {
+ width: s.page_w,
+ height: s.page_h,
+ left: s.left,
+ right: s.right,
+ top: s.top,
+ bottom: s.bottom,
+ col_left,
+ col_width,
+ }
+ }
+
+ fn fields(&self) -> FieldValues {
+ FieldValues {
+ page: self.page_number.max(1),
+ pages: self.total_pages.max(1),
+ section_pages: self.total_pages.max(1),
+ page_fmt: self.section().page_fmt.clone(),
+ }
+ }
+
+ /// Lays out a header or footer story for the current page.
+ fn hf_stack(
+ &self,
+ rid: Option<&String>,
+ sect: &Section,
+ fields: &FieldValues,
+ ) -> Option<Stack> {
+ let part = self.env.hf_part(rid?)?;
+ let ps = self.env.doc.part_story(&part)?;
+ Some(stack_story(
+ self.env,
+ &ps.story,
+ None,
+ &StackCtx {
+ story: StoryRef::Part(part),
+ width: sect.text_width(),
+ table: Default::default(),
+ fields: fields.clone(),
+ note_number: None,
+ float_frames: true,
+ page: Some(PageGeom {
+ width: sect.page_w,
+ height: sect.page_h,
+ left: sect.left,
+ right: sect.right,
+ top: sect.top,
+ bottom: sect.bottom,
+ col_left: sect.left + sect.gutter,
+ col_width: sect.text_width(),
+ }),
+ },
+ ))
+ }
+
+ fn start_page(&mut self, sect: usize, hard: bool) {
+ self.finish_page();
+ let s = self.sections[sect].clone();
+ let first_of_section = !self.section_started[sect];
+ self.section_started[sect] = true;
+ self.page_number = match (first_of_section, s.page_start) {
+ (true, Some(start)) => start,
+ _ => self.page_number + 1,
+ };
+ // Odd and even section starts insert a blank page when needed.
+ if first_of_section
+ && ((s.start == SectionStart::OddPage && self.page_number % 2 == 0)
+ || (s.start == SectionStart::EvenPage && self.page_number % 2 != 0))
+ && !self.pages.is_empty()
+ {
+ self.pages.push(Page {
+ width: s.page_w,
+ height: s.page_h,
+ section: sect,
+ number: self.page_number,
+ behind: Vec::new(),
+ items: Vec::new(),
+ front: Vec::new(),
+ body: Rect::from_xywh(s.left, s.top, s.text_width(), s.page_h - s.top - s.bottom),
+ header: None,
+ footer: None,
+ });
+ self.page_number += 1;
+ }
+ let settings = &self.env.doc.parts().settings;
+ let (headers, footers) = self.refs[sect.min(self.refs.len() - 1)].clone();
+ let pick = |r: &HeaderRefs| -> Option<String> {
+ if first_of_section && s.title_page {
+ return r.first.clone();
+ }
+ if settings.even_and_odd_headers && self.page_number % 2 == 0 {
+ return r.even.clone();
+ }
+ r.default.clone()
+ };
+ let fields = FieldValues {
+ page: self.page_number,
+ pages: self.total_pages.max(1),
+ section_pages: self.total_pages.max(1),
+ page_fmt: s.page_fmt.clone(),
+ };
+ let header_rid = pick(&headers);
+ let footer_rid = pick(&footers);
+ let header_part = header_rid.as_ref().and_then(|r| self.env.hf_part(r));
+ let footer_part = footer_rid.as_ref().and_then(|r| self.env.hf_part(r));
+ let header = self.hf_stack(header_rid.as_ref(), &s, &fields);
+ let footer = self.hf_stack(footer_rid.as_ref(), &s, &fields);
+ let mut chrome = Vec::new();
+ let mut behind = Vec::new();
+ let mut front = Vec::new();
+ let mut top = s.top;
+ let mut bottom = s.page_h - s.bottom;
+ let geom = PageGeom {
+ width: s.page_w,
+ height: s.page_h,
+ left: s.left,
+ right: s.right,
+ top: s.top,
+ bottom: s.bottom,
+ col_left: s.left,
+ col_width: s.text_width(),
+ };
+ let on_page = OnPage {
+ env: self.env,
+ fields: &fields,
+ geom: &geom,
+ };
+ if let Some(mut h) = header {
+ offset_items(&mut h.items, s.left + s.gutter, s.header);
+ for a in &mut h.anchors {
+ a.shift(s.left, s.header);
+ }
+ if !s.top_exact {
+ top = top.max(s.header + h.height);
+ }
+ chrome.extend(h.items);
+ place_anchors(&on_page, &h.anchors, &mut behind, &mut front);
+ place_frames(
+ &on_page,
+ &mut h.frames,
+ (s.left + s.gutter, s.header),
+ &mut chrome,
+ &mut behind,
+ &mut front,
+ );
+ }
+ if let Some(mut f) = footer {
+ let y = s.page_h - s.footer - f.height;
+ offset_items(&mut f.items, s.left + s.gutter, y);
+ for a in &mut f.anchors {
+ a.shift(s.left, y);
+ }
+ if !s.bottom_exact {
+ bottom = bottom.min(y);
+ }
+ chrome.extend(f.items);
+ place_anchors(&on_page, &f.anchors, &mut behind, &mut front);
+ place_frames(
+ &on_page,
+ &mut f.frames,
+ (s.left + s.gutter, y),
+ &mut chrome,
+ &mut behind,
+ &mut front,
+ );
+ }
+ let page = Page {
+ width: s.page_w,
+ height: s.page_h,
+ section: sect,
+ number: self.page_number,
+ behind: Vec::new(),
+ items: Vec::new(),
+ front: Vec::new(),
+ body: Rect::from_xywh(s.left, top, s.text_width(), bottom - top),
+ header: Some(Chrome {
+ part: header_part,
+ top: 0.0,
+ bottom: top,
+ }),
+ footer: Some(Chrome {
+ part: footer_part,
+ top: bottom,
+ bottom: s.page_h,
+ }),
+ };
+ self.cur = Some(Cur {
+ page,
+ sect,
+ col: 0,
+ top,
+ bottom,
+ y: top,
+ body: Vec::new(),
+ behind,
+ front,
+ chrome,
+ notes: Vec::new(),
+ notes_height: 0.0,
+ placed_any: false,
+ hard,
+ line_on_page: 0,
+ bands: Vec::new(),
+ sect_top: top,
+ sect_bottom: top,
+ });
+ }
+
+ fn finish_page(&mut self) {
+ let Some(mut cur) = self.cur.take() else {
+ return;
+ };
+ let s = self.sections[cur.sect.min(self.sections.len() - 1)].clone();
+ // Vertical alignment of the body.
+ if cur.col == 0 && s.v_align != PageVAlign::Top && !cur.body.is_empty() {
+ let used = cur.y - cur.top;
+ let free = (cur.bottom - cur.notes_height - cur.top - used).max(0.0);
+ let dy = match s.v_align {
+ PageVAlign::Center => free / 2.0,
+ PageVAlign::Bottom => free,
+ _ => 0.0,
+ };
+ if dy > 0.0 {
+ offset_items(&mut cur.body, 0.0, dy);
+ }
+ }
+ // Notes at the bottom of the page.
+ if !cur.notes.is_empty() {
+ let mut y = cur.bottom - cur.notes_height;
+ let x = s.left + s.gutter;
+ if let Some(sep) = self.separator_stack() {
+ let mut items = sep.items.clone();
+ offset_items(&mut items, x, y);
+ cur.body.extend(items);
+ y += sep.height;
+ }
+ for id in &cur.notes {
+ if let Some(st) = self.note_stacks.get(id) {
+ let mut items = st.items.clone();
+ offset_items(&mut items, x, y);
+ cur.body.extend(items);
+ y += st.height;
+ }
+ }
+ }
+ cur.page.behind = cur.behind;
+ let mut items = cur.chrome;
+ items.extend(cur.body);
+ cur.page.items = items;
+ cur.page.front = cur.front;
+ if let Some(b) = s.borders {
+ let (w, h) = (s.page_w, s.page_h);
+ let (l, t, r, bt) = if b.from_page_edge {
+ (
+ b.left.map_or(24.0, |x| x.space),
+ b.top.map_or(24.0, |x| x.space),
+ w - b.right.map_or(24.0, |x| x.space),
+ h - b.bottom.map_or(24.0, |x| x.space),
+ )
+ } else {
+ (
+ s.left - b.left.map_or(4.0, |x| x.space),
+ s.top - b.top.map_or(1.0, |x| x.space),
+ w - s.right + b.right.map_or(4.0, |x| x.space),
+ h - s.bottom + b.bottom.map_or(1.0, |x| x.space),
+ )
+ };
+ for (border, x0, y0, x1, y1) in [
+ (b.top, l, t, r, t),
+ (b.bottom, l, bt, r, bt),
+ (b.left, l, t, l, bt),
+ (b.right, r, t, r, bt),
+ ] {
+ if let Some(border) = border {
+ cur.page.behind.push(Item::Rule {
+ x0,
+ y0,
+ x1,
+ y1,
+ border,
+ });
+ }
+ }
+ }
+ self.pages.push(cur.page);
+ }
+
+ /// Moves to the next column, or the next page after the last column.
+ fn next_column(&mut self, hard: bool) {
+ let (sect, col, cols) = match &self.cur {
+ Some(c) => (c.sect, c.col, self.sections[c.sect].columns.len()),
+ None => return,
+ };
+ if col + 1 < cols {
+ if let Some(c) = &mut self.cur {
+ // The next column starts where the section started on the page.
+ c.sect_bottom = c.sect_bottom.max(c.y);
+ c.col += 1;
+ c.y = c.sect_top;
+ c.placed_any = false;
+ c.hard = hard;
+ }
+ } else {
+ self.start_page(sect, hard);
+ }
+ self.prev = None;
+ }
+
+ fn para(&mut self, b: &Block, width: f32) -> Arc<ParaBox> {
+ if let Some(pb) = self.boxes.get(&b.id) {
+ let fits = (pb
+ .lines
+ .lines
+ .first()
+ .map_or(width, |l| l.right + pb.format.props.ind_right)
+ - width)
+ .abs()
+ < 0.5;
+ if fits && !pb.inline.dynamic {
+ return Arc::clone(pb);
+ }
+ }
+ let pb = para_box(
+ self.env,
+ b,
+ &ParaCtx {
+ story: &StoryRef::Body,
+ width,
+ table: &Default::default(),
+ fields: &self.fields(),
+ note_number: None,
+ grid: self.grid(),
+ origin: Some(self.col_geom().0),
+ },
+ );
+ self.boxes.insert(b.id.clone(), Arc::clone(&pb));
+ pb
+ }
+
+ pub fn run(&mut self, blocks: &[&Block], section_of: &[usize]) {
+ let mut cur_section = usize::MAX;
+ let mut skip_to = 0;
+ for (i, b) in blocks.iter().enumerate() {
+ if i < skip_to {
+ continue;
+ }
+ let s = section_of[i].min(self.sections.len() - 1);
+ if self.cur.is_none() {
+ self.start_page(s, false);
+ cur_section = s;
+ } else if s != cur_section {
+ cur_section = s;
+ // Word 2013 and later keep the space before of a section's
+ // first paragraph, as after a page break; earlier versions
+ // drop it, as at any page top.
+ let hard = self.env.doc.parts().settings.compat_mode >= MODERN_COMPAT;
+ match self.sections[s].start {
+ SectionStart::Continuous => {
+ let same_size = {
+ let old = self.section();
+ let new = &self.sections[s];
+ (old.page_w - new.page_w).abs() < 1.0
+ && (old.page_h - new.page_h).abs() < 1.0
+ };
+ if same_size {
+ self.section_started[s] = true;
+ if let Some(c) = &mut self.cur {
+ // Below everything the previous section's
+ // columns hold on the page.
+ let y = c.sect_bottom.max(c.y);
+ c.sect = s;
+ c.col = 0;
+ c.y = y;
+ c.sect_top = y;
+ c.sect_bottom = y;
+ }
+ } else {
+ self.start_page(s, hard);
+ }
+ }
+ SectionStart::NextColumn => {
+ if let Some(c) = &mut self.cur {
+ c.sect = s;
+ }
+ self.section_started[s] = true;
+ self.next_column(hard);
+ }
+ _ => self.start_page(s, hard),
+ }
+ }
+ match b.kind {
+ BlockKind::Paragraph if self.bare_section_end(blocks, i, section_of) => {}
+ BlockKind::Paragraph => match self.place_frame(blocks, i) {
+ Some(end) => skip_to = end,
+ None => self.place_paragraph(blocks, i),
+ },
+ BlockKind::Table => self.place_table(b),
+ _ => {}
+ }
+ }
+ if self.cur.is_none() {
+ self.start_page(self.sections.len() - 1, false);
+ }
+ self.place_endnotes();
+ }
+
+ /// Whether `blocks[i]` is an empty paragraph that only ends a section and
+ /// takes no room: before a section going on on the same page below text
+ /// (for a section of several columns, the columns end with the text),
+ /// or, ending columns, when it would start a page of its own.
+ fn bare_section_end(&mut self, blocks: &[&Block], i: usize, section_of: &[usize]) -> bool {
+ let (Some(&s), Some(&next)) = (section_of.get(i), section_of.get(i + 1)) else {
+ return false;
+ };
+ if s == next {
+ return false;
+ }
+ let columns = self.sections.get(s).is_some_and(|c| c.columns.len() > 1);
+ let placed_any = self.cur.as_ref().is_some_and(|c| c.placed_any);
+ if !columns && !placed_any {
+ return false;
+ }
+ let (_, width) = self.col_geom();
+ let pb = self.para(blocks[i], width);
+ let empty = pb.inline.label_len == 0
+ && pb
+ .inline
+ .clusters
+ .iter()
+ .all(|c| matches!(c.kind, Kind::End | Kind::Zero));
+ if !empty {
+ return false;
+ }
+ let continuous = self
+ .sections
+ .get(next)
+ .is_some_and(|n| n.start == SectionStart::Continuous);
+ let y = self.cur.as_ref().map_or(0.0, |c| c.y);
+ continuous || (columns && y + pb.lines.height > self.avail_bottom() + EPS)
+ }
+
+ /// The pitch lines snap to in the current section, if they do.
+ fn grid(&self) -> Option<f32> {
+ let s = self.section();
+ (s.grid.snap_lines && s.grid.line_pitch > 0.0).then_some(s.grid.line_pitch)
+ }
+
+ pub fn finish(mut self) -> Vec<Page> {
+ self.finish_page();
+ self.pages
+ }
+}
diff --git a/crates/docx_engine/src/layout/flow/body/floats.rs b/crates/docx_engine/src/layout/flow/body/floats.rs
new file mode 100644
index 0000000000..5f6e3dd5ff
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/body/floats.rs
@@ -0,0 +1,295 @@
+//! Floating things in the body: text frames, the bands of the page that
+//! floats leave no room beside, and drawings placed on the page.
+
+use super::super::super::drawing::Wrap;
+use super::super::super::format::TableCtx;
+use super::super::super::inline::{FieldValues, Kind};
+use super::super::super::{Item, StoryRef};
+use super::super::Env;
+use super::super::anchors::{PageGeom, resolve};
+use super::super::frames::{
+ FrameWrap, PendingFrame, across_text, emit_frame, frame_box, resolve_frame,
+};
+use super::super::stack::{PendingAnchor, StackCtx, placed};
+use super::super::textbox::text_box_items;
+use super::paragraphs::Placing;
+use super::{EPS, Flow};
+use crate::model::block::Block;
+use std::sync::Arc;
+
+/// A frame at least this fraction of the column wide leaves no room for
+/// text beside it.
+const WIDE_FRAME: f32 = 0.66;
+
+/// A stretch of the page that body text skips, below and above a float
+/// that leaves no room beside it: from `top` to `bottom`, in the columns
+/// the float reaches into (between `left` and `right`).
+#[derive(Clone, Copy, Debug)]
+pub(super) struct Band {
+ pub(super) top: f32,
+ pub(super) bottom: f32,
+ pub(super) left: f32,
+ pub(super) right: f32,
+}
+
+impl Band {
+ /// Whether the band reaches into the column from `left`, `width` wide.
+ fn crosses(&self, left: f32, width: f32) -> bool {
+ self.left < left + width - EPS && self.right > left + EPS
+ }
+}
+
+impl Flow<'_, '_> {
+ /// The bands that cross the current column.
+ fn column_bands(&self) -> Vec<Band> {
+ let (left, width) = self.col_geom();
+ self.cur.as_ref().map_or(Vec::new(), |c| {
+ c.bands
+ .iter()
+ .filter(|b| b.crosses(left, width))
+ .copied()
+ .collect()
+ })
+ }
+
+ pub(super) fn avail_bottom(&self) -> f32 {
+ let bands = self.column_bands();
+ self.cur.as_ref().map_or(0.0, |c| {
+ // Text stops at the next blocked band below it.
+ bands
+ .iter()
+ .filter(|b| b.top >= c.y - EPS)
+ .fold(c.bottom - c.notes_height, |bottom, b| bottom.min(b.top))
+ })
+ }
+
+ /// Moves the current position past a blocked band it is in.
+ pub(super) fn skip_bands(&mut self) {
+ let bands = self.column_bands();
+ if let Some(c) = &mut self.cur {
+ while let Some(b) = bands
+ .iter()
+ .find(|b| b.top <= c.y + EPS && b.bottom > c.y + EPS)
+ {
+ c.y = b.bottom;
+ }
+ }
+ }
+
+ /// Places the text frame starting at `blocks[i]`, if it starts one, and
+ /// returns the index after its paragraphs.
+ pub(super) fn place_frame(&mut self, blocks: &[&Block], i: usize) -> Option<usize> {
+ let (col_left, width) = self.col_geom();
+ let sc = StackCtx {
+ story: StoryRef::Body,
+ width,
+ table: TableCtx::default(),
+ fields: self.fields(),
+ note_number: None,
+ float_frames: false,
+ page: Some(self.page_geom()),
+ };
+ let (mut f, end) = frame_box(self.env, &self.env.doc.body, blocks, i, &sc)?;
+ self.skip_bands();
+ let (y, placed_any) = self
+ .cur
+ .as_ref()
+ .map_or((0.0, false), |c| (c.y, c.placed_any));
+ f.para_top = y;
+ f.text_left = col_left;
+ let wrap = f.wrap();
+ // Text cannot go beside a frame across it that leaves no room.
+ let blocks_text = (wrap == FrameWrap::NotBeside
+ || (wrap == FrameWrap::Beside && f.width >= width * WIDE_FRAME))
+ && across_text(&f, &self.page_geom());
+ let in_flow = f.follows_text() && blocks_text;
+ if in_flow && y + f.height > self.avail_bottom() + EPS && placed_any {
+ self.next_column(false);
+ f.para_top = self.cur.as_ref().map_or(0.0, |c| c.y);
+ }
+ let geom = self.page_geom();
+ let fields = self.fields();
+ let rect = resolve_frame(&f, &geom);
+ let mut items = Vec::new();
+ let mut anchors = Vec::new();
+ emit_frame(&f, rect, &mut items, &mut anchors);
+ let on_page = OnPage {
+ env: self.env,
+ fields: &fields,
+ geom: &geom,
+ };
+ if let Some(c) = &mut self.cur {
+ c.body.extend(items);
+ place_anchors(&on_page, &anchors, &mut c.behind, &mut c.front);
+ if in_flow {
+ c.y = c.y.max(rect.y + rect.h + f.props.v_space);
+ c.placed_any = true;
+ } else if blocks_text {
+ c.bands.push(Band {
+ top: rect.y - f.props.v_space,
+ bottom: rect.y + rect.h + f.props.v_space,
+ left: rect.x,
+ right: rect.x + rect.w,
+ });
+ }
+ }
+ Some(end)
+ }
+
+ /// Reserves the bands of the floating drawings in the lines still to
+ /// place of a paragraph that goes on at the current position, `above`
+ /// points below the paragraph's own top (its space before). When such
+ /// a band does not fit, the paragraph moves to the next column first.
+ /// Returns the paragraph top the drawings are positioned from.
+ pub(super) fn reserve_float_bands(&mut self, p: &mut Placing, above: f32) -> f32 {
+ let Some((top, bottom, placed_any)) = self
+ .cur
+ .as_ref()
+ .map(|c| (c.y, c.bottom - c.notes_height, c.placed_any))
+ else {
+ return 0.0;
+ };
+ let mut para_top = top - above;
+ let mut bands = self.float_bands(p, top, para_top);
+ if placed_any && bands.iter().any(|b| b.bottom > bottom + EPS) {
+ // The paragraph starts the next column, with no space above.
+ self.next_column(false);
+ self.follow_column(p);
+ para_top = self.cur.as_ref().map_or(0.0, |c| c.y);
+ bands = self.float_bands(p, para_top, para_top);
+ }
+ if let Some(c) = &mut self.cur {
+ c.bands.extend(bands);
+ }
+ para_top
+ }
+
+ /// The bands of the floating drawings that leave no room for text
+ /// beside them in the lines of `p` still to place, when those lines
+ /// start at `top` in a paragraph starting at `para_top`.
+ fn float_bands(&self, p: &Placing, top: f32, para_top: f32) -> Vec<Band> {
+ let pb = &p.pb;
+ let geom = self.page_geom();
+ let lines = &pb.lines.lines;
+ let base = lines.get(p.li).map_or(0.0, |l| l.top);
+ let mut bands = Vec::new();
+ for line in lines.iter().skip(p.li) {
+ for k in line.start..line.end {
+ let Kind::Anchor(o) = pb.inline.clusters[k].kind else {
+ continue;
+ };
+ let d = &pb.inline.objects[o as usize];
+ let Some(anchor) = &d.anchor else {
+ continue;
+ };
+ let a = PendingAnchor {
+ drawing: Arc::new(d.clone()),
+ para_top,
+ line_top: top + line.top - base,
+ char_x: p.col_left + pb.lines.x[k],
+ story: pb.story.clone(),
+ block: pb.block.clone(),
+ object: o,
+ cell: None,
+ };
+ let Some(r) = resolve(&a, &geom) else {
+ continue;
+ };
+ let no_room = match anchor.wrap {
+ Wrap::TopAndBottom => true,
+ Wrap::Square | Wrap::Tight => r.w >= p.width * WIDE_FRAME,
+ Wrap::None => false,
+ };
+ let band = Band {
+ top: r.y - anchor.dist[0],
+ bottom: r.y + r.h + anchor.dist[1],
+ left: r.x,
+ right: r.x + r.w,
+ };
+ if no_room && !anchor.behind && band.crosses(p.col_left, p.width) {
+ bands.push(band);
+ }
+ }
+ }
+ bands
+ }
+
+ /// When a band starts within `next` points below the current position
+ /// and there is room below it, moves past it and says so.
+ pub(super) fn jump_band(&mut self, next: f32) -> bool {
+ let bands = self.column_bands();
+ let Some(c) = &mut self.cur else {
+ return false;
+ };
+ let bottom = c.bottom - c.notes_height;
+ let band = bands
+ .iter()
+ .filter(|b| b.top >= c.y - EPS && b.top < c.y + next + EPS)
+ .map(|b| b.bottom)
+ .fold(None, |acc: Option<f32>, b| {
+ Some(acc.map_or(b, |a| a.max(b)))
+ });
+ match band {
+ Some(b) if b + next <= bottom + EPS => {
+ c.y = b;
+ true
+ }
+ _ => false,
+ }
+ }
+}
+
+/// The page floating drawings and frames go on.
+pub(super) struct OnPage<'p, 'a> {
+ /// For the text in text boxes.
+ pub(super) env: &'p Env<'a>,
+ /// The page's field values.
+ pub(super) fields: &'p FieldValues,
+ /// The page.
+ pub(super) geom: &'p PageGeom,
+}
+
+/// Places a header's or footer's text frames, given where its stack went.
+pub(super) fn place_frames(
+ page: &OnPage<'_, '_>,
+ frames: &mut [PendingFrame],
+ origin: (f32, f32),
+ out: &mut Vec<Item>,
+ behind: &mut Vec<Item>,
+ front: &mut Vec<Item>,
+) {
+ for f in frames {
+ f.offset(origin.0, origin.1);
+ let rect = resolve_frame(f, page.geom);
+ let mut anchors = Vec::new();
+ emit_frame(f, rect, out, &mut anchors);
+ place_anchors(page, &anchors, behind, front);
+ }
+}
+
+/// Places floating drawings behind or in front of the text, with the text
+/// of text boxes over their shapes.
+pub(super) fn place_anchors(
+ page: &OnPage<'_, '_>,
+ anchors: &[PendingAnchor],
+ behind: &mut Vec<Item>,
+ front: &mut Vec<Item>,
+) {
+ let mut sorted: Vec<&PendingAnchor> = anchors.iter().collect();
+ sorted.sort_by_key(|a| a.drawing.anchor.as_ref().map_or(0, |x| x.z));
+ for a in sorted {
+ let Some(rect) = resolve(a, page.geom) else {
+ continue;
+ };
+ let out = if a.drawing.anchor.as_ref().is_some_and(|x| x.behind) {
+ &mut *behind
+ } else {
+ &mut *front
+ };
+ out.push(placed(Arc::clone(&a.drawing), rect, a.story.clone()));
+ out.extend(text_box_items(page.env, page.fields, a, rect));
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/layout/flow/body/floats/test.rs b/crates/docx_engine/src/layout/flow/body/floats/test.rs
new file mode 100644
index 0000000000..2cfda9f20d
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/body/floats/test.rs
@@ -0,0 +1,152 @@
+use crate::Document;
+use crate::layout::inline::Kind;
+use crate::layout::{Item, Layout, PlacedLine, StoryRef};
+use crate::test_support::{Parts, docx, fonts};
+use pptx_engine::path::Rect;
+
+const ARIAL_10: &str = r#"<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Arial" w:hAnsi="Arial"/><w:sz w:val="20"/></w:rPr></w:rPrDefault></w:docDefaults>"#;
+
+/// A letter page with one-inch margins, in two columns half an inch apart
+/// (216pt wide, at x 72 and 324).
+const TWO_COLUMNS: &str = r#"<w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720"/><w:cols w:num="2" w:space="720"/></w:sectPr>"#;
+
+/// Points in an EMU.
+const EMU: i64 = 12_700;
+
+fn layout(body: &str) -> Layout {
+ let parts = Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ };
+ Document::open(docx(body, &parts)).unwrap().layout(fonts())
+}
+
+fn text(p: &PlacedLine) -> String {
+ let l = p.line();
+ p.para.inline.clusters[l.start..l.end]
+ .iter()
+ .filter(|c| matches!(c.kind, Kind::Text | Kind::Space))
+ .map(|c| c.ch)
+ .collect()
+}
+
+fn body_lines(l: &Layout) -> Vec<&PlacedLine> {
+ l.pages[0].lines_of(&StoryRef::Body).collect()
+}
+
+fn find<'a>(l: &'a Layout, t: &str) -> &'a PlacedLine {
+ body_lines(l)
+ .into_iter()
+ .find(|p| text(p) == t)
+ .unwrap_or_else(|| panic!("no line {t:?}"))
+}
+
+fn drawings(l: &Layout) -> Vec<Rect> {
+ l.pages[0]
+ .all_items()
+ .filter_map(|i| match i {
+ Item::Drawing(d) => Some(d.rect),
+ _ => None,
+ })
+ .collect()
+}
+
+fn para(t: &str) -> String {
+ format!("<w:p><w:r><w:t>{t}</w:t></w:r></w:p>")
+}
+
+/// A one-inch picture anchored to its paragraph with `wrap`, `offset`
+/// points below the paragraph's top.
+fn anchored_picture(wrap: &str, offset: i64) -> String {
+ format!(
+ r#"<w:r><w:drawing><wp:anchor distT="0" distB="0" distL="0" distR="0" simplePos="0" relativeHeight="1" behindDoc="0" locked="0" layoutInCell="1" allowOverlap="1"><wp:simplePos x="0" y="0"/><wp:positionH relativeFrom="column"><wp:posOffset>0</wp:posOffset></wp:positionH><wp:positionV relativeFrom="paragraph"><wp:posOffset>{}</wp:posOffset></wp:positionV><wp:extent cx="914400" cy="914400"/><wp:effectExtent l="0" t="0" r="0" b="0"/>{wrap}<wp:docPr id="1" name="p"/><a:graphic><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:pic><pic:blipFill><a:blip r:embed="rIdX"/></pic:blipFill><pic:spPr/></pic:pic></a:graphicData></a:graphic></wp:anchor></w:drawing></w:r>"#,
+ offset * EMU
+ )
+}
+
+#[test]
+fn top_and_bottom_floats_push_text_below_them() {
+ let body = format!(
+ "<w:p>{}<w:r><w:t>Beside</w:t></w:r></w:p><w:p><w:r><w:t>Next</w:t></w:r></w:p>",
+ anchored_picture("<wp:wrapTopAndBottom/>", 0)
+ );
+ let l = layout(&body);
+ let ls = body_lines(&l);
+ // The picture spans 72..144: its paragraph's text goes below it.
+ assert!((ls[0].y - 144.0).abs() < 0.01, "{}", ls[0].y);
+ // Text that ignores it stays put.
+ let body = format!(
+ "<w:p>{}<w:r><w:t>Over</w:t></w:r></w:p>",
+ anchored_picture("<wp:wrapNone/>", 0)
+ );
+ let l = layout(&body);
+ assert!((body_lines(&l)[0].y - 72.0).abs() < 0.01);
+}
+
+#[test]
+fn text_continues_below_a_band_further_down() {
+ // A picture an inch below its paragraph: the paragraph's line stays on
+ // top, the next paragraph jumps the band instead of the page.
+ let body = format!(
+ "<w:p>{}<w:r><w:t>Above</w:t></w:r></w:p><w:p><w:r><w:t>Below</w:t></w:r></w:p>",
+ anchored_picture("<wp:wrapTopAndBottom/>", 12)
+ );
+ let l = layout(&body);
+ assert_eq!(l.pages.len(), 1);
+ let ls = body_lines(&l);
+ assert!((ls[0].y - 72.0).abs() < 0.01, "{}", ls[0].y);
+ assert!((ls[1].y - (72.0 + 12.0 + 72.0)).abs() < 0.01, "{}", ls[1].y);
+}
+
+#[test]
+fn drawings_that_move_their_paragraph_to_the_next_column_go_with_it() {
+ // The picture's paragraph comes less than an inch above the bottom of
+ // the first column: picture and paragraph go to the top of the second,
+ // and the text after them goes below the picture there. A picture
+ // raised above its paragraph does the same.
+ for raise in [0, 10] {
+ let filler: String = (0..52).map(|k| para(&format!("Line {k}"))).collect();
+ let body = format!(
+ "{filler}<w:p>{}<w:r><w:t>Anchor</w:t></w:r></w:p>{}{TWO_COLUMNS}",
+ anchored_picture("<wp:wrapTopAndBottom/>", -raise),
+ para("After")
+ );
+ let l = layout(&body);
+ let last = find(&l, "Line 51");
+ assert!(last.y + last.line().height + 72.0 > 720.0, "{}", last.y);
+ let picture = drawings(&l)[0];
+ let top = 72.0 - raise as f32;
+ assert!((picture.x - 324.0).abs() < 0.01, "{}", picture.x);
+ assert!((picture.y - top).abs() < 0.01, "{}", picture.y);
+ let (anchor, after) = (find(&l, "Anchor"), find(&l, "After"));
+ assert!((anchor.x - 324.0).abs() < 0.01, "{}", anchor.x);
+ assert!((anchor.y - (top + 72.0)).abs() < 0.01, "{}", anchor.y);
+ assert!((after.x - 324.0).abs() < 0.01, "{}", after.x);
+ let below = anchor.y + anchor.line().height;
+ assert!((after.y - below).abs() < 0.01, "{}", after.y);
+ }
+}
+
+#[test]
+fn bands_keep_text_out_of_the_columns_they_cross_only() {
+ // A picture across the first column: the second column's text runs
+ // past the picture's height undisturbed.
+ let right: String = (1..10).map(|k| para(&format!("Right {k}"))).collect();
+ let body = format!(
+ r#"{}<w:p>{}</w:p>{}<w:p><w:r><w:br w:type="column"/><w:t>Right 0</w:t></w:r></w:p>{right}{TWO_COLUMNS}"#,
+ para("Intro"),
+ anchored_picture("<wp:wrapTopAndBottom/>", 0),
+ para("Below"),
+ );
+ let l = layout(&body);
+ let h = find(&l, "Intro").line().height;
+ let picture = drawings(&l)[0];
+ assert!((picture.x - 72.0).abs() < 0.01, "{}", picture.x);
+ assert!(find(&l, "Below").y >= picture.y + picture.h - 0.01);
+ for k in 0..10 {
+ let line = find(&l, &format!("Right {k}"));
+ assert!((line.x - 324.0).abs() < 0.01, "{}", line.x);
+ let y = 72.0 + k as f32 * h;
+ assert!((line.y - y).abs() < 0.01, "Right {k}: {} != {y}", line.y);
+ }
+}
diff --git a/crates/docx_engine/src/layout/flow/body/notes.rs b/crates/docx_engine/src/layout/flow/body/notes.rs
new file mode 100644
index 0000000000..836267999e
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/body/notes.rs
@@ -0,0 +1,190 @@
+//! Notes: footnotes at the bottom of the page they are referenced on,
+//! endnotes after the body.
+
+use super::super::super::{Item, StoryRef};
+use super::super::offset_items;
+use super::super::stack::{Stack, StackCtx, stack_story};
+use super::{Flow, MODERN_COMPAT};
+use std::sync::Arc;
+
+/// The story id of the footnote separator.
+const SEPARATOR: i64 = -1;
+/// The story id of the footnote continuation notice.
+const CONTINUATION_NOTICE: i64 = -3;
+
+impl Flow<'_, '_> {
+ /// The footnote of a special `kind` (the separator, the continuation
+ /// notice), laid out.
+ fn special_note(&self, kind: &str, story: StoryRef) -> Option<Stack> {
+ let notes = self.env.doc.footnotes();
+ let note = notes.by_id.values().find(|n| n.kind == kind)?;
+ Some(stack_story(
+ self.env,
+ &note.story,
+ None,
+ &StackCtx {
+ story,
+ width: self.section().text_width(),
+ table: Default::default(),
+ fields: self.fields(),
+ note_number: None,
+ float_frames: false,
+ page: None,
+ },
+ ))
+ }
+
+ /// The room Word keeps below a page's footnotes for the notice that a
+ /// note goes on overleaf, when the document has one. Only documents
+ /// laid out like Word 2010 and earlier keep it on every page; from Word
+ /// 2013 on the notes reach down to the bottom margin.
+ fn notice_height(&mut self) -> f32 {
+ if self.notice.is_none() {
+ let story = StoryRef::Footnote(CONTINUATION_NOTICE);
+ let modern = self.env.doc.parts().settings.compat_mode >= MODERN_COMPAT;
+ let height = if modern {
+ 0.0
+ } else {
+ self.special_note("continuationNotice", story)
+ .map_or(0.0, |s| s.height)
+ };
+ self.notice = Some(height);
+ }
+ self.notice.unwrap_or(0.0)
+ }
+
+ pub(super) fn separator_stack(&mut self) -> Option<Stack> {
+ if self.separator.is_none() {
+ let sep = self.special_note("separator", StoryRef::Footnote(SEPARATOR));
+ self.separator = Some(match sep {
+ Some(stack) => stack,
+ None => Stack {
+ items: vec![Item::Rule {
+ x0: 0.0,
+ y0: 6.0,
+ x1: 144.0,
+ y1: 6.0,
+ border: crate::model::props::Border {
+ style: crate::model::props::LineStyle::Single,
+ width: 0.5,
+ space: 0.0,
+ color: crate::model::props::ColorRef::Auto,
+ },
+ }],
+ anchors: Vec::new(),
+ height: 12.0,
+ notes: Vec::new(),
+ frames: Vec::new(),
+ },
+ });
+ }
+ self.separator.clone()
+ }
+
+ pub(super) fn note_height(&mut self, id: i64) -> f32 {
+ if let Some(st) = self.note_stacks.get(&id) {
+ return st.height;
+ }
+ let Some(note) = self.env.doc.footnotes().by_id.get(&id) else {
+ return 0.0;
+ };
+ let number = self
+ .env
+ .note_numbers
+ .get(&(false, id))
+ .cloned()
+ .unwrap_or_default();
+ let st = stack_story(
+ self.env,
+ &note.story,
+ None,
+ &StackCtx {
+ story: StoryRef::Footnote(id),
+ width: self.section().text_width(),
+ table: Default::default(),
+ fields: self.fields(),
+ note_number: Some(number),
+ float_frames: false,
+ page: None,
+ },
+ );
+ let h = st.height;
+ self.note_stacks.insert(id, st);
+ h
+ }
+
+ /// Extra note height needed for these note references on this page.
+ pub(super) fn notes_needed(&mut self, ids: &[i64]) -> f32 {
+ let fresh: Vec<i64> = {
+ let cur = self.cur.as_ref();
+ ids.iter()
+ .copied()
+ .filter(|id| cur.is_none_or(|c| !c.notes.contains(id)))
+ .collect()
+ };
+ if fresh.is_empty() {
+ return 0.0;
+ }
+ let mut h: f32 = fresh.iter().map(|&id| self.note_height(id)).sum();
+ if self.cur.as_ref().is_some_and(|c| c.notes.is_empty()) {
+ h += self.separator_stack().map_or(0.0, |s| s.height) + self.notice_height();
+ }
+ h
+ }
+
+ pub(super) fn add_notes(&mut self, ids: &[i64]) {
+ let need = self.notes_needed(ids);
+ if let Some(cur) = &mut self.cur {
+ for id in ids {
+ if !cur.notes.contains(id) {
+ cur.notes.push(*id);
+ }
+ }
+ cur.notes_height += need;
+ }
+ }
+
+ pub(super) fn place_endnotes(&mut self) {
+ let notes = self.env.doc.endnotes();
+ // In the order of their references, which is also their numbering.
+ let numbers = Arc::clone(&self.env.note_numbers);
+ for &id in &numbers.endnotes {
+ let (Some(note), Some(number)) = (notes.by_id.get(&id), numbers.get(&(true, id)))
+ else {
+ continue;
+ };
+ let (_, width) = self.col_geom();
+ let st = stack_story(
+ self.env,
+ &note.story,
+ None,
+ &StackCtx {
+ story: StoryRef::Endnote(id),
+ width,
+ table: Default::default(),
+ fields: self.fields(),
+ note_number: Some(number.clone()),
+ float_frames: false,
+ page: None,
+ },
+ );
+ let (y, placed_any) = self
+ .cur
+ .as_ref()
+ .map_or((0.0, false), |c| (c.y, c.placed_any));
+ if y + st.height > self.avail_bottom() && placed_any {
+ self.next_column(false);
+ }
+ // The column it goes in, after any move to the next one.
+ let (col_left, _) = self.col_geom();
+ let y = self.cur.as_ref().map_or(0.0, |c| c.y);
+ let mut items = st.items.clone();
+ offset_items(&mut items, col_left, y);
+ if let Some(c) = &mut self.cur {
+ c.body.extend(items);
+ c.y += st.height;
+ c.placed_any = true;
+ }
+ }
+ }
+}
diff --git a/crates/docx_engine/src/layout/flow/body/paragraphs.rs b/crates/docx_engine/src/layout/flow/body/paragraphs.rs
new file mode 100644
index 0000000000..1763e1a150
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/body/paragraphs.rs
@@ -0,0 +1,459 @@
+//! Paragraphs in the body: placing their lines on pages and in columns,
+//! with keep-with-next chains, widow control, notes and line numbers.
+
+use super::super::super::format::TableCtx;
+use super::super::super::lines::LineEnd;
+use super::super::super::{Item, ParaBox, StoryRef};
+use super::super::stack::{
+ BorderJoin, Fragment, PendingAnchor, PrevPara, Sink, border_space, decorate, emit_lines,
+ prev_record, rebreak, space_after, space_before, table_box,
+};
+use super::floats::{OnPage, place_anchors};
+use super::{COLUMN_SLACK, EPS, Flow, LINE_NUMBER_DISTANCE};
+use crate::model::block::{Block, BlockKind};
+use crate::model::props::{LineSpacing, ParaProps};
+use crate::model::section::LineNumberRestart;
+use std::sync::Arc;
+
+/// A paragraph on its way onto the pages: its lines, broken for the
+/// column it is in, the first of them still to place, and that column.
+pub(super) struct Placing {
+ /// The paragraph's lines.
+ pub(super) pb: Arc<ParaBox>,
+ /// The first line still to place.
+ pub(super) li: usize,
+ /// The column's left edge (page x).
+ pub(super) col_left: f32,
+ /// The column's width.
+ pub(super) width: f32,
+}
+
+impl Flow<'_, '_> {
+ /// How paragraph `k` (formatted `props`) joins its neighbours' borders.
+ fn border_join(
+ &self,
+ blocks: &[&Block],
+ k: usize,
+ props: &ParaProps,
+ prev: Option<&PrevPara>,
+ ) -> BorderJoin {
+ let next = blocks
+ .get(k + 1)
+ .filter(|n| n.kind == BlockKind::Paragraph)
+ .map(|n| self.env.formats.paragraph(&n.props, &TableCtx::default()));
+ BorderJoin::new(
+ props,
+ prev.map(|p| &p.border),
+ next.as_ref().map(|f| &f.props),
+ )
+ }
+
+ /// Height a keep-with-next chain starting at `i` needs on one page.
+ fn keep_chain(&mut self, blocks: &[&Block], i: usize, width: f32) -> f32 {
+ let mut need = 0.0;
+ let mut prev: Option<PrevPara> = self.prev.clone();
+ let mut k = i;
+ while k < blocks.len() {
+ let b = blocks[k];
+ if b.kind != BlockKind::Paragraph {
+ // Keep with the first row of a table.
+ let tb = table_box(
+ self.env,
+ &self.env.doc.body,
+ b,
+ width,
+ &StoryRef::Body,
+ &self.fields(),
+ );
+ need += tb.rows.first().map_or(0.0, |r| r.height);
+ break;
+ }
+ let pb = self.para(b, width);
+ let props = &pb.format.props;
+ need += if k == i {
+ 0.0
+ } else {
+ space_before(props, prev.as_ref(), false, self.sum_spacing())
+ };
+ let join = self.border_join(blocks, k, props, prev.as_ref());
+ let (bt, bb) = border_space(props, join);
+ let lines = &pb.lines.lines;
+ if let Some(b) = lines
+ .iter()
+ .position(|l| matches!(l.ends, LineEnd::PageBreak | LineEnd::ColumnBreak))
+ {
+ // The chain ends at a page break.
+ need += bt + lines[..=b].iter().map(|l| l.height).sum::<f32>();
+ break;
+ }
+ if props.keep_next && k + 1 < blocks.len() && k - i < 32 {
+ need += bt + pb.lines.height + bb;
+ prev = Some(prev_record(props));
+ k += 1;
+ continue;
+ }
+ // The last paragraph of the chain: its first lines.
+ let take = if props.keep_lines || lines.len() <= 2 || !props.widow_control {
+ if props.keep_lines {
+ lines.len()
+ } else {
+ lines.len().min(1)
+ }
+ } else {
+ 2
+ };
+ need += bt
+ + lines
+ .iter()
+ .take(take.max(1))
+ .map(|l| l.height)
+ .sum::<f32>();
+ break;
+ }
+ need
+ }
+
+ pub(super) fn place_paragraph(&mut self, blocks: &[&Block], i: usize) {
+ let b = blocks[i];
+ let (_, width) = self.col_geom();
+ let pb = self.para(b, width);
+ let props = pb.format.props.clone();
+ let at_top = self.cur.as_ref().is_some_and(|c| !c.placed_any);
+ if props.page_break_before && !at_top {
+ // Not a hard break: the paragraph's space before goes, as at
+ // any page top.
+ let sect = self.cur.as_ref().map_or(0, |c| c.sect);
+ self.start_page(sect, false);
+ self.prev = None;
+ } else if props.keep_next && !at_top && !hard_break(&pb) {
+ // (A paragraph with a page break in it goes on after the break
+ // anyway: what comes before it stays.)
+ let need = self.keep_chain(blocks, i, width);
+ let (y, top) = self.cur.as_ref().map_or((0.0, 0.0), |c| (c.y, c.top));
+ let before = space_before(&props, self.prev.as_ref(), false, self.sum_spacing());
+ let avail = self.avail_bottom() - y - before;
+ let full = self.avail_bottom() - top;
+ if need > avail + EPS && need <= full {
+ self.next_column(false);
+ }
+ }
+ // The paragraph goes in the column it is now in.
+ let mut p = Placing {
+ pb,
+ li: 0,
+ col_left: 0.0,
+ width,
+ };
+ self.follow_column(&mut p);
+ let at_top = self.cur.as_ref().is_some_and(|c| !c.placed_any);
+ let hard = self.cur.as_ref().is_some_and(|c| c.hard)
+ && !self.env.doc.parts().settings.suppress_sp_bf_after_pg_brk;
+ let first_in_doc = self.pages.is_empty() && at_top;
+ let before = if at_top {
+ if hard || first_in_doc || self.env.options.space_before_at_page_top {
+ space_before(&props, None, first_in_doc, self.sum_spacing())
+ } else {
+ 0.0
+ }
+ } else {
+ space_before(&props, self.prev.as_ref(), false, self.sum_spacing())
+ };
+ let gap_top = self.cur.as_ref().map_or(0.0, |c| c.y);
+ if let Some(c) = &mut self.cur {
+ c.y += before;
+ }
+ // Where the paragraph's floating drawings are positioned from: its
+ // top, above its own space before.
+ let own = space_before(&props, None, first_in_doc, self.sum_spacing());
+ let mut anchor_top = self.reserve_float_bands(&mut p, before.min(own));
+ let mut join = self.border_join(blocks, i, &props, self.prev.as_ref());
+ let mut first_fragment = true;
+ while p.li < p.pb.lines.lines.len() {
+ let (li, lines_len) = (p.li, p.pb.lines.lines.len());
+ self.skip_bands();
+ self.suppress_top_spacing(&p.pb, li);
+ let (bt, bb) = border_space(&props, join);
+ let mut frag_top = self.cur.as_ref().map_or(0.0, |c| c.y);
+ if first_fragment {
+ if join.prev {
+ // The shared border box spans the gap to the previous paragraph.
+ frag_top = gap_top;
+ }
+ if let Some(c) = &mut self.cur {
+ c.y += bt;
+ }
+ }
+ let (fit, note_ids) = self.fit_lines(&p.pb, li);
+ let lines = &p.pb.lines.lines;
+ let remaining = lines_len - li;
+ let mut take = fit.min(remaining);
+ if let Some(k) = (li..li + take)
+ .find(|&k| matches!(lines[k].ends, LineEnd::PageBreak | LineEnd::ColumnBreak))
+ {
+ take = k - li + 1;
+ }
+ if take < remaining {
+ let breaks_inside = (li..li + take)
+ .any(|k| matches!(lines[k].ends, LineEnd::PageBreak | LineEnd::ColumnBreak));
+ if !breaks_inside {
+ if props.widow_control {
+ if remaining - take == 1 && take >= 2 {
+ take -= 1;
+ }
+ if li == 0 && take == 1 && remaining >= 2 {
+ take = 0;
+ }
+ }
+ let column = self.avail_bottom() - self.cur.as_ref().map_or(0.0, |c| c.top);
+ if props.keep_lines && li == 0 && p.pb.lines.height <= column {
+ take = 0;
+ }
+ }
+ }
+ let placed_any = self.cur.as_ref().is_some_and(|c| c.placed_any);
+ if take == 0 {
+ if placed_any {
+ if first_fragment && let Some(c) = &mut self.cur {
+ c.y -= bt;
+ }
+ let next = p.pb.lines.lines.get(li).map_or(0.0, |l| l.height);
+ if self.jump_band(next + bt) {
+ continue;
+ }
+ self.next_column(false);
+ self.follow_column(&mut p);
+ // A new column starts a new border box.
+ join.prev = false;
+ anchor_top = self.reserve_float_bands(&mut p, 0.0);
+ continue;
+ }
+ take = 1;
+ }
+ // Place lines li..li+take.
+ let ids: Vec<i64> = note_ids
+ .iter()
+ .take_while(|(k, _)| *k < li + take)
+ .map(|(_, id)| *id)
+ .collect();
+ self.add_notes(&ids);
+ let y = self.cur.as_ref().map_or(0.0, |c| c.y);
+ let mut items = Vec::new();
+ let mut anchors: Vec<PendingAnchor> = Vec::new();
+ let mut notes = Vec::new();
+ let sink = Sink {
+ items: &mut items,
+ anchors: &mut anchors,
+ notes: &mut notes,
+ };
+ let h = emit_lines(&p.pb, (li, li + take), (p.col_left, y), anchor_top, sink);
+ self.number_lines(&p.pb, li, li + take, p.col_left, y);
+ let last_fragment = li + take >= lines_len;
+ let bottom = y + h + if last_fragment { bb } else { 0.0 };
+ if props.shading.is_some() || props.borders.any() {
+ let mut deco = Vec::new();
+ if !first_fragment {
+ frag_top = y;
+ }
+ let frag = Fragment {
+ x: p.col_left,
+ width: p.width,
+ top: frag_top,
+ bottom,
+ first: first_fragment,
+ last: last_fragment,
+ };
+ decorate(&props, frag, join, &mut deco);
+ if let Some(c) = &mut self.cur {
+ c.body.extend(deco);
+ }
+ }
+ let geom = self.page_geom();
+ let fields = self.fields();
+ let on_page = OnPage {
+ env: self.env,
+ fields: &fields,
+ geom: &geom,
+ };
+ if let Some(c) = &mut self.cur {
+ c.body.extend(items);
+ place_anchors(&on_page, &anchors, &mut c.behind, &mut c.front);
+ c.y = bottom;
+ c.placed_any = true;
+ c.hard = false;
+ }
+ p.li += take;
+ first_fragment = false;
+ let last_end = p.pb.lines.lines[p.li - 1].ends;
+ if p.li < lines_len || matches!(last_end, LineEnd::PageBreak | LineEnd::ColumnBreak) {
+ match last_end {
+ LineEnd::PageBreak => {
+ let sect = self.cur.as_ref().map_or(0, |c| c.sect);
+ self.start_page(sect, true);
+ if p.pb.lines.lines[..p.li].iter().all(|l| l.height == 0.0) {
+ // A paragraph that starts with a page break
+ // starts after it, with its space before.
+ self.space_after_hard_break(&props);
+ }
+ }
+ LineEnd::ColumnBreak => self.next_column(true),
+ _ => {
+ // Lines continue below a band that stopped them,
+ // where their drawings' bands are already reserved.
+ let next = p.pb.lines.lines.get(p.li).map_or(0.0, |l| l.height);
+ if self.jump_band(next) {
+ continue;
+ }
+ self.next_column(false);
+ }
+ }
+ self.follow_column(&mut p);
+ // The drawings of the lines still to place go with them,
+ // positioned from where they go on.
+ anchor_top = self.reserve_float_bands(&mut p, 0.0);
+ }
+ }
+ self.prev = Some(prev_record(&props));
+ }
+
+ /// Takes the current column's left edge and width for a paragraph
+ /// whose lines from `p.li` on are still to be placed, breaking those
+ /// lines again when the column is not as wide as they were broken for.
+ pub(super) fn follow_column(&mut self, p: &mut Placing) {
+ let (left, w) = self.col_geom();
+ p.col_left = left;
+ if (w - p.width).abs() <= COLUMN_SLACK {
+ return;
+ }
+ p.width = w;
+ if let Some(line) = p.pb.lines.lines.get(p.li) {
+ p.pb = rebreak(self.env, &p.pb, (w, Some(left)), line.start, self.grid());
+ p.li = 0;
+ }
+ }
+
+ /// Adds the space before of a paragraph that started with a page break
+ /// at the top of the page the break started, unless the document
+ /// suppresses it there. (Word leaves it out for exactly spaced lines.)
+ fn space_after_hard_break(&mut self, props: &ParaProps) {
+ if self.env.doc.parts().settings.suppress_sp_bf_after_pg_brk
+ || matches!(props.line, LineSpacing::Exact(_))
+ {
+ return;
+ }
+ let before = space_before(props, None, false, self.sum_spacing());
+ if let Some(c) = &mut self.cur {
+ c.y += before;
+ }
+ }
+
+ /// Lifts the page's first line when the document suppresses extra line
+ /// spacing at the top of the page: an at-least line there is no taller
+ /// than its text's size (`w:suppressTopSpacing`).
+ fn suppress_top_spacing(&mut self, pb: &ParaBox, li: usize) {
+ if !self.env.doc.parts().settings.suppress_top_spacing {
+ return;
+ }
+ let LineSpacing::AtLeast(min) = pb.format.props.line else {
+ return;
+ };
+ let Some(line) = pb.lines.lines.get(li) else {
+ return;
+ };
+ let size = pb.inline.clusters[line.start..line.end]
+ .iter()
+ .map(|c| c.size)
+ .fold(0.0f32, f32::max);
+ if let Some(c) = &mut self.cur
+ && !c.placed_any
+ && c.col == 0
+ && (c.y - c.top).abs() < EPS
+ && size > 0.0
+ {
+ c.y -= (min - size).max(0.0);
+ }
+ }
+
+ /// How many lines from `li` fit in the current column, and the note
+ /// references (line index, id) of the lines considered.
+ fn fit_lines(&mut self, pb: &ParaBox, li: usize) -> (usize, Vec<(usize, i64)>) {
+ let lines = &pb.lines.lines;
+ let mut y = self.cur.as_ref().map_or(0.0, |c| c.y);
+ let bottom = self.avail_bottom();
+ // The extra room of multiple line spacing sits below the text and may
+ // run into the bottom margin: a line fits when its text does.
+ let props = &pb.format.props;
+ let spread = match props.line {
+ LineSpacing::Auto(m) if m > 1.0 && !(props.snap_to_grid && self.grid().is_some()) => m,
+ _ => 1.0,
+ };
+ let mut count = 0;
+ let mut ids: Vec<(usize, i64)> = Vec::new();
+ for (k, line) in lines.iter().enumerate().skip(li) {
+ let line_notes: Vec<i64> = pb
+ .inline
+ .notes
+ .iter()
+ .filter(|(at, endnote, _)| !endnote && *at >= line.start && *at < line.end)
+ .map(|(_, _, id)| *id)
+ .collect();
+ let mut pending: Vec<i64> = ids.iter().map(|(_, id)| *id).collect();
+ pending.extend(&line_notes);
+ let note_h = self.notes_needed(&pending);
+ // Above footnotes, a paragraph's space after must fit as well.
+ let notes =
+ !pending.is_empty() || self.cur.as_ref().is_some_and(|c| !c.notes.is_empty());
+ let after = if notes && k + 1 == lines.len() {
+ space_after(props)
+ } else {
+ 0.0
+ };
+ if y + line.height / spread + after > bottom - note_h + EPS {
+ break;
+ }
+ y += line.height;
+ count += 1;
+ ids.extend(line_notes.into_iter().map(|id| (k, id)));
+ }
+ (count, ids)
+ }
+
+ fn number_lines(&mut self, pb: &ParaBox, from: usize, to: usize, col_left: f32, y: f32) {
+ let s = self.section().clone();
+ let Some(ln) = s.line_numbers else {
+ return;
+ };
+ if pb.format.props.suppress_line_numbers {
+ return;
+ }
+ let Some(cur) = &mut self.cur else {
+ return;
+ };
+ if ln.restart == LineNumberRestart::NewPage && cur.line_on_page == 0 && self.line_no > 0 {
+ self.line_no = 0;
+ }
+ let base = pb.lines.lines.get(from).map_or(0.0, |l| l.top);
+ for line in &pb.lines.lines[from..to] {
+ self.line_no += 1;
+ cur.line_on_page += 1;
+ let n = ln.start - 1 + self.line_no;
+ if ln.count_by > 0 && n.is_multiple_of(ln.count_by) {
+ let mark = &pb.format.mark;
+ cur.body.push(Item::LineNumber {
+ text: n.to_string(),
+ right: col_left - ln.distance.unwrap_or(LINE_NUMBER_DISTANCE),
+ baseline: y + line.top - base + line.baseline,
+ size: mark.size,
+ font: mark.ascii.clone(),
+ });
+ }
+ }
+ }
+}
+
+/// Whether a page or column break ends one of the paragraph's lines.
+fn hard_break(pb: &ParaBox) -> bool {
+ pb.lines
+ .lines
+ .iter()
+ .any(|l| matches!(l.ends, LineEnd::PageBreak | LineEnd::ColumnBreak))
+}
diff --git a/crates/docx_engine/src/layout/flow/body/tables.rs b/crates/docx_engine/src/layout/flow/body/tables.rs
new file mode 100644
index 0000000000..bcaa6986b3
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/body/tables.rs
@@ -0,0 +1,221 @@
+//! Body tables: rows across columns and pages, and floating tables
+//! (`w:tblpPr`), which sit at a position of their own.
+
+use super::super::super::{Item, StoryRef};
+use super::super::anchors::PageGeom;
+use super::super::split::split_row;
+use super::super::stack::{RowBox, Sink, TableBox, emit_row, table_box};
+use super::floats::{OnPage, place_anchors};
+use super::{EPS, Flow};
+use crate::model::block::Block;
+use crate::model::props::TablePosition;
+use std::sync::Arc;
+
+/// Where a floating table's left edge goes on the page.
+pub(in crate::layout::flow) fn float_x(pos: &TablePosition, g: &PageGeom, width: f32) -> f32 {
+ let (x0, span) = match pos.h_anchor.as_str() {
+ "margin" => (g.left, g.width - g.left - g.right),
+ "page" => (0.0, g.width),
+ _ => (g.col_left, g.col_width),
+ };
+ match pos.x_align.as_deref() {
+ Some("center") => x0 + (span - width) / 2.0,
+ Some("right" | "outside") => x0 + span - width,
+ Some("left" | "inside") => x0,
+ _ => x0 + pos.x,
+ }
+}
+
+/// Where a floating table `height` tall starts on the page, `y` being the
+/// top of the text it is anchored to.
+pub(in crate::layout::flow) fn float_y(
+ pos: &TablePosition,
+ g: &PageGeom,
+ y: f32,
+ height: f32,
+) -> f32 {
+ let (y0, span) = match pos.v_anchor.as_str() {
+ "page" => (0.0, g.height),
+ "margin" => (g.top, g.height - g.top - g.bottom),
+ _ => (y, 0.0),
+ };
+ match pos.y_align.as_deref() {
+ Some("inline") => y,
+ Some("center") => y0 + (span - height) / 2.0,
+ Some("bottom" | "outside") => y0 + span - height,
+ Some("top" | "inside") => y0,
+ _ => y0 + pos.y,
+ }
+}
+
+/// Whether a row stays on the page of the row after it: rows with a
+/// paragraph kept with the next one do.
+fn keeps_with_next(row: &RowBox) -> bool {
+ row.cells.iter().any(|c| {
+ c.content
+ .items
+ .iter()
+ .any(|i| matches!(i, Item::Line(l) if l.para.format.props.keep_next))
+ })
+}
+
+/// The last row that goes to a page together with row `r`. Header rows
+/// also keep with the first row they head (when the table has one).
+fn keep_chain_end(tb: &TableBox, r: usize) -> usize {
+ let headed = tb.rows.iter().any(|row| !row.header);
+ let mut end = r;
+ while end + 1 < tb.rows.len()
+ && ((headed && tb.rows[end].header) || keeps_with_next(&tb.rows[end]))
+ {
+ end += 1;
+ }
+ end
+}
+
+impl Flow<'_, '_> {
+ pub(super) fn place_table(&mut self, b: &Block) {
+ let (mut col_left, width) = self.col_geom();
+ if let (Some(prev), Some(c)) = (self.prev.take(), &mut self.cur)
+ && c.placed_any
+ {
+ c.y += prev.after;
+ }
+ let mut tb = table_box(
+ self.env,
+ &self.env.doc.body,
+ b,
+ width,
+ &StoryRef::Body,
+ &self.fields(),
+ );
+ // A floating table takes no room beside it (text goes on below it)
+ // but sits at its own position.
+ let float = tb.geom.tbl.position.clone();
+ let height: f32 = tb.rows.iter().map(|r| r.height).sum();
+ if let Some(pos) = &float {
+ let g = self.page_geom();
+ Arc::make_mut(&mut tb).geom.left = float_x(pos, &g, tb.geom.width()) - col_left;
+ self.float_down(pos, height, true);
+ }
+ let headers: Vec<usize> = (0..tb.rows.len())
+ .take_while(|&r| tb.rows[r].header)
+ .collect();
+ let mut r = 0;
+ // The row was moved to a fresh column already: place it even if it
+ // does not fit, or a row taller than the page would never land.
+ let mut moved = false;
+ while r < tb.rows.len() {
+ self.skip_bands();
+ let h = tb.rows[r].height;
+ let (y, top, placed_any) = self
+ .cur
+ .as_ref()
+ .map_or((0.0, 0.0, false), |c| (c.y, c.top, c.placed_any));
+ let avail = self.avail_bottom();
+ // Rows kept with the next one go to the next column together
+ // when they do not fit here but would there.
+ let chain: f32 = tb.rows[r..=keep_chain_end(&tb, r)]
+ .iter()
+ .map(|row| row.height)
+ .sum();
+ let keep = placed_any && !moved && chain > h && y + chain > avail + EPS;
+ let mut next = keep && chain <= avail - top;
+ if !next && y + h > avail + EPS {
+ if self.jump_band(h) {
+ continue;
+ }
+ // A row that may break keeps the lines that fit here and
+ // goes on in the next column.
+ let split = split_row(&tb, r, avail - y);
+ next = split.is_some() || (placed_any && !moved);
+ if let Some((first, rest)) = split {
+ Arc::make_mut(&mut tb).rows[r] = first;
+ self.emit_table_row(&tb, r, col_left);
+ Arc::make_mut(&mut tb).rows[r] = rest;
+ }
+ }
+ if next {
+ self.next_column(false);
+ moved = true;
+ // Rows go on in the new column; a floating table keeps its
+ // place across the page.
+ let (left, _) = self.col_geom();
+ if float.is_some() {
+ Arc::make_mut(&mut tb).geom.left += col_left - left;
+ }
+ col_left = left;
+ if let Some(pos) = &float {
+ self.float_down(pos, height, false);
+ }
+ // Repeat header rows at the top of the new page.
+ if r >= headers.len() && !headers.is_empty() {
+ for &hr in &headers {
+ self.emit_table_row(&tb, hr, col_left);
+ }
+ }
+ continue;
+ }
+ self.emit_table_row(&tb, r, col_left);
+ moved = false;
+ r += 1;
+ }
+ if let (Some(pos), Some(c)) = (&float, &mut self.cur) {
+ c.y += pos.bottom_from_text;
+ }
+ self.prev = None;
+ }
+
+ /// Moves down to where floating table rows start on this page: below
+ /// the anchoring text on the first page (`first`), at the same place on
+ /// the page after that for tables positioned on the page.
+ fn float_down(&mut self, pos: &TablePosition, height: f32, first: bool) {
+ let on_page = pos.v_anchor != "text";
+ if !first && !on_page {
+ return;
+ }
+ let g = self.page_geom();
+ if let Some(c) = &mut self.cur {
+ let top = float_y(pos, &g, c.y, height);
+ // On a page with nothing on it yet, a table placed on the page
+ // goes to its place even above the body (over a tall header).
+ c.y = if on_page && !c.placed_any {
+ top
+ } else {
+ c.y.max(top)
+ };
+ }
+ }
+
+ fn emit_table_row(&mut self, tb: &TableBox, r: usize, col_left: f32) {
+ let y = self.cur.as_ref().map_or(0.0, |c| c.y);
+ let mut items = Vec::new();
+ let mut anchors = Vec::new();
+ let mut notes: Vec<(bool, i64)> = Vec::new();
+ let sink = Sink {
+ items: &mut items,
+ anchors: &mut anchors,
+ notes: &mut notes,
+ };
+ emit_row(tb, r, col_left, y, sink);
+ let ids: Vec<i64> = notes
+ .iter()
+ .filter(|(e, _)| !e)
+ .map(|(_, id)| *id)
+ .collect();
+ self.add_notes(&ids);
+ let geom = self.page_geom();
+ let fields = self.fields();
+ let on_page = OnPage {
+ env: self.env,
+ fields: &fields,
+ geom: &geom,
+ };
+ if let Some(c) = &mut self.cur {
+ c.body.extend(items);
+ place_anchors(&on_page, &anchors, &mut c.behind, &mut c.front);
+ c.y += tb.rows[r].height;
+ c.placed_any = true;
+ c.hard = false;
+ }
+ }
+}
diff --git a/crates/docx_engine/src/layout/flow/frames.rs b/crates/docx_engine/src/layout/flow/frames.rs
new file mode 100644
index 0000000000..a2c28005c8
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/frames.rs
@@ -0,0 +1,227 @@
+//! Text frames (`w:framePr`): paragraphs taken out of the flow and placed
+//! at a position of their own, with the surrounding text flowing beside or
+//! below them.
+
+use super::super::Item;
+use super::super::format::ParaFormat;
+use super::Env;
+use super::anchors::PageGeom;
+use super::stack::{PendingAnchor, StackCtx, stack_blocks};
+use crate::model::block::{Block, BlockKind, Story};
+use crate::model::props::{FramePr, HeightRule};
+use pptx_engine::path::Rect;
+
+/// Width added to an automatic frame's content so it does not wrap again.
+const AUTO_WIDTH_SLACK: f32 = 0.5;
+
+/// How text flows around a frame.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum FrameWrap {
+ /// Text flows beside the frame where there is room.
+ Beside,
+ /// No text beside the frame: it takes its band of the page.
+ NotBeside,
+ /// Text ignores the frame.
+ None,
+}
+
+/// A frame laid out, waiting for its position.
+#[derive(Clone, Debug)]
+pub struct PendingFrame {
+ /// Content, relative to the frame's top-left corner.
+ pub items: Vec<Item>,
+ /// Floating drawings inside, relative to the frame's top-left corner.
+ pub anchors: Vec<PendingAnchor>,
+ /// Width.
+ pub width: f32,
+ /// Height.
+ pub height: f32,
+ /// Placement.
+ pub props: FramePr,
+ /// Top of the text the frame is anchored to (container coordinates).
+ pub para_top: f32,
+ /// Left of the text area the frame is anchored in (container coordinates).
+ pub text_left: f32,
+}
+
+impl PendingFrame {
+ /// How text flows around it.
+ pub fn wrap(&self) -> FrameWrap {
+ match self.props.wrap.as_deref() {
+ Some("notBeside") => FrameWrap::NotBeside,
+ Some("none") => FrameWrap::None,
+ _ => FrameWrap::Beside,
+ }
+ }
+
+ /// Whether it sits in the flow of its text rather than on the page.
+ pub fn follows_text(&self) -> bool {
+ self.props.y_align.as_deref() == Some("inline")
+ || (self.props.v_anchor.as_deref() == Some("text") && self.props.y_align.is_none())
+ }
+
+ /// Moves it by (dx, dy) along with its container.
+ pub fn offset(&mut self, dx: f32, dy: f32) {
+ self.para_top += dy;
+ self.text_left += dx;
+ }
+}
+
+/// The frame a paragraph format puts its paragraph in (drop caps aside).
+pub fn frame_of(format: &ParaFormat) -> Option<&FramePr> {
+ format.props.frame.as_ref().filter(|f| f.drop_cap.is_none())
+}
+
+/// Lays out the frame that starts at `blocks[i]`: it holds the following
+/// paragraphs with the same frame properties. Returns the frame and the
+/// index after its last block.
+pub(in crate::layout) fn frame_box(
+ env: &Env<'_>,
+ story: &Story,
+ blocks: &[&Block],
+ i: usize,
+ sc: &StackCtx,
+) -> Option<(PendingFrame, usize)> {
+ let fmt = env.formats.paragraph(&blocks[i].props, &sc.table);
+ let props = frame_of(&fmt)?.clone();
+ let mut j = i + 1;
+ while j < blocks.len()
+ && blocks[j].kind == BlockKind::Paragraph
+ && frame_of(&env.formats.paragraph(&blocks[j].props, &sc.table)) == Some(&props)
+ {
+ j += 1;
+ }
+ let content = &blocks[i..j];
+ let layout = |width: f32| {
+ let ctx = StackCtx {
+ story: sc.story.clone(),
+ width,
+ table: sc.table.clone(),
+ fields: sc.fields.clone(),
+ note_number: sc.note_number.clone(),
+ float_frames: false,
+ page: None,
+ };
+ stack_blocks(env, story, content, &ctx, false)
+ };
+ let (stack, width) = match props.w.filter(|w| *w > 1.0) {
+ Some(w) => (layout(w), w),
+ None => {
+ // An automatic width fits the content.
+ let full = layout(sc.width);
+ let used = content_width(&full.items).min(sc.width);
+ if used + AUTO_WIDTH_SLACK < sc.width {
+ let w = used + AUTO_WIDTH_SLACK;
+ (layout(w), w)
+ } else {
+ (full, sc.width)
+ }
+ }
+ };
+ let height = match (props.h, props.h_rule) {
+ (Some(h), Some(HeightRule::Exact)) if h > 0.0 => h,
+ (_, Some(HeightRule::Auto)) | (None, _) => stack.height,
+ (Some(h), _) => stack.height.max(h),
+ };
+ Some((
+ PendingFrame {
+ items: stack.items,
+ anchors: stack.anchors,
+ width,
+ height,
+ props,
+ para_top: 0.0,
+ text_left: 0.0,
+ },
+ j,
+ ))
+}
+
+/// The right edge of the widest line in `items`.
+fn content_width(items: &[Item]) -> f32 {
+ items
+ .iter()
+ .filter_map(|i| match i {
+ Item::Line(l) => {
+ let line = l.line();
+ Some(l.x + line.left + line.width)
+ }
+ _ => None,
+ })
+ .fold(0.0, f32::max)
+}
+
+/// Where a frame `width` wide goes across a page, `text_left` being the
+/// left edge of the text it is anchored in.
+fn frame_x(p: &FramePr, width: f32, text_left: f32, g: &PageGeom) -> f32 {
+ let (x0, span) = match p.h_anchor.as_deref() {
+ Some("margin") => (g.left, g.width - g.left - g.right),
+ Some("text") => (text_left, g.col_width),
+ _ => (0.0, g.width),
+ };
+ match p.x_align.as_deref() {
+ Some("center") => x0 + (span - width) / 2.0,
+ Some("right" | "outside") => x0 + span - width,
+ Some("left" | "inside") => x0,
+ _ => x0 + p.x.unwrap_or(0.0),
+ }
+}
+
+/// Whether frame `f` of a stack laid out in the column of `g` stands
+/// across that column's text: a frame wholly in a margin leaves it alone.
+pub fn across_text(f: &PendingFrame, g: &PageGeom) -> bool {
+ let x = frame_x(&f.props, f.width, g.col_left, g);
+ x < g.col_left + g.col_width && x + f.width > g.col_left
+}
+
+/// Where a frame goes on a page.
+pub fn resolve_frame(f: &PendingFrame, g: &PageGeom) -> Rect {
+ let p = &f.props;
+ let x = frame_x(p, f.width, f.text_left, g);
+ let y = if f.follows_text() {
+ f.para_top + p.y.unwrap_or(0.0)
+ } else {
+ let (y0, vspan) = match p.v_anchor.as_deref() {
+ Some("page") => (0.0, g.height),
+ Some("text") => (f.para_top, 0.0),
+ _ => (g.top, g.height - g.top - g.bottom),
+ };
+ match p.y_align.as_deref() {
+ Some("center") => y0 + (vspan - f.height) / 2.0,
+ Some("bottom" | "outside") => y0 + vspan - f.height,
+ Some("top" | "inside") => y0,
+ _ => y0 + p.y.unwrap_or(0.0),
+ }
+ };
+ Rect::from_xywh(x, y, f.width, f.height)
+}
+
+/// A frame placed in its container without page knowledge (table cells):
+/// beside its text, aligned within the container's width.
+pub fn place_in_container(f: &PendingFrame, width: f32) -> Rect {
+ let p = &f.props;
+ let x = match p.x_align.as_deref() {
+ Some("center") => (width - f.width) / 2.0,
+ Some("right" | "outside") => width - f.width,
+ Some("left" | "inside") => 0.0,
+ _ => 0.0,
+ };
+ Rect::from_xywh(f.text_left + x, f.para_top, f.width, f.height)
+}
+
+/// Emits a frame's content at `rect`, and its floating drawings.
+pub fn emit_frame(
+ f: &PendingFrame,
+ rect: Rect,
+ out: &mut Vec<Item>,
+ anchors: &mut Vec<PendingAnchor>,
+) {
+ let mut items = f.items.clone();
+ super::offset_items(&mut items, rect.x, rect.y);
+ out.extend(items);
+ for a in &f.anchors {
+ let mut a = a.clone();
+ a.shift(rect.x, rect.y);
+ anchors.push(a);
+ }
+}
diff --git a/crates/docx_engine/src/layout/flow/numbers.rs b/crates/docx_engine/src/layout/flow/numbers.rs
new file mode 100644
index 0000000000..2fd8590415
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/numbers.rs
@@ -0,0 +1,230 @@
+//! List labels and note numbers of the body. Both count through the whole
+//! document; between layouts they are counted again only when the list
+//! items or note references they come from changed.
+
+use super::super::format::{Formats, ParaFormat, TableCtx};
+use super::note_id;
+use crate::document::Document;
+use crate::hash::FxMap;
+use crate::model::block::{Block, BlockId, BlockKind};
+use crate::model::content::{OBJECT_CHAR, key};
+use crate::model::numbering::{Counters, Label, format_number};
+use crate::model::props::RunProps;
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+/// List labels of the body's numbered paragraphs, with their run
+/// properties.
+pub(in crate::layout) type Labels = FxMap<BlockId, (Label, RunProps)>;
+
+/// Displayed note numbers by (endnote, id), and the endnotes in the order
+/// of their references (the order the endnote section lists them in).
+#[derive(Debug, Default)]
+pub(in crate::layout) struct NoteNumbers {
+ numbers: HashMap<(bool, i64), String>,
+ pub endnotes: Vec<i64>,
+}
+
+impl std::ops::Deref for NoteNumbers {
+ type Target = HashMap<(bool, i64), String>;
+ fn deref(&self) -> &Self::Target {
+ &self.numbers
+ }
+}
+
+/// What numbering reads of one paragraph.
+#[derive(Debug)]
+struct Marks {
+ /// The list and level it is an item of, with its format (hidden
+ /// paragraphs are not counted).
+ item: Option<(i64, u8, Arc<ParaFormat>)>,
+ /// Its note references in order: (endnote, id).
+ refs: Vec<(bool, i64)>,
+}
+
+impl Marks {
+ fn of(block: &Block, formats: &Formats<'_>) -> Self {
+ let fmt = formats.paragraph(&block.props, &TableCtx::default());
+ let item = match fmt.props.num {
+ Some((num_id, ilvl)) if !fmt.mark.vanish => Some((num_id, ilvl, Arc::clone(&fmt))),
+ _ => None,
+ };
+ let mut refs = Vec::new();
+ for (_, span) in block.content.spans_at() {
+ let Some(obj) = span.attrs.get(key::OBJ) else {
+ continue;
+ };
+ for _ in span.text.chars().filter(|c| *c == OBJECT_CHAR) {
+ let endnote = obj.contains("endnoteReference");
+ if !(endnote || obj.contains("footnoteReference")) {
+ continue;
+ }
+ if let Some(id) = note_id(obj) {
+ refs.push((endnote, id));
+ }
+ }
+ }
+ Self { item, refs }
+ }
+}
+
+/// A list item: the paragraph, its list and level, and its format.
+type Item = (BlockId, i64, u8, Arc<ParaFormat>);
+
+/// The body's list items and note references, in document order.
+#[derive(Debug, Default)]
+struct Sequence {
+ items: Vec<Item>,
+ refs: Vec<(bool, i64)>,
+}
+
+impl Sequence {
+ fn add(&mut self, id: &BlockId, marks: &Marks) {
+ if let Some((num_id, ilvl, fmt)) = &marks.item {
+ self.items
+ .push((id.clone(), *num_id, *ilvl, Arc::clone(fmt)));
+ }
+ self.refs.extend_from_slice(&marks.refs);
+ }
+
+ /// Whether the list items are the same paragraphs, in the same lists
+ /// and formats, so they get the same labels.
+ fn same_items(&self, other: &Self) -> bool {
+ self.items.len() == other.items.len()
+ && self
+ .items
+ .iter()
+ .zip(&other.items)
+ .all(|(a, b)| a.0 == b.0 && a.1 == b.1 && a.2 == b.2 && Arc::ptr_eq(&a.3, &b.3))
+ }
+
+ fn labels(&self, formats: &Formats<'_>) -> Labels {
+ let mut counters = Counters::default();
+ let mut labels = Labels::default();
+ for (id, num_id, ilvl, fmt) in &self.items {
+ if let Some(label) = counters.next(formats.numbering, formats.styles, *num_id, *ilvl) {
+ let props = formats.label_props(fmt, &label);
+ labels.insert(id.clone(), (label, props));
+ }
+ }
+ labels
+ }
+
+ fn numbers(&self, doc: &Document) -> NoteNumbers {
+ let settings = &doc.parts().settings;
+ let mut footnote = settings.footnotes.start;
+ let mut endnote = settings.endnotes.start;
+ let mut numbers = NoteNumbers::default();
+ for &(is_endnote, id) in &self.refs {
+ if numbers.contains_key(&(is_endnote, id)) {
+ continue;
+ }
+ let (fmt, n) = if is_endnote {
+ endnote += 1;
+ numbers.endnotes.push(id);
+ (&settings.endnotes.fmt, endnote - 1)
+ } else {
+ footnote += 1;
+ (&settings.footnotes.fmt, footnote - 1)
+ };
+ numbers
+ .numbers
+ .insert((is_endnote, id), format_number(n, fmt));
+ }
+ numbers
+ }
+}
+
+/// What the last count read and found.
+#[derive(Debug)]
+struct Kept {
+ generation: u64,
+ /// The body revision counted.
+ revision: u64,
+ /// Per paragraph: the version read, its marks, and the last count
+ /// that met it.
+ paras: FxMap<BlockId, (u64, Marks, u64)>,
+ count: u64,
+ sequence: Sequence,
+ labels: Arc<Labels>,
+ numbers: Arc<NoteNumbers>,
+}
+
+/// Labels and note numbers kept between layouts.
+#[derive(Debug, Default)]
+pub(in crate::layout) struct NumbersCache(Mutex<Option<Kept>>);
+
+/// Numbers notes in order of reference and computes list labels, reusing
+/// what `cache` kept from the last layout when the list items and note
+/// references are the same.
+pub(in crate::layout) fn count(
+ doc: &Document,
+ formats: &Formats<'_>,
+ cache: Option<&NumbersCache>,
+) -> (Arc<Labels>, Arc<NoteNumbers>) {
+ let Some(cache) = cache else {
+ let mut seq = Sequence::default();
+ doc.body.walk(|b, _| {
+ if b.kind == BlockKind::Paragraph {
+ seq.add(&b.id, &Marks::of(b, formats));
+ }
+ });
+ return (Arc::new(seq.labels(formats)), Arc::new(seq.numbers(doc)));
+ };
+ let mut guard = cache.0.lock().unwrap_or_else(|e| e.into_inner());
+ let kept = guard.take().filter(|k| k.generation == doc.generation);
+ if let Some(k) = &kept
+ && k.revision == doc.body.revision()
+ {
+ let out = (Arc::clone(&k.labels), Arc::clone(&k.numbers));
+ *guard = kept;
+ return out;
+ }
+ let mut kept = kept.unwrap_or_else(|| Kept {
+ generation: doc.generation,
+ revision: 0,
+ paras: FxMap::default(),
+ count: 0,
+ sequence: Sequence::default(),
+ labels: Arc::default(),
+ numbers: Arc::default(),
+ });
+ let fresh = kept.count == 0;
+ kept.count += 1;
+ let count = kept.count;
+ let paras = &mut kept.paras;
+ let mut seq = Sequence::default();
+ let mut walked = 0;
+ doc.body.walk(|b, _| {
+ if b.kind != BlockKind::Paragraph {
+ return;
+ }
+ walked += 1;
+ match paras.get_mut(&b.id) {
+ Some(entry) if entry.0 == b.version => {
+ entry.2 = count;
+ seq.add(&b.id, &entry.1);
+ }
+ _ => {
+ let marks = Marks::of(b, formats);
+ seq.add(&b.id, &marks);
+ paras.insert(b.id.clone(), (b.version, marks, count));
+ }
+ }
+ });
+ // Paragraphs gone from the body linger until there are many of them.
+ if paras.len() > 2 * walked + 64 {
+ paras.retain(|_, p| p.2 == count);
+ }
+ if fresh || !seq.same_items(&kept.sequence) {
+ kept.labels = Arc::new(seq.labels(formats));
+ }
+ if fresh || seq.refs != kept.sequence.refs {
+ kept.numbers = Arc::new(seq.numbers(doc));
+ }
+ kept.sequence = seq;
+ kept.revision = doc.body.revision();
+ let out = (Arc::clone(&kept.labels), Arc::clone(&kept.numbers));
+ *guard = Some(kept);
+ out
+}
diff --git a/crates/docx_engine/src/layout/flow/split.rs b/crates/docx_engine/src/layout/flow/split.rs
new file mode 100644
index 0000000000..c764890ffb
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/split.rs
@@ -0,0 +1,232 @@
+//! Splitting table rows across pages: each cell's content breaks between
+//! its lines, the rest continuing in the same row on the next page.
+
+use super::super::{Item, PlacedLine};
+use super::stack::{RowBox, Stack, TableBox};
+use crate::model::props::HeightRule;
+use pptx_engine::path::Rect;
+
+const EPS: f32 = 0.01;
+
+/// Lines of a stack as (top, bottom).
+fn line_spans(stack: &Stack) -> Vec<(f32, f32)> {
+ stack
+ .items
+ .iter()
+ .filter_map(|i| match i {
+ Item::Line(l) => Some((l.y, l.y + l.line().height)),
+ _ => None,
+ })
+ .collect()
+}
+
+/// Whether content may break after this line: not where widow and orphan
+/// control would leave a single line of its paragraph on either side.
+fn breaks_after(l: &PlacedLine) -> bool {
+ let n = l.para.lines.lines.len();
+ let before = l.line + 1;
+ before >= n || !l.para.format.props.widow_control || (before >= 2 && n - before >= 2)
+}
+
+/// The lowest line bottom at or above `limit` that no line crosses and
+/// that splits no paragraph against its widow control (0 when there is
+/// none).
+pub fn line_cut(stack: &Stack, limit: f32) -> f32 {
+ let lines = line_spans(stack);
+ stack
+ .items
+ .iter()
+ .filter_map(|i| match i {
+ Item::Line(l) if breaks_after(l) => Some(l.y + l.line().height),
+ _ => None,
+ })
+ .filter(|&cut| {
+ cut <= limit + EPS && !lines.iter().any(|&(t, b)| t < cut - EPS && b > cut + EPS)
+ })
+ .fold(0.0, f32::max)
+}
+
+/// Splits a stack at `cut` (a line boundary): what is above it, and what is
+/// below it moved up so its first line starts at the top.
+pub fn split_stack(stack: &Stack, cut: f32) -> (Stack, Stack) {
+ let shift = line_spans(stack)
+ .iter()
+ .map(|&(top, _)| top)
+ .filter(|&top| top >= cut - EPS)
+ .fold(f32::MAX, f32::min);
+ let shift = if shift == f32::MAX { cut } else { shift };
+ let mut a = Stack {
+ height: cut,
+ notes: stack.notes.clone(),
+ ..Stack::default()
+ };
+ let mut b = Stack {
+ height: (stack.height - shift).max(0.0),
+ ..Stack::default()
+ };
+ for item in &stack.items {
+ match item {
+ Item::Line(l) => {
+ if l.y < cut - EPS {
+ a.items.push(item.clone());
+ } else {
+ let mut l = l.clone();
+ l.y -= shift;
+ b.items.push(Item::Line(l));
+ }
+ }
+ Item::Fill { rect, color } => {
+ let (top, bottom) = (rect.y, rect.y + rect.h);
+ if top < cut - EPS {
+ a.items.push(Item::Fill {
+ rect: Rect::from_xywh(rect.x, top, rect.w, bottom.min(cut) - top),
+ color: *color,
+ });
+ }
+ if bottom > cut + EPS {
+ let from = top.max(shift);
+ if bottom > from {
+ b.items.push(Item::Fill {
+ rect: Rect::from_xywh(rect.x, from - shift, rect.w, bottom - from),
+ color: *color,
+ });
+ }
+ }
+ }
+ Item::Rule {
+ x0,
+ y0,
+ x1,
+ y1,
+ border,
+ } => {
+ let (top, bottom) = (y0.min(*y1), y0.max(*y1));
+ if bottom <= cut + EPS {
+ a.items.push(item.clone());
+ } else if top >= cut - EPS {
+ b.items.push(Item::Rule {
+ x0: *x0,
+ y0: y0 - shift,
+ x1: *x1,
+ y1: y1 - shift,
+ border: *border,
+ });
+ } else if (x0 - x1).abs() < EPS {
+ // A vertical rule continues on both sides of the cut.
+ a.items.push(Item::Rule {
+ x0: *x0,
+ y0: top,
+ x1: *x1,
+ y1: cut,
+ border: *border,
+ });
+ b.items.push(Item::Rule {
+ x0: *x0,
+ y0: 0.0,
+ x1: *x1,
+ y1: (bottom - shift).max(0.0),
+ border: *border,
+ });
+ } else {
+ a.items.push(item.clone());
+ }
+ }
+ Item::Drawing(d) => {
+ if d.rect.y < cut - EPS {
+ a.items.push(item.clone());
+ } else {
+ let mut d = d.clone();
+ d.rect.y -= shift;
+ b.items.push(Item::Drawing(d));
+ }
+ }
+ Item::LineNumber { baseline, .. } => {
+ if *baseline < cut {
+ a.items.push(item.clone());
+ }
+ }
+ }
+ }
+ for anchor in &stack.anchors {
+ if anchor.para_top < cut - EPS {
+ a.anchors.push(anchor.clone());
+ } else {
+ let mut anchor = anchor.clone();
+ anchor.shift(0.0, -shift);
+ b.anchors.push(anchor);
+ }
+ }
+ (a, b)
+}
+
+/// Splits row `r` so its first part fits in `room` points: every cell keeps
+/// the lines that fit and continues below them. `None` when the row may
+/// not break (cannot split, exact height, merged cells) or nothing of its
+/// overflowing cells fits.
+pub fn split_row(tb: &TableBox, r: usize, room: f32) -> Option<(RowBox, RowBox)> {
+ let row = &tb.rows[r];
+ let exact = matches!(
+ tb.geom.rows.get(r).and_then(|g| g.tr.height),
+ Some((_, HeightRule::Exact))
+ );
+ // Repeated header rows never break either.
+ if row.cant_split || row.header || exact || row.cells.iter().any(|c| c.rows != 1) {
+ return None;
+ }
+ let mut first = row.clone();
+ let mut rest = row.clone();
+ rest.header = false;
+ let (mut h1, mut h2) = (0.0f32, 0.0f32);
+ let mut fits_some = false;
+ let mut continues = false;
+ for (k, cell) in row.cells.iter().enumerate() {
+ let m = &cell.geom.margins;
+ let limit = room - m[0] - m[2] - row.border_top;
+ let content = &cell.content;
+ let (a, b) = if content.height <= limit + EPS {
+ (content.clone(), Stack::default())
+ } else {
+ let cut = line_cut(content, limit);
+ fits_some |= cut > EPS;
+ continues = true;
+ split_stack(content, cut)
+ };
+ h1 = h1.max(a.height + m[0] + m[2]);
+ h2 = h2.max(b.height + m[0] + m[2]);
+ first.cells[k].content = a;
+ rest.cells[k].content = b;
+ }
+ if !fits_some || !continues {
+ return None;
+ }
+ // Like a paragraph under widow control, a row leaves no single line
+ // behind or alone at the top of the next page.
+ let lines = |row: &RowBox| {
+ row.cells
+ .iter()
+ .map(|c| {
+ c.content
+ .items
+ .iter()
+ .filter(|i| matches!(i, Item::Line(_)))
+ .count()
+ })
+ .max()
+ .unwrap_or(0)
+ };
+ let widow_control = row.cells.iter().any(|c| {
+ c.content
+ .items
+ .iter()
+ .any(|i| matches!(i, Item::Line(l) if l.para.format.props.widow_control))
+ });
+ if widow_control && (lines(&first) < 2 || lines(&rest) < 2) {
+ return None;
+ }
+ // The first part ends at the page; the rest makes room for its top
+ // border again, and keeps the bottom one.
+ first.height = (h1 + row.border_top).min(room);
+ first.border_bottom = 0.0;
+ rest.height = h2 + row.border_top + row.border_bottom;
+ Some((first, rest))
+}
diff --git a/crates/docx_engine/src/layout/flow/stack.rs b/crates/docx_engine/src/layout/flow/stack.rs
new file mode 100644
index 0000000000..f086bfc87e
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/stack.rs
@@ -0,0 +1,984 @@
+//! Laying blocks out one after another without page breaks: table cells,
+//! headers, footers, notes and text boxes.
+
+mod cache;
+
+use super::super::format::{ParaFormat, TableCtx};
+use super::super::inline::{self, FieldValues, InlineCtx, Kind};
+use super::super::lines::{LineCtx, break_lines, break_lines_from};
+use super::super::table::{CellGeom, TableGeom, geometry};
+use super::super::{Item, ParaBox, PlacedDrawing, PlacedLine, StoryRef};
+use super::Env;
+use super::anchors::PageGeom;
+use super::frames::{
+ FrameWrap, PendingFrame, across_text, emit_frame, frame_box, place_in_container,
+};
+use crate::model::block::{Block, BlockId, BlockKind, Story};
+use crate::model::props::{Border, HeightRule, ParaBorders, ParaProps, VMerge};
+use pptx_engine::path::Rect;
+use std::sync::Arc;
+
+pub(in crate::layout) use cache::TableCache;
+
+/// A floating drawing whose position depends on the page it lands on.
+#[derive(Clone, Debug)]
+pub struct PendingAnchor {
+ /// The drawing.
+ pub drawing: Arc<super::super::drawing::Drawing>,
+ /// The anchoring paragraph's top (stack coordinates).
+ pub para_top: f32,
+ /// The anchoring line's top.
+ pub line_top: f32,
+ /// X of the anchor character from the text area left.
+ pub char_x: f32,
+ /// Story of the anchoring paragraph.
+ pub story: StoryRef,
+ /// The anchoring paragraph.
+ pub block: BlockId,
+ /// The drawing's index among the paragraph's objects.
+ pub object: u16,
+ /// The text area of the table cell the drawing is positioned in, when
+ /// it is: left edge (as `char_x`) and width.
+ pub cell: Option<(f32, f32)>,
+}
+
+impl PendingAnchor {
+ /// Moves it along with its container.
+ pub fn shift(&mut self, dx: f32, dy: f32) {
+ self.para_top += dy;
+ self.line_top += dy;
+ self.char_x += dx;
+ if let Some((x, _)) = &mut self.cell {
+ *x += dx;
+ }
+ }
+}
+
+/// Blocks laid out top to bottom.
+#[derive(Clone, Debug, Default)]
+pub struct Stack {
+ /// Items, relative to the stack's top-left (the text area's left edge).
+ pub items: Vec<Item>,
+ /// Floating drawings to place once the page is known.
+ pub anchors: Vec<PendingAnchor>,
+ /// Height.
+ pub height: f32,
+ /// Notes referenced inside.
+ pub notes: Vec<(bool, i64)>,
+ /// Text frames to place once the page is known.
+ pub frames: Vec<PendingFrame>,
+}
+
+/// What a stack is laid out in.
+pub struct StackCtx {
+ /// The story.
+ pub story: StoryRef,
+ /// Text area width.
+ pub width: f32,
+ /// Table formatting context of the paragraphs.
+ pub table: TableCtx,
+ /// Page-dependent field values.
+ pub fields: FieldValues,
+ /// The note being laid out, for its own number.
+ pub note_number: Option<String>,
+ /// Leave text frames for the page to place (headers and footers);
+ /// otherwise they are placed inside the stack.
+ pub float_frames: bool,
+ /// The page the stack goes on, with the stack's text area as its
+ /// column, when known while laying it out.
+ pub page: Option<PageGeom>,
+}
+
+/// The previous paragraph, for spacing between paragraphs.
+#[derive(Clone, Debug, Default)]
+pub struct PrevPara {
+ /// Its style.
+ pub style: Option<String>,
+ /// Its space after.
+ pub after: f32,
+ /// It uses contextual spacing.
+ pub contextual: bool,
+ /// Its space after is automatic.
+ pub auto_after: bool,
+ /// The list (numbering instance) it is an item of.
+ pub list: Option<i64>,
+ /// Its borders and indents, for border groups.
+ pub border: BorderBox,
+}
+
+/// What decides whether consecutive paragraphs share one border box.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct BorderBox {
+ /// Borders.
+ pub borders: ParaBorders,
+ /// Left and right indents.
+ pub indents: (f32, f32),
+}
+
+impl BorderBox {
+ /// A paragraph's border frame.
+ pub fn of(props: &ParaProps) -> Self {
+ Self {
+ borders: props.borders,
+ indents: (props.ind_left, props.ind_right),
+ }
+ }
+}
+
+/// How a paragraph joins the border box of its neighbours: Word draws
+/// consecutive paragraphs with the same borders as one box, with the
+/// `between` border (if any) instead of a bottom and top border inside it.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct BorderJoin {
+ /// The previous paragraph is in the same box.
+ pub prev: bool,
+ /// The next paragraph is in the same box.
+ pub next: bool,
+}
+
+impl BorderJoin {
+ /// The join of a paragraph between `prev` and `next` (their formats).
+ pub fn new(props: &ParaProps, prev: Option<&BorderBox>, next: Option<&ParaProps>) -> Self {
+ let own = BorderBox::of(props);
+ let shares = |o: &BorderBox| own.borders.any() && *o == own;
+ Self {
+ prev: prev.is_some_and(shares),
+ next: next.is_some_and(|n| shares(&BorderBox::of(n))),
+ }
+ }
+}
+
+/// Space before a paragraph (points), given the one before it. Word 2007
+/// and later separate paragraphs by the larger of the first's space after
+/// and the second's space before; with `doNotUseHTMLParagraphAutoSpacing`
+/// (`sum`) they add up, as in Word 2003.
+pub fn space_before(
+ props: &ParaProps,
+ prev: Option<&PrevPara>,
+ first_in_container: bool,
+ sum: bool,
+) -> f32 {
+ let mut before = if props.before_auto {
+ if first_in_container { 0.0 } else { 14.0 }
+ } else {
+ match props.before_lines {
+ Some(l) if l > 0.0 => l * 12.0,
+ _ => props.before,
+ }
+ };
+ let Some(prev) = prev else {
+ return before.max(0.0);
+ };
+ let same_style = prev.style == props.style;
+ if props.contextual_spacing && same_style {
+ before = 0.0;
+ }
+ let mut after = prev.after;
+ if prev.contextual && same_style {
+ after = 0.0;
+ }
+ let list = props.num.map(|(id, _)| id);
+ if props.before_auto && prev.auto_after && list.is_some() && prev.list == list {
+ // HTML-style auto spacing leaves none between the items of a list
+ // (but keeps it between two lists).
+ return 0.0;
+ }
+ if sum {
+ (after + before).max(0.0)
+ } else {
+ after.max(before).max(0.0)
+ }
+}
+
+/// Space after a paragraph (points).
+pub fn space_after(props: &ParaProps) -> f32 {
+ if props.after_auto {
+ 14.0
+ } else {
+ match props.after_lines {
+ Some(l) if l > 0.0 => l * 12.0,
+ _ => props.after,
+ }
+ .max(0.0)
+ }
+}
+
+/// The record a paragraph leaves for the next one's spacing.
+pub fn prev_record(props: &ParaProps) -> PrevPara {
+ PrevPara {
+ style: props.style.clone(),
+ after: space_after(props),
+ contextual: props.contextual_spacing,
+ auto_after: props.after_auto,
+ list: props.num.map(|(id, _)| id),
+ border: BorderBox::of(props),
+ }
+}
+
+/// How lines of a paragraph formatted `props` break in a text area `width`
+/// wide.
+fn line_ctx<'a>(
+ env: &Env<'_>,
+ props: &'a ParaProps,
+ width: f32,
+ grid: Option<f32>,
+ origin: Option<f32>,
+) -> LineCtx<'a> {
+ let settings = &env.doc.parts().settings;
+ LineCtx {
+ props,
+ width,
+ default_tab: settings.default_tab,
+ no_expand_shift_return: settings.do_not_expand_shift_return,
+ grid: grid.filter(|_| props.snap_to_grid),
+ shrink_spaces: settings.compat_mode >= 15,
+ mark_with_page_break: !settings.split_page_break_and_mark,
+ origin,
+ }
+}
+
+/// The rest of a laid-out paragraph, from cluster `from` on, broken again
+/// for a text area `width` wide: a paragraph going on in a column of
+/// another width.
+pub(in crate::layout) fn rebreak(
+ env: &Env<'_>,
+ pb: &ParaBox,
+ (width, origin): (f32, Option<f32>),
+ from: usize,
+ grid: Option<f32>,
+) -> Arc<ParaBox> {
+ let ctx = line_ctx(env, &pb.format.props, width, grid, origin);
+ Arc::new(ParaBox {
+ story: pb.story.clone(),
+ block: pb.block.clone(),
+ inline: pb.inline.clone(),
+ lines: break_lines_from(&pb.inline, &ctx, None, from),
+ format: Arc::clone(&pb.format),
+ })
+}
+
+/// What a paragraph is laid out for.
+#[derive(Clone, Copy)]
+pub(in crate::layout) struct ParaCtx<'c> {
+ /// The story it is in.
+ pub story: &'c StoryRef,
+ /// The width its lines fill.
+ pub width: f32,
+ /// The table it is in.
+ pub table: &'c TableCtx,
+ /// The values of the page fields it shows.
+ pub fields: &'c FieldValues,
+ /// The number of the note it is in.
+ pub note_number: Option<&'c str>,
+ /// The line pitch of the document grid its lines snap to.
+ pub grid: Option<f32>,
+ /// The page x of the left edge of the text area, when known.
+ pub origin: Option<f32>,
+}
+
+/// Lays out one paragraph into a box.
+pub(in crate::layout) fn para_box(env: &Env<'_>, block: &Block, cx: &ParaCtx<'_>) -> Arc<ParaBox> {
+ let ParaCtx {
+ story,
+ width,
+ table,
+ fields,
+ note_number,
+ grid,
+ origin,
+ } = *cx;
+ // Body labels are numbered across the document; other stories (whose
+ // block ids may repeat the body's) number their paragraphs themselves.
+ let own_label = (*story != StoryRef::Body)
+ .then(|| env.story_label(block, table))
+ .flatten();
+ let label = if *story == StoryRef::Body {
+ env.labels.get(&block.id).map(|(l, p)| (l, p))
+ } else {
+ own_label.as_ref().map(|(l, p)| (l, p))
+ };
+ let key = env.cache.map(|_| {
+ use std::hash::{Hash, Hasher};
+ let mut h = std::collections::hash_map::DefaultHasher::new();
+ table.hash(&mut h);
+ crate::layout::ParaKey {
+ version: block.version,
+ generation: env.doc.generation,
+ width: width.to_bits(),
+ table: h.finish(),
+ label: label.map(|(l, _)| (l.text.clone(), format!("{:?}{:?}", l.suffix, l.jc))),
+ grid: grid.map_or(0, f32::to_bits),
+ origin: origin.map_or(u32::MAX, f32::to_bits),
+ markup: env.options.markup,
+ note_number: note_number.map(str::to_owned),
+ }
+ });
+ if let (Some(cache), Some(key)) = (env.cache, key.as_ref())
+ && let Some(pb) = cache.get(story, &block.id, key)
+ && pb.inline.notes_current(&env.note_numbers)
+ {
+ return pb;
+ }
+ // Paragraphs with page fields are kept by the values they show.
+ let field_values = {
+ use std::hash::{Hash, Hasher};
+ let mut h = std::collections::hash_map::DefaultHasher::new();
+ (fields.page, fields.pages, fields.section_pages).hash(&mut h);
+ format!("{:?}", fields.page_fmt).hash(&mut h);
+ h.finish()
+ };
+ if let (Some(cache), Some(key)) = (env.cache, key.as_ref())
+ && let Some(pb) = cache.get_dynamic(story, &block.id, field_values, key)
+ && pb.inline.notes_current(&env.note_numbers)
+ {
+ return pb;
+ }
+ let format: Arc<ParaFormat> = env.formats.paragraph(&block.props, table);
+ let ctx = InlineCtx {
+ formats: &env.formats,
+ fonts: &env.fonts,
+ fields,
+ note_numbers: &env.note_numbers,
+ note_number,
+ markup: env.options.markup,
+ };
+ let built = inline::build(block, &format, label, &ctx);
+ let lines = break_lines(
+ &built,
+ &line_ctx(env, &format.props, width, grid, origin),
+ None,
+ );
+ let pb = Arc::new(ParaBox {
+ story: story.clone(),
+ block: block.id.clone(),
+ inline: built,
+ lines,
+ format,
+ });
+ // Page fields change with what comes before (note numbers are checked
+ // when the box is taken from the cache).
+ if let (Some(cache), Some(key)) = (env.cache, key) {
+ if pb.inline.dynamic {
+ cache.put_dynamic(story, &block.id, field_values, key, Arc::clone(&pb));
+ } else {
+ cache.put(story, &block.id, key, Arc::clone(&pb));
+ }
+ }
+ pb
+}
+
+/// Border spacing a paragraph adds above and below its lines.
+pub fn border_space(props: &ParaProps, join: BorderJoin) -> (f32, f32) {
+ let space =
+ |b: Option<crate::model::props::Border>| b.map_or(0.0, |b| b.space + b.total_width());
+ let top = if join.prev {
+ space(props.borders.between)
+ } else {
+ space(props.borders.top)
+ };
+ let bottom = if join.next {
+ 0.0
+ } else {
+ space(props.borders.bottom)
+ };
+ (top, bottom)
+}
+
+/// A piece of a paragraph on one page or in one column.
+#[derive(Clone, Copy, Debug)]
+pub struct Fragment {
+ /// The left edge of the column it is in.
+ pub x: f32,
+ /// The column's width.
+ pub width: f32,
+ /// Where it starts.
+ pub top: f32,
+ /// Where it ends.
+ pub bottom: f32,
+ /// Whether it holds the paragraph's first line.
+ pub first: bool,
+ /// Whether it holds the paragraph's last line.
+ pub last: bool,
+}
+
+/// Shading and borders around a paragraph fragment.
+pub fn decorate(props: &ParaProps, frag: Fragment, join: BorderJoin, out: &mut Vec<Item>) {
+ let Fragment {
+ x,
+ width,
+ top,
+ bottom,
+ first,
+ last,
+ } = frag;
+ let left = x + props
+ .ind_left
+ .min(props.ind_left + props.ind_first.min(0.0));
+ let right = x + width - props.ind_right;
+ let pad_l = props
+ .borders
+ .left
+ .map_or(0.0, |b| b.space + b.total_width());
+ let pad_r = props
+ .borders
+ .right
+ .map_or(0.0, |b| b.space + b.total_width());
+ if let Some(color) = props.shading {
+ out.push(Item::Fill {
+ rect: Rect::from_xywh(
+ left - pad_l,
+ top,
+ (right + pad_r) - (left - pad_l),
+ bottom - top,
+ ),
+ color,
+ });
+ }
+ let b = &props.borders;
+ let top_border = if join.prev { b.between } else { b.top };
+ if first && let Some(t) = top_border {
+ out.push(Item::Rule {
+ x0: left - pad_l,
+ y0: top + t.total_width() / 2.0,
+ x1: right + pad_r,
+ y1: top + t.total_width() / 2.0,
+ border: t,
+ });
+ }
+ if last
+ && !join.next
+ && let Some(bt) = b.bottom
+ {
+ out.push(Item::Rule {
+ x0: left - pad_l,
+ y0: bottom - bt.total_width() / 2.0,
+ x1: right + pad_r,
+ y1: bottom - bt.total_width() / 2.0,
+ border: bt,
+ });
+ }
+ if let Some(l) = b.left {
+ out.push(Item::Rule {
+ x0: left - l.space - l.total_width() / 2.0,
+ y0: top,
+ x1: left - l.space - l.total_width() / 2.0,
+ y1: bottom,
+ border: l,
+ });
+ }
+ if let Some(r) = b.right {
+ out.push(Item::Rule {
+ x0: right + r.space + r.total_width() / 2.0,
+ y0: top,
+ x1: right + r.space + r.total_width() / 2.0,
+ y1: bottom,
+ border: r,
+ });
+ }
+}
+
+/// Where laid out lines and rows go: their items, the floating drawings
+/// still to be positioned, and the note references (endnote?, id).
+pub(super) struct Sink<'o> {
+ pub items: &'o mut Vec<Item>,
+ pub anchors: &'o mut Vec<PendingAnchor>,
+ pub notes: &'o mut Vec<(bool, i64)>,
+}
+
+impl Stack {
+ /// The stack's items, anchors and notes, to add to.
+ pub(super) fn sink(&mut self) -> Sink<'_> {
+ Sink {
+ items: &mut self.items,
+ anchors: &mut self.anchors,
+ notes: &mut self.notes,
+ }
+ }
+}
+
+/// Emits a paragraph's lines `first..last` at (x, y), with the paragraph's
+/// floating drawings positioned from `para_top`; returns the height used.
+pub(super) fn emit_lines(
+ pb: &Arc<ParaBox>,
+ (first, last): (usize, usize),
+ (x, y): (f32, f32),
+ para_top: f32,
+ out: Sink<'_>,
+) -> f32 {
+ let Sink {
+ items: out,
+ anchors,
+ notes,
+ } = out;
+ let lines = &pb.lines.lines;
+ let base = lines.get(first).map_or(0.0, |l| l.top);
+ for (i, line) in lines.iter().enumerate().take(last).skip(first) {
+ let top = y + line.top - base;
+ out.push(Item::Line(PlacedLine {
+ para: Arc::clone(pb),
+ line: i,
+ x,
+ y: top,
+ clip: None,
+ }));
+ for c in line.start..line.end {
+ let cl = &pb.inline.clusters[c];
+ if let Kind::Anchor(o) = cl.kind {
+ anchors.push(PendingAnchor {
+ drawing: Arc::new(pb.inline.objects[o as usize].clone()),
+ para_top,
+ line_top: top,
+ char_x: x + pb.lines.x[c],
+ story: pb.story.clone(),
+ block: pb.block.clone(),
+ object: o,
+ cell: None,
+ });
+ }
+ }
+ for &(at, endnote, id) in &pb.inline.notes {
+ if at >= line.start && at < line.end && !endnote {
+ notes.push((endnote, id));
+ }
+ }
+ }
+ lines
+ .get(first..last)
+ .map_or(0.0, |ls| ls.iter().map(|l| l.height).sum())
+}
+
+/// Lays out the children of `parent` in `story`.
+pub(in crate::layout) fn stack_story(
+ env: &Env<'_>,
+ story: &Story,
+ parent: Option<&BlockId>,
+ sc: &StackCtx,
+) -> Stack {
+ let mut blocks: Vec<&Block> = Vec::new();
+ super::flow_blocks(story, parent, &mut blocks);
+ stack_blocks(env, story, &blocks, sc, true)
+}
+
+/// Lays out `blocks` of `story` top to bottom; with `frames`, paragraphs
+/// in text frames are taken out of the flow.
+pub(in crate::layout) fn stack_blocks(
+ env: &Env<'_>,
+ story: &Story,
+ blocks: &[&Block],
+ sc: &StackCtx,
+ frames: bool,
+) -> Stack {
+ let mut out = Stack::default();
+ let mut y = 0.0f32;
+ let mut prev: Option<PrevPara> = None;
+ let mut skip_to = 0;
+ for (i, b) in blocks.iter().enumerate() {
+ if i < skip_to {
+ continue;
+ }
+ if frames
+ && b.kind == BlockKind::Paragraph
+ && let Some((mut f, end)) = frame_box(env, story, blocks, i, sc)
+ {
+ skip_to = end;
+ f.para_top = y;
+ // Text continues below a frame anchored to it that allows
+ // nothing beside it, unless the frame is in a margin.
+ let band = if f.wrap() == FrameWrap::NotBeside
+ && f.follows_text()
+ && sc.page.as_ref().is_none_or(|g| across_text(&f, g))
+ {
+ f.height
+ } else {
+ 0.0
+ };
+ if sc.float_frames {
+ out.frames.push(f);
+ } else {
+ let rect = place_in_container(&f, sc.width);
+ emit_frame(&f, rect, &mut out.items, &mut out.anchors);
+ }
+ y += band;
+ continue;
+ }
+ match b.kind {
+ BlockKind::Paragraph => {
+ let pb = para_box(
+ env,
+ b,
+ &ParaCtx {
+ story: &sc.story,
+ width: sc.width,
+ table: &sc.table,
+ fields: &sc.fields,
+ note_number: sc.note_number.as_deref(),
+ grid: None,
+ origin: None,
+ },
+ );
+ let props = &pb.format.props;
+ let gap_top = y;
+ let sum = !env.doc.parts().settings.html_auto_spacing;
+ let before = space_before(props, prev.as_ref(), i == 0, sum);
+ y += before;
+ // Floating drawings are positioned from the paragraph's top,
+ // above its own space before.
+ let para_top = y - before.min(space_before(props, None, i == 0, sum));
+ let next = blocks
+ .get(i + 1)
+ .filter(|n| n.kind == BlockKind::Paragraph)
+ .map(|n| env.formats.paragraph(&n.props, &sc.table));
+ let join = BorderJoin::new(
+ props,
+ prev.as_ref().map(|p| &p.border),
+ next.as_ref().map(|f| &f.props),
+ );
+ let (bt, bb) = border_space(props, join);
+ // A box shared with the previous paragraph spans the gap too.
+ let top = if join.prev { gap_top } else { y };
+ y += bt;
+ let n = pb.lines.lines.len();
+ let h = emit_lines(&pb, (0, n), (0.0, y), para_top, out.sink());
+ y += h + bb;
+ if props.shading.is_some() || props.borders.any() {
+ let mut deco = Vec::new();
+ let frag = Fragment {
+ x: 0.0,
+ width: sc.width,
+ top,
+ bottom: y,
+ first: true,
+ last: true,
+ };
+ decorate(props, frag, join, &mut deco);
+ // Decorations go under the text.
+ let at = out.items.len() - n;
+ out.items.splice(at..at, deco);
+ }
+ prev = Some(prev_record(props));
+ }
+ BlockKind::Table => {
+ // A table ends the run of paragraphs for spacing purposes.
+ if let Some(p) = prev.take() {
+ y += p.after;
+ }
+ let tb = table_box(env, story, b, sc.width, &sc.story, &sc.fields);
+ let mut ty = y;
+ for r in 0..tb.rows.len() {
+ emit_row(&tb, r, 0.0, ty, out.sink());
+ ty += tb.rows[r].height;
+ }
+ y = ty;
+ }
+ _ => {}
+ }
+ }
+ if let Some(p) = prev {
+ y += p.after;
+ }
+ out.height = y;
+ out
+}
+
+/// A cell laid out.
+#[derive(Clone, Debug)]
+pub struct CellBox {
+ /// Geometry and formatting.
+ pub geom: CellGeom,
+ /// X from the table's left edge.
+ pub x: f32,
+ /// Width.
+ pub width: f32,
+ /// Content (relative to the content area).
+ pub content: Stack,
+ /// Rows the cell spans (vertical merge); 0 for a merged continuation.
+ pub rows: usize,
+}
+
+/// A row laid out.
+#[derive(Clone, Debug)]
+pub struct RowBox {
+ /// Height.
+ pub height: f32,
+ /// Cells.
+ pub cells: Vec<CellBox>,
+ /// Keep the row on one page.
+ pub cant_split: bool,
+ /// Repeat on each page.
+ pub header: bool,
+ /// Width of the border line along the row's top: the row makes room
+ /// for it above its cells' content.
+ pub border_top: f32,
+ /// Width of the border line along the row's bottom when the row makes
+ /// room for it too (the last row of the table).
+ pub border_bottom: f32,
+}
+
+/// A table laid out (rows not yet placed).
+#[derive(Clone, Debug)]
+pub struct TableBox {
+ /// Geometry.
+ pub geom: TableGeom,
+ /// Rows.
+ pub rows: Vec<RowBox>,
+}
+
+/// Lays out a table's rows within a container `avail` wide (from the
+/// cache when nothing they show changed).
+pub(in crate::layout) fn table_box(
+ env: &Env<'_>,
+ story: &Story,
+ table: &Block,
+ avail: f32,
+ story_ref: &StoryRef,
+ fields: &FieldValues,
+) -> Arc<TableBox> {
+ cache::table_box(env, story, table, avail, story_ref, fields)
+}
+
+/// Lays out a table's rows within a container `avail` wide.
+fn lay_out_table(
+ env: &Env<'_>,
+ story: &Story,
+ table: &Block,
+ avail: f32,
+ story_ref: &StoryRef,
+ fields: &FieldValues,
+) -> TableBox {
+ let geom = geometry(story, table, &env.formats, avail);
+ let mut rows: Vec<RowBox> = Vec::with_capacity(geom.rows.len());
+ let row_count = geom.rows.len();
+ for (ri, row) in geom.rows.iter().enumerate() {
+ let mut cells = Vec::with_capacity(row.cells.len());
+ let mut content_h: f32 = 0.0;
+ for cell in &row.cells {
+ let width: f32 = geom.cols
+ [cell.col.min(geom.cols.len())..(cell.col + cell.span).min(geom.cols.len())]
+ .iter()
+ .sum();
+ // Right-to-left tables put the first column at the right.
+ let x = if geom.tbl.bidi == Some(true) {
+ geom.width() - geom.col_x(cell.col) - width
+ } else {
+ geom.col_x(cell.col)
+ };
+ let inner = (width - cell.margins[1] - cell.margins[3]).max(4.0);
+ let continuation = cell.v_merge == Some(VMerge::Continue);
+ let content = if continuation {
+ Stack::default()
+ } else {
+ stack_story(
+ env,
+ story,
+ Some(&cell.id),
+ &StackCtx {
+ story: story_ref.clone(),
+ width: inner,
+ table: cell.ctx.clone(),
+ fields: fields.clone(),
+ note_number: None,
+ float_frames: false,
+ page: None,
+ },
+ )
+ };
+ if cell.v_merge.is_none() {
+ content_h = content_h.max(content.height + cell.margins[0] + cell.margins[2]);
+ }
+ cells.push(CellBox {
+ geom: cell.clone(),
+ x,
+ width,
+ content,
+ rows: usize::from(!continuation),
+ });
+ }
+ // Horizontal borders take room of their own: the one along the top
+ // of each row, and the one along the bottom of the last row.
+ let border_top = border_room(
+ row.cells
+ .iter()
+ .filter(|c| c.v_merge != Some(VMerge::Continue))
+ .map(|c| c.borders[0]),
+ );
+ let border_bottom = if ri + 1 == row_count {
+ border_room(row.cells.iter().map(|c| c.borders[2]))
+ } else {
+ 0.0
+ };
+ let content_h = content_h + border_top + border_bottom;
+ let height = match row.tr.height {
+ Some((h, HeightRule::Exact)) if h > 0.0 => h,
+ Some((h, HeightRule::AtLeast)) => content_h.max(h),
+ _ => content_h,
+ };
+ // An empty row still shows its end-of-row mark's line.
+ let height = if height <= 0.0 { 12.0 } else { height };
+ rows.push(RowBox {
+ height,
+ cells,
+ cant_split: row.tr.cant_split.unwrap_or(false),
+ header: row.tr.header.unwrap_or(false),
+ border_top,
+ border_bottom,
+ });
+ }
+ // Vertical merges: spans, and growing the last spanned row to fit.
+ for r in 0..rows.len() {
+ for c in 0..rows[r].cells.len() {
+ if rows[r].cells[c].geom.v_merge != Some(VMerge::Restart) {
+ continue;
+ }
+ let col = rows[r].cells[c].geom.col;
+ let mut span = 1;
+ while r + span < rows.len()
+ && rows[r + span]
+ .cells
+ .iter()
+ .any(|x| x.geom.col == col && x.geom.v_merge == Some(VMerge::Continue))
+ {
+ span += 1;
+ }
+ rows[r].cells[c].rows = span;
+ let cell = &rows[r].cells[c];
+ let need = cell.content.height
+ + cell.geom.margins[0]
+ + cell.geom.margins[2]
+ + rows[r].border_top
+ + rows[r + span - 1].border_bottom;
+ let have: f32 = rows[r..r + span].iter().map(|x| x.height).sum();
+ if need > have {
+ rows[r + span - 1].height += need - have;
+ }
+ }
+ }
+ TableBox { geom, rows }
+}
+
+/// The room the widest of `borders` takes.
+fn border_room(borders: impl Iterator<Item = Option<Border>>) -> f32 {
+ borders
+ .flatten()
+ .map(|b| b.total_width())
+ .fold(0.0, f32::max)
+}
+
+/// Emits row `r` with its top-left table corner at (x, y) (x = the
+/// container's text area left; the table's own offset is added).
+pub(super) fn emit_row(tb: &TableBox, r: usize, x: f32, y: f32, out: Sink<'_>) {
+ let Sink {
+ items: out,
+ anchors,
+ notes,
+ } = out;
+ let row = &tb.rows[r];
+ let tx = x + tb.geom.left;
+ for cell in &row.cells {
+ if cell.rows == 0 {
+ continue;
+ }
+ let h: f32 = tb.rows[r..(r + cell.rows).min(tb.rows.len())]
+ .iter()
+ .map(|x| x.height)
+ .sum();
+ let cx = tx + cell.x;
+ let g = &cell.geom;
+ if let Some(color) = g.shading {
+ out.push(Item::Fill {
+ rect: Rect::from_xywh(cx, y, cell.width, h),
+ color,
+ });
+ }
+ let last = (r + cell.rows).min(tb.rows.len()) - 1;
+ let (top_room, bottom_room) = (row.border_top, tb.rows[last].border_bottom);
+ let content_h = cell.content.height;
+ let avail = h - g.margins[0] - g.margins[2] - top_room - bottom_room;
+ let dy = match g.tc.v_align.as_deref() {
+ Some("center") => ((avail - content_h) / 2.0).max(0.0),
+ Some("bottom") => (avail - content_h).max(0.0),
+ _ => 0.0,
+ };
+ let content_y = y + top_room + g.margins[0] + dy;
+ let mut items = cell.content.items.clone();
+ super::offset_items(&mut items, cx + g.margins[1], content_y);
+ let exact = matches!(tb.geom.rows[r].tr.height, Some((_, HeightRule::Exact)));
+ if exact {
+ let clip = Rect::from_xywh(cx, y, cell.width, h);
+ for it in &mut items {
+ if let Item::Line(l) = it {
+ l.clip = Some(clip);
+ }
+ }
+ }
+ out.extend(items);
+ for a in &cell.content.anchors {
+ let mut a = a.clone();
+ a.shift(cx + g.margins[1], content_y);
+ if a.cell.is_none() && a.drawing.anchor.as_ref().is_some_and(|x| x.in_cell) {
+ a.cell = Some((cx + g.margins[1], cell.width - g.margins[1] - g.margins[3]));
+ }
+ anchors.push(a);
+ }
+ notes.extend(cell.content.notes.iter().copied());
+ // Borders: the bottom of a merged span comes from its last row.
+ let bottom = if cell.rows > 1 {
+ tb.rows
+ .get(r + cell.rows - 1)
+ .and_then(|last| last.cells.iter().find(|c| c.geom.col == g.col))
+ .map_or(g.borders[2], |c| c.geom.borders[2])
+ } else {
+ g.borders[2]
+ };
+ // Horizontal lines run along the middle of the room made for them:
+ // a row's top, or the next row's top for a bottom border.
+ let top = y + top_room / 2.0;
+ let bottom_y = match tb.rows.get(last + 1) {
+ Some(next) => y + h + next.border_top / 2.0,
+ None => y + h - bottom_room / 2.0,
+ };
+ let edges = [
+ (g.borders[0], cx, top, cx + cell.width, top),
+ (g.borders[1], cx, y, cx, y + h),
+ (bottom, cx, bottom_y, cx + cell.width, bottom_y),
+ (g.borders[3], cx + cell.width, y, cx + cell.width, y + h),
+ ];
+ for (border, x0, y0, x1, y1) in edges {
+ if let Some(border) = border {
+ out.push(Item::Rule {
+ x0,
+ y0,
+ x1,
+ y1,
+ border,
+ });
+ }
+ }
+ if let Some(d) = g.diagonals[0] {
+ out.push(Item::Rule {
+ x0: cx,
+ y0: y,
+ x1: cx + cell.width,
+ y1: y + h,
+ border: d,
+ });
+ }
+ if let Some(d) = g.diagonals[1] {
+ out.push(Item::Rule {
+ x0: cx + cell.width,
+ y0: y,
+ x1: cx,
+ y1: y + h,
+ border: d,
+ });
+ }
+ }
+}
+
+/// A drawing placed at a rectangle.
+pub fn placed(drawing: Arc<super::super::drawing::Drawing>, rect: Rect, story: StoryRef) -> Item {
+ Item::Drawing(PlacedDrawing {
+ drawing,
+ rect,
+ story,
+ })
+}
diff --git a/crates/docx_engine/src/layout/flow/stack/cache.rs b/crates/docx_engine/src/layout/flow/stack/cache.rs
new file mode 100644
index 0000000000..907a68700c
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/stack/cache.rs
@@ -0,0 +1,162 @@
+//! Laid-out tables kept between layouts: a table is stacked again only
+//! when something it shows changed.
+
+use super::super::super::inline::FieldValues;
+use super::super::super::{Item, ParaBox, StoryRef};
+use super::super::Env;
+use super::{TableBox, lay_out_table};
+use crate::hash::FxMap;
+use crate::model::block::{Block, BlockId, BlockKind, Story};
+use crate::model::numbering::Suffix;
+use crate::model::props::Align;
+use std::sync::{Arc, Mutex};
+
+/// What a laid-out table depends on besides the page fields and note
+/// numbers it shows.
+#[derive(Debug, PartialEq)]
+struct TableKey {
+ /// Versions of the table and of every block inside it, in order.
+ blocks: Vec<u64>,
+ /// List labels of the body paragraphs inside (numbered through the
+ /// document), by their place in `blocks`.
+ labels: Vec<(usize, String, Suffix, Align)>,
+ width: u32,
+ generation: u64,
+ markup: bool,
+}
+
+impl TableKey {
+ fn of(env: &Env<'_>, story: &Story, table: &Block, width: f32, story_ref: &StoryRef) -> Self {
+ let body = *story_ref == StoryRef::Body;
+ let mut blocks = Vec::new();
+ let mut labels = Vec::new();
+ story.walk_from(&table.id, &mut |b| {
+ if body
+ && b.kind == BlockKind::Paragraph
+ && let Some((label, _)) = env.labels.get(&b.id)
+ {
+ labels.push((blocks.len(), label.text.clone(), label.suffix, label.jc));
+ }
+ blocks.push(b.version);
+ });
+ Self {
+ blocks,
+ labels,
+ width: width.to_bits(),
+ generation: env.doc.generation,
+ markup: env.options.markup,
+ }
+ }
+}
+
+/// A laid-out table and what it was laid out from.
+#[derive(Debug)]
+struct Cached {
+ key: TableKey,
+ /// The page field values it shows, when it shows any.
+ fields: Option<FieldValues>,
+ /// Its paragraphs with note references, whose numbers can change
+ /// without the table changing.
+ notes: Vec<Arc<ParaBox>>,
+ tb: Arc<TableBox>,
+ epoch: u64,
+}
+
+/// Laid-out tables by story and table block: a few per table, since one
+/// layout can stack a table more than once (at a column's width, and in
+/// a keep-with-next chain measured for another column).
+#[derive(Debug, Default)]
+pub(in crate::layout) struct TableCache(Mutex<FxMap<(StoryRef, BlockId), Vec<Cached>>>);
+
+impl TableCache {
+ fn get(
+ &self,
+ epoch: u64,
+ id: &(StoryRef, BlockId),
+ key: &TableKey,
+ fields: &FieldValues,
+ notes: &std::collections::HashMap<(bool, i64), String>,
+ ) -> Option<Arc<TableBox>> {
+ let mut guard = self.0.lock().unwrap_or_else(|e| e.into_inner());
+ let hit = guard.get_mut(id)?.iter_mut().find(|c| {
+ c.key == *key
+ && c.fields.as_ref().is_none_or(|f| f == fields)
+ && c.notes.iter().all(|pb| pb.inline.notes_current(notes))
+ })?;
+ hit.epoch = epoch;
+ Some(Arc::clone(&hit.tb))
+ }
+
+ fn put(&self, id: (StoryRef, BlockId), entry: Cached) {
+ /// Tables kept per table block.
+ const KEEP: usize = 4;
+ let mut guard = self.0.lock().unwrap_or_else(|e| e.into_inner());
+ let list = guard.entry(id).or_default();
+ list.retain(|c| c.key != entry.key || c.fields != entry.fields);
+ if list.len() >= KEEP
+ && let Some(oldest) = (0..list.len()).min_by_key(|&i| list[i].epoch)
+ {
+ list.remove(oldest);
+ }
+ list.push(entry);
+ }
+
+ /// Drops the tables the pass that ended at `epoch` did not use.
+ pub(in crate::layout) fn end(&self, epoch: u64) {
+ let mut guard = self.0.lock().unwrap_or_else(|e| e.into_inner());
+ guard.retain(|_, list| {
+ list.retain(|c| c.epoch == epoch);
+ !list.is_empty()
+ });
+ }
+}
+
+/// Lays out a table's rows within a container `avail` wide, or takes
+/// them from the cache when nothing they show changed.
+pub(super) fn table_box(
+ env: &Env<'_>,
+ story: &Story,
+ table: &Block,
+ avail: f32,
+ story_ref: &StoryRef,
+ fields: &FieldValues,
+) -> Arc<TableBox> {
+ let Some(cache) = env.cache else {
+ return Arc::new(lay_out_table(env, story, table, avail, story_ref, fields));
+ };
+ let epoch = cache.epoch();
+ let id = (story_ref.clone(), table.id.clone());
+ let key = TableKey::of(env, story, table, avail, story_ref);
+ if let Some(tb) = cache
+ .tables
+ .get(epoch, &id, &key, fields, &env.note_numbers)
+ {
+ return tb;
+ }
+ let tb = Arc::new(lay_out_table(env, story, table, avail, story_ref, fields));
+ let mut dynamic = false;
+ let mut notes: Vec<Arc<ParaBox>> = Vec::new();
+ for cell in tb.rows.iter().flat_map(|r| &r.cells) {
+ for item in &cell.content.items {
+ if let Item::Line(l) = item {
+ dynamic |= l.para.inline.dynamic;
+ if !l.para.inline.notes.is_empty()
+ && !notes.last().is_some_and(|pb| Arc::ptr_eq(pb, &l.para))
+ {
+ notes.push(Arc::clone(&l.para));
+ }
+ }
+ }
+ }
+ cache.tables.put(
+ id,
+ Cached {
+ key,
+ fields: dynamic.then(|| fields.clone()),
+ notes,
+ tb: Arc::clone(&tb),
+ epoch,
+ },
+ );
+ tb
+}
diff --git a/crates/docx_engine/src/layout/flow/test.rs b/crates/docx_engine/src/layout/flow/test.rs
new file mode 100644
index 0000000000..c9aeaa868b
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/test.rs
@@ -0,0 +1,963 @@
+use crate::Document;
+use crate::layout::inline::Kind;
+use crate::layout::{Item, Layout, PlacedLine, StoryRef};
+use crate::test_support::{Parts, docx, fonts, shape_paragraph};
+
+const ARIAL_10: &str = r#"<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Arial" w:hAnsi="Arial"/><w:sz w:val="20"/></w:rPr></w:rPrDefault></w:docDefaults>"#;
+
+const SECTION: &str = r#"<w:sectPr><w:headerReference w:type="default" r:id="rIdH1"/><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720"/></w:sectPr>"#;
+
+fn layout(body: &str, parts: &Parts<'_>) -> Layout {
+ Document::open(docx(body, parts)).unwrap().layout(fonts())
+}
+
+fn lines<'a>(l: &'a Layout, story: &'a StoryRef) -> Vec<&'a PlacedLine> {
+ l.pages[0].lines_of(story).collect()
+}
+
+fn text(p: &PlacedLine) -> String {
+ let l = p.line();
+ p.para.inline.clusters[l.start..l.end]
+ .iter()
+ .filter(|c| matches!(c.kind, Kind::Text | Kind::Space | Kind::Tab))
+ .map(|c| if c.kind == Kind::Tab { '\t' } else { c.ch })
+ .collect()
+}
+
+fn header_part() -> StoryRef {
+ StoryRef::Part("/word/header1.xml".into())
+}
+
+#[test]
+fn paragraphs_with_the_same_borders_share_one_box() {
+ let bordered = |t: &str| {
+ format!(
+ r#"<w:p><w:pPr><w:pBdr><w:top w:val="single" w:sz="4" w:space="6" w:color="auto"/><w:bottom w:val="single" w:sz="4" w:space="6" w:color="auto"/></w:pBdr></w:pPr><w:r><w:t>{t}</w:t></w:r></w:p>"#
+ )
+ };
+ let body = format!("{}{}", bordered("One"), bordered("Two"));
+ let l = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let rules = l.pages[0]
+ .items
+ .iter()
+ .filter(|i| matches!(i, Item::Rule { y0, y1, .. } if (y0 - y1).abs() < 0.01))
+ .count();
+ // One top border above the first and one bottom border below the last.
+ assert_eq!(rules, 2);
+ let ls = lines(&l, &StoryRef::Body);
+ let gap = ls[1].y - (ls[0].y + ls[0].line().height);
+ assert!(gap.abs() < 0.01, "border space between them: {gap}");
+}
+
+#[test]
+fn header_frames_float_beside_the_header_text() {
+ let header = r#"<w:p><w:pPr><w:framePr w:wrap="around" w:vAnchor="text" w:hAnchor="margin" w:xAlign="right" w:y="1"/><w:jc w:val="right"/></w:pPr><w:r><w:t>7</w:t></w:r></w:p><w:p><w:r><w:t>Header text</w:t></w:r></w:p>"#;
+ let body = format!("<w:p><w:r><w:t>Body</w:t></w:r></w:p>{SECTION}");
+ let l = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ header: Some(header),
+ ..Parts::default()
+ },
+ );
+ let part = header_part();
+ let hs = lines(&l, &part);
+ let frame = hs.iter().find(|p| text(p) == "7").expect("frame line");
+ let rest = hs.iter().find(|p| text(p) == "Header text").expect("text");
+ // The frame takes no room: the text starts at the header distance, on
+ // the frame's row, and the frame sits at the right margin.
+ assert!((rest.y - 36.0).abs() < 0.01, "{}", rest.y);
+ assert!((frame.y - rest.y - 0.05).abs() < 0.01, "{}", frame.y);
+ let line = frame.line();
+ let right = frame.x + line.left + line.width;
+ assert!((right - 540.0).abs() < 1.0, "{right}");
+}
+
+#[test]
+fn turning_numbering_off_drops_the_list_style_indent() {
+ let styles = format!(
+ r#"{ARIAL_10}<w:style w:type="paragraph" w:styleId="Bullets"><w:pPr><w:numPr><w:numId w:val="1"/></w:numPr><w:ind w:left="924" w:hanging="357"/></w:pPr></w:style>"#
+ );
+ let numbering = r#"<w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:numFmt w:val="bullet"/><w:lvlText w:val="-"/><w:pPr><w:ind w:left="1080" w:hanging="360"/></w:pPr></w:lvl></w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>"#;
+ let body = r#"<w:p><w:pPr><w:pStyle w:val="Bullets"/><w:numPr><w:ilvl w:val="0"/><w:numId w:val="0"/></w:numPr></w:pPr><w:r><w:t>Plain</w:t></w:r></w:p>"#;
+ let l = layout(
+ body,
+ &Parts {
+ styles: Some(&styles),
+ numbering: Some(numbering),
+ ..Parts::default()
+ },
+ );
+ let p = lines(&l, &StoryRef::Body)[0];
+ assert_eq!(text(p), "Plain");
+ assert!(p.line().left.abs() < 0.01, "{}", p.line().left);
+}
+
+#[test]
+fn check_box_form_fields_show_a_box() {
+ let body = r#"<w:p><w:r><w:fldChar w:fldCharType="begin"><w:ffData><w:name w:val="Check1"/><w:checkBox><w:sizeAuto/><w:default w:val="1"/></w:checkBox></w:ffData></w:fldChar></w:r><w:r><w:instrText xml:space="preserve"> FORMCHECKBOX </w:instrText></w:r><w:r><w:fldChar w:fldCharType="separate"/></w:r><w:r><w:fldChar w:fldCharType="end"/></w:r><w:r><w:t xml:space="preserve"> Yes</w:t></w:r></w:p>"#;
+ let l = layout(
+ body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let p = lines(&l, &StoryRef::Body)[0];
+ assert_eq!(text(p), "\u{2612} Yes");
+ let box_ = p
+ .para
+ .inline
+ .clusters
+ .iter()
+ .find(|c| c.ch == '\u{2612}')
+ .unwrap();
+ assert!((box_.advance - 10.0).abs() < 0.01, "{}", box_.advance);
+}
+
+#[test]
+fn header_paragraphs_do_not_take_body_list_labels() {
+ let numbering = r#"<w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/></w:lvl></w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>"#;
+ let body = format!(
+ r#"<w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr><w:r><w:t>Item</w:t></w:r></w:p>{SECTION}"#
+ );
+ let l = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ numbering: Some(numbering),
+ header: Some(r#"<w:p><w:r><w:t>Header</w:t></w:r></w:p>"#),
+ ..Parts::default()
+ },
+ );
+ assert_eq!(text(lines(&l, &StoryRef::Body)[0]), "1.\tItem");
+ let part = header_part();
+ assert_eq!(text(lines(&l, &part)[0]), "Header");
+}
+
+#[test]
+fn links_take_their_color_from_their_formatting() {
+ use pptx_engine::model::color::Rgba;
+ let styles = format!(
+ r#"{ARIAL_10}<w:style w:type="character" w:styleId="Hyperlink"><w:name w:val="Hyperlink"/><w:rPr><w:color w:val="0000FF"/><w:u w:val="single"/></w:rPr></w:style><w:style w:type="paragraph" w:styleId="TOC1"><w:name w:val="toc 1"/></w:style>"#
+ );
+ let link = |p_style: &str, r_style: &str| {
+ format!(
+ r#"<w:p><w:pPr>{p_style}</w:pPr><w:hyperlink w:anchor="x"><w:r><w:rPr>{r_style}</w:rPr><w:t>Link</w:t></w:r></w:hyperlink></w:p>"#
+ )
+ };
+ let body = [
+ link("", r#"<w:rStyle w:val="Hyperlink"/>"#),
+ link("", ""),
+ link(
+ r#"<w:pStyle w:val="TOC1"/>"#,
+ r#"<w:rStyle w:val="Hyperlink"/>"#,
+ ),
+ ]
+ .concat();
+ let l = layout(
+ &body,
+ &Parts {
+ styles: Some(&styles),
+ ..Parts::default()
+ },
+ );
+ let colors: Vec<Rgba> = lines(&l, &StoryRef::Body)
+ .iter()
+ .map(|p| p.para.inline.runs[p.para.inline.clusters[0].run as usize].color)
+ .collect();
+ // The Hyperlink style's blue; no forced blue without it; table of
+ // contents entries keep the entry's own color.
+ assert_eq!(colors[0], Rgba::from_u8(0, 0, 0xFF));
+ assert_eq!(colors[1], Rgba::BLACK);
+ assert_eq!(colors[2], Rgba::BLACK);
+}
+
+/// A one-cell table row of `n` paragraphs, preceded by `before` filler
+/// paragraphs; `tr` holds row properties.
+fn tall_row(before: usize, n: usize, tr: &str) -> String {
+ let filler: String = (0..before)
+ .map(|i| format!("<w:p><w:r><w:t>Filler {i}</w:t></w:r></w:p>"))
+ .collect();
+ let cell: String = (0..n)
+ .map(|i| format!("<w:p><w:r><w:t>Cell line {i}</w:t></w:r></w:p>"))
+ .collect();
+ format!(
+ r#"{filler}<w:tbl><w:tblPr><w:tblW w:w="5000" w:type="dxa"/></w:tblPr><w:tblGrid><w:gridCol w:w="5000"/></w:tblGrid><w:tr><w:trPr>{tr}</w:trPr><w:tc><w:tcPr><w:tcW w:w="5000" w:type="dxa"/></w:tcPr>{cell}</w:tc></w:tr></w:tbl><w:p/>"#
+ )
+}
+
+fn page_texts(l: &Layout, page: usize) -> Vec<String> {
+ l.pages[page]
+ .lines_of(&StoryRef::Body)
+ .map(text)
+ .filter(|t| !t.is_empty())
+ .collect()
+}
+
+#[test]
+fn table_rows_break_across_pages_between_lines() {
+ let l = layout(
+ &tall_row(40, 30, ""),
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let first = page_texts(&l, 0);
+ let second = page_texts(&l, 1);
+ // The row starts below the filler on the first page and goes on.
+ assert!(first.iter().any(|t| t == "Cell line 0"), "{first:?}");
+ assert!(!first.iter().any(|t| t == "Cell line 29"), "{first:?}");
+ assert!(second.iter().any(|t| t == "Cell line 29"), "{second:?}");
+ let last_on_first = first.iter().filter(|t| t.starts_with("Cell")).count();
+ assert_eq!(
+ second.iter().filter(|t| t.starts_with("Cell")).count(),
+ 30 - last_on_first
+ );
+}
+
+#[test]
+fn rows_that_cannot_split_move_whole() {
+ let l = layout(
+ &tall_row(40, 30, "<w:cantSplit/>"),
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ assert!(!page_texts(&l, 0).iter().any(|t| t.starts_with("Cell")));
+ assert!(page_texts(&l, 1).iter().any(|t| t == "Cell line 0"));
+}
+
+/// `before` filler lines, then a one-column table of `rows`, each given
+/// as (row properties, cell content).
+fn table_after(before: usize, rows: &[(&str, &str)]) -> String {
+ let filler: String = (0..before)
+ .map(|i| format!("<w:p><w:r><w:t>Filler {i}</w:t></w:r></w:p>"))
+ .collect();
+ let rows: String = rows
+ .iter()
+ .map(|(tr, cell)| {
+ format!(
+ r#"<w:tr><w:trPr>{tr}</w:trPr><w:tc><w:tcPr><w:tcW w:w="5000" w:type="dxa"/></w:tcPr>{cell}</w:tc></w:tr>"#
+ )
+ })
+ .collect();
+ format!(
+ r#"{filler}<w:tbl><w:tblPr><w:tblW w:w="5000" w:type="dxa"/></w:tblPr><w:tblGrid><w:gridCol w:w="5000"/></w:tblGrid>{rows}</w:tbl><w:p/>{LETTER}"#
+ )
+}
+
+#[test]
+fn rows_break_between_lines_as_widow_control_allows() {
+ // A four-line paragraph whose first three lines fit on the page: two
+ // stay, two go on, so neither page has a single line of it.
+ let cell = r#"<w:p><w:r><w:t>L1</w:t><w:br/><w:t>L2</w:t><w:br/><w:t>L3</w:t><w:br/><w:t>L4</w:t></w:r></w:p>"#;
+ let l = layout(&table_after(53, &[("", cell)]), &arial_10());
+ let cells = |page| -> Vec<String> {
+ page_texts(&l, page)
+ .into_iter()
+ .filter(|t| t.starts_with('L'))
+ .collect()
+ };
+ assert_eq!(cells(0), ["L1", "L2"]);
+ assert_eq!(cells(1), ["L3", "L4"]);
+ // Two one-line paragraphs with room for one: the row leaves no single
+ // line behind and goes over whole.
+ let cell = r#"<w:p><w:r><w:t>L1</w:t></w:r></w:p><w:p><w:r><w:t>L2</w:t></w:r></w:p>"#;
+ let l = layout(&table_after(55, &[("", cell)]), &arial_10());
+ assert!(!page_texts(&l, 0).iter().any(|t| t.starts_with('L')));
+ assert_eq!(
+ page_texts(&l, 1)
+ .into_iter()
+ .filter(|t| t.starts_with('L'))
+ .collect::<Vec<_>>(),
+ ["L1", "L2"]
+ );
+}
+
+#[test]
+fn header_rows_and_rows_kept_with_the_next_stay_together() {
+ let para =
+ |t: &str, ppr: &str| format!("<w:p><w:pPr>{ppr}</w:pPr><w:r><w:t>{t}</w:t></w:r></w:p>");
+ let header = ("<w:tblHeader/>", para("Head", ""));
+ let kept = ("", para("Kept", "<w:keepNext/>"));
+ let (row, free, last) = (para("Row", ""), para("Free", ""), para("Last", ""));
+ for (filler, rows) in [
+ // Room for one more line: not the header alone.
+ (
+ 55,
+ vec![(header.0, header.1.as_str()), ("", &row), ("", &row)],
+ ),
+ // Room for three: the first row, not both kept rows without the
+ // last.
+ (
+ 53,
+ vec![
+ ("", &free),
+ (kept.0, kept.1.as_str()),
+ (kept.0, kept.1.as_str()),
+ ("", &last),
+ ],
+ ),
+ ] {
+ let l = layout(&table_after(filler, &rows), &arial_10());
+ let first = page_texts(&l, 0);
+ let second = page_texts(&l, 1);
+ // A header row never ends a page alone; rows kept with the next
+ // go over with the row they keep with.
+ assert!(
+ !first.iter().any(|t| t == "Head" || t == "Kept"),
+ "{first:?}"
+ );
+ assert!(
+ second.iter().any(|t| t == "Kept" || t == "Head"),
+ "{second:?}"
+ );
+ }
+}
+
+#[test]
+fn rows_taller_than_a_page_split_instead_of_overflowing() {
+ let l = layout(
+ &tall_row(0, 120, ""),
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ assert!(l.pages.len() >= 3, "{}", l.pages.len());
+ for page in &l.pages {
+ for p in page.lines_of(&StoryRef::Body) {
+ assert!(p.y + p.line().height <= page.height - 72.0 + 0.5, "{}", p.y);
+ }
+ }
+}
+
+const LETTER: &str = r#"<w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720"/></w:sectPr>"#;
+
+fn arial_10() -> Parts<'static> {
+ Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ }
+}
+
+#[test]
+fn right_to_left_runs_size_lines_by_their_complex_script_size() {
+ let para = |rpr: &str| {
+ format!(
+ r#"<w:p><w:r><w:rPr>{rpr}<w:sz w:val="40"/><w:szCs w:val="20"/></w:rPr><w:t>abc</w:t></w:r></w:p>"#
+ )
+ };
+ let body = format!("{}{}{LETTER}", para("<w:rtl/>"), para(""));
+ let l = layout(&body, &arial_10());
+ let ls = lines(&l, &StoryRef::Body);
+ let (rtl, ltr) = (ls[0].line().height, ls[1].line().height);
+ assert!((ltr / rtl - 2.0).abs() < 0.01, "{rtl} {ltr}");
+}
+
+/// A two-column table 500pt wide placed by `tblpPr` attributes `pos`, of
+/// `rows` rows of `lines` paragraphs.
+fn floating_table(pos: &str, rows: usize, lines: usize) -> String {
+ let cell = |c: &str, r: usize| -> String {
+ (0..lines)
+ .map(|i| format!("<w:p><w:r><w:t>{c}{r}.{i}</w:t></w:r></w:p>"))
+ .collect()
+ };
+ let rows: String = (0..rows)
+ .map(|r| {
+ format!(
+ r#"<w:tr><w:trPr><w:cantSplit/></w:trPr><w:tc>{}</w:tc><w:tc>{}</w:tc></w:tr>"#,
+ cell("A", r),
+ cell("B", r)
+ )
+ })
+ .collect();
+ format!(
+ r#"<w:tbl><w:tblPr><w:tblpPr {pos}/><w:tblW w:w="10000" w:type="dxa"/></w:tblPr><w:tblGrid><w:gridCol w:w="5000"/><w:gridCol w:w="5000"/></w:tblGrid>{rows}</w:tbl>"#
+ )
+}
+
+fn find<'a>(l: &'a Layout, page: usize, t: &str) -> &'a PlacedLine {
+ l.pages[page]
+ .lines_of(&StoryRef::Body)
+ .find(|p| text(p) == t)
+ .unwrap_or_else(|| panic!("no line {t:?} on page {page}"))
+}
+
+#[test]
+fn floating_tables_sit_at_their_position() {
+ let pos = r#"w:vertAnchor="text" w:horzAnchor="margin" w:tblpXSpec="center" w:tblpY="400" w:bottomFromText="200""#;
+ let body = format!(
+ "<w:p><w:r><w:t>Before</w:t></w:r></w:p>{}<w:p><w:r><w:t>After</w:t></w:r></w:p>{LETTER}",
+ floating_table(pos, 1, 1)
+ );
+ let l = layout(&body, &arial_10());
+ let before = find(&l, 0, "Before");
+ let cell = find(&l, 0, "A0.0");
+ let after = find(&l, 0, "After");
+ // Centered on the 468pt text area, 20pt below the text it follows.
+ assert!((cell.x - (72.0 - 16.0 + 5.4)).abs() < 0.1, "{}", cell.x);
+ let top = before.y + before.line().height + 20.0;
+ assert!((cell.y - top).abs() < 0.1, "{} {top}", cell.y);
+ // Text goes on below it, at its distance from text.
+ let bottom = cell.y + cell.line().height + 10.0;
+ assert!((after.y - bottom).abs() < 0.1, "{} {bottom}", after.y);
+}
+
+#[test]
+fn page_positioned_floating_tables_go_on_at_the_same_place() {
+ let pos = r#"w:vertAnchor="page" w:horzAnchor="page" w:tblpX="1000" w:tblpY="3000""#;
+ let body = format!("{}<w:p/>{LETTER}", floating_table(pos, 12, 6));
+ let l = layout(&body, &arial_10());
+ assert!(l.pages.len() >= 2);
+ let first = find(&l, 0, "A0.0");
+ assert!((first.y - 150.0).abs() < 0.1, "{}", first.y);
+ assert!((first.x - 55.4).abs() < 0.1, "{}", first.x);
+ let next = l.pages[1]
+ .lines_of(&StoryRef::Body)
+ .next()
+ .expect("the table goes on");
+ assert!((next.y - 150.0).abs() < 0.1, "{}", next.y);
+}
+
+#[test]
+fn right_to_left_tables_start_at_the_right() {
+ let table = r#"<w:tbl><w:tblPr><w:bidiVisual/><w:tblW w:w="4000" w:type="dxa"/></w:tblPr><w:tblGrid><w:gridCol w:w="2000"/><w:gridCol w:w="2000"/></w:tblGrid><w:tr><w:tc><w:p><w:r><w:t>First</w:t></w:r></w:p></w:tc><w:tc><w:p><w:r><w:t>Second</w:t></w:r></w:p></w:tc></w:tr></w:tbl>"#;
+ let body = format!("{table}<w:p/>{LETTER}");
+ let l = layout(&body, &arial_10());
+ let first = find(&l, 0, "First");
+ let second = find(&l, 0, "Second");
+ // The first column is rightmost, the text of its cell ending at the
+ // right margin (cell margins of 5.4pt, columns 100pt wide).
+ assert!(
+ (first.x - 5.4 + 100.0 - 5.4 - 540.0).abs() < 0.1,
+ "{}",
+ first.x
+ );
+ assert!((first.x - second.x - 100.0).abs() < 0.1, "{}", second.x);
+}
+
+#[test]
+fn table_rows_make_room_for_their_borders() {
+ let line =
+ |side: &str| format!(r#"<w:{side} w:val="single" w:sz="16" w:space="0" w:color="auto"/>"#);
+ let row = |t: &str| format!("<w:tr><w:tc><w:p><w:r><w:t>{t}</w:t></w:r></w:p></w:tc></w:tr>");
+ let body = format!(
+ r#"<w:tbl><w:tblPr><w:tblW w:w="4000" w:type="dxa"/><w:tblBorders>{}{}{}</w:tblBorders></w:tblPr><w:tblGrid><w:gridCol w:w="4000"/></w:tblGrid>{}{}</w:tbl><w:p><w:r><w:t>After</w:t></w:r></w:p>{LETTER}"#,
+ line("top"),
+ line("insideH"),
+ line("bottom"),
+ row("One"),
+ row("Two"),
+ );
+ let l = layout(&body, &arial_10());
+ let (one, two, after) = (find(&l, 0, "One"), find(&l, 0, "Two"), find(&l, 0, "After"));
+ let h = one.line().height;
+ // Each row makes room for the 2pt line along its top, the last row for
+ // the one along its bottom too.
+ assert!((one.y - 74.0).abs() < 0.01, "{}", one.y);
+ assert!((two.y - (one.y + h + 2.0)).abs() < 0.01, "{}", two.y);
+ assert!((after.y - (two.y + h + 2.0)).abs() < 0.01, "{}", after.y);
+}
+
+#[test]
+fn frames_in_the_margin_leave_the_text_beside_them() {
+ let header = r#"<w:p><w:pPr><w:framePr w:w="400" w:h="400" w:hRule="exact" w:wrap="notBeside" w:vAnchor="text" w:hAnchor="page" w:x="11000" w:y="0"/></w:pPr><w:r><w:t>9</w:t></w:r></w:p><w:p><w:r><w:t>Header text</w:t></w:r></w:p>"#;
+ let body = format!("<w:p><w:r><w:t>Body</w:t></w:r></w:p>{SECTION}");
+ let l = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ header: Some(header),
+ ..Parts::default()
+ },
+ );
+ let part = header_part();
+ let hs = lines(&l, &part);
+ let rest = hs.iter().find(|p| text(p) == "Header text").expect("text");
+ // The frame is right of the text area: the text stays at the top.
+ assert!((rest.y - 36.0).abs() < 0.01, "{}", rest.y);
+}
+
+#[test]
+fn keeping_with_the_next_paragraph_stops_at_a_page_break() {
+ let filler: String = (0..55)
+ .map(|i| format!("<w:p><w:r><w:t>Filler {i}</w:t></w:r></w:p>"))
+ .collect();
+ let body = format!(
+ r#"{filler}<w:p><w:pPr><w:keepNext/></w:pPr><w:r><w:br w:type="page"/><w:t>Heading</w:t></w:r></w:p><w:p><w:r><w:t>Text</w:t></w:r></w:p>{LETTER}"#
+ );
+ let l = layout(&body, &arial_10());
+ assert_eq!(l.pages.len(), 2);
+ assert!(page_texts(&l, 1).iter().any(|t| t == "Heading"));
+}
+
+fn drawing_rects(l: &Layout) -> Vec<pptx_engine::path::Rect> {
+ l.pages[0]
+ .all_items()
+ .filter_map(|i| match i {
+ Item::Drawing(d) => Some(d.rect),
+ _ => None,
+ })
+ .collect()
+}
+
+#[test]
+fn text_box_text_sits_in_its_shape() {
+ let body = format!(
+ "{}{LETTER}",
+ shape_paragraph("page", 200, 300, Some("Inside"))
+ );
+ let l = layout(&body, &arial_10());
+ let inside = l.pages[0]
+ .all_items()
+ .find_map(|i| match i {
+ Item::Line(p) if text(p) == "Inside" => Some(p),
+ _ => None,
+ })
+ .expect("the text box text");
+ assert!(matches!(inside.para.story, StoryRef::TextBox(..)));
+ // Inside the shape, past its default insets of 7.2pt and 3.6pt.
+ assert!((inside.x - 207.2).abs() < 0.01, "{}", inside.x);
+ assert!((inside.y - 303.6).abs() < 0.01, "{}", inside.y);
+}
+
+#[test]
+fn drawings_in_table_cells_are_positioned_in_the_cell() {
+ let cell = shape_paragraph("column", 10, 0, None);
+ let body = format!(
+ r#"<w:tbl><w:tblPr><w:tblW w:w="6000" w:type="dxa"/></w:tblPr><w:tblGrid><w:gridCol w:w="2000"/><w:gridCol w:w="4000"/></w:tblGrid><w:tr><w:tc><w:p/></w:tc><w:tc>{cell}</w:tc></w:tr></w:tbl><w:p/>{LETTER}"#
+ );
+ let l = layout(&body, &arial_10());
+ let rects = drawing_rects(&l);
+ // The first cell's text lines up with the margin (tables before Word
+ // 2013), so the second cell's text starts 100pt to the right of it.
+ assert_eq!(rects.len(), 1);
+ assert!(
+ (rects[0].x - (72.0 + 100.0 + 10.0)).abs() < 0.01,
+ "{}",
+ rects[0].x
+ );
+}
+
+const PAGE: &str = r#"<w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720"/>"#;
+
+/// A section break paragraph ending a section of `cols` columns that
+/// started `how` (`continuous` or `nextPage`).
+fn section_end(how: &str, cols: &str) -> String {
+ format!(r#"<w:p><w:pPr><w:sectPr><w:type w:val="{how}"/>{PAGE}{cols}</w:sectPr></w:pPr></w:p>"#)
+}
+
+fn para(t: &str) -> String {
+ format!("<w:p><w:r><w:t>{t}</w:t></w:r></w:p>")
+}
+
+#[test]
+fn sections_on_one_page_stack_their_columns() {
+ let two = r#"<w:cols w:num="2" w:space="720"/>"#;
+ let body = format!(
+ r#"{}{}{}<w:p><w:r><w:br w:type="column"/><w:t>Right</w:t></w:r></w:p>{}{}<w:sectPr><w:type w:val="continuous"/>{PAGE}</w:sectPr>"#,
+ para("Intro"),
+ section_end("nextPage", ""),
+ para("Left"),
+ section_end("continuous", two),
+ para("After"),
+ );
+ let l = layout(&body, &arial_10());
+ let intro = find(&l, 0, "Intro");
+ let h = intro.line().height;
+ let (left, right, after) = (
+ find(&l, 0, "Left"),
+ find(&l, 0, "Right"),
+ find(&l, 0, "After"),
+ );
+ // The two columns start right below the first section's text (its
+ // empty section break paragraph takes no room), the second at
+ // 72 + 216 + 36.
+ assert!((left.y - (72.0 + h)).abs() < 0.01, "{}", left.y);
+ assert!((right.y - left.y).abs() < 0.01, "{}", right.y);
+ assert!((right.x - 324.0).abs() < 0.01, "{}", right.x);
+ // The next section starts below both columns: the column break and the
+ // empty paragraph ending the columns take no room.
+ assert!((after.y - (left.y + h)).abs() < 0.01, "{}", after.y);
+}
+
+#[test]
+fn paragraphs_going_on_in_a_wider_column_fill_it() {
+ let cols = r#"<w:cols w:num="2" w:space="720" w:equalWidth="0"><w:col w:w="2000" w:space="720"/><w:col w:w="6640"/></w:cols>"#;
+ let words = "word ".repeat(600);
+ let body = format!("{}<w:sectPr>{PAGE}{cols}</w:sectPr>", para(words.trim()));
+ let l = layout(&body, &arial_10());
+ let ls = lines(&l, &StoryRef::Body);
+ let (narrow, wide): (Vec<&PlacedLine>, Vec<&PlacedLine>) =
+ ls.iter().copied().partition(|p| p.x < 150.0);
+ assert!(!narrow.is_empty() && !wide.is_empty());
+ // The second column is 332pt wide: its lines hold more than the first
+ // column's 100pt.
+ let widest = wide.iter().map(|p| p.line().width).fold(0.0f32, f32::max);
+ assert!(widest > 300.0, "{widest}");
+ assert!(
+ (wide[0].x - (72.0 + 100.0 + 36.0)).abs() < 0.01,
+ "{}",
+ wide[0].x
+ );
+}
+
+#[test]
+fn ending_full_columns_does_not_start_a_page() {
+ // Two columns of 56 lines each fill the page; the empty paragraph that
+ // ends their section would only fit on a page of its own.
+ let filler: String = (0..112).map(|k| para(&format!("Line {k}"))).collect();
+ let body = format!(
+ "{filler}{}{}<w:sectPr>{PAGE}</w:sectPr>",
+ section_end("nextPage", r#"<w:cols w:num="2" w:space="720"/>"#),
+ para("Next"),
+ );
+ let l = layout(&body, &arial_10());
+ assert_eq!(page_texts(&l, 0).len(), 112);
+ assert_eq!(l.pages.len(), 2);
+ assert_eq!(page_texts(&l, 1), vec!["Next".to_owned()]);
+}
+
+#[test]
+fn empty_breaks_to_continuous_sections_take_no_room_below_text() {
+ // An empty paragraph ending a section before a continuous one adds no
+ // line below text; one that starts the page keeps its line.
+ let continuous = format!("<w:sectPr><w:type w:val=\"continuous\"/>{PAGE}</w:sectPr>");
+ let body = format!(
+ "{}{}{}{continuous}",
+ para("One"),
+ section_end("continuous", ""),
+ para("Two"),
+ );
+ let l = layout(&body, &arial_10());
+ let (one, two) = (find(&l, 0, "One"), find(&l, 0, "Two"));
+ assert!(
+ (two.y - (one.y + one.line().height)).abs() < 0.01,
+ "{}",
+ two.y
+ );
+ let body = format!("{}{}{continuous}", section_end("nextPage", ""), para("Two"));
+ let l = layout(&body, &arial_10());
+ let two = find(&l, 0, "Two");
+ assert!(two.y > 72.0 + 1.0, "{}", two.y);
+}
+
+#[test]
+fn suppressed_top_spacing_lifts_the_first_line_of_a_page() {
+ // At least 18pt lines of 10pt text.
+ let body = format!(
+ r#"<w:p><w:pPr><w:spacing w:line="360" w:lineRule="atLeast"/></w:pPr><w:r><w:t>Top</w:t></w:r><w:r><w:br/><w:t>Next</w:t></w:r></w:p><w:sectPr>{PAGE}</w:sectPr>"#
+ );
+ let plain = layout(&body, &arial_10());
+ assert!((find(&plain, 0, "Top").y - 72.0).abs() < 0.01);
+ let settings = "<w:compat><w:suppressTopSpacing/></w:compat>";
+ let l = layout(
+ &body,
+ &Parts {
+ settings: Some(settings),
+ ..arial_10()
+ },
+ );
+ // The first line keeps only its text's size; the next is not lifted.
+ let (top, next) = (find(&l, 0, "Top"), find(&l, 0, "Next"));
+ assert!((top.y - (72.0 - 8.0)).abs() < 0.01, "{}", top.y);
+ assert!((next.y - top.y - 18.0).abs() < 0.01, "{}", next.y);
+}
+
+#[test]
+fn multiple_spacing_below_the_last_line_may_run_into_the_margin() {
+ // Triple-spaced lines of 10pt text, 34.5pt each: the 19th line's text
+ // ends within the 648pt column, its spacing below it does not.
+ let body: String = (0..25)
+ .map(|k| {
+ format!(
+ r#"<w:p><w:pPr><w:spacing w:line="720" w:lineRule="auto"/></w:pPr><w:r><w:t>Line {k}</w:t></w:r></w:p>"#
+ )
+ })
+ .collect();
+ let l = layout(&format!("{body}{LETTER}"), &arial_10());
+ assert_eq!(page_texts(&l, 0).len(), 19);
+ let last = find(&l, 0, "Line 18");
+ let line = last.line();
+ assert!(last.y + line.height > 720.0, "{}", last.y);
+ assert!(last.y + line.height / 3.0 <= 720.0, "{}", last.y);
+}
+
+#[test]
+fn paragraph_positions_count_from_above_the_space_before() {
+ // A shape 10pt below the top of a paragraph with 12pt space before,
+ // after a line of text, in the body and in a table cell.
+ let shape = shape_paragraph("paragraph", 0, 10, None).replacen(
+ "<w:p>",
+ r#"<w:p><w:pPr><w:spacing w:before="240"/></w:pPr>"#,
+ 1,
+ );
+ let intro = para("Intro");
+ let cell = format!(
+ r#"<w:tbl><w:tblPr><w:tblW w:w="6000" w:type="dxa"/></w:tblPr><w:tblGrid><w:gridCol w:w="6000"/></w:tblGrid><w:tr><w:tc>{intro}{shape}</w:tc></w:tr></w:tbl><w:p/>"#
+ );
+ for body in [format!("{intro}{shape}"), cell] {
+ let l = layout(&format!("{body}{LETTER}"), &arial_10());
+ let h = find(&l, 0, "Intro").line().height;
+ let rects = drawing_rects(&l);
+ assert_eq!(rects.len(), 1);
+ assert!(
+ (rects[0].y - (72.0 + h + 10.0)).abs() < 0.01,
+ "{}",
+ rects[0].y
+ );
+ }
+}
+
+/// A right-to-left paragraph (or not) of runs marked right to left.
+fn rtl_para(bidi: bool, rpr: &str, text: &str) -> String {
+ let ppr = if bidi { "<w:pPr><w:bidi/></w:pPr>" } else { "" };
+ format!(
+ r#"<w:p>{ppr}<w:r><w:rPr>{rpr}<w:rtl/></w:rPr><w:t xml:space="preserve">{text}</w:t></w:r></w:p>"#
+ )
+}
+
+#[test]
+fn right_to_left_paragraphs_read_from_the_right() {
+ let body = format!(
+ "{}{LETTER}",
+ rtl_para(true, "", "\u{05E9}\u{05DC}\u{05D5}\u{05DD} abc 12")
+ );
+ let l = layout(&body, &arial_10());
+ let ls = lines(&l, &StoryRef::Body);
+ let pl = ls[0];
+ let (x, adv) = (&pl.para.lines.x, &pl.para.lines.adv);
+ let width = 468.0;
+ // The first letter sits at the right edge, the next ones to its left.
+ assert!((x[0] + adv[0] - width).abs() < 0.5, "{} {}", x[0], adv[0]);
+ assert!(x[1] < x[0] && x[2] < x[1]);
+ // Latin text and numbers keep their own order inside it.
+ let at = |c: char| {
+ let i = pl
+ .para
+ .inline
+ .clusters
+ .iter()
+ .position(|k| k.ch == c)
+ .unwrap();
+ x[i]
+ };
+ assert!(at('a') < at('b') && at('b') < at('c'));
+ assert!(at('1') < at('2'));
+ // ...and come after (left of) the Hebrew word.
+ assert!(at('c') < x[3]);
+}
+
+#[test]
+fn hebrew_and_arabic_take_the_weight_of_their_run() {
+ let body = format!(
+ "{}{}{LETTER}",
+ rtl_para(true, "<w:b/><w:bCs/>", "\u{05E9}"),
+ rtl_para(true, "", "\u{05E9}")
+ );
+ let l = layout(&body, &arial_10());
+ let ls = lines(&l, &StoryRef::Body);
+ let face = |i: usize| ls[i].para.inline.clusters[0].font.unwrap();
+ let (bold, regular) = (face(0), face(1));
+ assert_eq!(fonts().family(bold.face), "Noto Sans Hebrew");
+ assert_ne!(bold.face, regular.face, "a bold face, not the regular one");
+ assert!(!bold.synthetic_bold);
+}
+
+#[test]
+fn arabic_letters_join() {
+ // beh seen meem, then lam alef.
+ let body = format!(
+ "{}{LETTER}",
+ rtl_para(true, "", "\u{0628}\u{0633}\u{0645} \u{0644}\u{0627}")
+ );
+ let l = layout(&body, &arial_10());
+ let ls = lines(&l, &StoryRef::Body);
+ let clusters = &ls[0].para.inline.clusters;
+ let face = clusters[0].font.unwrap().face;
+ let glyph = |c: char| fonts().glyph(face, c).unwrap();
+ assert_eq!(fonts().family(face), "Noto Sans Arabic");
+ assert_eq!(clusters[0].glyph, glyph('\u{FE91}'), "initial beh");
+ assert_eq!(clusters[1].glyph, glyph('\u{FEB4}'), "medial seen");
+ assert_eq!(clusters[2].glyph, glyph('\u{FEE2}'), "final meem");
+ assert_eq!(clusters[4].glyph, glyph('\u{FEFB}'), "lam-alef");
+ assert_eq!(clusters[5].kind, Kind::Zero);
+}
+
+/// A paragraph with 12pt space before (and `ppr` besides, and `spacing`
+/// attributes), `run` before its text `t`.
+fn spaced(t: &str, ppr: &str, spacing: &str, run: &str) -> String {
+ format!(
+ r#"<w:p><w:pPr>{ppr}<w:spacing w:before="240" {spacing}/></w:pPr><w:r>{run}<w:t>{t}</w:t></w:r></w:p>"#
+ )
+}
+
+#[test]
+fn space_before_stays_at_a_page_top_only_after_a_page_break() {
+ let page_break = r#"<w:br w:type="page"/>"#;
+ let body = [
+ para("One"),
+ // Starting a page of its own is no hard break.
+ spaced("Two", "<w:pageBreakBefore/>", "", ""),
+ format!("<w:p><w:r>{page_break}</w:r></w:p>"),
+ spaced("Three", "", "", ""),
+ // A paragraph that starts with a page break starts after it.
+ spaced("Four", "", "", page_break),
+ // (Exactly spaced lines leave the space out there.)
+ spaced("Five", "", r#"w:line="300" w:lineRule="exact""#, page_break),
+ ]
+ .concat();
+ let l = layout(&format!("{body}{LETTER}"), &arial_10());
+ assert_eq!(l.pages.len(), 5);
+ for (page, t, y) in [
+ (1, "Two", 72.0),
+ (2, "Three", 84.0),
+ (3, "Four", 84.0),
+ (4, "Five", 72.0),
+ ] {
+ let line = find(&l, page, t);
+ assert!((line.y - y).abs() < 0.01, "{t}: {}", line.y);
+ }
+ // A heading kept with the paragraph after it moves to the next page
+ // without its space before.
+ let filler: String = (0..54).map(|k| para(&format!("Line {k}"))).collect();
+ let body = format!(
+ "{filler}{}{}{LETTER}",
+ spaced("Heading", "<w:keepNext/>", "", ""),
+ para(&"word ".repeat(200)),
+ );
+ let l = layout(&body, &arial_10());
+ let heading = find(&l, 1, "Heading");
+ assert!((heading.y - 72.0).abs() < 0.01, "{}", heading.y);
+}
+
+#[test]
+fn sections_keep_space_before_from_word_2013_on() {
+ let body = format!(
+ "{}{}{}<w:sectPr>{PAGE}</w:sectPr>",
+ para("One"),
+ section_end("nextPage", ""),
+ spaced("Two", "", "", ""),
+ );
+ for (mode, y) in [(14, 72.0), (15, 84.0)] {
+ let settings = format!(
+ r#"<w:compat><w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="{mode}"/></w:compat>"#
+ );
+ let l = layout(
+ &body,
+ &Parts {
+ settings: Some(&settings),
+ ..arial_10()
+ },
+ );
+ let two = find(&l, 1, "Two");
+ assert!((two.y - y).abs() < 0.01, "mode {mode}: {}", two.y);
+ }
+}
+
+#[test]
+fn footnotes_leave_room_for_the_continuation_notice() {
+ let separator = r#"<w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote>"#;
+ // An empty paragraph with a 20pt mark: 23pt high.
+ let notice = r#"<w:footnote w:type="continuationNotice" w:id="0"><w:p><w:pPr><w:rPr><w:sz w:val="40"/></w:rPr></w:pPr></w:p></w:footnote>"#;
+ let note = r#"<w:footnote w:id="1"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> The note.</w:t></w:r></w:p></w:footnote>"#;
+ let body = format!(
+ r#"<w:p><w:r><w:t>Text</w:t></w:r><w:r><w:footnoteReference w:id="1"/></w:r></w:p>{LETTER}"#
+ );
+ let note_bottom = |footnotes: &str, settings: Option<&str>| {
+ let l = layout(
+ &body,
+ &Parts {
+ footnotes: Some(footnotes),
+ settings,
+ ..arial_10()
+ },
+ );
+ let line = l.pages[0]
+ .lines_of(&StoryRef::Footnote(1))
+ .next()
+ .expect("the note");
+ line.y + line.line().height
+ };
+ let plain = note_bottom(&format!("{separator}{note}"), None);
+ assert!((plain - 720.0).abs() < 0.01, "{plain}");
+ let with_notice = note_bottom(&format!("{separator}{notice}{note}"), None);
+ assert!(
+ (with_notice - (720.0 - 20.0 * 1.1499)).abs() < 0.01,
+ "{with_notice}"
+ );
+ // From Word 2013 on, the notes reach down to the margin.
+ let word_2013 = r#"<w:compat><w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="15"/></w:compat>"#;
+ let modern = note_bottom(&format!("{separator}{notice}{note}"), Some(word_2013));
+ assert!((modern - 720.0).abs() < 0.01, "{modern}");
+}
+
+#[test]
+fn space_after_must_fit_above_footnotes() {
+ // One-line paragraphs 11.5pt high with 12pt after, the first with a
+ // footnote: the notes (default 12pt separator and an 11.5pt note) end
+ // the column at 696.5.
+ let paras = |note: bool| -> String {
+ (0..30)
+ .map(|k| {
+ let reference = if note && k == 0 {
+ r#"<w:r><w:footnoteReference w:id="1"/></w:r>"#
+ } else {
+ ""
+ };
+ format!(
+ r#"<w:p><w:pPr><w:spacing w:after="240"/></w:pPr><w:r><w:t>P{k}</w:t></w:r>{reference}</w:p>"#
+ )
+ })
+ .collect()
+ };
+ let footnotes = r#"<w:footnote w:id="1"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> The note.</w:t></w:r></w:p></w:footnote>"#;
+ let count = |note: bool| {
+ let l = layout(
+ &format!("{}{LETTER}", paras(note)),
+ &Parts {
+ footnotes: Some(footnotes),
+ ..arial_10()
+ },
+ );
+ page_texts(&l, 0).len()
+ };
+ // The 27th paragraph's line would fit above the notes, its space after
+ // would not. Without notes the space after may run into the margin.
+ assert_eq!(count(true), 26);
+ assert_eq!(count(false), 28);
+}
+
+#[test]
+fn auto_spacing_vanishes_between_items_of_one_list_only() {
+ // Two items of list 1, then two of list 2, all spaced automatically:
+ // none between the items of a list, 14pt between the two lists.
+ let numbering = r#"<w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:numFmt w:val="bullet"/><w:lvlText w:val="-"/></w:lvl></w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num><w:num w:numId="2"><w:abstractNumId w:val="0"/></w:num>"#;
+ let item = |num: u32| {
+ format!(
+ r#"<w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="{num}"/></w:numPr><w:spacing w:before="100" w:beforeAutospacing="1" w:after="100" w:afterAutospacing="1"/></w:pPr><w:r><w:t>Item</w:t></w:r></w:p>"#
+ )
+ };
+ let body = format!("{}{}{}{}{LETTER}", item(1), item(1), item(2), item(2));
+ let parts = Parts {
+ numbering: Some(numbering),
+ ..arial_10()
+ };
+ let l = layout(&body, &parts);
+ let ls = lines(&l, &StoryRef::Body);
+ let gap = |k: usize| ls[k + 1].y - (ls[k].y + ls[k].line().height);
+ assert!(gap(0).abs() < 0.01, "{}", gap(0));
+ assert!((gap(1) - 14.0).abs() < 0.01, "{}", gap(1));
+ assert!(gap(2).abs() < 0.01, "{}", gap(2));
+}
diff --git a/crates/docx_engine/src/layout/flow/textbox.rs b/crates/docx_engine/src/layout/flow/textbox.rs
new file mode 100644
index 0000000000..c5ef0d09ec
--- /dev/null
+++ b/crates/docx_engine/src/layout/flow/textbox.rs
@@ -0,0 +1,58 @@
+//! Text boxes: the text of a floating shape, laid out in the shape once the
+//! shape has its place on the page.
+
+use super::super::drawing::TextAnchor;
+use super::super::inline::FieldValues;
+use super::super::{Item, StoryRef};
+use super::stack::{PendingAnchor, StackCtx, stack_story};
+use super::{Env, offset_items};
+use crate::model::block::IdGen;
+use crate::model::parse::StoryReader;
+use pptx_engine::path::Rect;
+
+/// The text of the shape of `a` laid out in `rect`, where the shape went.
+pub(super) fn text_box_items(
+ env: &Env<'_>,
+ fields: &FieldValues,
+ a: &PendingAnchor,
+ rect: Rect,
+) -> Vec<Item> {
+ let Some(tb) = a.drawing.text_box() else {
+ return Vec::new();
+ };
+ let mut ids = IdGen::sequential();
+ let story = StoryReader::new(&a.drawing.tree, &mut ids)
+ .read(tb.content)
+ .story;
+ let [left, top, right, bottom] = tb.insets;
+ let stack = stack_story(
+ env,
+ &story,
+ None,
+ &StackCtx {
+ story: StoryRef::TextBox(a.block.clone(), a.object),
+ width: (rect.w - left - right).max(1.0),
+ table: Default::default(),
+ fields: fields.clone(),
+ note_number: None,
+ float_frames: false,
+ page: None,
+ },
+ );
+ let room = rect.h - top - bottom;
+ let dy = match tb.anchor {
+ TextAnchor::Top => 0.0,
+ TextAnchor::Middle => (room - stack.height) / 2.0,
+ TextAnchor::Bottom => room - stack.height,
+ }
+ .max(0.0);
+ let mut items = stack.items;
+ offset_items(&mut items, rect.x + left, rect.y + top + dy);
+ // Text that does not fit in the shape is cut off at its edges.
+ for it in &mut items {
+ if let Item::Line(l) = it {
+ l.clip = Some(rect);
+ }
+ }
+ items
+}
diff --git a/crates/docx_engine/src/layout/fonts.rs b/crates/docx_engine/src/layout/fonts.rs
new file mode 100644
index 0000000000..c04bbcee3a
--- /dev/null
+++ b/crates/docx_engine/src/layout/fonts.rs
@@ -0,0 +1,381 @@
+//! Font selection and text measurement for layout.
+//!
+//! Word measures with GDI metrics: a line of "single" spacing is the font's
+//! Windows ascent plus descent plus whatever external leading the `hhea`
+//! line gap adds beyond them. The bundled substitutes (Liberation, Carlito,
+//! Caladea) share their originals' advance widths and vertical metrics, so
+//! line breaks and line heights match the originals.
+
+mod widths;
+
+pub use widths::Widths;
+
+use crate::hash::FxMap;
+use pptx_engine::font::{FaceId, FontChoice, FontDb, SymbolFont, remap_symbol};
+use std::cell::RefCell;
+
+/// Vertical metrics of a face in em units, as Word uses them.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct VMetrics {
+ /// Ascent above the baseline.
+ pub ascent: f32,
+ /// Descent below the baseline.
+ pub descent: f32,
+ /// External leading Word adds to single line spacing.
+ pub leading: f32,
+}
+
+impl VMetrics {
+ /// Height of a single-spaced line, in em.
+ pub fn line(&self) -> f32 {
+ self.ascent + self.descent + self.leading
+ }
+}
+
+/// Vertical metrics (units per em, win ascent, win descent, hhea ascender,
+/// hhea descender, hhea line gap) of the fonts Word documents name most,
+/// taken from the Microsoft originals. Layout uses them whenever a document
+/// asks for one of these families, so line heights match Word even where
+/// the bundled substitute's vertical metrics differ (Caladea's do, and the
+/// Unicode face that draws Symbol and Wingdings bullets).
+const TRUE_METRICS: &[(&str, [f32; 6])] = &[
+ (
+ "times new roman",
+ [2048.0, 1825.0, 443.0, 1825.0, 443.0, 87.0],
+ ),
+ ("arial", [2048.0, 1854.0, 434.0, 1854.0, 434.0, 67.0]),
+ ("calibri", [2048.0, 1950.0, 550.0, 1536.0, 512.0, 452.0]),
+ (
+ "calibri light",
+ [2048.0, 1950.0, 550.0, 1536.0, 512.0, 452.0],
+ ),
+ ("cambria", [2048.0, 1946.0, 455.0, 1946.0, 455.0, 0.0]),
+ ("courier new", [2048.0, 1705.0, 615.0, 1705.0, 615.0, 0.0]),
+ ("verdana", [2048.0, 2059.0, 430.0, 2059.0, 430.0, 0.0]),
+ ("tahoma", [2048.0, 2049.0, 423.0, 2049.0, 423.0, 0.0]),
+ ("georgia", [2048.0, 1878.0, 449.0, 1878.0, 449.0, 0.0]),
+ (
+ "simplified arabic",
+ [2048.0, 2416.0, 979.0, 2416.0, 979.0, 0.0],
+ ),
+ (
+ "traditional arabic",
+ [2048.0, 2095.0, 1044.0, 2095.0, 1044.0, 0.0],
+ ),
+ ("symbol", [2048.0, 2059.0, 443.0, 2059.0, 443.0, 0.0]),
+ ("wingdings", [2048.0, 1841.0, 420.0, 1841.0, 420.0, 0.0]),
+];
+
+/// Arabic families drawn with a Noto substitute: how wide their letters
+/// are relative to the substitute's, and their space (em), measured from
+/// the originals so lines break where Word breaks them.
+const ARABIC_WIDTHS: &[(&str, f32, f32)] = &[("simplified arabic", 0.875, 0.317)];
+
+/// Families drawn by squeezing their wider substitute: Arial Narrow is
+/// Arial at 82% of its width; Lucida Sans runs a little narrower than the
+/// DejaVu Sans that stands in for it.
+const CONDENSED: &[(&str, f32)] = &[
+ ("arial narrow", 0.82),
+ ("liberation sans narrow", 0.82),
+ ("helvetica narrow", 0.82),
+ ("helvetica condensed", 0.82),
+ ("lucida sans", 0.965),
+ ("lucida sans unicode", 0.965),
+];
+
+/// A face whose `n` is at least this wide (em) is not a condensed face.
+const REGULAR_N_WIDTH: f32 = 0.5;
+
+/// Average advance (em) of Arabic letters in joined text (Simplified
+/// Arabic, Arial, Times New Roman measure about this much).
+const ARABIC_ADVANCE: f32 = 0.35;
+/// Average advance (em) of Hebrew letters.
+const HEBREW_ADVANCE: f32 = 0.5;
+
+/// The typical advance (em) of a character of a script no bundled face
+/// covers, so layout keeps the text's length without the font.
+pub fn missing_advance(c: char) -> Option<f32> {
+ if is_wide(c) {
+ // Every CJK font draws these one em wide.
+ return Some(1.0);
+ }
+ match c as u32 {
+ // Vowel marks and other combining signs take no room.
+ 0x064B..=0x065F
+ | 0x0670
+ | 0x06D6..=0x06ED
+ | 0x0591..=0x05BD
+ | 0x05BF
+ | 0x05C1
+ | 0x05C2
+ | 0x05C4
+ | 0x05C5
+ | 0x05C7 => Some(0.0),
+ 0x0600..=0x06FF | 0x0750..=0x077F | 0x08A0..=0x08FF | 0xFB50..=0xFDFF | 0xFE70..=0xFEFF => {
+ Some(ARABIC_ADVANCE)
+ }
+ 0x0590..=0x05FF | 0xFB1D..=0xFB4F => Some(HEBREW_ADVANCE),
+ _ => None,
+ }
+}
+
+/// Whether a character is East Asian wide or full-width (ideographs, kana,
+/// hangul, CJK punctuation and full-width forms): one em in any CJK font.
+pub fn is_wide(c: char) -> bool {
+ matches!(c as u32,
+ 0x1100..=0x115F | 0x2E80..=0x303E | 0x3041..=0x33FF | 0x3400..=0x4DBF
+ | 0x4E00..=0x9FFF | 0xA000..=0xA4CF | 0xA960..=0xA97F | 0xAC00..=0xD7A3
+ | 0xF900..=0xFAFF | 0xFE10..=0xFE19 | 0xFE30..=0xFE6F | 0xFF01..=0xFF60
+ | 0xFFE0..=0xFFE6 | 0x20000..=0x2FFFD | 0x30000..=0x3FFFD)
+}
+
+/// A resolved font: face plus synthesis flags.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub struct Font {
+ /// The face.
+ pub face: FaceId,
+ /// Embolden outlines.
+ pub synthetic_bold: bool,
+ /// Slant outlines.
+ pub synthetic_italic: bool,
+ /// Characters are remapped from a symbol font encoding.
+ pub symbol: Option<SymbolKind>,
+ /// The advances of the font the face stands in for, when known.
+ pub widths: Option<Widths>,
+}
+
+/// A symbol font encoding (hashable mirror of [`SymbolFont`]).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum SymbolKind {
+ /// Wingdings.
+ Wingdings,
+ /// Wingdings 2.
+ Wingdings2,
+ /// Wingdings 3.
+ Wingdings3,
+ /// Symbol.
+ Symbol,
+ /// Webdings.
+ Webdings,
+}
+
+impl SymbolKind {
+ fn from_font(f: SymbolFont) -> Self {
+ match f {
+ SymbolFont::Wingdings => SymbolKind::Wingdings,
+ SymbolFont::Wingdings2 => SymbolKind::Wingdings2,
+ SymbolFont::Wingdings3 => SymbolKind::Wingdings3,
+ SymbolFont::Symbol => SymbolKind::Symbol,
+ SymbolFont::Webdings => SymbolKind::Webdings,
+ }
+ }
+
+ fn to_font(self) -> SymbolFont {
+ match self {
+ SymbolKind::Wingdings => SymbolFont::Wingdings,
+ SymbolKind::Wingdings2 => SymbolFont::Wingdings2,
+ SymbolKind::Wingdings3 => SymbolFont::Wingdings3,
+ SymbolKind::Symbol => SymbolFont::Symbol,
+ SymbolKind::Webdings => SymbolFont::Webdings,
+ }
+ }
+}
+
+/// A measured character.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct Glyph {
+ /// The face that draws it (the requested one or a fallback).
+ pub font: Font,
+ /// Glyph id (0 = none).
+ pub id: u16,
+ /// Advance in em units.
+ pub advance: f32,
+}
+
+/// Fonts plus measurement caches. Interior mutability keeps layout code
+/// free to measure through shared references.
+pub struct Fonts<'a> {
+ db: &'a FontDb,
+ /// Per family, the font for each of regular, italic, bold and bold
+ /// italic (`Some(None)`: none). Looked up for every character, so by
+ /// `&str` without allocating.
+ choices: RefCell<FxMap<String, [Option<Option<Font>>; 4]>>,
+ glyphs: RefCell<FxMap<(Font, char), Glyph>>,
+ metrics: RefCell<FxMap<FaceId, VMetrics>>,
+}
+
+impl<'a> Fonts<'a> {
+ /// Wraps a font database.
+ pub fn new(db: &'a FontDb) -> Self {
+ Self {
+ db,
+ choices: RefCell::new(FxMap::default()),
+ glyphs: RefCell::new(FxMap::default()),
+ metrics: RefCell::new(FxMap::default()),
+ }
+ }
+
+ /// The database.
+ pub fn db(&self) -> &'a FontDb {
+ self.db
+ }
+
+ /// The font for a family name and style.
+ pub fn select(&self, family: &str, bold: bool, italic: bool) -> Option<Font> {
+ let style = usize::from(bold) * 2 + usize::from(italic);
+ if let Some(Some(known)) = self.choices.borrow().get(family).map(|c| c[style]) {
+ return known;
+ }
+ let font = self.choose(family, bold, italic);
+ self.choices
+ .borrow_mut()
+ .entry(family.to_owned())
+ .or_default()[style] = Some(font);
+ font
+ }
+
+ fn choose(&self, family: &str, bold: bool, italic: bool) -> Option<Font> {
+ let lower = family.trim().to_lowercase();
+ let symbol = SymbolFont::from_family(&lower).map(SymbolKind::from_font);
+ let choice: FontChoice = if symbol.is_some() {
+ // Symbol fonts are drawn from a face with the Unicode equivalents.
+ self.db.select("DejaVu Sans", bold, italic)?
+ } else {
+ self.db.select(family, bold, italic)?
+ };
+ Some(Font {
+ face: choice.face,
+ synthetic_bold: choice.synthetic_bold,
+ synthetic_italic: choice.synthetic_italic,
+ symbol,
+ widths: Widths::for_family(&lower, bold),
+ })
+ }
+
+ /// Vertical metrics for text a document set in `family`, drawn with
+ /// `face`: the original font's when known, else the face's own.
+ pub fn vmetrics_for(&self, family: &str, face: FaceId) -> VMetrics {
+ let lower = family.trim().to_lowercase();
+ if let Some((_, m)) = TRUE_METRICS.iter().find(|(name, _)| *name == lower) {
+ let [upem, wa, wd, ha, hd, gap] = *m;
+ let leading = (gap - ((wa + wd) - (ha + hd))).max(0.0);
+ return VMetrics {
+ ascent: wa / upem,
+ descent: wd / upem,
+ leading: leading / upem,
+ };
+ }
+ self.vmetrics(face)
+ }
+
+ /// Horizontal scale that makes `face` as wide as `family` when the face
+ /// substitutes a condensed family at regular width (else 1).
+ pub fn width_factor(&self, family: &str, face: FaceId) -> f32 {
+ let lower = family.trim().to_lowercase();
+ let Some((_, factor)) = CONDENSED.iter().find(|(name, _)| *name == lower) else {
+ return 1.0;
+ };
+ let n = self
+ .db
+ .glyph(face, 'n')
+ .map_or(0.0, |g| self.db.advance(face, g));
+ if n >= REGULAR_N_WIDTH { *factor } else { 1.0 }
+ }
+
+ /// For an Arabic family drawn by a substitute: the scale of its
+ /// letters' advances and its space's advance (em).
+ pub fn arabic_widths(&self, family: &str) -> Option<(f32, f32)> {
+ let family = family.trim();
+ ARABIC_WIDTHS
+ .iter()
+ .find(|(name, _, _)| name.eq_ignore_ascii_case(family))
+ .map(|&(_, letters, space)| (letters, space))
+ }
+
+ /// Vertical metrics of a face.
+ pub fn vmetrics(&self, face: FaceId) -> VMetrics {
+ if let Some(m) = self.metrics.borrow().get(&face) {
+ return *m;
+ }
+ let fm = self.db.metrics(face);
+ let (mut ascent, mut descent) = (fm.win_ascent, fm.win_descent);
+ if ascent + descent <= 0.0 {
+ ascent = fm.ascent;
+ descent = fm.descent;
+ }
+ let hhea = fm.ascent + fm.descent;
+ let leading = (fm.line_gap - ((ascent + descent) - hhea)).max(0.0);
+ let m = VMetrics {
+ ascent,
+ descent,
+ leading,
+ };
+ self.metrics.borrow_mut().insert(face, m);
+ m
+ }
+
+ /// Measures one character in `font`, falling back to another face when
+ /// the font has no glyph for it.
+ pub fn glyph(&self, font: Font, ch: char) -> Glyph {
+ if let Some(g) = self.glyphs.borrow().get(&(font, ch)) {
+ return *g;
+ }
+ let mapped = match font.symbol {
+ Some(s) => remap_symbol(s.to_font(), ch),
+ None => ch,
+ };
+ let g = match self.db.glyph(font.face, mapped) {
+ Some(id) => Glyph {
+ font,
+ id,
+ advance: font
+ .widths
+ .and_then(|w| w.advance(mapped))
+ .unwrap_or_else(|| self.db.advance(font.face, id)),
+ },
+ None => {
+ let fallback = self.db.fallback_for(
+ mapped,
+ font.face,
+ font.synthetic_bold,
+ font.synthetic_italic,
+ );
+ match fallback.and_then(|c| self.db.glyph(c.face, mapped).map(|id| (c, id))) {
+ Some((c, id)) => Glyph {
+ font: Font {
+ face: c.face,
+ synthetic_bold: c.synthetic_bold,
+ synthetic_italic: c.synthetic_italic,
+ symbol: None,
+ widths: None,
+ },
+ id,
+ advance: self.db.advance(c.face, id),
+ },
+ None => {
+ // No face has it: the script's typical advance, else
+ // a space's so text keeps its shape.
+ let space = self.db.glyph(font.face, ' ');
+ Glyph {
+ font,
+ id: 0,
+ advance: missing_advance(ch).unwrap_or_else(|| {
+ space.map_or(0.25, |s| self.db.advance(font.face, s))
+ }),
+ }
+ }
+ }
+ }
+ };
+ self.glyphs.borrow_mut().insert((font, ch), g);
+ g
+ }
+
+ /// Pair kerning in em units.
+ pub fn kerning(&self, face: FaceId, left: u16, right: u16) -> f32 {
+ self.db.kerning(face, left, right)
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/layout/fonts/test.rs b/crates/docx_engine/src/layout/fonts/test.rs
new file mode 100644
index 0000000000..0b3637e362
--- /dev/null
+++ b/crates/docx_engine/src/layout/fonts/test.rs
@@ -0,0 +1,58 @@
+use super::*;
+use crate::test_support::fonts;
+
+#[test]
+fn east_asian_characters_without_a_face_take_an_em() {
+ let f = Fonts::new(fonts());
+ let font = f.select("SimSun", false, false).unwrap();
+ for c in ['中', 'あ', 'カ', '한', ',', '\u{3000}'] {
+ assert!(is_wide(c), "{c}");
+ assert!((f.glyph(font, c).advance - 1.0).abs() < 1e-6, "{c}");
+ }
+ assert!(!is_wide('a'));
+ assert!(!is_wide('\u{FF61}'), "half-width forms stay narrow");
+}
+
+#[test]
+fn arabic_and_hebrew_letters_come_from_the_bundled_faces() {
+ let f = Fonts::new(fonts());
+ let font = f.select("Simplified Arabic", false, false).unwrap();
+ let beh = f.glyph(font, 'ب');
+ assert_ne!(beh.id, 0);
+ assert_eq!(f.db().family(beh.font.face), "Noto Naskh Arabic");
+ let arial = f.select("Arial", false, false).unwrap();
+ let shin = f.glyph(arial, 'ש');
+ assert_ne!(shin.id, 0);
+ assert_eq!(f.db().family(shin.font.face), "Noto Sans Hebrew");
+ // Without a face for them, letters keep their script's typical width.
+ assert_eq!(missing_advance('ب'), Some(ARABIC_ADVANCE));
+ assert_eq!(missing_advance('\u{064E}'), Some(0.0));
+ assert_eq!(missing_advance('ש'), Some(HEBREW_ADVANCE));
+ assert_eq!(missing_advance('a'), None);
+}
+
+#[test]
+fn condensed_families_squeeze_regular_substitutes() {
+ let f = Fonts::new(fonts());
+ let narrow = f.select("Arial Narrow", false, false).unwrap();
+ assert!((f.width_factor("Arial Narrow", narrow.face) - 0.82).abs() < 1e-6);
+ let arial = f.select("Arial", false, false).unwrap();
+ assert!((f.width_factor("Arial", arial.face) - 1.0).abs() < 1e-6);
+ let lucida = f.select("Lucida Sans", false, false).unwrap();
+ assert!((f.width_factor("Lucida Sans", lucida.face) - 0.965).abs() < 1e-6);
+}
+
+#[test]
+fn tahoma_takes_its_own_advances() {
+ let f = Fonts::new(fonts());
+ let regular = f.select("Tahoma", false, false).unwrap();
+ let bold = f.select("Tahoma", true, false).unwrap();
+ let arial = f.select("Arial", false, false).unwrap();
+ assert_eq!(regular.face, arial.face, "drawn with the Arial substitute");
+ assert!((f.glyph(regular, 't').advance - 0.334).abs() < 1e-6);
+ assert!((f.glyph(regular, ' ').advance - 0.313).abs() < 1e-6);
+ assert!((f.glyph(bold, 'W').advance - 1.028).abs() < 1e-6);
+ // Characters the table lacks keep the substitute's advance.
+ let z = f.glyph(regular, 'z').advance;
+ assert!((z - f.glyph(arial, 'z').advance).abs() < 1e-6);
+}
diff --git a/crates/docx_engine/src/layout/fonts/widths.rs b/crates/docx_engine/src/layout/fonts/widths.rs
new file mode 100644
index 0000000000..744e5f65fe
--- /dev/null
+++ b/crates/docx_engine/src/layout/fonts/widths.rs
@@ -0,0 +1,76 @@
+//! Advance widths of fonts no bundled face matches width for width.
+//!
+//! Tahoma is drawn with Liberation Sans, whose letters are as wide on
+//! average but not one by one (Tahoma's capitals are narrower, its spaces
+//! and `t`, `f` and `r` wider), so lines of Tahoma would break elsewhere
+//! than in Word. These tables hold the originals' advances, in thousandths
+//! of an em, for the characters documents use most (read from Word's PDF
+//! exports of documents set in Tahoma); other characters keep the
+//! substitute's advance.
+
+/// A font whose advances are known here.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum Widths {
+ /// Tahoma (also Word's "MS Shell Dlg 2").
+ Tahoma,
+ /// Tahoma Bold.
+ TahomaBold,
+}
+
+/// Thousandths of an em per em.
+const MILLI: f32 = 1000.0;
+
+/// Tahoma's advances, sorted by character.
+#[rustfmt::skip]
+const TAHOMA: &[(char, u16)] = &[
+ (' ', 313), ('#', 728), ('%', 977), ('\'', 211), ('(', 383), (')', 383), ('+', 728),
+ (',', 303), ('-', 363), ('.', 303), ('/', 382), ('0', 546), ('1', 546), ('2', 546),
+ ('3', 546), ('4', 546), ('5', 546), ('6', 546), ('7', 546), ('8', 546), ('9', 546),
+ (':', 354), (';', 354), ('?', 474), ('@', 909), ('A', 600), ('B', 589), ('C', 601),
+ ('D', 678), ('E', 561), ('F', 521), ('G', 667), ('H', 675), ('I', 373), ('J', 417),
+ ('K', 588), ('L', 498), ('M', 771), ('N', 667), ('O', 708), ('P', 551), ('Q', 708),
+ ('R', 621), ('S', 557), ('T', 584), ('U', 656), ('V', 597), ('W', 902), ('Y', 576),
+ ('a', 525), ('b', 553), ('c', 461), ('d', 553), ('e', 526), ('f', 318), ('g', 553),
+ ('h', 558), ('i', 229), ('j', 282), ('k', 498), ('l', 229), ('m', 840), ('n', 558),
+ ('o', 543), ('p', 553), ('q', 553), ('r', 360), ('s', 446), ('t', 334), ('u', 558),
+ ('v', 498), ('w', 742), ('x', 495), ('y', 498), ('\u{00A9}', 929), ('\u{2013}', 546),
+ ('\u{2018}', 211), ('\u{2019}', 211),
+];
+
+/// Tahoma Bold's advances, sorted by character.
+#[rustfmt::skip]
+const TAHOMA_BOLD: &[(char, u16)] = &[
+ (' ', 293), ('(', 454), (')', 454), (',', 313), ('-', 431), ('.', 313), ('/', 577),
+ ('0', 637), ('1', 637), ('2', 637), ('3', 637), ('4', 637), ('5', 637), ('6', 637),
+ ('7', 637), ('8', 637), ('9', 637), (':', 363), ('?', 566), ('@', 920), ('A', 685),
+ ('B', 686), ('C', 667), ('D', 757), ('E', 615), ('F', 581), ('G', 745), ('H', 764),
+ ('I', 483), ('J', 500), ('L', 572), ('M', 893), ('N', 771), ('O', 770), ('P', 657),
+ ('R', 726), ('S', 633), ('T', 612), ('W', 1028), ('a', 599), ('b', 632), ('c', 527),
+ ('d', 629), ('e', 594), ('f', 382), ('g', 629), ('h', 640), ('i', 302), ('j', 363),
+ ('k', 603), ('l', 302), ('m', 954), ('n', 640), ('o', 617), ('p', 629), ('q', 629),
+ ('r', 434), ('s', 515), ('t', 416), ('u', 640), ('v', 579), ('w', 890), ('x', 604),
+ ('y', 576), ('\u{2013}', 637), ('\u{2018}', 275), ('\u{2019}', 275),
+];
+
+impl Widths {
+ /// The table for a family (lowercase) in a weight, if there is one.
+ pub fn for_family(family: &str, bold: bool) -> Option<Self> {
+ match (family, bold) {
+ ("tahoma" | "ms shell dlg 2", false) => Some(Widths::Tahoma),
+ ("tahoma" | "ms shell dlg 2", true) => Some(Widths::TahomaBold),
+ _ => None,
+ }
+ }
+
+ /// The advance of `ch` in em, when known.
+ pub fn advance(self, ch: char) -> Option<f32> {
+ let table = match self {
+ Widths::Tahoma => TAHOMA,
+ Widths::TahomaBold => TAHOMA_BOLD,
+ };
+ table
+ .binary_search_by_key(&ch, |&(c, _)| c)
+ .ok()
+ .map(|i| f32::from(table[i].1) / MILLI)
+ }
+}
diff --git a/crates/docx_engine/src/layout/format.rs b/crates/docx_engine/src/layout/format.rs
new file mode 100644
index 0000000000..9ed014507c
--- /dev/null
+++ b/crates/docx_engine/src/layout/format.rs
@@ -0,0 +1,376 @@
+//! Resolved formatting of paragraphs and runs, with caches.
+
+use crate::hash::FxMap;
+use crate::model::content::{Attrs, key};
+use crate::model::numbering::{Label, Numbering};
+use crate::model::props::{PPr, ParaProps, RPr, RunProps, TblPr, TcPr, ThemeInfo, TrPr};
+use crate::model::section::Section;
+use crate::model::settings::Settings;
+use crate::model::styles::Styles;
+use crate::xml::{Decl, SnippetContext};
+use std::sync::Arc;
+use std::sync::Mutex;
+
+/// The table context of a paragraph: which table style and conditional
+/// formats apply to the cell it is in.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
+pub struct TableCtx {
+ /// Table style id.
+ pub style: Option<String>,
+ /// Applicable conditions, in precedence order.
+ pub conds: Vec<&'static str>,
+}
+
+/// A paragraph's resolved formatting.
+#[derive(Clone, Debug)]
+pub struct ParaFormat {
+ /// Paragraph properties.
+ pub props: ParaProps,
+ /// Run properties every run starts from (defaults, table and paragraph
+ /// styles), before character styles and direct formatting.
+ pub base_rpr: RPr,
+ /// The paragraph mark's resolved run properties.
+ pub mark: Arc<RunProps>,
+ /// Section properties when the paragraph ends a section.
+ pub section: Option<Section>,
+}
+
+/// Table formatting from the table style for one cell.
+#[derive(Clone, Debug, Default)]
+pub struct CellStyle {
+ /// Table properties.
+ pub tbl: TblPr,
+ /// Row properties.
+ pub tr: TrPr,
+ /// Cell properties.
+ pub tc: TcPr,
+}
+
+/// Resolves formatting against a document's style sheet.
+pub struct Formats<'d> {
+ /// Styles.
+ pub styles: &'d Styles,
+ /// Numbering.
+ pub numbering: &'d Numbering,
+ /// Settings.
+ pub settings: &'d Settings,
+ /// Theme.
+ pub theme: &'d ThemeInfo,
+ snippets: SnippetContext,
+ cache: Arc<FormatCache>,
+}
+
+/// Run properties parsed from attribute snippets, by (element name, XML).
+type SnippetRuns = FxMap<(Box<str>, Box<str>), RPr>;
+
+/// Resolved runs by the address of their attribute set and of their
+/// paragraph format, with the attribute set they were resolved for.
+type RunsById = FxMap<(usize, usize), (Attrs, Arc<RunProps>)>;
+
+/// Resolved formats, kept between layouts of the same style sheet.
+#[derive(Debug, Default)]
+pub struct FormatCache {
+ paras: Mutex<FxMap<(String, TableCtx), Arc<ParaFormat>>>,
+ runs: Mutex<FxMap<(Attrs, usize), Arc<RunProps>>>,
+ run_snippets: Mutex<SnippetRuns>,
+ /// Resolved runs by the identity of their attribute set (which the
+ /// entry holds, so the address stays its own) and paragraph format.
+ run_ids: Mutex<RunsById>,
+ parsed: Mutex<Parsed>,
+}
+
+/// Property elements parsed from their XML, by kind (`tblPr`, `tcPr`...).
+#[derive(Default)]
+struct Parsed(FxMap<&'static str, FxMap<Box<str>, Arc<dyn std::any::Any + Send + Sync>>>);
+
+impl std::fmt::Debug for Parsed {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_map()
+ .entries(self.0.iter().map(|(k, v)| (k, v.len())))
+ .finish()
+ }
+}
+
+fn lock<T>(m: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+ m.lock().unwrap_or_else(|e| e.into_inner())
+}
+
+impl<'d> Formats<'d> {
+ /// A resolver for a document's parts.
+ pub fn new(
+ styles: &'d Styles,
+ numbering: &'d Numbering,
+ settings: &'d Settings,
+ theme: &'d ThemeInfo,
+ decls: &[Decl],
+ ) -> Self {
+ Self {
+ styles,
+ numbering,
+ settings,
+ theme,
+ snippets: SnippetContext::new(decls),
+ cache: Arc::new(FormatCache::default()),
+ }
+ }
+
+ /// A resolver that keeps its results in `cache` (which must belong to
+ /// the same style sheet).
+ pub fn with_cache(mut self, cache: Arc<FormatCache>) -> Self {
+ self.cache = cache;
+ self
+ }
+
+ /// The snippet context of the main part.
+ pub fn snippets(&self) -> &SnippetContext {
+ &self.snippets
+ }
+
+ /// A property element read from its XML once per style sheet: tables
+ /// repeat the same row and cell properties, and every layout reads them.
+ pub fn parsed<T: Clone + Send + Sync + 'static>(
+ &self,
+ kind: &'static str,
+ xml: &str,
+ read: impl FnOnce() -> T,
+ ) -> T {
+ if let Some(v) = lock(&self.cache.parsed)
+ .0
+ .get(kind)
+ .and_then(|m| m.get(xml))
+ .and_then(|v| v.downcast_ref::<T>())
+ {
+ return v.clone();
+ }
+ let value = read();
+ lock(&self.cache.parsed)
+ .0
+ .entry(kind)
+ .or_default()
+ .insert(xml.into(), Arc::new(value.clone()));
+ value
+ }
+
+ /// Reads direct paragraph properties from a `w:pPr` snippet.
+ pub fn read_ppr(&self, xml: &str) -> PPr {
+ if xml.is_empty() {
+ return PPr::default();
+ }
+ self.snippets
+ .parse(xml)
+ .map(|t| PPr::read(&t, t.root(), self.theme))
+ .unwrap_or_default()
+ }
+
+ fn table_rpr(&self, table: &TableCtx, into: &mut RPr) {
+ if let Some(ts) = self.styles.table_style(table.style.as_deref()) {
+ into.apply(&ts.rpr, true);
+ for c in &table.conds {
+ if let Some((_, f)) = ts.cond.iter().find(|(t, _)| t == c) {
+ into.apply(&f.rpr, true);
+ }
+ }
+ }
+ }
+
+ fn table_ppr(&self, table: &TableCtx, into: &mut PPr) {
+ if let Some(ts) = self.styles.table_style(table.style.as_deref()) {
+ into.apply(&ts.ppr);
+ for c in &table.conds {
+ if let Some((_, f)) = ts.cond.iter().find(|(t, _)| t == c) {
+ into.apply(&f.ppr);
+ }
+ }
+ }
+ }
+
+ /// Table-style formatting for a cell.
+ pub fn cell_style(&self, table: &TableCtx) -> CellStyle {
+ let mut out = CellStyle::default();
+ if let Some(ts) = self.styles.table_style(table.style.as_deref()) {
+ out.tbl.apply(&ts.tbl);
+ out.tr.apply(&ts.tr);
+ out.tc.apply(&ts.tc);
+ for c in &table.conds {
+ if let Some((_, f)) = ts.cond.iter().find(|(t, _)| t == c) {
+ out.tbl.apply(&f.tbl);
+ out.tr.apply(&f.tr);
+ out.tc.apply(&f.tc);
+ }
+ }
+ }
+ out
+ }
+
+ /// A paragraph's formatting from its `w:pPr` snippet.
+ pub fn paragraph(&self, ppr_xml: &str, table: &TableCtx) -> Arc<ParaFormat> {
+ let cache_key = (ppr_xml.to_owned(), table.clone());
+ if let Some(f) = lock(&self.cache.paras).get(&cache_key) {
+ return Arc::clone(f);
+ }
+ let (direct, section) = if ppr_xml.is_empty() {
+ (PPr::default(), None)
+ } else {
+ match self.snippets.parse(ppr_xml) {
+ Ok(t) => {
+ let p = PPr::read(&t, t.root(), self.theme);
+ let section = t
+ .w_child(t.root(), "sectPr")
+ .map(|s| Section::read(&t, s, self.theme));
+ (p, section)
+ }
+ Err(_) => (PPr::default(), None),
+ }
+ };
+ let style = self.styles.paragraph_style(direct.style.as_deref());
+ let mut props = self.styles.doc_ppr.clone();
+ self.table_ppr(table, &mut props);
+ let style_num = style.map(|s| s.ppr.num).unwrap_or_default();
+ let num_id = direct.num.num_id.or(style_num.num_id);
+ let ilvl = direct.num.ilvl.or(style_num.ilvl).unwrap_or(0);
+ let level_ppr = num_id
+ .filter(|id| *id > 0)
+ .and_then(|id| self.numbering.level_ppr(id, ilvl, self.styles));
+ let numbering_from_style = direct.num.num_id.is_none() && style_num.num_id.is_some();
+ match (&level_ppr, style) {
+ (Some(lp), Some(s)) if numbering_from_style => {
+ props.apply(lp);
+ props.apply(&s.ppr);
+ }
+ (Some(lp), Some(s)) => {
+ props.apply(&s.ppr);
+ props.apply(lp);
+ }
+ (Some(lp), None) => props.apply(lp),
+ (None, Some(s)) => props.apply(&s.ppr),
+ (None, None) => {}
+ }
+ if direct.num.num_id == Some(0) && style_num.num_id.is_some_and(|id| id > 0) {
+ // Turning a list style's numbering off also drops the indents
+ // that go with it.
+ props.ind_left = self.styles.doc_ppr.ind_left;
+ props.ind_first = self.styles.doc_ppr.ind_first;
+ }
+ props.apply(&direct);
+ props.style = style.map(|s| s.id.clone()).or(direct.style.clone());
+ // Run base: defaults, table style, paragraph style (toggling).
+ let mut base_rpr = self.styles.doc_rpr.clone();
+ self.table_rpr(table, &mut base_rpr);
+ if let Some(s) = style {
+ base_rpr.apply(&s.rpr, true);
+ }
+ let mut mark = base_rpr.clone();
+ if let Some(cs) = direct.mark.style.as_deref()
+ && let Some(c) = self.styles.character_style(Some(cs))
+ {
+ mark.apply(&c.rpr, true);
+ }
+ mark.apply(&direct.mark, false);
+ let format = Arc::new(ParaFormat {
+ props: props.resolve(),
+ base_rpr,
+ mark: Arc::new(mark.resolve()),
+ section,
+ });
+ lock(&self.cache.paras).insert(cache_key, Arc::clone(&format));
+ format
+ }
+
+ fn snippet_rpr(&self, qname: &str, xml: &str) -> RPr {
+ let cache_key: (Box<str>, Box<str>) = (qname.into(), xml.into());
+ if let Some(r) = lock(&self.cache.run_snippets).get(&cache_key) {
+ return r.clone();
+ }
+ let mut r = RPr::default();
+ if let Ok(t) = self.snippets.parse(xml) {
+ r.read_child(&t, t.root(), self.theme);
+ }
+ lock(&self.cache.run_snippets).insert(cache_key, r.clone());
+ r
+ }
+
+ /// Direct run properties carried by span attributes.
+ pub fn direct_rpr(&self, attrs: &Attrs) -> RPr {
+ let mut r = RPr::default();
+ for (qname, xml) in attrs.run_props() {
+ let part = self.snippet_rpr(qname, xml);
+ r.apply(&part, false);
+ }
+ r
+ }
+
+ /// A run's resolved properties within a paragraph.
+ pub fn run(&self, attrs: &Attrs, para: &Arc<ParaFormat>) -> Arc<RunProps> {
+ // Spans share attribute sets, and a laid-out paragraph keeps its
+ // format: most runs are found by identity without hashing.
+ let id_key = (attrs.ptr(), Arc::as_ptr(para) as usize);
+ if let Some((held, r)) = lock(&self.cache.run_ids).get(&id_key)
+ && held.same(attrs)
+ {
+ return Arc::clone(r);
+ }
+ let resolved = self.run_by_value(attrs, para);
+ let mut ids = lock(&self.cache.run_ids);
+ if ids.len() > 200_000 {
+ ids.clear();
+ }
+ ids.insert(id_key, (attrs.clone(), Arc::clone(&resolved)));
+ resolved
+ }
+
+ fn run_by_value(&self, attrs: &Attrs, para: &Arc<ParaFormat>) -> Arc<RunProps> {
+ // Spans differ only in their run-property keys for formatting purposes.
+ let fmt_attrs = attrs.without(|k| !k.starts_with(key::RUN_PROP));
+ let cache_key = (fmt_attrs, Arc::as_ptr(para) as usize);
+ if let Some(r) = lock(&self.cache.runs).get(&cache_key) {
+ return Arc::clone(r);
+ }
+ let direct = self.direct_rpr(attrs);
+ let mut r = para.base_rpr.clone();
+ if let Some(cs) = direct.style.as_deref()
+ && let Some(c) = self.styles.character_style(Some(cs))
+ {
+ if c.name.eq_ignore_ascii_case("hyperlink") && self.is_toc_entry(para) {
+ // Word shows table of contents links in the entry's own
+ // formatting, without the link color or underline.
+ let mut link = c.rpr.clone();
+ link.color = None;
+ link.underline = None;
+ r.apply(&link, true);
+ } else {
+ r.apply(&c.rpr, true);
+ }
+ }
+ r.apply(&direct, false);
+ let resolved = Arc::new(r.resolve());
+ lock(&self.cache.runs).insert(cache_key, Arc::clone(&resolved));
+ resolved
+ }
+
+ /// Whether a paragraph is a table of contents entry (a built-in `toc N`
+ /// style, whatever the document's language calls it).
+ fn is_toc_entry(&self, para: &ParaFormat) -> bool {
+ self.styles
+ .paragraph_style(para.props.style.as_deref())
+ .is_some_and(|s| {
+ let name = s.name.to_ascii_lowercase();
+ name.strip_prefix("toc ")
+ .is_some_and(|n| n.trim().parse::<u8>().is_ok())
+ })
+ }
+
+ /// Label run properties: the paragraph mark's, with the level's on top.
+ pub fn label_props(&self, para: &ParaFormat, label: &Label) -> RunProps {
+ let mut r = para.base_rpr.clone();
+ // The paragraph mark's direct formatting carries over to the number.
+ let mark = &para.props.mark;
+ r.apply(mark, false);
+ r.apply(&label.rpr, false);
+ let mut props = r.resolve();
+ // Numbers are never underlined or struck through by the paragraph's text formatting.
+ if label.rpr.underline.is_none() {
+ props.underline = None;
+ }
+ props
+ }
+}
diff --git a/crates/docx_engine/src/layout/inline.rs b/crates/docx_engine/src/layout/inline.rs
new file mode 100644
index 0000000000..449d3dd8e3
--- /dev/null
+++ b/crates/docx_engine/src/layout/inline.rs
@@ -0,0 +1,1160 @@
+//! A paragraph's content as measured clusters, ready for line breaking.
+//!
+//! Every character becomes a cluster with its advance, font and break
+//! opportunity; list labels, field results that depend on the page, and
+//! note numbers are synthetic clusters that occupy no content offsets.
+
+use super::bidi::{self, Class};
+use super::drawing::{Drawing, parse_drawing};
+use super::fonts::{Font, Fonts};
+use super::format::{Formats, ParaFormat};
+use crate::model::block::Block;
+use crate::model::content::Attrs;
+use crate::model::numbering::{Label, NumFmt, Suffix, format_number};
+use crate::model::props::{RunProps, VertAlign};
+use crate::xml::parse_int;
+use pptx_engine::font::arabic::{self, JoinForm, Joining};
+use pptx_engine::model::color::Rgba;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+mod script;
+
+use script::{breaks_after, is_cjk, is_complex};
+
+/// Superscript and subscript size relative to the run (LibreOffice's
+/// Word-compatible defaults).
+const SCRIPT_SIZE: f32 = 0.58;
+/// Superscript raise as a fraction of the run size.
+const SUPER_RAISE: f32 = 0.33;
+/// Subscript drop as a fraction of the run size.
+const SUB_DROP: f32 = 0.08;
+/// Small capitals size relative to the run.
+const SMALL_CAPS_SIZE: f32 = 0.8;
+/// Resolution of the device Word measures some runs on.
+const DEVICE_DPI: f32 = 600.0;
+
+/// Whether Word measures a run with a device font: runs with character
+/// scaling or kerning come out as wide as a font of a whole number of
+/// pixels at 600 dpi (10pt text measures as 9.96pt).
+pub(super) fn device_metrics(props: &RunProps, size: f32) -> bool {
+ (props.scale - 1.0).abs() > 0.001 || (props.kern > 0.0 && size >= props.kern)
+}
+
+/// `size` rounded to whole device pixels.
+fn device_size(size: f32) -> f32 {
+ (size * DEVICE_DPI / 72.0).round().max(1.0) * 72.0 / DEVICE_DPI
+}
+
+/// What a cluster is.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Kind {
+ /// A visible character.
+ Text,
+ /// A breakable space.
+ Space,
+ /// A tab.
+ Tab,
+ /// A line break.
+ LineBreak,
+ /// A page break.
+ PageBreak,
+ /// A column break.
+ ColumnBreak,
+ /// An inline drawing (index into `objects`).
+ Object(u16),
+ /// A floating drawing's anchor (index into `objects`).
+ Anchor(u16),
+ /// Takes no space: hidden text, field codes, bookmarks.
+ Zero,
+ /// A soft hyphen: invisible unless the line breaks after it.
+ SoftHyphen,
+ /// The note separator line (`true` = continuation separator).
+ Separator(bool),
+ /// The paragraph mark.
+ End,
+}
+
+/// A line-break opportunity after a cluster.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Brk {
+ /// No break.
+ No,
+ /// A break is allowed after this cluster.
+ After,
+}
+
+/// One measured unit of a paragraph.
+#[derive(Clone, Copy, Debug)]
+pub struct Cluster {
+ /// Kind.
+ pub kind: Kind,
+ /// Content offset (UTF-16) where the cluster starts.
+ pub offset: u32,
+ /// Content length it covers (0 for synthetic clusters).
+ pub len: u16,
+ /// Index of its run style.
+ pub run: u16,
+ /// Natural advance (points).
+ pub advance: f32,
+ /// Glyph id (text clusters).
+ pub glyph: u16,
+ /// Font of the glyph.
+ pub font: Option<Font>,
+ /// The character displayed.
+ pub ch: char,
+ /// Break opportunity.
+ pub brk: Brk,
+ /// Explicit tab stop for absolute position tabs (`w:ptab`).
+ pub ptab: Option<(f32, crate::model::props::TabAlign)>,
+ /// Drawn size of a text cluster (points); differs from the run's for
+ /// small capitals.
+ pub size: f32,
+}
+
+/// How a run shows tracked changes.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
+pub enum Revision {
+ /// Not a tracked change.
+ #[default]
+ None,
+ /// Inserted text.
+ Inserted,
+ /// Deleted text.
+ Deleted,
+ /// Text whose formatting changed: drawn as it is now, with a change bar.
+ Formatted,
+}
+
+impl Revision {
+ /// Whether the text shows as inserted or deleted.
+ pub fn marked(self) -> bool {
+ matches!(self, Self::Inserted | Self::Deleted)
+ }
+}
+
+/// Drawing style of a run.
+#[derive(Clone, Debug)]
+pub struct RunStyle {
+ /// Resolved properties.
+ pub props: Arc<RunProps>,
+ /// Size drawn (after super/subscript and small caps).
+ pub size: f32,
+ /// Baseline shift (points, up).
+ pub shift: f32,
+ /// Text color.
+ pub color: Rgba,
+ /// Tracked change.
+ pub revision: Revision,
+ /// Inside a hyperlink.
+ pub link: bool,
+ /// Ascent for line height (points).
+ pub ascent: f32,
+ /// Descent for line height (points).
+ pub descent: f32,
+ /// External leading (points).
+ pub leading: f32,
+ /// The primary font of the run.
+ pub font: Option<Font>,
+}
+
+/// Dynamic field values.
+#[derive(Clone, Debug, PartialEq)]
+pub struct FieldValues {
+ /// Page number.
+ pub page: i64,
+ /// Number of pages.
+ pub pages: i64,
+ /// Pages in the section.
+ pub section_pages: i64,
+ /// Section page number format.
+ pub page_fmt: NumFmt,
+}
+
+impl Default for FieldValues {
+ fn default() -> Self {
+ Self {
+ page: 1,
+ pages: 1,
+ section_pages: 1,
+ page_fmt: NumFmt::Decimal,
+ }
+ }
+}
+
+/// What inline building needs besides the paragraph.
+pub struct InlineCtx<'a> {
+ /// Formatting resolver.
+ pub formats: &'a Formats<'a>,
+ /// Fonts.
+ pub fonts: &'a Fonts<'a>,
+ /// Page-dependent field values.
+ pub fields: &'a FieldValues,
+ /// Displayed note numbers by (endnote, id).
+ pub note_numbers: &'a HashMap<(bool, i64), String>,
+ /// The number of the note being laid out (for `w:footnoteRef`).
+ pub note_number: Option<&'a str>,
+ /// Show tracked changes (else show the final text).
+ pub markup: bool,
+}
+
+/// A paragraph as clusters.
+#[derive(Clone, Debug, Default)]
+pub struct Inline {
+ /// Clusters in order; the last one is the paragraph mark.
+ pub clusters: Vec<Cluster>,
+ /// Run styles.
+ pub runs: Vec<RunStyle>,
+ /// Drawings (inline and floating).
+ pub objects: Vec<Drawing>,
+ /// Note references: (cluster index, endnote, note id).
+ pub notes: Vec<(usize, bool, i64)>,
+ /// The number each note reference shows (as `notes`).
+ pub note_labels: Vec<String>,
+ /// Whether the paragraph shows page-dependent fields.
+ pub dynamic: bool,
+ /// Clusters belonging to the list label.
+ pub label_len: usize,
+ /// Hyperlink targets by cluster range (start, end, relationship id or anchor).
+ pub links: Vec<(usize, usize, String)>,
+ /// Embedding level of each cluster (Unicode bidirectional algorithm);
+ /// empty when the paragraph is all left to right.
+ pub levels: Vec<u8>,
+ /// The paragraph's mark is a tracked insertion or deletion shown with
+ /// markup.
+ pub mark_changed: bool,
+ /// The paragraph's properties are a tracked change shown with markup.
+ pub props_changed: bool,
+}
+
+/// A field being read.
+struct FieldState {
+ instr: String,
+ in_result: bool,
+ dynamic: Option<Dynamic>,
+ emitted: bool,
+ /// A legacy check box form field: whether it is checked.
+ checkbox: Option<bool>,
+}
+
+/// Whether a field's `w:fldChar` start holds a check box form field, and
+/// its state.
+fn checkbox_state(xml: &str) -> Option<bool> {
+ let start = xml.find(":checkBox")?;
+ let rest = &xml[start..];
+ let on = |name: &str| {
+ rest.find(name).is_some_and(|i| {
+ let tag = &rest[i..rest[i..].find('>').map_or(rest.len(), |e| i + e)];
+ !(tag.contains("\"0\"") || tag.contains("\"false\"") || tag.contains("\"off\""))
+ })
+ };
+ Some(if rest.contains(":checked") {
+ on(":checked")
+ } else {
+ on(":default")
+ })
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum Dynamic {
+ Page,
+ Pages,
+ SectionPages,
+}
+
+fn field_kind(instr: &str) -> Option<Dynamic> {
+ let word = instr.split_whitespace().next()?.to_ascii_uppercase();
+ match word.as_str() {
+ "PAGE" => Some(Dynamic::Page),
+ "NUMPAGES" => Some(Dynamic::Pages),
+ "SECTIONPAGES" => Some(Dynamic::SectionPages),
+ _ => None,
+ }
+}
+
+/// The `\*` format switch of a field instruction.
+fn field_format(instr: &str, default: &NumFmt) -> NumFmt {
+ let mut words = instr.split_whitespace();
+ while let Some(w) = words.next() {
+ if w == "\\*" {
+ return match words.next().unwrap_or("") {
+ "ROMAN" | "Roman" => NumFmt::UpperRoman,
+ "roman" => NumFmt::LowerRoman,
+ "ALPHABETIC" | "Alphabetic" => NumFmt::UpperLetter,
+ "alphabetic" => NumFmt::LowerLetter,
+ "CardText" => NumFmt::CardinalText,
+ "OrdText" => NumFmt::OrdinalText,
+ "Ordinal" => NumFmt::Ordinal,
+ "Arabic" | "arabic" => NumFmt::Decimal,
+ _ => continue,
+ };
+ }
+ }
+ default.clone()
+}
+
+struct Builder<'a, 'b> {
+ ctx: &'b InlineCtx<'a>,
+ para: &'b Arc<ParaFormat>,
+ out: Inline,
+ /// Style index by (properties, revision, link, complex script).
+ run_index: crate::hash::FxMap<(usize, Revision, bool, bool), u16>,
+ /// Each style's properties as given (before condensing).
+ run_props: Vec<Arc<RunProps>>,
+}
+
+impl Builder<'_, '_> {
+ fn run_style(&mut self, props: &Arc<RunProps>, revision: Revision, link: bool) -> u16 {
+ self.style_for(props, revision, link, false)
+ }
+
+ /// The style of the complex-script text (Arabic, Hebrew, or any text of
+ /// a right-to-left run) of style `run`: its own font and size also give
+ /// its lines their height.
+ fn complex_style(&mut self, run: u16) -> u16 {
+ let style = &self.out.runs[run as usize];
+ let p = &style.props;
+ if p.cs == p.ascii && p.size_cs == p.size && p.bold_cs == p.bold && p.italic_cs == p.italic
+ {
+ return run;
+ }
+ let (revision, link) = (style.revision, style.link);
+ let props = Arc::clone(&self.run_props[run as usize]);
+ self.style_for(&props, revision, link, true)
+ }
+
+ fn style_for(
+ &mut self,
+ props: &Arc<RunProps>,
+ revision: Revision,
+ link: bool,
+ complex: bool,
+ ) -> u16 {
+ let key = (Arc::as_ptr(props) as usize, revision, link, complex);
+ if let Some(&i) = self.run_index.get(&key) {
+ return i;
+ }
+ let given = Arc::clone(props);
+ let fonts = self.ctx.fonts;
+ let (family, base) = if complex {
+ (&props.cs, props.size_cs)
+ } else {
+ (&props.ascii, props.size)
+ };
+ let font = if complex {
+ fonts.select(family, props.bold_cs, props.italic_cs)
+ } else {
+ fonts.select(family, props.bold, props.italic)
+ };
+ // A condensed family drawn with a regular-width face is squeezed.
+ let factor = font.map_or(1.0, |f| fonts.width_factor(family, f.face));
+ let (ascent, descent, leading) = match font {
+ Some(f) => {
+ let m = fonts.vmetrics_for(family, f.face);
+ (m.ascent * base, m.descent * base, m.leading * base)
+ }
+ None => (base * 0.9, base * 0.25, 0.0),
+ };
+ let props = &if (factor - 1.0).abs() > f32::EPSILON {
+ Arc::new(RunProps {
+ scale: props.scale * factor,
+ ..(**props).clone()
+ })
+ } else {
+ Arc::clone(props)
+ };
+ let (size, shift) = match props.vert_align {
+ VertAlign::Super => (base * SCRIPT_SIZE, base * SUPER_RAISE),
+ VertAlign::Sub => (base * SCRIPT_SIZE, -base * SUB_DROP),
+ VertAlign::Baseline => (base, 0.0),
+ };
+ // Links take their color from their formatting (usually the
+ // Hyperlink character style), like any other text.
+ let mut color = props.color.unwrap_or_else(|| auto_color(props));
+ if revision.marked() && self.ctx.markup {
+ // Word's default "by author" revision color for one author.
+ color = Rgba::from_u8(0xC0, 0x00, 0x00);
+ }
+ let style = RunStyle {
+ props: Arc::clone(props),
+ size,
+ shift: shift + props.position,
+ color,
+ revision,
+ link,
+ ascent,
+ descent,
+ leading,
+ font,
+ };
+ let i = self.out.runs.len() as u16;
+ self.out.runs.push(style);
+ self.run_props.push(given);
+ self.run_index.insert(key, i);
+ i
+ }
+
+ fn push(&mut self, c: Cluster) {
+ self.out.clusters.push(c);
+ }
+
+ fn zero(&mut self, offset: usize, len: usize, run: u16) {
+ self.push(Cluster {
+ kind: Kind::Zero,
+ offset: offset as u32,
+ len: len as u16,
+ run,
+ advance: 0.0,
+ glyph: 0,
+ font: None,
+ ch: '\u{FFFC}',
+ brk: Brk::No,
+ ptab: None,
+ size: 0.0,
+ });
+ }
+
+ /// Measures and pushes one visible character.
+ fn text_char(&mut self, ch: char, next: Option<char>, offset: usize, len: usize, run: u16) {
+ let given = &self.out.runs[run as usize].props;
+ // A run marked right to left (or complex script) is complex-script
+ // text throughout (its size and weight), though Word sets its Latin
+ // letters and digits in the run's Latin font.
+ let marked = given.cs_flag || given.rtl;
+ let complex = marked || is_complex(ch);
+ let latin = marked && !is_complex(ch) && ch.is_ascii_alphanumeric();
+ let run = if complex {
+ self.complex_style(run)
+ } else {
+ run
+ };
+ let props = Arc::clone(&self.out.runs[run as usize].props);
+ let fonts = self.ctx.fonts;
+ let (family, bold, italic, mut size) = if complex {
+ let family = if latin { &props.ascii } else { &props.cs };
+ (family, props.bold_cs, props.italic_cs, props.size_cs)
+ } else if is_cjk(ch) || (props.hint.as_deref() == Some("eastAsia") && !ch.is_ascii()) {
+ (&props.east_asia, props.bold, props.italic, props.size)
+ } else if ch.is_ascii() {
+ (&props.ascii, props.bold, props.italic, props.size)
+ } else {
+ (&props.h_ansi, props.bold, props.italic, props.size)
+ };
+ let mut shown = ch;
+ if props.caps || props.small_caps {
+ let upper = ch.to_uppercase().next().unwrap_or(ch);
+ if props.small_caps && !props.caps && upper != ch {
+ size *= SMALL_CAPS_SIZE;
+ }
+ shown = upper;
+ }
+ size = match props.vert_align {
+ VertAlign::Baseline => size,
+ _ => size * SCRIPT_SIZE,
+ };
+ if device_metrics(&props, size) {
+ size = device_size(size);
+ }
+ let Some(font) = fonts.select(family, bold, italic) else {
+ self.zero(offset, len, run);
+ return;
+ };
+ let g = fonts.glyph(font, shown);
+ let mut advance = g.advance * size * props.scale + props.spacing;
+ if ch == '\u{00A0}' {
+ advance = fonts.glyph(font, ' ').advance * size * props.scale + props.spacing;
+ }
+ // An Arabic family drawn by a substitute keeps its own widths.
+ if complex && let Some((letters, space)) = fonts.arabic_widths(family) {
+ if matches!(ch, ' ' | '\u{00A0}') {
+ advance = space * size * props.scale + props.spacing;
+ } else if g.font.face != font.face || arabic::joining(ch) != Joining::None {
+ advance = g.advance * letters * size * props.scale + props.spacing;
+ }
+ }
+ // Pair kerning only when the run asks for it.
+ if props.kern > 0.0
+ && size >= props.kern
+ && let Some(prev) = self.out.clusters.last_mut()
+ && prev.kind == Kind::Text
+ && prev.font.map(|f| f.face) == Some(g.font.face)
+ {
+ prev.advance += fonts.kerning(g.font.face, prev.glyph, g.id) * size;
+ }
+ let kind = if ch == ' ' || ch == '\u{2002}' || ch == '\u{2003}' || ch == '\u{3000}' {
+ Kind::Space
+ } else {
+ Kind::Text
+ };
+ let brk = if kind == Kind::Space || breaks_after(ch, next) {
+ Brk::After
+ } else {
+ Brk::No
+ };
+ self.push(Cluster {
+ kind,
+ offset: offset as u32,
+ len: len as u16,
+ run,
+ advance,
+ glyph: g.id,
+ font: Some(g.font),
+ ch: shown,
+ brk,
+ ptab: None,
+ size,
+ });
+ }
+
+ /// Pushes synthetic text (labels, field results, note numbers).
+ fn synthetic(&mut self, text: &str, offset: usize, first_len: usize, run: u16) {
+ let chars: Vec<char> = text.chars().collect();
+ for (i, &c) in chars.iter().enumerate() {
+ let len = if i == 0 { first_len } else { 0 };
+ if c == '\t' {
+ self.tab(offset, len, run);
+ continue;
+ }
+ self.text_char(c, chars.get(i + 1).copied(), offset, len, run);
+ }
+ if chars.is_empty() && first_len > 0 {
+ self.zero(offset, first_len, run);
+ }
+ }
+
+ /// A legacy check box form field: a box as wide as the font is high.
+ fn checkbox(&mut self, checked: bool, offset: usize, len: usize, run: u16) {
+ let ch = if checked { '\u{2612}' } else { '\u{2610}' };
+ self.text_char(ch, None, offset, len, run);
+ if let Some(c) = self.out.clusters.last_mut()
+ && c.kind == Kind::Text
+ {
+ c.advance = c.size.max(1.0);
+ }
+ }
+
+ /// Joins Arabic letters: each takes its initial, medial, final or
+ /// isolated presentation form, and lam with a following alef becomes
+ /// one ligature (the alef's cluster then draws nothing).
+ fn shape_arabic(&mut self) {
+ let clusters = &mut self.out.clusters;
+ if !clusters
+ .iter()
+ .any(|c| c.kind == Kind::Text && arabic::joining(c.ch) != Joining::None)
+ {
+ return;
+ }
+ let types: Vec<Joining> = clusters
+ .iter()
+ .map(|c| match c.kind {
+ Kind::Text => arabic::joining(c.ch),
+ // Bookmarks and other hidden markers do not break a word.
+ Kind::Zero => Joining::Transparent,
+ _ => Joining::None,
+ })
+ .collect();
+ let forms = arabic::forms_of(&types);
+ let fonts = self.ctx.fonts;
+ let db = fonts.db();
+ let runs = &self.out.runs;
+ let measure = |c: &Cluster, glyph: u16, face| {
+ let props = &runs[c.run as usize].props;
+ let letters = fonts.arabic_widths(&props.cs).map_or(1.0, |w| w.0);
+ db.advance(face, glyph) * letters * c.size * props.scale + props.spacing
+ };
+ let mut i = 0;
+ while i < clusters.len() {
+ let (Some(form), Some(font)) = (forms[i], clusters[i].font) else {
+ i += 1;
+ continue;
+ };
+ let face = font.face;
+ let joined = matches!(form, JoinForm::Medial | JoinForm::Final);
+ let lam_alef = (clusters[i].ch == '\u{0644}')
+ .then(|| clusters.get(i + 1))
+ .flatten()
+ .filter(|next| next.kind == Kind::Text && next.font.map(|f| f.face) == Some(face))
+ .and_then(|next| arabic::lam_alef(next.ch, joined))
+ .and_then(|lig| db.glyph(face, lig));
+ if let Some(glyph) = lam_alef {
+ let advance = measure(&clusters[i], glyph, face);
+ let c = &mut clusters[i];
+ c.glyph = glyph;
+ c.advance = advance;
+ let tail = &mut clusters[i + 1];
+ tail.kind = Kind::Zero;
+ tail.glyph = 0;
+ tail.advance = 0.0;
+ i += 2;
+ continue;
+ }
+ if let Some(glyph) =
+ arabic::presentation_form(clusters[i].ch, form).and_then(|p| db.glyph(face, p))
+ {
+ let advance = measure(&clusters[i], glyph, face);
+ let c = &mut clusters[i];
+ c.glyph = glyph;
+ c.advance = advance;
+ }
+ i += 1;
+ }
+ }
+
+ /// Resolves the clusters' embedding levels when the paragraph is right
+ /// to left or holds right-to-left text, and mirrors brackets that read
+ /// right to left.
+ fn resolve_bidi(&mut self) {
+ let base = u8::from(self.para.props.bidi);
+ let clusters = &self.out.clusters;
+ let classes: Vec<Class> = clusters
+ .iter()
+ .map(|c| match c.kind {
+ Kind::Text => bidi::class(c.ch),
+ Kind::Space => Class::Ws,
+ Kind::Tab => Class::S,
+ Kind::LineBreak => Class::Ws,
+ Kind::Zero | Kind::Anchor(_) | Kind::SoftHyphen => Class::Bn,
+ Kind::End => Class::B,
+ _ => Class::On,
+ })
+ .collect();
+ if !bidi::needed(&classes, base == 1) {
+ return;
+ }
+ let rtl: Vec<bool> = clusters
+ .iter()
+ .map(|c| self.out.runs[c.run as usize].props.rtl)
+ .collect();
+ let levels = bidi::levels(&classes, &rtl, base);
+ let db = self.ctx.fonts.db();
+ for (c, &level) in self.out.clusters.iter_mut().zip(&levels) {
+ if level % 2 == 0 || c.kind != Kind::Text {
+ continue;
+ }
+ if let (Some(m), Some(font)) = (bidi::mirror(c.ch), c.font)
+ && let Some(glyph) = db.glyph(font.face, m)
+ {
+ c.glyph = glyph;
+ }
+ }
+ self.out.levels = levels;
+ }
+
+ fn tab(&mut self, offset: usize, len: usize, run: u16) {
+ self.push(Cluster {
+ kind: Kind::Tab,
+ offset: offset as u32,
+ len: len as u16,
+ run,
+ advance: 0.0,
+ glyph: 0,
+ font: self.out.runs[run as usize].font,
+ ch: '\t',
+ brk: Brk::After,
+ ptab: None,
+ size: 0.0,
+ });
+ }
+
+ fn simple(&mut self, kind: Kind, offset: usize, len: usize, run: u16) {
+ self.push(Cluster {
+ kind,
+ offset: offset as u32,
+ len: len as u16,
+ run,
+ advance: 0.0,
+ glyph: 0,
+ font: None,
+ ch: '\u{FFFC}',
+ brk: Brk::After,
+ ptab: None,
+ size: 0.0,
+ });
+ }
+}
+
+/// Text color for `auto`: black, or white on dark shading.
+fn auto_color(props: &RunProps) -> Rgba {
+ match props.shading.or(props.highlight) {
+ Some(bg) if bg.r * 0.299 + bg.g * 0.587 + bg.b * 0.114 < 0.4 => Rgba::WHITE,
+ _ => Rgba::BLACK,
+ }
+}
+
+fn wrapper_instr(open: &str) -> Option<String> {
+ // `<w:fldSimple w:instr="PAGE \* MERGEFORMAT">`
+ let i = open.find("instr=\"")?;
+ let rest = &open[i + 7..];
+ let end = rest.find('"')?;
+ Some(rest[..end].replace("&quot;", "\"").replace("&amp;", "&"))
+}
+
+impl Inline {
+ /// Whether the note references show the numbers their notes have now
+ /// (numbers follow the references' order through the document).
+ pub fn notes_current(&self, numbers: &HashMap<(bool, i64), String>) -> bool {
+ self.notes
+ .iter()
+ .zip(&self.note_labels)
+ .all(|(&(_, endnote, id), shown)| {
+ numbers
+ .get(&(endnote, id))
+ .map_or(shown.is_empty(), |n| n == shown)
+ })
+ }
+}
+
+/// Builds the clusters of a paragraph.
+pub fn build(
+ block: &Block,
+ para: &Arc<ParaFormat>,
+ label: Option<(&Label, &RunProps)>,
+ ctx: &InlineCtx<'_>,
+) -> Inline {
+ let mut b = Builder {
+ ctx,
+ para,
+ out: Inline::default(),
+ run_index: crate::hash::FxMap::default(),
+ run_props: Vec::new(),
+ };
+ let mark_run = {
+ let mark = Arc::clone(&para.mark);
+ let run = b.run_style(&mark, Revision::None, false);
+ // A right-to-left mark is sized like complex-script text.
+ if mark.rtl || mark.cs_flag {
+ b.complex_style(run)
+ } else {
+ run
+ }
+ };
+ // The mark's revision also shows on the list label, as in Word.
+ let mark_revision = if !ctx.markup {
+ Revision::None
+ } else if para.mark.mark_deleted {
+ Revision::Deleted
+ } else if para.mark.mark_inserted {
+ Revision::Inserted
+ } else {
+ Revision::None
+ };
+ b.out.mark_changed = mark_revision != Revision::None;
+ b.out.props_changed = ctx.markup && block.props.contains("pPrChange");
+ // List label.
+ if let Some((label, props)) = label {
+ let props = Arc::new(props.clone());
+ let run = b.run_style(&props, mark_revision, false);
+ b.synthetic(&label.text, 0, 0, run);
+ match label.suffix {
+ Suffix::Tab => b.tab(0, 0, run),
+ Suffix::Space => b.synthetic(" ", 0, 0, run),
+ Suffix::Nothing => {}
+ }
+ b.out.label_len = b.out.clusters.len();
+ }
+ let mut fields: Vec<FieldState> = Vec::new();
+ let mut simple_dynamic_open: Option<String> = None;
+ let mut link_start: Option<(usize, String)> = None;
+ let spans: Vec<(usize, &crate::model::content::Span)> = block.content.spans_at().collect();
+ for (si, (start, span)) in spans.iter().enumerate() {
+ let attrs: &Attrs = &span.attrs;
+ let wrappers = attrs.wrappers();
+ let revision = if wrappers
+ .iter()
+ .any(|w| matches!(w.local(), "del" | "moveFrom"))
+ {
+ Revision::Deleted
+ } else if wrappers
+ .iter()
+ .any(|w| matches!(w.local(), "ins" | "moveTo"))
+ {
+ Revision::Inserted
+ } else if attrs.run_props().any(|(q, _)| q.ends_with("rPrChange")) {
+ Revision::Formatted
+ } else {
+ Revision::None
+ };
+ let link_wrapper = wrappers.iter().find(|w| w.local() == "hyperlink");
+ let link = link_wrapper.is_some();
+ // Track hyperlink extents for the editor (cluster ranges).
+ match (link_wrapper, &link_start) {
+ (Some(w), None) => link_start = Some((b.out.clusters.len(), w.open.clone())),
+ (Some(w), Some((_, open))) if *open != w.open => {
+ let (s, o) = link_start.take().unwrap_or_default();
+ b.out.links.push((s, b.out.clusters.len(), o));
+ link_start = Some((b.out.clusters.len(), w.open.clone()));
+ }
+ (None, Some(_)) => {
+ let (s, o) = link_start.take().unwrap_or_default();
+ b.out.links.push((s, b.out.clusters.len(), o));
+ }
+ _ => {}
+ }
+ // Simple fields that show page numbers.
+ let simple = wrappers
+ .iter()
+ .rev()
+ .find(|w| w.local() == "fldSimple")
+ .and_then(|w| wrapper_instr(&w.open).map(|i| (w.open.clone(), i)));
+ let simple_dynamic = simple
+ .as_ref()
+ .and_then(|(open, instr)| field_kind(instr).map(|k| (open.clone(), instr.clone(), k)));
+ let props = ctx.formats.run(attrs, para);
+ let hidden_revision = revision == Revision::Deleted && !ctx.markup;
+ // Without markup the document shows as if every change were
+ // accepted: insertions look like any other text.
+ let shown = if ctx.markup { revision } else { Revision::None };
+ let run = b.run_style(&props, shown, link);
+ let text: Vec<char> = span.text.chars().collect();
+ let mut offset = *start;
+ for (ci, &ch) in text.iter().enumerate() {
+ let len = ch.len_utf16();
+ let next = text
+ .get(ci + 1)
+ .copied()
+ .or_else(|| spans.get(si + 1).and_then(|(_, s)| s.text.chars().next()));
+ // Markers: bookmarks, comment ranges, math...
+ if attrs.marker().is_some() {
+ b.zero(offset, len, run);
+ offset += len;
+ continue;
+ }
+ if let Some(obj) = attrs.object() {
+ object(
+ &mut b,
+ obj,
+ &mut fields,
+ offset,
+ len,
+ run,
+ hidden_revision || props.vanish,
+ );
+ offset += len;
+ continue;
+ }
+ if attrs.is_instr()
+ && let Some(f) = fields.last_mut()
+ && !f.in_result
+ {
+ f.instr.push(ch);
+ }
+ let field_hidden = attrs.is_instr() || fields_hidden(&fields);
+ if let Some((open, instr, kind)) = &simple_dynamic {
+ if simple_dynamic_open.as_ref() != Some(open) {
+ simple_dynamic_open = Some(open.clone());
+ let value = dynamic_value(*kind, instr, ctx.fields);
+ b.out.dynamic = true;
+ b.synthetic(&value, offset, len, run);
+ } else {
+ b.zero(offset, len, run);
+ }
+ offset += len;
+ continue;
+ }
+ simple_dynamic_open = None;
+ if field_hidden || props.vanish || hidden_revision {
+ b.zero(offset, len, run);
+ offset += len;
+ continue;
+ }
+ match ch {
+ '\t' => b.tab(offset, len, run),
+ '\n' => b.simple(Kind::LineBreak, offset, len, run),
+ '\u{00AD}' => b.simple(Kind::SoftHyphen, offset, len, run),
+ '\u{200B}' => {
+ b.zero(offset, len, run);
+ if let Some(c) = b.out.clusters.last_mut() {
+ c.brk = Brk::After;
+ }
+ }
+ _ => b.text_char(ch, next, offset, len, run),
+ }
+ offset += len;
+ }
+ }
+ if let Some((s, o)) = link_start {
+ b.out.links.push((s, b.out.clusters.len(), o));
+ }
+ // The paragraph mark.
+ let end = block.content.len();
+ let hidden_mark = para.mark.vanish || (para.mark.mark_deleted && !ctx.markup);
+ b.push(Cluster {
+ kind: Kind::End,
+ offset: end as u32,
+ len: 0,
+ run: mark_run,
+ advance: 0.0,
+ glyph: 0,
+ font: None,
+ ch: if hidden_mark { '\u{0}' } else { '\u{00B6}' },
+ brk: Brk::After,
+ ptab: None,
+ size: 0.0,
+ });
+ b.shape_arabic();
+ b.resolve_bidi();
+ b.out
+}
+
+fn dynamic_value(kind: Dynamic, instr: &str, f: &FieldValues) -> String {
+ let fmt = field_format(instr, &f.page_fmt);
+ match kind {
+ Dynamic::Page => format_number(f.page, &fmt),
+ Dynamic::Pages => format_number(f.pages, &field_format(instr, &NumFmt::Decimal)),
+ Dynamic::SectionPages => {
+ format_number(f.section_pages, &field_format(instr, &NumFmt::Decimal))
+ }
+ }
+}
+
+/// Handles one object character.
+fn object(
+ b: &mut Builder<'_, '_>,
+ xml: &str,
+ fields: &mut Vec<FieldState>,
+ offset: usize,
+ len: usize,
+ run: u16,
+ hidden: bool,
+) {
+ // Cheap dispatch on the element name before parsing.
+ let name = xml
+ .trim_start_matches('<')
+ .split(|c: char| c.is_whitespace() || c == '>' || c == '/')
+ .next()
+ .unwrap_or("");
+ let local = name.rsplit(':').next().unwrap_or(name);
+ match local {
+ "fldChar" => {
+ let kind = attr_value(xml, "fldCharType").unwrap_or_default();
+ match kind.as_str() {
+ "begin" => fields.push(FieldState {
+ instr: String::new(),
+ in_result: false,
+ dynamic: None,
+ emitted: false,
+ checkbox: checkbox_state(xml),
+ }),
+ "separate" => {
+ if let Some(f) = fields.last_mut() {
+ f.in_result = true;
+ f.dynamic = field_kind(&f.instr);
+ }
+ let outer_hidden = fields_hidden(&fields[..fields.len().saturating_sub(1)]);
+ if let Some(f) = fields.last_mut()
+ && let Some(kind) = f.dynamic
+ && !f.emitted
+ && !outer_hidden
+ {
+ let instr = fields.last().map(|f| f.instr.clone()).unwrap_or_default();
+ let value = dynamic_value(kind, &instr, b.ctx.fields);
+ if let Some(f) = fields.last_mut() {
+ f.emitted = true;
+ }
+ b.out.dynamic = true;
+ b.synthetic(&value, offset, len, run);
+ return;
+ }
+ }
+ "end" => {
+ let f = fields.pop();
+ if let Some(f) = &f
+ && let Some(checked) = f.checkbox
+ && f.instr.split_whitespace().next() == Some("FORMCHECKBOX")
+ && !hidden
+ && !fields_hidden(fields)
+ {
+ b.checkbox(checked, offset, len, run);
+ return;
+ }
+ if let Some(f) = f
+ && !f.emitted
+ && let Some(kind) = field_kind(&f.instr)
+ && !f.in_result
+ && !fields_hidden(fields)
+ {
+ // A field without a stored result still shows its value.
+ let value = dynamic_value(kind, &f.instr, b.ctx.fields);
+ b.out.dynamic = true;
+ b.synthetic(&value, offset, len, run);
+ return;
+ }
+ }
+ _ => {}
+ }
+ b.zero(offset, len, run);
+ }
+ _ if hidden || fields_hidden(fields) => b.zero(offset, len, run),
+ "footnoteReference" | "endnoteReference" => {
+ let endnote = local == "endnoteReference";
+ let custom =
+ attr_value(xml, "customMarkFollows").is_some_and(|v| v == "1" || v == "true");
+ let id = attr_value(xml, "id")
+ .and_then(|v| parse_int(&v))
+ .unwrap_or(0);
+ let number = b
+ .ctx
+ .note_numbers
+ .get(&(endnote, id))
+ .cloned()
+ .unwrap_or_default();
+ let at = b.out.clusters.len();
+ if custom || number.is_empty() {
+ b.zero(offset, len, run);
+ } else {
+ b.synthetic(&number, offset, len, run);
+ }
+ b.out.notes.push((at, endnote, id));
+ b.out.note_labels.push(number);
+ }
+ "footnoteRef" | "endnoteRef" => {
+ let number = b.ctx.note_number.unwrap_or("").to_owned();
+ b.synthetic(&number, offset, len, run);
+ }
+ "separator" | "continuationSeparator" => {
+ b.simple(
+ Kind::Separator(local == "continuationSeparator"),
+ offset,
+ len,
+ run,
+ );
+ }
+ "br" => {
+ let kind = match attr_value(xml, "type").as_deref() {
+ Some("page") => Kind::PageBreak,
+ Some("column") => Kind::ColumnBreak,
+ _ => Kind::LineBreak,
+ };
+ b.simple(kind, offset, len, run);
+ }
+ "cr" => b.simple(Kind::LineBreak, offset, len, run),
+ "tab" => b.tab(offset, len, run),
+ "ptab" => {
+ b.tab(offset, len, run);
+ let align = match attr_value(xml, "alignment").as_deref() {
+ Some("center") => crate::model::props::TabAlign::Center,
+ Some("right") => crate::model::props::TabAlign::Right,
+ _ => crate::model::props::TabAlign::Left,
+ };
+ let relative_to_indent = attr_value(xml, "relativeTo").as_deref() == Some("indent");
+ if let Some(c) = b.out.clusters.last_mut() {
+ // Position resolved at line layout: NaN = "the edge for this alignment".
+ c.ptab = Some((if relative_to_indent { -1.0 } else { f32::NAN }, align));
+ }
+ }
+ "sym" => {
+ let font = attr_value(xml, "font").unwrap_or_default();
+ let code = attr_value(xml, "char")
+ .and_then(|c| u32::from_str_radix(&c, 16).ok())
+ .and_then(char::from_u32)
+ .unwrap_or('\u{2022}');
+ let style = &b.out.runs[run as usize];
+ let props = Arc::clone(&style.props);
+ let size = style.size;
+ let Some(f) = b.ctx.fonts.select(&font, props.bold, props.italic) else {
+ b.zero(offset, len, run);
+ return;
+ };
+ let g = b.ctx.fonts.glyph(f, code);
+ b.push(Cluster {
+ kind: Kind::Text,
+ offset: offset as u32,
+ len: len as u16,
+ run,
+ advance: g.advance * size * props.scale + props.spacing,
+ glyph: g.id,
+ font: Some(g.font),
+ ch: code,
+ brk: Brk::No,
+ ptab: None,
+ size,
+ });
+ }
+ "noBreakHyphen" => b.text_char('\u{2011}', None, offset, len, run),
+ "softHyphen" => b.simple(Kind::SoftHyphen, offset, len, run),
+ "drawing" | "pict" | "object" | "AlternateContent" => {
+ match parse_drawing(xml, b.ctx.formats.snippets()) {
+ Some(d) => {
+ let index = b.out.objects.len() as u16;
+ let floating = d.anchor.is_some();
+ let width = d.width + d.effect[0] + d.effect[2];
+ b.out.objects.push(d);
+ if floating {
+ b.push(Cluster {
+ kind: Kind::Anchor(index),
+ offset: offset as u32,
+ len: len as u16,
+ run,
+ advance: 0.0,
+ glyph: 0,
+ font: None,
+ ch: '\u{FFFC}',
+ brk: Brk::No,
+ ptab: None,
+ size: 0.0,
+ });
+ } else {
+ b.push(Cluster {
+ kind: Kind::Object(index),
+ offset: offset as u32,
+ len: len as u16,
+ run,
+ advance: width,
+ glyph: 0,
+ font: None,
+ ch: '\u{FFFC}',
+ brk: Brk::After,
+ ptab: None,
+ size: 0.0,
+ });
+ }
+ }
+ None => b.zero(offset, len, run),
+ }
+ }
+ "dayShort" | "dayLong" | "monthShort" | "monthLong" | "yearShort" | "yearLong"
+ | "pgNum" => {
+ let value = if local == "pgNum" {
+ format_number(b.ctx.fields.page, &b.ctx.fields.page_fmt)
+ } else {
+ String::new()
+ };
+ b.synthetic(&value, offset, len, run);
+ }
+ _ => b.zero(offset, len, run),
+ }
+}
+
+/// Whether an enclosing field hides its content (instruction part, or a
+/// dynamic result already replaced).
+fn fields_hidden(fields: &[FieldState]) -> bool {
+ fields.iter().any(|f| !f.in_result || f.dynamic.is_some())
+}
+
+/// A quick attribute read on an element's start tag.
+fn attr_value(xml: &str, name: &str) -> Option<String> {
+ let tag_end = xml.find('>').unwrap_or(xml.len());
+ let tag = &xml[..tag_end];
+ let mut search = 0;
+ while let Some(i) = tag[search..].find(name) {
+ let at = search + i;
+ let before = tag
+ .as_bytes()
+ .get(at.wrapping_sub(1))
+ .copied()
+ .unwrap_or(b' ');
+ let after = &tag[at + name.len()..];
+ if (before == b':' || before == b' ') && after.trim_start().starts_with('=') {
+ let after = after.trim_start()[1..].trim_start();
+ let quote = after.chars().next()?;
+ let rest = &after[1..];
+ let end = rest.find(quote)?;
+ return Some(rest[..end].replace("&quot;", "\"").replace("&amp;", "&"));
+ }
+ search = at + name.len();
+ }
+ None
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/layout/inline/script.rs b/crates/docx_engine/src/layout/inline/script.rs
new file mode 100644
index 0000000000..40023d3dc4
--- /dev/null
+++ b/crates/docx_engine/src/layout/inline/script.rs
@@ -0,0 +1,94 @@
+//! Character classes for inline layout: scripts that take their own fonts
+//! and the places lines may break besides spaces.
+
+/// East Asian (CJK) text: ideographs, kana, hangul and their punctuation.
+pub(super) fn is_cjk(c: char) -> bool {
+ matches!(c as u32,
+ 0x1100..=0x11FF | 0x2E80..=0x2FDF | 0x3000..=0x30FF | 0x3100..=0x31FF
+ | 0x3200..=0x4DBF | 0x4E00..=0x9FFF | 0xA960..=0xA97F | 0xAC00..=0xD7FF
+ | 0xF900..=0xFAFF | 0xFE30..=0xFE4F | 0xFF00..=0xFFEF | 0x20000..=0x2FA1F)
+}
+
+/// Complex-script text (right-to-left and South and South-East Asian
+/// scripts), set in a run's complex-script font.
+pub(super) fn is_complex(c: char) -> bool {
+ matches!(c as u32,
+ 0x0590..=0x08FF | 0x0900..=0x0DFF | 0x0E00..=0x0EFF | 0x0F00..=0x0FFF
+ | 0x1000..=0x109F | 0x1780..=0x17FF | 0xFB1D..=0xFDFF | 0xFE70..=0xFEFF)
+}
+
+/// East Asian punctuation that may not start a line (kinsoku).
+fn no_line_start(c: char) -> bool {
+ matches!(
+ c,
+ '\u{3001}'
+ | '\u{3002}'
+ | '\u{FF0C}'
+ | '\u{FF0E}'
+ | '\u{FF1A}'
+ | '\u{FF1B}'
+ | '\u{FF01}'
+ | '\u{FF1F}'
+ | '\u{FF09}'
+ | '\u{FF3D}'
+ | '\u{FF5D}'
+ | '\u{300D}'
+ | '\u{300F}'
+ | '\u{3009}'
+ | '\u{300B}'
+ | '\u{3011}'
+ | '\u{3015}'
+ | '\u{3017}'
+ | '\u{3019}'
+ | '\u{301B}'
+ | '\u{2019}'
+ | '\u{201D}'
+ | '\u{30FC}'
+ | '\u{3005}'
+ | '\u{309D}'
+ | '\u{309E}'
+ | '\u{30FD}'
+ | '\u{30FE}'
+ | '\u{FF65}'
+ )
+}
+
+/// East Asian punctuation that may not end a line (kinsoku).
+fn no_line_end(c: char) -> bool {
+ matches!(
+ c,
+ '\u{FF08}'
+ | '\u{FF3B}'
+ | '\u{FF5B}'
+ | '\u{300C}'
+ | '\u{300E}'
+ | '\u{3008}'
+ | '\u{300A}'
+ | '\u{3010}'
+ | '\u{3014}'
+ | '\u{3016}'
+ | '\u{3018}'
+ | '\u{301A}'
+ | '\u{2018}'
+ | '\u{201C}'
+ )
+}
+
+/// Characters after which a line may break besides spaces.
+pub(super) fn breaks_after(c: char, next: Option<char>) -> bool {
+ // Joiners glue their neighbours together.
+ let joiner = |c: char| matches!(c, '\u{200D}' | '\u{2060}' | '\u{FEFF}');
+ if joiner(c) || next.is_some_and(joiner) {
+ return false;
+ }
+ match c {
+ '-' | '\u{2010}' | '\u{2012}' | '\u{2013}' | '\u{2014}' => {
+ next.is_some_and(|n| !n.is_ascii_digit() && !n.is_whitespace())
+ }
+ '\u{200B}' => true,
+ c if no_line_end(c) => false,
+ _ if next.is_some_and(no_line_start) => false,
+ c if is_cjk(c) => true,
+ _ => next.is_some_and(is_cjk),
+ }
+}
diff --git a/crates/docx_engine/src/layout/inline/test.rs b/crates/docx_engine/src/layout/inline/test.rs
new file mode 100644
index 0000000000..ff474d6fb1
--- /dev/null
+++ b/crates/docx_engine/src/layout/inline/test.rs
@@ -0,0 +1,65 @@
+use super::*;
+
+#[test]
+fn reads_field_kinds_and_formats() {
+ assert_eq!(field_kind(" PAGE \\* MERGEFORMAT "), Some(Dynamic::Page));
+ assert_eq!(field_kind("NUMPAGES"), Some(Dynamic::Pages));
+ assert_eq!(field_kind("REF _Ref1 \\h"), None);
+ assert_eq!(
+ field_format("PAGE \\* roman", &NumFmt::Decimal),
+ NumFmt::LowerRoman
+ );
+ assert_eq!(
+ field_format("PAGE", &NumFmt::UpperRoman),
+ NumFmt::UpperRoman
+ );
+}
+
+#[test]
+fn reads_attributes_from_tags() {
+ assert_eq!(
+ attr_value(r#"<w:fldChar w:fldCharType="begin"/>"#, "fldCharType").as_deref(),
+ Some("begin")
+ );
+ assert_eq!(
+ attr_value(r#"<w:footnoteReference w:id="12"/>"#, "id").as_deref(),
+ Some("12")
+ );
+ assert_eq!(attr_value(r#"<w:br w:type="page"/>"#, "clear"), None);
+}
+
+#[test]
+fn scaled_and_kerned_runs_measure_at_device_sizes() {
+ assert!((device_size(10.0) - 9.96).abs() < 1e-4);
+ assert!((device_size(12.0) - 12.0).abs() < 1e-4);
+ assert!((device_size(8.5) - 8.52).abs() < 1e-4);
+ let mut props = crate::model::props::RPr::default().resolve();
+ assert!(!device_metrics(&props, 10.0));
+ props.scale = 1.03;
+ assert!(device_metrics(&props, 10.0));
+ props.scale = 1.0;
+ props.kern = 14.0;
+ assert!(!device_metrics(&props, 10.0));
+ assert!(device_metrics(&props, 14.0));
+}
+
+#[test]
+fn breaks_after_hyphens_and_cjk() {
+ assert!(breaks_after('-', Some('a')));
+ assert!(!breaks_after('-', Some('1')));
+ assert!(breaks_after('中', Some('文')));
+ assert!(!breaks_after('a', Some('b')));
+ // A joiner keeps a hyphen with what follows.
+ assert!(!breaks_after('-', Some('\u{200D}')));
+ assert!(!breaks_after('\u{2060}', Some('中')));
+}
+
+#[test]
+fn east_asian_punctuation_keeps_to_its_text() {
+ // Closing punctuation never starts a line, opening never ends one.
+ assert!(!breaks_after('中', Some(',')));
+ assert!(!breaks_after('中', Some('。')));
+ assert!(breaks_after(',', Some('文')));
+ assert!(!breaks_after('《', Some('文')));
+ assert!(!breaks_after('「', Some('文')));
+}
diff --git a/crates/docx_engine/src/layout/lines.rs b/crates/docx_engine/src/layout/lines.rs
new file mode 100644
index 0000000000..172fe4928c
--- /dev/null
+++ b/crates/docx_engine/src/layout/lines.rs
@@ -0,0 +1,696 @@
+//! Line breaking and line boxes.
+//!
+//! Word breaks greedily: words are added until the next one would cross the
+//! right indent, spaces hang past it, and a word longer than the line is
+//! broken where it overflows. Tabs jump to the next stop (custom stops, the
+//! hanging indent, then default stops after the last custom one); right,
+//! center and decimal stops align the text that follows them. In justified
+//! paragraphs, Word 2013 and later also keep a word that crosses the edge
+//! slightly by shrinking the line's spaces.
+
+use super::bidi;
+use super::inline::{Inline, Kind, device_metrics};
+use crate::model::props::{Align, LineSpacing, ParaProps, TabAlign, TabLeader};
+
+/// How a line ended.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LineEnd {
+ /// The text wrapped.
+ Wrap,
+ /// A manual line break.
+ Break,
+ /// A page break.
+ PageBreak,
+ /// A column break.
+ ColumnBreak,
+ /// The end of the paragraph.
+ Paragraph,
+}
+
+/// One laid-out line.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Line {
+ /// First cluster.
+ pub start: usize,
+ /// One past the last cluster.
+ pub end: usize,
+ /// Top, relative to the paragraph's first line top (points).
+ pub top: f32,
+ /// Height (points).
+ pub height: f32,
+ /// Baseline below the line top (points).
+ pub baseline: f32,
+ /// Left edge of the line's text area (points from the text area left).
+ pub left: f32,
+ /// Right edge of the line's text area.
+ pub right: f32,
+ /// Width of the content without trailing spaces.
+ pub width: f32,
+ /// How the line ended.
+ pub ends: LineEnd,
+ /// The line ends at a soft hyphen that shows as a hyphen.
+ pub hyphen: bool,
+}
+
+/// A paragraph's lines plus cluster positions.
+#[derive(Clone, Debug, Default)]
+pub struct Lines {
+ /// The lines.
+ pub lines: Vec<Line>,
+ /// X of each cluster from the text area's left edge (points).
+ pub x: Vec<f32>,
+ /// Final advance of each cluster (after tabs and justification).
+ pub adv: Vec<f32>,
+ /// Leaders of tab clusters.
+ pub leaders: Vec<(usize, TabLeader)>,
+ /// Total height of the lines.
+ pub height: f32,
+}
+
+/// What line layout needs to know about the paragraph's surroundings.
+#[derive(Clone, Copy, Debug)]
+pub struct LineCtx<'a> {
+ /// Paragraph properties.
+ pub props: &'a ParaProps,
+ /// Width of the text area (column or cell content).
+ pub width: f32,
+ /// Default tab interval.
+ pub default_tab: f32,
+ /// Lines ending in manual breaks are not stretched when justified.
+ pub no_expand_shift_return: bool,
+ /// Document grid pitch when lines snap to it.
+ pub grid: Option<f32>,
+ /// Justified lines may shrink their spaces to fit more text (Word 2013
+ /// and later).
+ pub shrink_spaces: bool,
+ /// A paragraph mark right after a page break stays on the break's line
+ /// rather than going to the next page alone.
+ pub mark_with_page_break: bool,
+ /// Page x of the text area's left edge, when known. Word places lines
+ /// in device units, which decides where the first tab of a line that
+ /// starts on a default tab stop goes.
+ pub origin: Option<f32>,
+}
+
+/// Space a wrapping float takes from a line: (left inset, right inset) for
+/// a line spanning `top..bottom` (paragraph-relative points).
+pub type Exclusion<'a> = &'a dyn Fn(f32, f32) -> (f32, f32);
+
+const EPS: f32 = 0.01;
+
+/// How much Word 2013 and later may shrink a space to squeeze one more word
+/// into a justified line: a share of the space's glyph, without letter
+/// spacing.
+const SPACE_SHRINK: f32 = 0.25;
+/// The share of a space's whole advance that text Word measures with a
+/// device font (scaled or kerned runs) may lose: it squeezes less, as the
+/// line ends of the UN's New York documents show.
+const DEVICE_SPACE_SHRINK: f32 = 0.21;
+/// Word only shrinks spaces for a word that crosses the right edge by less
+/// than this fraction of its own width.
+const MAX_WORD_OVERFLOW: f32 = 0.35;
+
+struct Stop {
+ pos: f32,
+ align: TabAlign,
+ leader: TabLeader,
+ /// Set in the paragraph's tabs (not a default stop).
+ custom: bool,
+}
+
+/// A length in twips in Word's device units (1/600 inch), rounded half to
+/// even.
+fn device_units(twips: i64) -> i64 {
+ let n = twips * 5;
+ let (q, r) = (n.div_euclid(12), n.rem_euclid(12));
+ match (2 * r).cmp(&12) {
+ std::cmp::Ordering::Greater => q + 1,
+ std::cmp::Ordering::Equal => q + (q & 1),
+ std::cmp::Ordering::Less => q,
+ }
+}
+
+/// Whether a line starting `x` points into a text area whose left edge is
+/// at page x `origin` really starts before that point in Word: Word starts
+/// it at the rounded edge plus the rounded indent, and places tab stops at
+/// the rounded sum (A4 pages with 2 cm margins and indents start a device
+/// unit early).
+fn starts_early(origin: f32, x: f32) -> bool {
+ let twips = |v: f32| (v * 20.0).round() as i64;
+ let (origin, x) = (twips(origin), twips(x));
+ device_units(origin) + device_units(x) < device_units(origin + x)
+}
+
+/// The stop a tab at `x` goes to; `line_start` when nothing comes before it
+/// on its line.
+fn next_stop(x: f32, ctx: &LineCtx<'_>, first_line: bool, line_start: bool) -> Stop {
+ let p = ctx.props;
+ let mut best: Option<Stop> = None;
+ for s in &p.tabs {
+ if s.align == TabAlign::Bar || s.pos <= x + EPS {
+ continue;
+ }
+ if best.as_ref().is_none_or(|b| s.pos < b.pos) {
+ best = Some(Stop {
+ pos: s.pos,
+ align: s.align,
+ leader: s.leader,
+ custom: true,
+ });
+ }
+ }
+ // A hanging indent is an implicit stop on the first line.
+ if first_line
+ && p.ind_first < 0.0
+ && p.ind_left > x + EPS
+ && best.as_ref().is_none_or(|b| p.ind_left < b.pos)
+ {
+ best = Some(Stop {
+ pos: p.ind_left,
+ align: TabAlign::Left,
+ leader: TabLeader::None,
+ custom: false,
+ });
+ }
+ if let Some(b) = best {
+ return b;
+ }
+ // Default stops, only after the last custom stop.
+ let interval = ctx.default_tab.max(1.0);
+ let last_custom = p
+ .tabs
+ .iter()
+ .filter(|s| s.align != TabAlign::Bar)
+ .map(|s| s.pos)
+ .fold(f32::MIN, f32::max);
+ let from = x.max(last_custom);
+ let mut pos = ((from + EPS) / interval).floor() * interval + interval;
+ // A line starting on a default stop that Word starts just before it:
+ // its first tab goes to that stop.
+ let on_stop = x > EPS && ((x / interval).round() * interval - x).abs() < EPS;
+ if line_start
+ && on_stop
+ && last_custom < x - EPS
+ && ctx.origin.is_some_and(|o| starts_early(o, x))
+ {
+ pos = x;
+ }
+ Stop {
+ pos,
+ align: TabAlign::Left,
+ leader: TabLeader::None,
+ custom: false,
+ }
+}
+
+/// Width of the clusters after `from` up to the next tab or line end, and
+/// of the part before a decimal separator.
+fn segment_width(inline: &Inline, from: usize) -> (f32, f32) {
+ let mut w = 0.0;
+ let mut before_decimal: Option<f32> = None;
+ for c in &inline.clusters[from..] {
+ match c.kind {
+ Kind::Tab | Kind::LineBreak | Kind::PageBreak | Kind::ColumnBreak | Kind::End => break,
+ _ => {}
+ }
+ if before_decimal.is_none() && (c.ch == '.' || c.ch == ',') && c.kind == Kind::Text {
+ before_decimal = Some(w);
+ }
+ w += c.advance;
+ }
+ (w, before_decimal.unwrap_or(w))
+}
+
+/// How much Word may shrink each cluster when it squeezes a justified line
+/// (points; only spaces shrink).
+fn squeeze_room(inline: &Inline) -> Vec<f32> {
+ inline
+ .clusters
+ .iter()
+ .map(|c| {
+ if c.kind != Kind::Space {
+ return 0.0;
+ }
+ let Some(style) = inline.runs.get(usize::from(c.run)) else {
+ return c.advance * SPACE_SHRINK;
+ };
+ let props = &style.props;
+ if device_metrics(props, c.size) {
+ c.advance * DEVICE_SPACE_SHRINK
+ } else {
+ (c.advance - props.spacing).max(0.0) * SPACE_SHRINK
+ }
+ })
+ .collect()
+}
+
+/// Width of the unbreakable run of clusters starting at `from`: up to and
+/// including the next cluster that allows a break after it, stopping
+/// before spaces, tabs and breaks.
+fn word_width(inline: &Inline, adv: &[f32], from: usize) -> f32 {
+ let mut w = 0.0;
+ for (k, c) in inline.clusters.iter().enumerate().skip(from) {
+ match c.kind {
+ Kind::Space
+ | Kind::Tab
+ | Kind::LineBreak
+ | Kind::PageBreak
+ | Kind::ColumnBreak
+ | Kind::End
+ | Kind::SoftHyphen => break,
+ _ => {}
+ }
+ w += adv[k];
+ if c.brk == super::inline::Brk::After {
+ break;
+ }
+ }
+ w
+}
+
+fn is_content(kind: Kind) -> bool {
+ matches!(
+ kind,
+ Kind::Text | Kind::Object(_) | Kind::Tab | Kind::Separator(_)
+ )
+}
+
+/// Breaks a paragraph into lines.
+pub fn break_lines(inline: &Inline, ctx: &LineCtx<'_>, exclude: Option<Exclusion<'_>>) -> Lines {
+ break_lines_from(inline, ctx, exclude, 0)
+}
+
+/// Breaks the rest of a paragraph, from cluster `start` on, into lines (a
+/// paragraph going on in a column of another width). The lines' tops
+/// count from the first of them.
+pub fn break_lines_from(
+ inline: &Inline,
+ ctx: &LineCtx<'_>,
+ exclude: Option<Exclusion<'_>>,
+ start: usize,
+) -> Lines {
+ let p = ctx.props;
+ let n = inline.clusters.len();
+ let shrink = ctx.shrink_spaces && p.jc == Align::Justify;
+ let mut adv: Vec<f32> = inline.clusters.iter().map(|c| c.advance).collect();
+ let squeezable = squeeze_room(inline);
+ for (i, c) in inline.clusters.iter().enumerate() {
+ if let Kind::Separator(continuation) = c.kind {
+ adv[i] = if continuation {
+ ctx.width
+ } else {
+ 144.0f32.min(ctx.width)
+ };
+ }
+ }
+ let mut x_pos = vec![0.0f32; n];
+ let mut leaders: Vec<(usize, TabLeader)> = Vec::new();
+ let mut lines: Vec<Line> = Vec::new();
+ let mut top = 0.0f32;
+ let mut i = start.min(n);
+ while i < n {
+ let first = lines.is_empty() && start == 0;
+ let mut left = p.ind_left + if first { p.ind_first } else { 0.0 };
+ let mut right = ctx.width - p.ind_right;
+ if let Some(ex) = exclude {
+ // Estimate the line's height with the paragraph mark's font.
+ let (l, r) = ex(top, top + 12.0);
+ left = left.max(l);
+ right = right.min(ctx.width - r);
+ }
+ if right - left < 12.0 {
+ right = left + 12.0;
+ }
+ let mut x = left;
+ let mut j = i;
+ let mut last_break: Option<usize> = None;
+ let mut ends = LineEnd::Wrap;
+ let mut has_content = false;
+ let mut line_leaders: Vec<(usize, TabLeader)> = Vec::new();
+ // How much the spaces since the last tab may shrink (justification
+ // only adjusts those).
+ let mut room = 0.0f32;
+ while j < n {
+ let c = &inline.clusters[j];
+ match c.kind {
+ Kind::LineBreak | Kind::PageBreak | Kind::ColumnBreak | Kind::End => {
+ x_pos[j] = x;
+ ends = match c.kind {
+ Kind::LineBreak => LineEnd::Break,
+ Kind::PageBreak => LineEnd::PageBreak,
+ Kind::ColumnBreak => LineEnd::ColumnBreak,
+ _ => LineEnd::Paragraph,
+ };
+ j += 1;
+ if ends == LineEnd::PageBreak
+ && ctx.mark_with_page_break
+ && inline.clusters[j..]
+ .iter()
+ .all(|c| matches!(c.kind, Kind::Zero | Kind::End))
+ {
+ // Nothing but the paragraph mark follows the break:
+ // the mark stays with it.
+ x_pos[j..n].fill(x);
+ j = n;
+ }
+ break;
+ }
+ Kind::Tab => {
+ let stop = match c.ptab {
+ Some((pos, align)) => {
+ let edge_left = if pos < 0.0 { p.ind_left } else { 0.0 };
+ let edge_right = if pos < 0.0 {
+ ctx.width - p.ind_right
+ } else {
+ ctx.width
+ };
+ Stop {
+ pos: match align {
+ TabAlign::Center => (edge_left + edge_right) / 2.0,
+ TabAlign::Right => edge_right,
+ _ => edge_left,
+ },
+ align,
+ leader: TabLeader::None,
+ custom: false,
+ }
+ }
+ None => next_stop(x, ctx, first, !has_content),
+ };
+ // A tab to a stop of its own past the right edge goes
+ // to the next line, as a word that does not fit would.
+ if stop.custom
+ && stop.align == TabAlign::Left
+ && stop.pos > right + EPS
+ && has_content
+ {
+ ends = LineEnd::Wrap;
+ break;
+ }
+ let (seg, before_dec) = segment_width(inline, j + 1);
+ let target = match stop.align {
+ TabAlign::Right => stop.pos - seg,
+ TabAlign::Center => stop.pos - seg / 2.0,
+ TabAlign::Decimal => stop.pos - before_dec,
+ _ => stop.pos,
+ };
+ adv[j] = (target - x).max(0.0);
+ if stop.leader != TabLeader::None {
+ line_leaders.push((j, stop.leader));
+ }
+ x_pos[j] = x;
+ x += adv[j];
+ has_content = true;
+ last_break = Some(j);
+ room = 0.0;
+ }
+ Kind::Space => {
+ x_pos[j] = x;
+ x += adv[j];
+ room += squeezable[j];
+ last_break = Some(j);
+ }
+ Kind::Zero | Kind::Anchor(_) => x_pos[j] = x,
+ Kind::SoftHyphen => {
+ x_pos[j] = x;
+ last_break = Some(j);
+ }
+ _ => {
+ // How far a word may cross the right edge when shrinking
+ // the spaces before it can pull it back in.
+ let allowance = if shrink && room > 0.0 && x + adv[j] > right + EPS {
+ let word = word_width(inline, &adv, last_break.map_or(i, |b| b + 1));
+ room.min(word * MAX_WORD_OVERFLOW)
+ } else {
+ 0.0
+ };
+ if x + adv[j] > right + allowance + EPS && has_content {
+ ends = LineEnd::Wrap;
+ if let Some(b) = last_break {
+ j = b + 1;
+ }
+ break;
+ }
+ x_pos[j] = x;
+ x += adv[j];
+ has_content |= is_content(c.kind);
+ if c.brk == super::inline::Brk::After {
+ last_break = Some(j);
+ }
+ }
+ }
+ j += 1;
+ }
+ if j <= i {
+ j = i + 1;
+ }
+ // Zero-width clusters right after a wrap stay on this line.
+ while ends == LineEnd::Wrap
+ && j < n
+ && matches!(inline.clusters[j].kind, Kind::Zero | Kind::Anchor(_))
+ {
+ x_pos[j] = x_pos[j - 1] + adv[j - 1];
+ j += 1;
+ }
+ let hyphen = ends == LineEnd::Wrap && inline.clusters[j - 1].kind == Kind::SoftHyphen;
+ // Content width: up to the last cluster that is not a trailing space.
+ let mut content_end = i;
+ for k in i..j {
+ if !matches!(
+ inline.clusters[k].kind,
+ Kind::Space
+ | Kind::Zero
+ | Kind::End
+ | Kind::LineBreak
+ | Kind::PageBreak
+ | Kind::ColumnBreak
+ | Kind::Anchor(_)
+ | Kind::SoftHyphen
+ ) {
+ content_end = k + 1;
+ }
+ }
+ let content_right = if content_end > i {
+ x_pos[content_end - 1] + adv[content_end - 1]
+ } else {
+ left
+ };
+ // Alignment and justification.
+ let last_line = matches!(
+ ends,
+ LineEnd::Paragraph | LineEnd::PageBreak | LineEnd::ColumnBreak
+ );
+ let stretch = match p.jc {
+ Align::Justify => !(last_line || ends == LineEnd::Break && ctx.no_expand_shift_return),
+ Align::Distribute => true,
+ _ => false,
+ };
+ let last_tab = (i..content_end)
+ .rev()
+ .find(|&k| inline.clusters[k].kind == Kind::Tab)
+ .map_or(i, |k| k + 1);
+ let spaces: Vec<usize> = (last_tab..content_end)
+ .filter(|&k| inline.clusters[k].kind == Kind::Space)
+ .collect();
+ // Text that only fits with shrunk spaces shrinks them, on any line
+ // and never by more than they may shrink.
+ let squeeze = shrink && right - content_right < -EPS && !spaces.is_empty();
+ let slack = if squeeze {
+ let room: f32 = spaces.iter().map(|&k| squeezable[k]).sum();
+ (right - content_right).max(-room)
+ } else {
+ (right - content_right).max(0.0)
+ };
+ if (stretch && slack > EPS) || squeeze {
+ if !spaces.is_empty() {
+ let each = slack / spaces.len() as f32;
+ let mut shift = 0.0;
+ for k in last_tab..j {
+ x_pos[k] += shift;
+ if spaces.binary_search(&k).is_ok() {
+ adv[k] += each;
+ shift += each;
+ }
+ }
+ } else if p.jc == Align::Distribute && content_end > last_tab + 1 {
+ let gaps = (content_end - last_tab - 1) as f32;
+ let each = slack / gaps;
+ for (g, k) in (last_tab..j).enumerate() {
+ x_pos[k] += each * (g.min(content_end - last_tab - 1)) as f32;
+ }
+ }
+ } else if matches!(p.jc, Align::Center | Align::Right) && slack > EPS {
+ let shift = if p.jc == Align::Center {
+ slack / 2.0
+ } else {
+ slack
+ };
+ for x in &mut x_pos[i..j] {
+ *x += shift;
+ }
+ }
+ if !inline.levels.is_empty() {
+ visual_order(inline, i, j, ctx, &mut x_pos, &adv);
+ }
+ leaders.extend(line_leaders);
+ let (mut height, mut baseline) = line_height(inline, i, j, ctx, &adv);
+ if matches!(ends, LineEnd::PageBreak | LineEnd::ColumnBreak)
+ && !has_content
+ && (j < n || ends == LineEnd::PageBreak)
+ {
+ // A paragraph that starts with a break starts after it, and a
+ // page that ends with a bare break has nothing below it: the
+ // break takes no room where it is.
+ height = 0.0;
+ baseline = 0.0;
+ }
+ lines.push(Line {
+ start: i,
+ end: j,
+ top,
+ height,
+ baseline,
+ left,
+ right,
+ width: content_right - left + if squeeze { slack } else { 0.0 },
+ ends,
+ hyphen,
+ });
+ top += height;
+ i = j;
+ }
+ Lines {
+ height: top,
+ lines,
+ x: x_pos,
+ adv,
+ leaders,
+ }
+}
+
+/// Puts a line of bidirectional text (clusters `start..end`, laid out
+/// left to right in logical order) in visual order: a right-to-left
+/// paragraph's line mirrored to start at the right, and runs against the
+/// paragraph's direction reversed in place.
+fn visual_order(
+ inline: &Inline,
+ start: usize,
+ end: usize,
+ ctx: &LineCtx<'_>,
+ x: &mut [f32],
+ adv: &[f32],
+) {
+ let base = u8::from(ctx.props.bidi);
+ let mut levels = inline.levels[start..end].to_vec();
+ // The line's trailing whitespace is at the paragraph's level.
+ for k in (start..end).rev() {
+ if !matches!(
+ inline.clusters[k].kind,
+ Kind::Space
+ | Kind::Zero
+ | Kind::End
+ | Kind::LineBreak
+ | Kind::PageBreak
+ | Kind::ColumnBreak
+ | Kind::Anchor(_)
+ | Kind::SoftHyphen
+ ) {
+ break;
+ }
+ levels[k - start] = base;
+ }
+ bidi::reorder(
+ &mut x[start..end],
+ &adv[start..end],
+ &levels,
+ base,
+ (0.0, ctx.width),
+ );
+}
+
+/// Height and baseline of a line spanning clusters `start..end`.
+fn line_height(
+ inline: &Inline,
+ start: usize,
+ end: usize,
+ ctx: &LineCtx<'_>,
+ adv: &[f32],
+) -> (f32, f32) {
+ // Each font's external leading sits above its ascent: the line's top
+ // part is the largest of them, its bottom part the largest descent.
+ let mut above: f32 = 0.0;
+ let mut object: f32 = 0.0;
+ let mut descent: f32 = 0.0;
+ let mut leading: f32 = 0.0;
+ let mut seen = false;
+ let mut text = false;
+ for c in &inline.clusters[start..end] {
+ let style = &inline.runs[c.run as usize];
+ match c.kind {
+ Kind::Zero | Kind::Anchor(_) => continue,
+ Kind::Object(o) => {
+ let d = &inline.objects[o as usize];
+ object = object.max(d.height + d.effect[1] + d.effect[3]);
+ seen = true;
+ }
+ Kind::End => {
+ // The paragraph mark sizes a line without text (empty, or
+ // only pictures, which sit on its baseline); text lines take
+ // their height from the text alone.
+ if text || (c.ch == '\u{0}' && seen) {
+ continue;
+ }
+ above = above.max(style.leading + style.ascent);
+ descent = descent.max(style.descent);
+ leading = leading.max(style.leading);
+ seen = true;
+ }
+ _ => {
+ above = above.max(style.leading + style.ascent);
+ descent = descent.max(style.descent);
+ leading = leading.max(style.leading);
+ seen = true;
+ text = true;
+ }
+ }
+ }
+ let _ = adv;
+ if !seen {
+ // A line of hidden content: the paragraph mark's metrics.
+ let style = &inline.runs[inline.clusters[end - 1].run as usize];
+ above = style.leading + style.ascent;
+ descent = style.descent;
+ leading = style.leading;
+ }
+ // Pictures stand on the baseline below the text's leading.
+ let top = above.max(object + leading);
+ let natural = top + descent;
+ let (mut height, mut baseline) = match ctx.props.line {
+ LineSpacing::Auto(m) if m >= 1.0 => {
+ // Extra space of multiple line spacing goes below the text.
+ (natural * m, top)
+ }
+ LineSpacing::Auto(m) => {
+ // Reduced spacing takes the space from above the text.
+ let h = natural * m.max(0.05);
+ (h, h - descent)
+ }
+ LineSpacing::Exact(v) => (v, v - descent * (v / natural.max(0.01)).min(1.0)),
+ LineSpacing::AtLeast(v) => {
+ let h = natural.max(v);
+ (h, h - descent)
+ }
+ };
+ if let Some(pitch) = ctx.grid
+ && pitch > 1.0
+ && matches!(ctx.props.line, LineSpacing::Auto(_))
+ {
+ let snapped = (height / pitch - 0.05).ceil().max(1.0) * pitch;
+ baseline += (snapped - height) / 2.0;
+ height = snapped;
+ }
+ (height, baseline)
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/layout/lines/test.rs b/crates/docx_engine/src/layout/lines/test.rs
new file mode 100644
index 0000000000..c5cc41ffbf
--- /dev/null
+++ b/crates/docx_engine/src/layout/lines/test.rs
@@ -0,0 +1,448 @@
+use crate::Document;
+use crate::layout::{Item, Layout, PlacedLine};
+use crate::test_support::{Parts, docx, fonts};
+
+fn layout(body: &str, parts: &Parts<'_>) -> (Document, Layout) {
+ let doc = Document::open(docx(body, parts)).unwrap();
+ let l = doc.layout(fonts());
+ (doc, l)
+}
+
+fn lines(l: &Layout, page: usize) -> Vec<&PlacedLine> {
+ l.pages[page]
+ .items
+ .iter()
+ .filter_map(|i| match i {
+ Item::Line(p) => Some(p),
+ _ => None,
+ })
+ .collect()
+}
+
+fn line_text(p: &PlacedLine) -> String {
+ let l = p.line();
+ p.para.inline.clusters[l.start..l.end]
+ .iter()
+ .filter(|c| {
+ !matches!(
+ c.kind,
+ crate::layout::inline::Kind::End | crate::layout::inline::Kind::Zero
+ )
+ })
+ .map(|c| if c.ch == '\u{FFFC}' { '#' } else { c.ch })
+ .collect()
+}
+
+const ARIAL_10: &str = r#"<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Arial" w:hAnsi="Arial"/><w:sz w:val="20"/></w:rPr></w:rPrDefault></w:docDefaults>"#;
+
+fn para(text: &str) -> String {
+ format!("<w:p><w:r><w:t xml:space=\"preserve\">{text}</w:t></w:r></w:p>")
+}
+
+#[test]
+fn wraps_at_spaces_and_hangs_trailing_spaces() {
+ let words = "lorem ipsum dolor sit amet ".repeat(20);
+ let (_, l) = layout(
+ &para(&words),
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let ls = lines(&l, 0);
+ assert!(ls.len() > 3);
+ for p in &ls[..ls.len() - 1] {
+ let line = p.line();
+ // Lines fit the 6.5" text width and break after a space.
+ assert!(line.width <= 468.0 + 0.1, "{}", line.width);
+ assert!(line_text(p).ends_with(' '), "{:?}", line_text(p));
+ }
+ // Arial 10pt single spacing: 1.149 em.
+ let h = ls[0].line().height;
+ assert!((h - 11.499).abs() < 0.01, "{h}");
+}
+
+#[test]
+fn breaks_long_words_where_they_overflow() {
+ let word = "x".repeat(200);
+ let (_, l) = layout(
+ &para(&word),
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let ls = lines(&l, 0);
+ assert!(ls.len() >= 2);
+ assert!(ls[0].line().width <= 468.0 + 0.1);
+}
+
+#[test]
+fn tabs_use_custom_then_default_stops() {
+ let body = r#"<w:p><w:pPr><w:tabs><w:tab w:val="right" w:pos="9360"/></w:tabs></w:pPr><w:r><w:t>Left</w:t><w:tab/><w:t>Right</w:t></w:r></w:p>
+ <w:p><w:r><w:t>a</w:t><w:tab/><w:t>b</w:t></w:r></w:p>"#;
+ let (_, l) = layout(
+ body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let ls = lines(&l, 0);
+ // "Right" ends at the right tab stop (6.5").
+ let p = ls[0];
+ let c = &p.para.inline.clusters;
+ let last = (0..c.len())
+ .rev()
+ .find(|&i| c[i].kind == crate::layout::inline::Kind::Text)
+ .unwrap();
+ let end = p.para.lines.x[last] + p.para.lines.adv[last];
+ assert!((end - 468.0).abs() < 0.05, "{end}");
+ // A default stop every half inch.
+ let p = ls[1];
+ let b = p
+ .para
+ .inline
+ .clusters
+ .iter()
+ .position(|c| c.ch == 'b')
+ .unwrap();
+ assert!((p.para.lines.x[b] - 36.0).abs() < 0.05);
+}
+
+#[test]
+fn justifies_all_but_the_last_line() {
+ let words = "justify these words please ".repeat(15);
+ let body =
+ format!(r#"<w:p><w:pPr><w:jc w:val="both"/></w:pPr><w:r><w:t>{words}</w:t></w:r></w:p>"#);
+ let (_, l) = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let ls = lines(&l, 0);
+ for p in &ls[..ls.len() - 1] {
+ let line = p.line();
+ let c = &p.para.inline.clusters;
+ let last = (line.start..line.end)
+ .rev()
+ .find(|&i| c[i].kind == crate::layout::inline::Kind::Text)
+ .unwrap();
+ let end = p.para.lines.x[last] + p.para.lines.adv[last];
+ assert!((end - 468.0).abs() < 0.05, "{end}");
+ }
+}
+
+const COMPAT_15: &str = r#"<w:compat><w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="15"/></w:compat>"#;
+
+/// Line texts of a justified paragraph of `words` with a right indent that
+/// makes the last of its first `fit` words cross the edge by `over` points.
+fn justified_lines(words: &[&str], fit: usize, over: f32, settings: Option<&str>) -> Vec<String> {
+ justified_lines_in(ARIAL_10, words, fit, over, settings)
+}
+
+/// [`justified_lines`] with the styles `styles`.
+fn justified_lines_in(
+ styles: &str,
+ words: &[&str],
+ fit: usize,
+ over: f32,
+ settings: Option<&str>,
+) -> Vec<String> {
+ let parts = Parts {
+ styles: Some(styles),
+ settings,
+ ..Parts::default()
+ };
+ // The natural width of the first `fit` words on one line.
+ let probe = para(&words[..fit].join(" "));
+ let (_, l) = layout(&probe, &parts);
+ let natural = lines(&l, 0)[0].line().width;
+ let right = ((468.0 - (natural - over)) * 20.0).round();
+ let body = format!(
+ r#"<w:p><w:pPr><w:ind w:right="{right}"/><w:jc w:val="both"/></w:pPr><w:r><w:t xml:space="preserve">{}</w:t></w:r></w:p>"#,
+ words.join(" ")
+ );
+ let (_, l) = layout(&body, &parts);
+ lines(&l, 0).iter().map(|p| line_text(p)).collect()
+}
+
+#[test]
+fn justified_lines_shrink_spaces_for_a_word_that_barely_overflows() {
+ let words = ["aaaa"; 14];
+ // Word 2013 and later shrink the spaces to keep the tenth word.
+ let shrunk = justified_lines(&words, 10, 3.0, Some(COMPAT_15));
+ assert_eq!(shrunk[0].split_whitespace().count(), 10, "{shrunk:?}");
+ // Earlier versions (and too large an overflow) wrap it.
+ let old = justified_lines(&words, 10, 3.0, None);
+ assert_eq!(old[0].split_whitespace().count(), 9, "{old:?}");
+ let far = justified_lines(&words, 10, 7.0, Some(COMPAT_15));
+ assert_eq!(far[0].split_whitespace().count(), 9, "{far:?}");
+}
+
+#[test]
+fn spaces_shrink_by_a_quarter_of_their_glyph_unless_measured_on_a_device() {
+ let words = ["aaaa"; 14];
+ // Nine 2.78pt spaces may give a quarter of their width: 6.25pt.
+ let plain = justified_lines(&words, 10, 5.8, Some(COMPAT_15));
+ assert_eq!(plain[0].split_whitespace().count(), 10, "{plain:?}");
+ // Kerned text, which Word measures with a device font, gives only 21%
+ // of each space (5.2pt): the word wraps.
+ let kerned = ARIAL_10.replace("<w:sz ", r#"<w:kern w:val="2"/><w:sz "#);
+ let device = justified_lines_in(&kerned, &words, 10, 5.8, Some(COMPAT_15));
+ assert_eq!(device[0].split_whitespace().count(), 9, "{device:?}");
+}
+
+#[test]
+fn justified_lines_do_not_shrink_for_a_short_word() {
+ let mut words = vec!["aaaa"; 9];
+ words.extend(["a", "aaaa", "aaaa"]);
+ // Crossing by more than a third of its own width, a short word wraps.
+ let l = justified_lines(&words, 10, 2.5, Some(COMPAT_15));
+ assert_eq!(l[0].split_whitespace().count(), 9, "{l:?}");
+}
+
+#[test]
+fn numbered_paragraphs_get_labels_and_hanging_tabs() {
+ let numbering = r#"<w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/><w:pPr><w:ind w:left="720" w:hanging="360"/></w:pPr></w:lvl></w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>"#;
+ let body = r#"<w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr><w:r><w:t>First</w:t></w:r></w:p>
+ <w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr><w:r><w:t>Second</w:t></w:r></w:p>"#;
+ let (_, l) = layout(
+ body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ numbering: Some(numbering),
+ ..Parts::default()
+ },
+ );
+ let ls = lines(&l, 0);
+ assert_eq!(line_text(ls[0]), "1.\tFirst");
+ assert_eq!(line_text(ls[1]), "2.\tSecond");
+ // The label hangs at 0.25" and the text starts at the 0.5" indent.
+ let p = ls[0];
+ assert!((p.para.lines.x[0] - 18.0).abs() < 0.05);
+ let f = p
+ .para
+ .inline
+ .clusters
+ .iter()
+ .position(|c| c.ch == 'F')
+ .unwrap();
+ assert!((p.para.lines.x[f] - 36.0).abs() < 0.05);
+}
+
+#[test]
+fn page_breaks_and_widow_control() {
+ let mut body = String::new();
+ for i in 0..60 {
+ body.push_str(&para(&format!("Paragraph {i}")));
+ }
+ body.push_str(r#"<w:p><w:r><w:br w:type="page"/></w:r></w:p>"#);
+ body.push_str(&para("After the break"));
+ let (_, l) = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ assert!(l.pages.len() >= 2);
+ let last = l.pages.len() - 1;
+ assert!(
+ lines(&l, last)
+ .iter()
+ .any(|p| line_text(p).contains("After the break"))
+ );
+}
+
+/// The lines of the page after a paragraph that ends with a page break.
+fn after_page_break(settings: Option<&str>) -> Vec<(f32, String)> {
+ let body = format!(
+ r#"{}<w:p><w:r><w:t>Before</w:t></w:r><w:r><w:br w:type="page"/></w:r></w:p>{}"#,
+ para("First"),
+ para("After")
+ );
+ let (_, l) = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ settings,
+ ..Parts::default()
+ },
+ );
+ assert_eq!(l.pages.len(), 2);
+ lines(&l, 1).iter().map(|p| (p.y, line_text(p))).collect()
+}
+
+#[test]
+fn the_mark_after_a_page_break_stays_with_it() {
+ // The paragraph mark stays on the break's line, so the next page starts
+ // with the next paragraph.
+ let next = after_page_break(None);
+ assert_eq!(next.len(), 1, "{next:?}");
+ assert_eq!(next[0].1, "After");
+ assert!((next[0].0 - 72.0).abs() < 0.01, "{next:?}");
+ // Split apart, the mark starts the next page as an empty line.
+ let split = after_page_break(Some("<w:compat><w:splitPgBreakAndParaMark/></w:compat>"));
+ assert_eq!(split.len(), 2, "{split:?}");
+ assert_eq!(split[0].1, "");
+ assert!((split[0].0 - 72.0).abs() < 0.01, "{split:?}");
+ assert!(split[1].0 > 72.0 + 10.0, "{split:?}");
+}
+
+#[test]
+fn keep_with_next_moves_headings() {
+ let mut body = String::new();
+ for i in 0..56 {
+ body.push_str(&para(&format!("Filler {i}")));
+ }
+ body.push_str(r#"<w:p><w:pPr><w:keepNext/></w:pPr><w:r><w:t>Heading</w:t></w:r></w:p>"#);
+ body.push_str(&para(&"text ".repeat(40)));
+ let (_, l) = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let first: Vec<String> = lines(&l, 0).iter().map(|p| line_text(p)).collect();
+ let second: Vec<String> = lines(&l, 1).iter().map(|p| line_text(p)).collect();
+ // The heading never ends a page without the start of the next paragraph.
+ if first.last().is_some_and(|t| t.contains("Heading")) {
+ panic!("heading stranded at the bottom: {first:?}");
+ }
+ assert!(
+ first.iter().any(|t| t.contains("Heading")) || second.iter().any(|t| t.contains("Heading"))
+ );
+}
+
+#[test]
+fn headers_footnotes_and_page_fields() {
+ let header = r#"<w:p><w:r><w:t xml:space="preserve">Page </w:t></w:r><w:r><w:fldChar w:fldCharType="begin"/></w:r><w:r><w:instrText>PAGE</w:instrText></w:r><w:r><w:fldChar w:fldCharType="separate"/></w:r><w:r><w:t>9</w:t></w:r><w:r><w:fldChar w:fldCharType="end"/></w:r></w:p>"#;
+ let footnotes = r#"<w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote><w:footnote w:id="1"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> The note.</w:t></w:r></w:p></w:footnote>"#;
+ let body = r#"<w:p><w:r><w:t>Text</w:t></w:r><w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:footnoteReference w:id="1"/></w:r></w:p>
+ <w:sectPr><w:headerReference w:type="default" r:id="rIdH1"/><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720"/></w:sectPr>"#;
+ let (_, l) = layout(
+ body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ header: Some(header),
+ footnotes: Some(footnotes),
+ ..Parts::default()
+ },
+ );
+ let texts: Vec<String> = lines(&l, 0).iter().map(|p| line_text(p)).collect();
+ assert!(texts.iter().any(|t| t == "Page 1"), "{texts:?}");
+ assert!(texts.iter().any(|t| t == "Text1"), "{texts:?}");
+ assert!(texts.iter().any(|t| t.contains("1 The note.")), "{texts:?}");
+}
+
+#[test]
+fn the_paragraph_mark_only_sizes_lines_without_text() {
+ // Text at 9pt with a 20pt paragraph mark: the line is as high as the
+ // text; an empty paragraph takes the mark's height.
+ let body = r#"<w:p><w:pPr><w:rPr><w:sz w:val="40"/></w:rPr></w:pPr><w:r><w:rPr><w:sz w:val="18"/></w:rPr><w:t>Small</w:t></w:r></w:p><w:p><w:pPr><w:rPr><w:sz w:val="40"/></w:rPr></w:pPr></w:p>"#;
+ let (_, l) = layout(
+ body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let ls = lines(&l, 0);
+ // Arial single spacing is 1.1499 em.
+ let (text, empty) = (ls[0].line().height, ls[1].line().height);
+ assert!((text - 9.0 * 1.1499).abs() < 0.01, "{text}");
+ assert!((empty - 20.0 * 1.1499).abs() < 0.01, "{empty}");
+}
+
+#[test]
+fn lines_of_mixed_fonts_take_the_tallest_ascent_with_its_own_leading() {
+ // A 12pt Symbol bullet before 12pt Arial text. Symbol's ascent (1.005
+ // em, no leading) tops Arial's leading plus ascent (0.938 em); Word
+ // does not add Arial's leading on top of Symbol's ascent.
+ let body = r#"<w:p><w:r><w:rPr><w:rFonts w:ascii="Symbol" w:hAnsi="Symbol"/><w:sz w:val="24"/></w:rPr><w:t>a</w:t></w:r><w:r><w:rPr><w:sz w:val="24"/></w:rPr><w:t xml:space="preserve"> text</w:t></w:r></w:p>"#;
+ let (_, l) = layout(
+ body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let line = lines(&l, 0)[0].line().clone();
+ let ascent = 12.0 * 2059.0 / 2048.0;
+ let descent = 12.0 * 443.0 / 2048.0;
+ assert!((line.baseline - ascent).abs() < 0.01, "{}", line.baseline);
+ assert!(
+ (line.height - (ascent + descent)).abs() < 0.01,
+ "{}",
+ line.height
+ );
+}
+
+#[test]
+fn tabs_to_stops_past_the_right_edge_go_to_the_next_line() {
+ // Stops at 1" and 7" in a 6.5" wide text area: the second tab cannot
+ // reach its stop on the line.
+ let body = r#"<w:p><w:pPr><w:tabs><w:tab w:val="left" w:pos="1440"/><w:tab w:val="left" w:pos="10080"/></w:tabs></w:pPr><w:r><w:t>from</w:t><w:tab/><w:t xml:space="preserve"> to</w:t><w:tab/><w:t>end</w:t></w:r></w:p>"#;
+ let (_, l) = layout(
+ body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ ..Parts::default()
+ },
+ );
+ let ls = lines(&l, 0);
+ assert_eq!(ls.len(), 2);
+ assert_eq!(line_text(ls[0]), "from\t to");
+ // On its own line the tab goes to the first stop.
+ let p = ls[1];
+ let e = p
+ .para
+ .inline
+ .clusters
+ .iter()
+ .position(|c| c.ch == 'e')
+ .unwrap();
+ assert!(
+ (p.para.lines.x[e] - 72.0).abs() < 0.05,
+ "{}",
+ p.para.lines.x[e]
+ );
+}
+
+/// Where the text after two leading tabs starts (points from the margin),
+/// on a page with left margin `margin`, the paragraph indented `indent`,
+/// with default stops every `stop` (all twips).
+fn after_two_tabs(margin: u32, indent: u32, stop: u32) -> f32 {
+ let body = format!(
+ r#"<w:p><w:pPr><w:ind w:left="{indent}"/></w:pPr><w:r><w:tab/><w:tab/><w:t>Text</w:t></w:r></w:p><w:sectPr><w:pgSz w:w="11906" w:h="16838"/><w:pgMar w:top="1440" w:right="{margin}" w:bottom="1440" w:left="{margin}" w:header="720" w:footer="720"/></w:sectPr>"#
+ );
+ let settings = format!(r#"<w:defaultTabStop w:val="{stop}"/>"#);
+ let (_, l) = layout(
+ &body,
+ &Parts {
+ styles: Some(ARIAL_10),
+ settings: Some(&settings),
+ ..Parts::default()
+ },
+ );
+ let p = lines(&l, 0)[0];
+ let t = p.para.inline.clusters.iter().position(|c| c.ch == 'T');
+ p.para.lines.x[t.expect("the text")]
+}
+
+#[test]
+fn a_line_word_starts_just_before_a_default_stop_tabs_to_it() {
+ // 2 cm margin and indent, 1 cm stops: Word starts the line a device
+ // unit before the 2 cm stop, so the first tab stops there and only the
+ // second reaches 3 cm.
+ let x = after_two_tabs(1134, 1134, 567);
+ assert!((x - 85.05).abs() < 0.01, "{x}");
+ // 1 inch margin, half-inch indent and stops: nothing rounds, and each
+ // tab goes a stop further.
+ let x = after_two_tabs(1440, 720, 720);
+ assert!((x - 108.0).abs() < 0.01, "{x}");
+}
diff --git a/crates/docx_engine/src/layout/table.rs b/crates/docx_engine/src/layout/table.rs
new file mode 100644
index 0000000000..8cc5532bd5
--- /dev/null
+++ b/crates/docx_engine/src/layout/table.rs
@@ -0,0 +1,342 @@
+//! Table geometry: grid columns, cell properties and borders, row boxes.
+
+use super::format::{Formats, TableCtx};
+use crate::model::block::{Block, BlockKind, Story};
+use crate::model::props::{Border, BordersPr, TblPr, TcPr, TrPr, VMerge, Width};
+use crate::model::styles::{CellPlace, cell_conditions};
+use crate::xml::{SnippetContext, parse_int};
+
+/// A cell's resolved geometry and formatting.
+#[derive(Clone, Debug)]
+pub struct CellGeom {
+ /// The cell block.
+ pub id: crate::model::block::BlockId,
+ /// First grid column.
+ pub col: usize,
+ /// Grid columns spanned.
+ pub span: usize,
+ /// Vertical merge state.
+ pub v_merge: Option<VMerge>,
+ /// Merged cell properties.
+ pub tc: TcPr,
+ /// Margins: top, left, bottom, right.
+ pub margins: [f32; 4],
+ /// Background.
+ pub shading: Option<pptx_engine::model::color::Rgba>,
+ /// Borders: top, left, bottom, right (`None` = no border).
+ pub borders: [Option<Border>; 4],
+ /// Diagonal borders: top-left to bottom-right, top-right to bottom-left.
+ pub diagonals: [Option<Border>; 2],
+ /// Formatting context for its paragraphs.
+ pub ctx: TableCtx,
+}
+
+/// A row's resolved geometry.
+#[derive(Clone, Debug)]
+pub struct RowGeom {
+ /// Row properties.
+ pub tr: TrPr,
+ /// Cells.
+ pub cells: Vec<CellGeom>,
+}
+
+/// A table's resolved geometry.
+#[derive(Clone, Debug)]
+pub struct TableGeom {
+ /// Grid column widths (points).
+ pub cols: Vec<f32>,
+ /// X of the table's left edge from the container's text area left.
+ pub left: f32,
+ /// Merged table properties.
+ pub tbl: TblPr,
+ /// Rows.
+ pub rows: Vec<RowGeom>,
+}
+
+impl TableGeom {
+ /// Total grid width.
+ pub fn width(&self) -> f32 {
+ self.cols.iter().sum()
+ }
+
+ /// X of grid column `c`'s left edge (from the table's left edge).
+ pub fn col_x(&self, c: usize) -> f32 {
+ self.cols[..c.min(self.cols.len())].iter().sum()
+ }
+}
+
+fn read_props<T>(
+ snippets: &SnippetContext,
+ xml: &str,
+ local: &str,
+ read: impl Fn(&crate::xml::XmlTree, crate::xml::NodeId) -> T,
+) -> Option<T> {
+ if xml.is_empty() {
+ return None;
+ }
+ let (tree, kids) = snippets.parse_many(xml).ok()?;
+ kids.into_iter()
+ .find(|&k| tree.is_w(k, local))
+ .map(|k| read(&tree, k))
+}
+
+fn grid_cols(snippets: &SnippetContext, xml: &str) -> Vec<f32> {
+ let Ok((tree, kids)) = snippets.parse_many(xml) else {
+ return Vec::new();
+ };
+ let Some(grid) = kids.into_iter().find(|&k| tree.is_w(k, "tblGrid")) else {
+ return Vec::new();
+ };
+ tree.children_named(grid, crate::xml::Ns::W, "gridCol")
+ .map(|c| {
+ tree.w_attr(c, "w")
+ .and_then(parse_int)
+ .map_or(0.0, crate::units::twips)
+ })
+ .collect()
+}
+
+/// Resolves a table's geometry within a container `avail` points wide.
+pub fn geometry(story: &Story, table: &Block, formats: &Formats<'_>, avail: f32) -> TableGeom {
+ let snippets = formats.snippets();
+ let theme = formats.theme;
+ let direct = formats.parsed("tblPr", &table.props, || {
+ read_props(snippets, &table.props, "tblPr", |t, n| {
+ TblPr::read(t, n, theme)
+ })
+ .unwrap_or_default()
+ });
+ let style = formats.styles.table_style(direct.style.as_deref());
+ let mut tbl = TblPr::default();
+ if let Some(s) = style {
+ tbl.apply(&s.tbl);
+ }
+ tbl.apply(&direct);
+ tbl.style = style.map(|s| s.id.clone());
+ let look = tbl.look.unwrap_or_default();
+ let bidi = tbl.bidi == Some(true);
+ let mut cols = formats.parsed("tblGrid", &table.props, || {
+ grid_cols(snippets, &table.props)
+ });
+
+ // Rows and cells.
+ let row_ids: Vec<_> = story
+ .children(Some(&table.id))
+ .iter()
+ .filter(|r| story.get(r).is_some_and(|b| b.kind == BlockKind::Row))
+ .cloned()
+ .collect();
+ struct RawRow {
+ tr: TrPr,
+ cells: Vec<(crate::model::block::BlockId, TcPr)>,
+ }
+ let mut raw: Vec<RawRow> = Vec::new();
+ for rid in &row_ids {
+ let Some(row) = story.get(rid) else {
+ continue;
+ };
+ let tr = formats.parsed("trPr", &row.props, || {
+ read_props(snippets, &row.props, "trPr", TrPr::read).unwrap_or_default()
+ });
+ let cells = story
+ .children(Some(rid))
+ .iter()
+ .filter_map(|c| {
+ let cell = story.get(c)?;
+ (cell.kind == BlockKind::Cell).then(|| {
+ let tc = formats.parsed("tcPr", &cell.props, || {
+ read_props(snippets, &cell.props, "tcPr", |t, n| {
+ TcPr::read(t, n, theme)
+ })
+ .unwrap_or_default()
+ });
+ (c.clone(), tc)
+ })
+ })
+ .collect();
+ raw.push(RawRow { tr, cells });
+ }
+ // The grid must cover every row.
+ let needed = raw
+ .iter()
+ .map(|r| {
+ r.tr.grid_before.unwrap_or(0) as usize
+ + r.cells
+ .iter()
+ .map(|(_, tc)| tc.grid_span.unwrap_or(1) as usize)
+ .sum::<usize>()
+ + r.tr.grid_after.unwrap_or(0) as usize
+ })
+ .max()
+ .unwrap_or(0);
+ let total_width = match tbl.width {
+ Some(Width::Abs(w)) if w > 1.0 => Some(w),
+ Some(Width::Pct(p)) if p > 0.0 => Some(avail * p),
+ _ => None,
+ };
+ if cols.len() < needed || cols.iter().all(|w| *w <= 0.0) {
+ // No usable grid: share the width (or the cells' preferred widths).
+ let first = raw.first();
+ let mut widths: Vec<f32> = Vec::new();
+ if let Some(r) = first {
+ for (_, tc) in &r.cells {
+ let span = tc.grid_span.unwrap_or(1).max(1) as usize;
+ let w = match tc.width {
+ Some(Width::Abs(w)) if w > 0.0 => Some(w),
+ Some(Width::Pct(p)) => Some(total_width.unwrap_or(avail) * p),
+ _ => None,
+ };
+ for _ in 0..span {
+ widths.push(w.map_or(0.0, |w| w / span as f32));
+ }
+ }
+ }
+ widths.resize(needed.max(1), 0.0);
+ let known: f32 = widths.iter().sum();
+ let unknown = widths.iter().filter(|w| **w <= 0.0).count();
+ let target = total_width.unwrap_or(avail);
+ if unknown > 0 {
+ let each = ((target - known) / unknown as f32).max(18.0);
+ for w in &mut widths {
+ if *w <= 0.0 {
+ *w = each;
+ }
+ }
+ }
+ cols = widths;
+ }
+ // A preferred table width wider or narrower than the grid scales autofit tables.
+ if let Some(target) = total_width
+ && tbl.fixed != Some(true)
+ {
+ let sum: f32 = cols.iter().sum();
+ if sum > 0.0 && (sum - target).abs() > 1.0 && target <= avail * 1.5 {
+ let k = target / sum;
+ for c in &mut cols {
+ *c *= k;
+ }
+ }
+ }
+ let rows_count = raw.len();
+ let header_rows = raw.iter().take_while(|r| r.tr.header == Some(true)).count();
+ let mut rows: Vec<RowGeom> = Vec::with_capacity(raw.len());
+ let band_rows = tbl.row_band.unwrap_or(1) as usize;
+ let band_cols = tbl.col_band.unwrap_or(1) as usize;
+ for (ri, r) in raw.iter().enumerate() {
+ let mut col = r.tr.grid_before.unwrap_or(0) as usize;
+ let ncells = r.cells.len();
+ let mut cells = Vec::with_capacity(ncells);
+ for (ci, (id, direct_tc)) in r.cells.iter().enumerate() {
+ let span = direct_tc.grid_span.unwrap_or(1).max(1) as usize;
+ let place = CellPlace {
+ row: ri,
+ rows: rows_count,
+ col: ci,
+ cols: ncells,
+ header_rows: header_rows.max(1),
+ row_band: band_rows,
+ col_band: band_cols,
+ };
+ let conds = cell_conditions(&look, place);
+ let ctx = TableCtx {
+ style: tbl.style.clone(),
+ conds,
+ };
+ let styled = formats.cell_style(&ctx);
+ let mut tc = styled.tc.clone();
+ tc.apply(direct_tc);
+ // Margins: cell, then table (direct over style), then Word's defaults.
+ let mut cell_tbl = TblPr::default();
+ cell_tbl.apply(&styled.tbl);
+ cell_tbl.apply(&direct);
+ let (dt, dl, db, dr) = cell_tbl.margins();
+ let mut margins = [
+ tc.margins.top.unwrap_or(dt),
+ tc.margins.left.unwrap_or(dl),
+ tc.margins.bottom.unwrap_or(db),
+ tc.margins.right.unwrap_or(dr),
+ ];
+ // Borders: table edges or inside lines, overridden by the cell.
+ let mut tb = BordersPr::default();
+ tb.apply(&styled.tbl.borders);
+ tb.apply(&direct.borders);
+ let first_row = ri == 0;
+ let last_row = ri + 1 == rows_count;
+ let first_col = col == 0;
+ let last_col = col + span >= cols.len();
+ let edge = |own: Option<Option<Border>>,
+ outer: Option<Option<Border>>,
+ inner: Option<Option<Border>>,
+ is_outer: bool| {
+ own.unwrap_or_else(|| {
+ if is_outer {
+ outer.flatten()
+ } else {
+ inner.flatten()
+ }
+ })
+ };
+ let mut borders = [
+ edge(tc.borders.top, tb.top, tb.inside_h, first_row),
+ edge(tc.borders.left, tb.left, tb.inside_v, first_col),
+ edge(tc.borders.bottom, tb.bottom, tb.inside_h, last_row),
+ edge(tc.borders.right, tb.right, tb.inside_v, last_col),
+ ];
+ if bidi {
+ // Left and right mean start and end: a right-to-left table
+ // starts at the right.
+ borders.swap(1, 3);
+ margins.swap(1, 3);
+ }
+ let shading = tc.shading.flatten().or_else(|| cell_tbl.shading.flatten());
+ cells.push(CellGeom {
+ id: id.clone(),
+ col,
+ span,
+ v_merge: tc.v_merge,
+ diagonals: [tc.borders.tl2br.flatten(), tc.borders.tr2bl.flatten()],
+ tc,
+ margins,
+ shading,
+ borders,
+ ctx,
+ });
+ col += span;
+ }
+ rows.push(RowGeom {
+ tr: r.tr.clone(),
+ cells,
+ });
+ }
+ // Horizontal position.
+ let width: f32 = cols.iter().sum();
+ let first_margin = rows
+ .first()
+ .and_then(|r| r.cells.first())
+ .map_or(5.4, |c| c.margins[if bidi { 3 } else { 1 }]);
+ let indent = tbl.ind.unwrap_or(0.0);
+ let compat = formats.settings.compat_mode;
+ let mut left = if compat < 15 {
+ indent - first_margin
+ } else {
+ indent
+ };
+ let jc = match (tbl.jc.as_deref(), bidi) {
+ (Some("start"), false) | (Some("end"), true) => Some("left"),
+ (Some("start"), true) | (Some("end"), false) => Some("right"),
+ (jc, _) => jc,
+ };
+ match jc {
+ Some("center") => left = (avail - width) / 2.0,
+ Some("right") => left = avail - width,
+ // A right-to-left table is indented from the right.
+ None if bidi => left = avail - width - left,
+ _ => {}
+ }
+ TableGeom {
+ cols,
+ left,
+ tbl,
+ rows,
+ }
+}
diff --git a/crates/docx_engine/src/layout/test.rs b/crates/docx_engine/src/layout/test.rs
new file mode 100644
index 0000000000..8eb2c944c0
--- /dev/null
+++ b/crates/docx_engine/src/layout/test.rs
@@ -0,0 +1,336 @@
+//! Laying a document out again from the cache after edits gives the same
+//! pages as laying it out afresh.
+
+use crate::document::Document;
+use crate::edit::{BreakKind, EditOp, Pos, Session, Unit};
+use crate::model::block::{BlockId, BlockKind};
+use crate::test_support::{Parts, docx, fonts, layout_diff};
+use std::path::{Path, PathBuf};
+
+fn fixture(name: &str) -> Vec<u8> {
+ let path = Path::new(env!("CARGO_MANIFEST_DIR"))
+ .join("tests/fixtures")
+ .join(name);
+ std::fs::read(path).expect("fixture")
+}
+
+/// Where the session's layout (laid out again from its cache) differs
+/// from laying its document out afresh.
+fn stale(s: &mut Session) -> Option<String> {
+ let cached = s.layout(fonts());
+ let fresh = s.document().layout(fonts());
+ layout_diff(&cached, &fresh)
+}
+
+fn check(s: &mut Session, what: &str, failures: &mut Vec<String>) {
+ if let Some(d) = stale(s) {
+ failures.push(format!("after {what}: {d}"));
+ }
+}
+
+fn caret(s: &mut Session, block: &BlockId, offset: usize) {
+ let at = Pos::new(block.clone(), offset);
+ s.apply(
+ &[EditOp::Select {
+ anchor: at.clone(),
+ focus: at,
+ }],
+ None,
+ fonts(),
+ )
+ .expect("select");
+}
+
+fn type_text(s: &mut Session, text: &str) {
+ s.apply(
+ &[EditOp::InsertText {
+ text: text.to_owned(),
+ }],
+ Some("typing"),
+ fonts(),
+ )
+ .expect("type");
+}
+
+/// Runs an edit that may not apply to every document (a row outside a
+/// table): only the layout afterwards matters.
+fn run(s: &mut Session, op: EditOp) {
+ let _ = s.apply(&[op], None, fonts());
+}
+
+fn backspace(s: &mut Session) {
+ run(
+ s,
+ EditOp::Delete {
+ forward: false,
+ unit: Unit::Char,
+ },
+ );
+}
+
+/// Body paragraphs to edit.
+struct Targets {
+ first: BlockId,
+ in_table: Option<BlockId>,
+ in_list: Option<BlockId>,
+ middle: BlockId,
+ last: BlockId,
+}
+
+fn targets(doc: &Document) -> Option<Targets> {
+ let body = doc.body();
+ let paras = body.paragraphs();
+ let in_table = paras
+ .iter()
+ .find(|id| {
+ body.ancestors(id)
+ .iter()
+ .any(|a| body.get(a).is_some_and(|b| b.kind == BlockKind::Cell))
+ })
+ .cloned();
+ let in_list = paras
+ .iter()
+ .find(|id| body.get(id).is_some_and(|b| b.props.contains("numPr")))
+ .cloned();
+ Some(Targets {
+ first: paras.first()?.clone(),
+ in_table,
+ in_list,
+ middle: paras.get(paras.len() / 2)?.clone(),
+ last: paras.last()?.clone(),
+ })
+}
+
+fn len_of(s: &Session, id: &BlockId) -> usize {
+ s.document().body().get(id).map_or(0, |b| b.content.len())
+}
+
+/// Types into, splits and joins paragraphs, breaks pages, adds a note and
+/// a table row, then undoes it all and redoes a step, comparing the
+/// session's layout with a fresh one after each.
+fn exercise(s: &mut Session) -> Vec<String> {
+ let mut failures = Vec::new();
+ check(s, "opening", &mut failures);
+ let Some(t) = targets(s.document()) else {
+ return failures;
+ };
+ let typed = [
+ Some(&t.first),
+ t.in_table.as_ref(),
+ t.in_list.as_ref(),
+ Some(&t.middle),
+ Some(&t.last),
+ ];
+ for (k, id) in typed.into_iter().flatten().enumerate() {
+ caret(s, id, 1.min(len_of(s, id)));
+ type_text(s, "x");
+ check(s, &format!("typing in paragraph {k}"), &mut failures);
+ }
+ // A new list item renumbers the items after it.
+ let item = t.in_list.as_ref().unwrap_or(&t.middle);
+ caret(s, item, 0);
+ run(s, EditOp::InsertParagraph);
+ check(s, "starting a paragraph", &mut failures);
+ backspace(s);
+ check(s, "joining it again", &mut failures);
+ caret(s, &t.middle, len_of(s, &t.middle));
+ run(
+ s,
+ EditOp::InsertBreak {
+ kind: BreakKind::Page,
+ },
+ );
+ check(s, "breaking the page", &mut failures);
+ backspace(s);
+ check(s, "removing the break", &mut failures);
+ if let Some(cell) = &t.in_table {
+ caret(s, cell, 0);
+ run(s, EditOp::InsertRow { below: true });
+ check(s, "adding a table row", &mut failures);
+ }
+ // A note before the others renumbers them.
+ caret(s, &t.first, 1.min(len_of(s, &t.first)));
+ run(s, EditOp::InsertNote { endnote: false });
+ type_text(s, "A new note.");
+ run(s, EditOp::ExitStory);
+ check(s, "adding a footnote", &mut failures);
+ caret(s, &t.middle, 0);
+ type_text(
+ s,
+ "Several more words that make the paragraph longer, so that it takes \
+ another line and what follows it moves down the page. ",
+ );
+ check(s, "lengthening a paragraph", &mut failures);
+ while s.can_undo() {
+ s.undo(fonts());
+ check(s, "undo", &mut failures);
+ }
+ s.redo(fonts());
+ check(s, "redo", &mut failures);
+ failures
+}
+
+#[test]
+fn relaying_out_after_edits_matches_a_fresh_layout() {
+ for name in ["complex-msa.docx", "mutual-nda.docx", "simple_test.docx"] {
+ let doc = Document::open(fixture(name)).expect("open");
+ let failures = exercise(&mut Session::new(doc));
+ assert!(failures.is_empty(), "{name}: {}", failures.join("\n"));
+ }
+}
+
+const NUMBERING: &str = r#"<w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/><w:pPr><w:ind w:left="720" w:hanging="360"/></w:pPr></w:lvl></w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>"#;
+
+const FOOTNOTES: &str = r#"<w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote><w:footnote w:type="continuationSeparator" w:id="0"><w:p><w:r><w:continuationSeparator/></w:r></w:p></w:footnote><w:footnote w:id="1"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> The first note.</w:t></w:r></w:p></w:footnote><w:footnote w:id="2"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> The second note, which is long enough to take more than one line at the foot of the page.</w:t></w:r></w:p></w:footnote>"#;
+
+const HEADER: &str = r#"<w:p><w:r><w:t xml:space="preserve">Page </w:t></w:r><w:fldSimple w:instr="PAGE"><w:r><w:t>1</w:t></w:r></w:fldSimple><w:r><w:t xml:space="preserve"> of </w:t></w:r><w:fldSimple w:instr="NUMPAGES"><w:r><w:t>1</w:t></w:r></w:fldSimple></w:p>"#;
+
+const SECTION: &str = r#"<w:headerReference w:type="default" r:id="rIdH1"/><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720" w:gutter="0"/>"#;
+
+/// Several pages of paragraphs, list items, a heading kept with the next
+/// paragraph, a table with a nested table and list items in its cells,
+/// footnotes, a header with page fields and two sections.
+fn long_document() -> Vec<u8> {
+ let text = "The parties agree that the terms of this agreement apply to every \
+ order placed under it, unless an order says otherwise in writing.";
+ let para = |s: &str| format!(r#"<w:p><w:r><w:t xml:space="preserve">{s}</w:t></w:r></w:p>"#);
+ let item = |s: &str| {
+ format!(
+ r#"<w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr><w:r><w:t xml:space="preserve">{s}</w:t></w:r></w:p>"#
+ )
+ };
+ let noted = |s: &str, id: u32| {
+ format!(
+ r#"<w:p><w:r><w:t xml:space="preserve">{s}</w:t></w:r><w:r><w:footnoteReference w:id="{id}"/></w:r></w:p>"#
+ )
+ };
+ let cell = |inner: &str| {
+ format!(r#"<w:tc><w:tcPr><w:tcW w:w="4500" w:type="dxa"/></w:tcPr>{inner}</w:tc>"#)
+ };
+ let nested = format!(
+ r#"<w:tbl><w:tblPr><w:tblBorders><w:top w:val="single" w:sz="4"/><w:bottom w:val="single" w:sz="4"/></w:tblBorders></w:tblPr><w:tblGrid><w:gridCol w:w="2000"/><w:gridCol w:w="2000"/></w:tblGrid><w:tr>{}{}</w:tr></w:tbl>{}"#,
+ cell(&para("Inner one")),
+ cell(&para("Inner two")),
+ para("")
+ );
+ let table = format!(
+ r#"<w:tbl><w:tblPr><w:tblBorders><w:insideH w:val="single" w:sz="4"/></w:tblBorders></w:tblPr><w:tblGrid><w:gridCol w:w="4500"/><w:gridCol w:w="4500"/></w:tblGrid><w:tr>{}{}</w:tr><w:tr>{}{}</w:tr><w:tr>{}{}</w:tr></w:tbl>"#,
+ cell(&item("A numbered cell")),
+ cell(&para(text)),
+ cell(&nested),
+ cell(&item("Another numbered cell")),
+ cell(&para("Short")),
+ cell(&para(text)),
+ );
+ let mut body = String::new();
+ for i in 0..30 {
+ body.push_str(&para(&format!("{i}. {text}")));
+ }
+ body.push_str(&noted("A paragraph with a note.", 1));
+ for i in 0..6 {
+ body.push_str(&item(&format!("Item {i}: {text}")));
+ }
+ body.push_str(r#"<w:p><w:pPr><w:keepNext/></w:pPr><w:r><w:t>A heading kept with the table</w:t></w:r></w:p>"#);
+ body.push_str(&table);
+ for i in 0..24 {
+ body.push_str(&para(&format!("{i}. {text} {text}")));
+ }
+ body.push_str(&format!(
+ r#"<w:p><w:pPr><w:sectPr>{SECTION}<w:type w:val="nextPage"/></w:sectPr></w:pPr></w:p>"#
+ ));
+ body.push_str(&noted("The second section, with another note.", 2));
+ for i in 0..16 {
+ body.push_str(&item(&format!("Later item {i}: {text}")));
+ body.push_str(&para(&format!("{text} {text} {text}")));
+ }
+ body.push_str(&format!("<w:sectPr>{SECTION}</w:sectPr>"));
+ docx(
+ &body,
+ &Parts {
+ numbering: Some(NUMBERING),
+ header: Some(HEADER),
+ footnotes: Some(FOOTNOTES),
+ ..Parts::default()
+ },
+ )
+}
+
+#[test]
+fn relaying_out_a_long_document_after_edits_matches_a_fresh_layout() {
+ let doc = Document::open(long_document()).expect("open");
+ let mut s = Session::new(doc);
+ let pages = s.pages(fonts()).len();
+ assert!(pages >= 5, "{pages} pages");
+ let failures = exercise(&mut s);
+ assert!(failures.is_empty(), "{}", failures.join("\n"));
+}
+
+/// The documents named by `DOCX_ENGINE_DOCS`: `.docx` files, or
+/// directories of them, separated by the platform's path separator.
+fn docs_from_env() -> Vec<PathBuf> {
+ let Some(list) = std::env::var_os("DOCX_ENGINE_DOCS") else {
+ return Vec::new();
+ };
+ let mut out = Vec::new();
+ for path in std::env::split_paths(&list) {
+ if path.is_dir() {
+ let mut files: Vec<PathBuf> = std::fs::read_dir(&path)
+ .map(|d| d.filter_map(|e| e.ok()).map(|e| e.path()).collect())
+ .unwrap_or_default();
+ files.retain(|f| f.extension().is_some_and(|e| e == "docx"));
+ files.sort();
+ out.extend(files);
+ } else {
+ out.push(path);
+ }
+ }
+ out
+}
+
+fn open_path(path: &Path) -> Option<Session> {
+ let doc = Document::open(std::fs::read(path).ok()?).ok()?;
+ Some(Session::new(doc))
+}
+
+#[test]
+#[ignore = "edits the documents named by DOCX_ENGINE_DOCS; run with --ignored --nocapture"]
+fn zz_relaying_out_documents_matches_a_fresh_layout() {
+ let mut failed = Vec::new();
+ for path in docs_from_env() {
+ let Some(mut s) = open_path(&path) else {
+ eprintln!("{}: does not open", path.display());
+ continue;
+ };
+ let failures = exercise(&mut s);
+ eprintln!("{}: {} differences", path.display(), failures.len());
+ if let Some(first) = failures.first() {
+ failed.push(format!("{}: {first}", path.display()));
+ }
+ }
+ assert!(failed.is_empty(), "{}", failed.join("\n\n"));
+}
+
+#[test]
+#[ignore = "times typing in the documents named by DOCX_ENGINE_DOCS; run with --ignored --nocapture"]
+fn zz_typing_time() {
+ /// Keystrokes timed per document.
+ const KEYSTROKES: u32 = 30;
+ for path in docs_from_env() {
+ let Some(mut s) = open_path(&path) else {
+ continue;
+ };
+ let pages = s.pages(fonts()).len();
+ let paras = s.document().body().paragraphs();
+ let Some(target) = paras.get(40).or(paras.last()).cloned() else {
+ continue;
+ };
+ caret(&mut s, &target, 1);
+ let started = std::time::Instant::now();
+ for _ in 0..KEYSTROKES {
+ type_text(&mut s, "x");
+ }
+ let each = started.elapsed() / KEYSTROKES;
+ let name = path.file_stem().unwrap_or_default().to_string_lossy();
+ eprintln!("{name}: {pages} pages, {each:?} per keystroke");
+ }
+}
diff --git a/crates/docx_engine/src/lib.rs b/crates/docx_engine/src/lib.rs
new file mode 100644
index 0000000000..fa19b61200
--- /dev/null
+++ b/crates/docx_engine/src/lib.rs
@@ -0,0 +1,28 @@
+//! A from-scratch Word (`.docx`) engine: parse, lay out, render, edit, save.
+//!
+//! The same code runs natively (tests, the corpus CLI) and as WebAssembly in
+//! the browser editor's worker. Paragraphs are attributed strings (text plus
+//! formatting spans) inside a tree of blocks with stable ids, which is also
+//! the shape of the collaborative state, so local edits map to small CRDT
+//! operations and remote ones apply to single blocks. Content the engine does
+//! not interpret is kept as XML snippets and written back unchanged.
+
+#![deny(missing_docs)]
+
+pub mod collab;
+pub mod document;
+pub mod edit;
+mod error;
+pub mod hash;
+pub mod layout;
+pub mod model;
+pub mod render;
+#[cfg(test)]
+mod test_support;
+pub mod units;
+#[cfg(target_arch = "wasm32")]
+mod wasm;
+pub mod xml;
+
+pub use document::Document;
+pub use error::{Error, Result};
diff --git a/crates/docx_engine/src/model.rs b/crates/docx_engine/src/model.rs
new file mode 100644
index 0000000000..c4869e2a02
--- /dev/null
+++ b/crates/docx_engine/src/model.rs
@@ -0,0 +1,11 @@
+//! The document model: blocks, formatting, styles, numbering, sections.
+
+pub mod block;
+pub mod content;
+pub mod numbering;
+pub mod parse;
+pub mod props;
+pub mod section;
+pub mod settings;
+pub mod styles;
+pub mod write;
diff --git a/crates/docx_engine/src/model/block.rs b/crates/docx_engine/src/model/block.rs
new file mode 100644
index 0000000000..027f786ae3
--- /dev/null
+++ b/crates/docx_engine/src/model/block.rs
@@ -0,0 +1,530 @@
+//! Blocks: paragraphs, tables and their rows and cells, content controls.
+//!
+//! A story (the body, a header, a footnote) is a tree of blocks addressed by
+//! stable ids. Each block keeps its own element's attributes and property
+//! elements as XML, and children are ordered by fractional position keys, so
+//! the same tree maps directly onto the collaborative maps: concurrent edits
+//! to different blocks never conflict, and inserting a paragraph never
+//! renumbers its neighbours.
+
+use super::content::Content;
+use crate::hash::FxMap;
+use pptx_engine::collab::order;
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+static VERSION: AtomicU64 = AtomicU64::new(1);
+
+/// A version number no other change in this process has used, so a block's
+/// (id, version) identifies its content across stories and document copies.
+pub fn next_version() -> u64 {
+ VERSION.fetch_add(1, Ordering::Relaxed)
+}
+
+/// Identifies a block, stable across edits, saves and peers.
+#[derive(Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct BlockId(Arc<str>);
+
+impl Serialize for BlockId {
+ fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
+ s.serialize_str(&self.0)
+ }
+}
+
+impl<'de> Deserialize<'de> for BlockId {
+ fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ let s = String::deserialize(d)?;
+ Ok(BlockId(s.into()))
+ }
+}
+
+impl BlockId {
+ /// Wraps an id string.
+ pub fn new(id: &str) -> Self {
+ Self(id.into())
+ }
+
+ /// The id as a string.
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+impl std::fmt::Debug for BlockId {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ write!(f, "#{}", self.0)
+ }
+}
+
+impl std::fmt::Display for BlockId {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(&self.0)
+ }
+}
+
+/// What a block is.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum BlockKind {
+ /// `w:p`; `props` is its `w:pPr`, `content` its runs.
+ #[serde(rename = "p")]
+ Paragraph,
+ /// `w:tbl`; `props` is `w:tblPr` and `w:tblGrid`.
+ #[serde(rename = "tbl")]
+ Table,
+ /// `w:tr`; `props` is `w:tblPrEx` and `w:trPr`.
+ #[serde(rename = "tr")]
+ Row,
+ /// `w:tc`; `props` is `w:tcPr`.
+ #[serde(rename = "tc")]
+ Cell,
+ /// A block-level element wrapping blocks (`w:sdt`, `w:customXml`);
+ /// `props` is JSON `[open, close]` markup around the children.
+ #[serde(rename = "sdt")]
+ Container,
+ /// Any other block-level element, kept verbatim in `props`.
+ #[serde(rename = "x")]
+ Opaque,
+}
+
+impl BlockKind {
+ /// The short code used in collaborative entries.
+ pub fn code(self) -> &'static str {
+ match self {
+ BlockKind::Paragraph => "p",
+ BlockKind::Table => "tbl",
+ BlockKind::Row => "tr",
+ BlockKind::Cell => "tc",
+ BlockKind::Container => "sdt",
+ BlockKind::Opaque => "x",
+ }
+ }
+
+ /// Parses a short code.
+ pub fn from_code(code: &str) -> Option<Self> {
+ Some(match code {
+ "p" => BlockKind::Paragraph,
+ "tbl" => BlockKind::Table,
+ "tr" => BlockKind::Row,
+ "tc" => BlockKind::Cell,
+ "sdt" => BlockKind::Container,
+ "x" => BlockKind::Opaque,
+ _ => return None,
+ })
+ }
+}
+
+/// One block.
+#[derive(Clone, Debug)]
+pub struct Block {
+ /// Stable id.
+ pub id: BlockId,
+ /// Kind.
+ pub kind: BlockKind,
+ /// The containing block (`None` = the story itself).
+ pub parent: Option<BlockId>,
+ /// Fractional position among its siblings.
+ pub order: String,
+ /// Attributes of the block's element as written (with a leading space).
+ pub attrs: String,
+ /// Property elements (or the whole element for opaque blocks), as XML.
+ pub props: String,
+ /// Runs of a paragraph.
+ pub content: Content,
+ /// Bumped on every change; layout caches key on it.
+ pub version: u64,
+}
+
+impl Block {
+ /// A new block.
+ pub fn new(id: BlockId, kind: BlockKind, parent: Option<BlockId>, order: String) -> Self {
+ Self {
+ id,
+ kind,
+ parent,
+ order,
+ attrs: String::new(),
+ props: String::new(),
+ content: Content::new(),
+ version: 0,
+ }
+ }
+
+ /// The open/close markup of a container.
+ pub fn container_markup(&self) -> (String, String) {
+ serde_json::from_str::<(String, String)>(&self.props).unwrap_or_default()
+ }
+}
+
+/// A tree of blocks.
+#[derive(Clone, Debug, Default)]
+pub struct Story {
+ blocks: FxMap<BlockId, Block>,
+ /// Children of each parent (`None` = top level), sorted by (order, id).
+ children: FxMap<Option<BlockId>, Vec<BlockId>>,
+ /// Changes on every change (a [`next_version`] value).
+ revision: u64,
+ /// Changes when blocks are added, removed or moved (not when their
+ /// content or properties change).
+ structure: u64,
+}
+
+static NO_CHILDREN: Vec<BlockId> = Vec::new();
+
+impl Story {
+ /// An empty story.
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Changes on every change to the story.
+ pub fn revision(&self) -> u64 {
+ self.revision
+ }
+
+ /// Changes when blocks are added, removed or moved: what depends only on
+ /// the order of blocks (not their text) keys on it.
+ pub fn structure(&self) -> u64 {
+ self.structure
+ }
+
+ /// Number of blocks.
+ pub fn len(&self) -> usize {
+ self.blocks.len()
+ }
+
+ /// Whether the story has no blocks.
+ pub fn is_empty(&self) -> bool {
+ self.blocks.is_empty()
+ }
+
+ /// A block.
+ pub fn get(&self, id: &BlockId) -> Option<&Block> {
+ self.blocks.get(id)
+ }
+
+ /// A block, for changing. Bumps its version.
+ pub fn get_mut(&mut self, id: &BlockId) -> Option<&mut Block> {
+ let version = next_version();
+ self.revision = version;
+ let block = self.blocks.get_mut(id)?;
+ block.version = version;
+ Some(block)
+ }
+
+ /// Whether the block exists.
+ pub fn contains(&self, id: &BlockId) -> bool {
+ self.blocks.contains_key(id)
+ }
+
+ /// Every block, in no particular order.
+ pub fn blocks(&self) -> impl Iterator<Item = &Block> {
+ self.blocks.values()
+ }
+
+ /// Children of `parent` (`None` = top level), in order.
+ pub fn children(&self, parent: Option<&BlockId>) -> &[BlockId] {
+ self.children.get(&parent.cloned()).unwrap_or(&NO_CHILDREN)
+ }
+
+ fn sort_children(&mut self, parent: Option<&BlockId>) {
+ let blocks = &self.blocks;
+ if let Some(list) = self.children.get_mut(&parent.cloned()) {
+ list.sort_by(|a, b| {
+ let (ka, kb) = (
+ blocks.get(a).map_or("", |x| x.order.as_str()),
+ blocks.get(b).map_or("", |x| x.order.as_str()),
+ );
+ ka.cmp(kb).then_with(|| a.cmp(b))
+ });
+ }
+ }
+
+ /// Where a block with this position key and id goes among `list`
+ /// (sorted by key, then id).
+ fn slot(blocks: &FxMap<BlockId, Block>, list: &[BlockId], order: &str, id: &BlockId) -> usize {
+ list.partition_point(|c| {
+ let key = blocks.get(c).map_or("", |x| x.order.as_str());
+ (key, c) < (order, id)
+ })
+ }
+
+ /// Adds or replaces a block, keeping its parent's children ordered.
+ /// Placing it costs a binary search, so reading a long document's
+ /// blocks one by one stays linear.
+ pub fn insert(&mut self, mut block: Block) {
+ self.revision = next_version();
+ block.version = self.revision;
+ let id = block.id.clone();
+ let same_place = self
+ .blocks
+ .get(&id)
+ .is_some_and(|old| old.parent == block.parent && old.order == block.order);
+ if same_place {
+ // Content or properties only: the block keeps its place.
+ self.blocks.insert(id, block);
+ return;
+ }
+ self.structure = self.revision;
+ // Take it out of the list it is in now.
+ if let Some(old) = self.blocks.get(&id) {
+ let blocks = &self.blocks;
+ if let Some(list) = self.children.get_mut(&old.parent) {
+ let at = Self::slot(blocks, list, &old.order, &id);
+ if list.get(at) == Some(&id) {
+ list.remove(at);
+ } else {
+ list.retain(|c| *c != id);
+ }
+ }
+ }
+ let parent = block.parent.clone();
+ let order = block.order.clone();
+ self.blocks.insert(id.clone(), block);
+ let blocks = &self.blocks;
+ let list = self.children.entry(parent).or_default();
+ let at = Self::slot(blocks, list, &order, &id);
+ list.insert(at, id);
+ }
+
+ /// Changes a block's position key (and parent).
+ pub fn move_block(&mut self, id: &BlockId, parent: Option<BlockId>, order: String) {
+ let Some(mut block) = self.blocks.get(id).cloned() else {
+ return;
+ };
+ block.parent = parent;
+ block.order = order;
+ self.insert(block);
+ }
+
+ /// Removes a block and everything inside it; returns the removed ids.
+ pub fn remove(&mut self, id: &BlockId) -> Vec<BlockId> {
+ let mut removed = Vec::new();
+ let mut stack = vec![id.clone()];
+ while let Some(at) = stack.pop() {
+ if let Some(kids) = self.children.remove(&Some(at.clone())) {
+ stack.extend(kids);
+ }
+ if let Some(b) = self.blocks.remove(&at) {
+ if let Some(list) = self.children.get_mut(&b.parent) {
+ list.retain(|c| *c != at);
+ }
+ removed.push(at);
+ }
+ }
+ self.revision = next_version();
+ self.structure = self.revision;
+ removed
+ }
+
+ /// Removes one block, keeping its children (which become orphans until
+ /// re-parented or removed).
+ pub fn remove_one(&mut self, id: &BlockId) -> Option<Block> {
+ let b = self.blocks.remove(id)?;
+ if let Some(list) = self.children.get_mut(&b.parent) {
+ list.retain(|c| c != id);
+ }
+ self.revision = next_version();
+ self.structure = self.revision;
+ Some(b)
+ }
+
+ /// Visits blocks depth-first in document order.
+ pub fn walk(&self, mut f: impl FnMut(&Block, usize)) {
+ fn go(
+ story: &Story,
+ parent: Option<&BlockId>,
+ depth: usize,
+ f: &mut dyn FnMut(&Block, usize),
+ ) {
+ for id in story.children(parent) {
+ if let Some(b) = story.blocks.get(id) {
+ f(b, depth);
+ go(story, Some(id), depth + 1, f);
+ }
+ }
+ }
+ go(self, None, 0, &mut f);
+ }
+
+ /// Visits a block and everything inside it, depth-first in order.
+ pub fn walk_from(&self, id: &BlockId, f: &mut dyn FnMut(&Block)) {
+ let Some(b) = self.blocks.get(id) else {
+ return;
+ };
+ f(b);
+ for c in self.children(Some(id)) {
+ self.walk_from(c, f);
+ }
+ }
+
+ /// Paragraph ids in document order (including those inside tables).
+ pub fn paragraphs(&self) -> Vec<BlockId> {
+ let mut out = Vec::new();
+ self.walk(|b, _| {
+ if b.kind == BlockKind::Paragraph {
+ out.push(b.id.clone());
+ }
+ });
+ out
+ }
+
+ /// The chain of ancestors of a block, nearest first.
+ pub fn ancestors(&self, id: &BlockId) -> Vec<BlockId> {
+ let mut out = Vec::new();
+ let mut at = self.blocks.get(id).and_then(|b| b.parent.clone());
+ while let Some(p) = at {
+ at = self.blocks.get(&p).and_then(|b| b.parent.clone());
+ out.push(p);
+ }
+ out
+ }
+
+ /// The position key for a new child of `parent` placed after `after`
+ /// (`None` = first) and before the sibling that follows it.
+ pub fn key_after(&self, parent: Option<&BlockId>, after: Option<&BlockId>) -> String {
+ let kids = self.children(parent);
+ let index = match after {
+ Some(a) => kids
+ .iter()
+ .position(|k| k == a)
+ .map_or(kids.len(), |i| i + 1),
+ None => 0,
+ };
+ let low = index
+ .checked_sub(1)
+ .and_then(|i| kids.get(i))
+ .and_then(|k| self.blocks.get(k))
+ .map(|b| b.order.as_str());
+ let high = kids
+ .get(index)
+ .and_then(|k| self.blocks.get(k))
+ .map(|b| b.order.as_str());
+ order::key_between(low, high)
+ }
+
+ /// The position key for a new child of `parent` placed just before
+ /// `before`.
+ pub fn key_before(&self, parent: Option<&BlockId>, before: &BlockId) -> String {
+ let kids = self.children(parent);
+ let index = kids.iter().position(|k| k == before).unwrap_or(0);
+ let low = index
+ .checked_sub(1)
+ .and_then(|i| kids.get(i))
+ .and_then(|k| self.blocks.get(k))
+ .map(|b| b.order.as_str());
+ let high = kids
+ .get(index)
+ .and_then(|k| self.blocks.get(k))
+ .map(|b| b.order.as_str());
+ order::key_between(low, high)
+ }
+
+ /// Re-sorts every children list (after bulk changes to order keys).
+ pub fn resort(&mut self) {
+ let parents: Vec<Option<BlockId>> = self.children.keys().cloned().collect();
+ for p in parents {
+ self.sort_children(p.as_ref());
+ }
+ }
+
+ /// Blocks whose parent is missing (left behind by concurrent deletes).
+ pub fn orphans(&self) -> Vec<BlockId> {
+ self.blocks
+ .values()
+ .filter(|b| {
+ b.parent
+ .as_ref()
+ .is_some_and(|p| !self.blocks.contains_key(p))
+ })
+ .map(|b| b.id.clone())
+ .collect()
+ }
+}
+
+/// Generates block ids: sequential for documents opened locally, random
+/// (per-peer seeded) for collaborative ones so concurrent inserts never collide.
+#[derive(Debug)]
+pub struct IdGen {
+ next: u64,
+ random: Option<Arc<pptx_engine::opc::IdSource>>,
+ /// Put before sequential ids (stories outside the body).
+ prefix: Option<Box<str>>,
+}
+
+impl IdGen {
+ /// Sequential ids starting at 1.
+ pub fn sequential() -> Self {
+ Self {
+ next: 1,
+ random: None,
+ prefix: None,
+ }
+ }
+
+ /// Sequential ids after a prefix: stable for a story read from the same
+ /// XML, and distinct from every other story's.
+ pub fn prefixed(prefix: &str) -> Self {
+ Self {
+ next: 1,
+ random: None,
+ prefix: Some(prefix.into()),
+ }
+ }
+
+ /// Random ids from a seeded source.
+ pub fn random(seed: u64) -> Self {
+ Self {
+ next: 1,
+ random: Some(Arc::new(pptx_engine::opc::IdSource::new(seed))),
+ prefix: None,
+ }
+ }
+
+ /// Whether ids are random.
+ pub fn is_random(&self) -> bool {
+ self.random.is_some()
+ }
+
+ /// The random source, if any.
+ pub fn source(&self) -> Option<&Arc<pptx_engine::opc::IdSource>> {
+ self.random.as_ref()
+ }
+
+ /// The next id.
+ pub fn next_id(&mut self) -> BlockId {
+ match &self.random {
+ Some(r) => BlockId::new(&radix36(r.next_in(1 << 40..1 << 52))),
+ None => {
+ let n = self.next;
+ self.next += 1;
+ match &self.prefix {
+ Some(p) => BlockId::new(&format!("{p}{}", radix36(n))),
+ None => BlockId::new(&radix36(n)),
+ }
+ }
+ }
+ }
+}
+
+fn radix36(mut n: u64) -> String {
+ const DIGITS: &[u8] = b"0123456789abcdefghijklmnopqrstuvwxyz";
+ let mut out = Vec::new();
+ loop {
+ out.push(DIGITS[(n % 36) as usize]);
+ n /= 36;
+ if n == 0 {
+ break;
+ }
+ }
+ out.reverse();
+ String::from_utf8(out).unwrap_or_default()
+}
+
+/// Spreads `count` fresh position keys evenly.
+pub fn initial_keys(count: usize) -> Vec<String> {
+ order::keys_between(None, None, count)
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/model/block/test.rs b/crates/docx_engine/src/model/block/test.rs
new file mode 100644
index 0000000000..219b69239b
--- /dev/null
+++ b/crates/docx_engine/src/model/block/test.rs
@@ -0,0 +1,72 @@
+use super::*;
+
+#[test]
+fn children_stay_ordered_by_key() {
+ let mut s = Story::new();
+ let a = BlockId::new("a");
+ let b = BlockId::new("b");
+ s.insert(Block::new(
+ a.clone(),
+ BlockKind::Paragraph,
+ None,
+ "V".into(),
+ ));
+ s.insert(Block::new(
+ b.clone(),
+ BlockKind::Paragraph,
+ None,
+ "F".into(),
+ ));
+ assert_eq!(s.children(None), &[b.clone(), a.clone()]);
+ let key = s.key_after(None, Some(&b));
+ assert!(key.as_str() > "F" && key.as_str() < "V");
+ let c = BlockId::new("c");
+ s.insert(Block::new(c.clone(), BlockKind::Paragraph, None, key));
+ assert_eq!(s.children(None), &[b.clone(), c.clone(), a.clone()]);
+ s.move_block(&a, None, s.key_after(None, None));
+ assert_eq!(s.children(None)[0], a);
+}
+
+#[test]
+fn removing_a_table_removes_its_cells() {
+ let mut s = Story::new();
+ let t = BlockId::new("t");
+ let r = BlockId::new("r");
+ let c = BlockId::new("c");
+ let p = BlockId::new("p");
+ s.insert(Block::new(t.clone(), BlockKind::Table, None, "V".into()));
+ s.insert(Block::new(
+ r.clone(),
+ BlockKind::Row,
+ Some(t.clone()),
+ "V".into(),
+ ));
+ s.insert(Block::new(
+ c.clone(),
+ BlockKind::Cell,
+ Some(r.clone()),
+ "V".into(),
+ ));
+ s.insert(Block::new(
+ p.clone(),
+ BlockKind::Paragraph,
+ Some(c.clone()),
+ "V".into(),
+ ));
+ assert_eq!(s.paragraphs(), vec![p.clone()]);
+ assert_eq!(s.ancestors(&p), vec![c.clone(), r.clone(), t.clone()]);
+ let removed = s.remove(&t);
+ assert_eq!(removed.len(), 4);
+ assert!(s.is_empty());
+}
+
+#[test]
+fn ids_are_unique() {
+ let mut seq = IdGen::sequential();
+ assert_eq!(seq.next_id().as_str(), "1");
+ let mut r1 = IdGen::random(1);
+ let mut r2 = IdGen::random(2);
+ let a: Vec<BlockId> = (0..100).map(|_| r1.next_id()).collect();
+ let b: Vec<BlockId> = (0..100).map(|_| r2.next_id()).collect();
+ assert!(a.iter().all(|x| !b.contains(x)));
+}
diff --git a/crates/docx_engine/src/model/content.rs b/crates/docx_engine/src/model/content.rs
new file mode 100644
index 0000000000..1f3497af5e
--- /dev/null
+++ b/crates/docx_engine/src/model/content.rs
@@ -0,0 +1,648 @@
+//! Paragraph content as an attributed string.
+//!
+//! A paragraph's runs are flattened into text plus attribute spans, the shape
+//! a rich-text CRDT stores (one Loro text per paragraph, marks for formatting).
+//! Every run property element is its own attribute (`r:w:b` → `<w:b/>`), so
+//! two people formatting overlapping text in different ways both win.
+//! Non-text run content (pictures, field characters, note references,
+//! bookmarks...) is an object character, U+FFFC, whose `obj` attribute holds
+//! its XML. Hyperlinks, tracked changes, content controls and the other
+//! elements that wrap runs are a `wrap` attribute listing their tags.
+//!
+//! Positions are UTF-16 code units, the unit JavaScript strings and the CRDT
+//! use, so offsets mean the same thing on both sides of the worker boundary.
+
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+/// The object replacement character standing in for non-text content.
+pub const OBJECT_CHAR: char = '\u{FFFC}';
+
+/// Attribute keys.
+pub mod key {
+ /// XML of an object character's element, which belongs inside a run
+ /// (pictures, field characters, note references, symbols...).
+ pub const OBJ: &str = "obj";
+ /// XML of an object character's element, which sits between runs
+ /// (bookmarks, comment ranges, math...).
+ pub const MARK: &str = "mark";
+ /// JSON `[[open, close], ...]` of the elements wrapping the text, outermost first.
+ pub const WRAP: &str = "wrap";
+ /// Marks field instruction text (`w:instrText`).
+ pub const INSTR: &str = "instr";
+ /// Prefix of run property keys: `r:` + the property element's qualified name.
+ pub const RUN_PROP: &str = "r:";
+ /// Prefix of run element attribute keys: `ra:` + the attribute's qualified name.
+ pub const RUN_ATTR: &str = "ra:";
+}
+
+/// An immutable attribute set, shared between spans.
+#[derive(Clone, Default, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct Attrs(Arc<BTreeMap<Box<str>, Box<str>>>);
+
+impl std::fmt::Debug for Attrs {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_map().entries(self.0.iter()).finish()
+ }
+}
+
+impl Attrs {
+ /// The empty set.
+ pub fn empty() -> Self {
+ Self::default()
+ }
+
+ /// A set from key/value pairs.
+ pub fn from_pairs<K: Into<Box<str>>, V: Into<Box<str>>>(
+ pairs: impl IntoIterator<Item = (K, V)>,
+ ) -> Self {
+ Self(Arc::new(
+ pairs
+ .into_iter()
+ .map(|(k, v)| (k.into(), v.into()))
+ .collect(),
+ ))
+ }
+
+ /// One value.
+ pub fn get(&self, key: &str) -> Option<&str> {
+ self.0.get(key).map(|v| &**v)
+ }
+
+ /// Whether two sets are the same shared object (cheap identity, for
+ /// caches keyed by `ptr`).
+ pub fn same(&self, other: &Attrs) -> bool {
+ Arc::ptr_eq(&self.0, &other.0)
+ }
+
+ /// The shared object's address, for caches that hold on to the set.
+ pub fn ptr(&self) -> usize {
+ Arc::as_ptr(&self.0) as *const () as usize
+ }
+
+ /// Whether the set holds `key`.
+ pub fn has(&self, key: &str) -> bool {
+ self.0.contains_key(key)
+ }
+
+ /// Whether the set is empty.
+ pub fn is_empty(&self) -> bool {
+ self.0.is_empty()
+ }
+
+ /// Every entry, in key order.
+ pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
+ self.0.iter().map(|(k, v)| (&**k, &**v))
+ }
+
+ /// The set with `key` set to `value` (or removed when `None`).
+ pub fn with(&self, key: &str, value: Option<&str>) -> Self {
+ if self.get(key) == value {
+ return self.clone();
+ }
+ let mut map = (*self.0).clone();
+ match value {
+ Some(v) => {
+ map.insert(key.into(), v.into());
+ }
+ None => {
+ map.remove(key);
+ }
+ }
+ Self(Arc::new(map))
+ }
+
+ /// The set without the keys `drop` selects.
+ pub fn without(&self, drop: impl Fn(&str) -> bool) -> Self {
+ if !self.0.keys().any(|k| drop(k)) {
+ return self.clone();
+ }
+ Self(Arc::new(
+ self.0
+ .iter()
+ .filter(|(k, _)| !drop(k))
+ .map(|(k, v)| (k.clone(), v.clone()))
+ .collect(),
+ ))
+ }
+
+ /// Run property entries (`r:` keys) with the prefix stripped.
+ pub fn run_props(&self) -> impl Iterator<Item = (&str, &str)> {
+ self.iter()
+ .filter_map(|(k, v)| k.strip_prefix(key::RUN_PROP).map(|k| (k, v)))
+ }
+
+ /// The run-level object XML of an object character.
+ pub fn object(&self) -> Option<&str> {
+ self.get(key::OBJ)
+ }
+
+ /// The paragraph-level marker XML of an object character.
+ pub fn marker(&self) -> Option<&str> {
+ self.get(key::MARK)
+ }
+
+ /// Whether the character carries an object or a marker.
+ pub fn is_object(&self) -> bool {
+ self.has(key::OBJ) || self.has(key::MARK)
+ }
+
+ /// The wrapper stack, outermost first.
+ pub fn wrappers(&self) -> Vec<Wrapper> {
+ self.get(key::WRAP)
+ .and_then(|w| serde_json::from_str::<Vec<(String, String)>>(w).ok())
+ .unwrap_or_default()
+ .into_iter()
+ .map(|(open, close)| Wrapper { open, close })
+ .collect()
+ }
+
+ /// Whether the text is field instruction text.
+ pub fn is_instr(&self) -> bool {
+ self.has(key::INSTR)
+ }
+
+ /// The formatting a character typed next to this one inherits: run
+ /// properties and wrappers, without object or field-code markers.
+ pub fn for_typing(&self) -> Self {
+ self.without(|k| k == key::OBJ || k == key::MARK || k == key::INSTR)
+ }
+}
+
+/// An element wrapping runs: its opening markup (start tag and property
+/// children) and closing markup.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Wrapper {
+ /// Markup before the content.
+ pub open: String,
+ /// Markup after the content.
+ pub close: String,
+}
+
+impl Wrapper {
+ /// The element's qualified name.
+ pub fn qname(&self) -> &str {
+ let tag = self.open.trim_start_matches('<');
+ let end = tag
+ .find(|c: char| c.is_whitespace() || c == '>' || c == '/')
+ .unwrap_or(tag.len());
+ &tag[..end]
+ }
+
+ /// The local name (after the prefix).
+ pub fn local(&self) -> &str {
+ let q = self.qname();
+ q.rsplit(':').next().unwrap_or(q)
+ }
+}
+
+/// Encodes a wrapper stack as the `wrap` attribute value.
+pub fn encode_wrappers(stack: &[Wrapper]) -> Option<String> {
+ if stack.is_empty() {
+ return None;
+ }
+ let pairs: Vec<(&str, &str)> = stack
+ .iter()
+ .map(|w| (w.open.as_str(), w.close.as_str()))
+ .collect();
+ serde_json::to_string(&pairs).ok()
+}
+
+/// A run of text sharing one attribute set.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Span {
+ /// The text.
+ pub text: String,
+ /// Its attributes.
+ pub attrs: Attrs,
+}
+
+/// Number of UTF-16 code units in `s`.
+pub fn utf16_len(s: &str) -> usize {
+ s.chars().map(char::len_utf16).sum()
+}
+
+/// Byte offset of UTF-16 offset `at` in `s` (clamped to the end; an offset
+/// inside a surrogate pair rounds up to the next character).
+pub fn byte_at(s: &str, at: usize) -> usize {
+ let mut units = 0;
+ for (i, c) in s.char_indices() {
+ if units >= at {
+ return i;
+ }
+ units += c.len_utf16();
+ }
+ s.len()
+}
+
+/// A paragraph's content: spans with distinct neighbouring attributes.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct Content {
+ spans: Vec<Span>,
+}
+
+/// One operation of a rich-text delta (Quill's format, as Loro reads and
+/// writes it). Lengths are UTF-16 code units.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum DeltaOp {
+ /// Insert text with exactly these attributes.
+ Insert {
+ /// The text.
+ insert: String,
+ /// Its attributes (every one it has).
+ #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+ attributes: BTreeMap<String, serde_json::Value>,
+ },
+ /// Delete characters.
+ Delete {
+ /// How many.
+ delete: usize,
+ },
+ /// Keep characters, changing the listed attributes (`null` removes one).
+ Retain {
+ /// How many.
+ retain: usize,
+ /// Attribute changes.
+ #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+ attributes: BTreeMap<String, serde_json::Value>,
+ },
+}
+
+fn attrs_to_json(attrs: &Attrs) -> BTreeMap<String, serde_json::Value> {
+ attrs
+ .iter()
+ .map(|(k, v)| (k.to_owned(), serde_json::Value::String(v.to_owned())))
+ .collect()
+}
+
+fn json_to_attr(v: &serde_json::Value) -> Option<String> {
+ match v {
+ serde_json::Value::Null => None,
+ serde_json::Value::String(s) => Some(s.clone()),
+ other => Some(other.to_string()),
+ }
+}
+
+impl Content {
+ /// Empty content.
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Content from spans (normalized).
+ pub fn from_spans(spans: impl IntoIterator<Item = Span>) -> Self {
+ let mut c = Self::new();
+ for s in spans {
+ c.push(&s.text, s.attrs);
+ }
+ c
+ }
+
+ /// Appends text with `attrs`, merging with the last span when equal.
+ pub fn push(&mut self, text: &str, attrs: Attrs) {
+ if text.is_empty() {
+ return;
+ }
+ if let Some(last) = self.spans.last_mut()
+ && last.attrs == attrs
+ {
+ last.text.push_str(text);
+ return;
+ }
+ self.spans.push(Span {
+ text: text.to_owned(),
+ attrs,
+ });
+ }
+
+ /// The spans.
+ pub fn spans(&self) -> &[Span] {
+ &self.spans
+ }
+
+ /// Length in UTF-16 code units.
+ pub fn len(&self) -> usize {
+ self.spans.iter().map(|s| utf16_len(&s.text)).sum()
+ }
+
+ /// Whether there is no content.
+ pub fn is_empty(&self) -> bool {
+ self.spans.is_empty()
+ }
+
+ /// The plain text, object characters included.
+ pub fn text(&self) -> String {
+ self.spans.iter().map(|s| s.text.as_str()).collect()
+ }
+
+ /// Spans with their UTF-16 start offsets.
+ pub fn spans_at(&self) -> impl Iterator<Item = (usize, &Span)> {
+ let mut at = 0;
+ self.spans.iter().map(move |s| {
+ let start = at;
+ at += utf16_len(&s.text);
+ (start, s)
+ })
+ }
+
+ /// Attributes of the character at `pos` (`None` past the end).
+ pub fn attrs_at(&self, pos: usize) -> Option<&Attrs> {
+ let mut at = 0;
+ for s in &self.spans {
+ let len = utf16_len(&s.text);
+ if pos < at + len {
+ return Some(&s.attrs);
+ }
+ at += len;
+ }
+ None
+ }
+
+ /// The formatting text typed at `pos` gets: that of the character before
+ /// it, or after it at the start of the paragraph.
+ pub fn typing_attrs(&self, pos: usize) -> Attrs {
+ let before = if pos > 0 {
+ self.attrs_at(pos - 1)
+ } else {
+ None
+ };
+ // Typing after an object (a picture, a field end) takes the formatting
+ // of the text around it, never the object itself.
+ before
+ .or_else(|| self.attrs_at(pos))
+ .map(Attrs::for_typing)
+ .unwrap_or_default()
+ }
+
+ /// Splits spans so that `pos` falls on a span boundary; returns the index
+ /// of the first span at or after `pos`.
+ fn split_at(&mut self, pos: usize) -> usize {
+ let mut at = 0;
+ for i in 0..self.spans.len() {
+ let len = utf16_len(&self.spans[i].text);
+ if pos == at {
+ return i;
+ }
+ if pos < at + len {
+ let b = byte_at(&self.spans[i].text, pos - at);
+ let tail = self.spans[i].text.split_off(b);
+ let attrs = self.spans[i].attrs.clone();
+ self.spans.insert(i + 1, Span { text: tail, attrs });
+ return i + 1;
+ }
+ at += len;
+ }
+ self.spans.len()
+ }
+
+ fn normalize(&mut self) {
+ let mut out: Vec<Span> = Vec::with_capacity(self.spans.len());
+ for s in self.spans.drain(..) {
+ if s.text.is_empty() {
+ continue;
+ }
+ match out.last_mut() {
+ Some(last) if last.attrs == s.attrs => last.text.push_str(&s.text),
+ _ => out.push(s),
+ }
+ }
+ self.spans = out;
+ }
+
+ /// Inserts `text` with `attrs` at `pos`.
+ pub fn insert(&mut self, pos: usize, text: &str, attrs: Attrs) {
+ if text.is_empty() {
+ return;
+ }
+ let i = self.split_at(pos.min(self.len()));
+ self.spans.insert(
+ i,
+ Span {
+ text: text.to_owned(),
+ attrs,
+ },
+ );
+ self.normalize();
+ }
+
+ /// Inserts other content at `pos`.
+ pub fn insert_content(&mut self, pos: usize, other: &Content) {
+ let i = self.split_at(pos.min(self.len()));
+ for (k, s) in other.spans.iter().enumerate() {
+ self.spans.insert(i + k, s.clone());
+ }
+ self.normalize();
+ }
+
+ /// Removes `[start, end)`.
+ pub fn delete(&mut self, start: usize, end: usize) {
+ if end <= start {
+ return;
+ }
+ let a = self.split_at(start);
+ let b = self.split_at(end);
+ self.spans.drain(a..b);
+ self.normalize();
+ }
+
+ /// A copy of `[start, end)`.
+ pub fn slice(&self, start: usize, end: usize) -> Content {
+ let mut copy = self.clone();
+ let len = copy.len();
+ copy.delete(end.min(len), len);
+ copy.delete(0, start.min(end));
+ copy
+ }
+
+ /// Splits off `[pos, len)` and returns it.
+ pub fn split_off(&mut self, pos: usize) -> Content {
+ let i = self.split_at(pos.min(self.len()));
+ let tail = self.spans.split_off(i);
+ Content { spans: tail }
+ }
+
+ /// Applies `f` to the attributes of every character in `[start, end)`.
+ pub fn map_attrs(&mut self, start: usize, end: usize, f: impl Fn(&Attrs) -> Attrs) {
+ if end <= start {
+ return;
+ }
+ let a = self.split_at(start);
+ let b = self.split_at(end);
+ for s in &mut self.spans[a..b] {
+ s.attrs = f(&s.attrs);
+ }
+ self.normalize();
+ }
+
+ /// Sets (or with `None` removes) one attribute on `[start, end)`.
+ pub fn set_attr(&mut self, start: usize, end: usize, key: &str, value: Option<&str>) {
+ self.map_attrs(start, end, |a| a.with(key, value));
+ }
+
+ /// The content as a delta of inserts (a fresh text's full state).
+ pub fn to_delta(&self) -> Vec<DeltaOp> {
+ self.spans
+ .iter()
+ .map(|s| DeltaOp::Insert {
+ insert: s.text.clone(),
+ attributes: attrs_to_json(&s.attrs),
+ })
+ .collect()
+ }
+
+ /// Content from a delta of inserts (retains and deletes are ignored).
+ pub fn from_delta(delta: &[DeltaOp]) -> Self {
+ let mut c = Content::new();
+ for op in delta {
+ if let DeltaOp::Insert { insert, attributes } = op {
+ let attrs = Attrs::from_pairs(
+ attributes
+ .iter()
+ .filter_map(|(k, v)| json_to_attr(v).map(|v| (k.clone(), v))),
+ );
+ c.push(insert, attrs);
+ }
+ }
+ c
+ }
+
+ /// Applies a delta in place.
+ pub fn apply_delta(&mut self, delta: &[DeltaOp]) {
+ let mut pos = 0;
+ for op in delta {
+ match op {
+ DeltaOp::Retain { retain, attributes } => {
+ if !attributes.is_empty() {
+ let changes: Vec<(String, Option<String>)> = attributes
+ .iter()
+ .map(|(k, v)| (k.clone(), json_to_attr(v)))
+ .collect();
+ self.map_attrs(pos, pos + retain, |a| {
+ let mut a = a.clone();
+ for (k, v) in &changes {
+ a = a.with(k, v.as_deref());
+ }
+ a
+ });
+ }
+ pos += retain;
+ }
+ DeltaOp::Insert { insert, attributes } => {
+ let attrs = Attrs::from_pairs(
+ attributes
+ .iter()
+ .filter_map(|(k, v)| json_to_attr(v).map(|v| (k.clone(), v))),
+ );
+ self.insert(pos, insert, attrs);
+ pos += utf16_len(insert);
+ }
+ DeltaOp::Delete { delete } => self.delete(pos, pos + delete),
+ }
+ }
+ }
+}
+
+/// Builds the delta that inserts `text` with `attrs` at `pos`.
+pub fn insert_delta(pos: usize, text: &str, attrs: &Attrs) -> Vec<DeltaOp> {
+ let mut d = Vec::new();
+ if pos > 0 {
+ d.push(DeltaOp::Retain {
+ retain: pos,
+ attributes: BTreeMap::new(),
+ });
+ }
+ d.push(DeltaOp::Insert {
+ insert: text.to_owned(),
+ attributes: attrs_to_json(attrs),
+ });
+ d
+}
+
+/// Builds the delta that inserts `content` at `pos`.
+pub fn insert_content_delta(pos: usize, content: &Content) -> Vec<DeltaOp> {
+ let mut d = Vec::new();
+ if pos > 0 {
+ d.push(DeltaOp::Retain {
+ retain: pos,
+ attributes: BTreeMap::new(),
+ });
+ }
+ d.extend(content.to_delta());
+ d
+}
+
+/// Builds the delta that deletes `[start, end)`.
+pub fn delete_delta(start: usize, end: usize) -> Vec<DeltaOp> {
+ let mut d = Vec::new();
+ if start > 0 {
+ d.push(DeltaOp::Retain {
+ retain: start,
+ attributes: BTreeMap::new(),
+ });
+ }
+ d.push(DeltaOp::Delete {
+ delete: end - start,
+ });
+ d
+}
+
+/// The delta that changes attributes of `before` into those of `after`,
+/// which must hold the same text.
+pub fn attr_delta(before: &Content, after: &Content) -> Vec<DeltaOp> {
+ // Walk both span lists in step over shared boundaries.
+ let mut cuts: Vec<usize> = Vec::new();
+ for (start, s) in before.spans_at() {
+ cuts.push(start);
+ cuts.push(start + utf16_len(&s.text));
+ }
+ for (start, s) in after.spans_at() {
+ cuts.push(start);
+ cuts.push(start + utf16_len(&s.text));
+ }
+ cuts.sort_unstable();
+ cuts.dedup();
+ let mut d: Vec<DeltaOp> = Vec::new();
+ let mut pending_retain = 0usize;
+ for w in cuts.windows(2) {
+ let (a, b) = (w[0], w[1]);
+ let old = before.attrs_at(a).cloned().unwrap_or_default();
+ let new = after.attrs_at(a).cloned().unwrap_or_default();
+ let mut changes = BTreeMap::new();
+ for (k, v) in new.iter() {
+ if old.get(k) != Some(v) {
+ changes.insert(k.to_owned(), serde_json::Value::String(v.to_owned()));
+ }
+ }
+ for (k, _) in old.iter() {
+ if !new.has(k) {
+ changes.insert(k.to_owned(), serde_json::Value::Null);
+ }
+ }
+ if changes.is_empty() {
+ pending_retain += b - a;
+ continue;
+ }
+ if pending_retain > 0 {
+ d.push(DeltaOp::Retain {
+ retain: pending_retain,
+ attributes: BTreeMap::new(),
+ });
+ pending_retain = 0;
+ }
+ match d.last_mut() {
+ Some(DeltaOp::Retain { retain, attributes }) if *attributes == changes => {
+ *retain += b - a;
+ }
+ _ => d.push(DeltaOp::Retain {
+ retain: b - a,
+ attributes: changes,
+ }),
+ }
+ }
+ d
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/model/content/test.rs b/crates/docx_engine/src/model/content/test.rs
new file mode 100644
index 0000000000..bd11e5ba1a
--- /dev/null
+++ b/crates/docx_engine/src/model/content/test.rs
@@ -0,0 +1,89 @@
+use super::*;
+
+fn bold() -> Attrs {
+ Attrs::from_pairs([("r:w:b", "<w:b/>")])
+}
+
+#[test]
+fn push_merges_equal_spans() {
+ let mut c = Content::new();
+ c.push("ab", Attrs::empty());
+ c.push("cd", Attrs::empty());
+ c.push("ef", bold());
+ assert_eq!(c.spans().len(), 2);
+ assert_eq!(c.text(), "abcdef");
+ assert_eq!(c.len(), 6);
+}
+
+#[test]
+fn insert_delete_and_split_use_utf16_offsets() {
+ let mut c = Content::new();
+ c.push("a\u{1F600}b", Attrs::empty());
+ assert_eq!(c.len(), 4);
+ c.insert(3, "X", bold());
+ assert_eq!(c.text(), "a\u{1F600}Xb");
+ assert_eq!(c.attrs_at(3), Some(&bold()));
+ c.delete(1, 3);
+ assert_eq!(c.text(), "aXb");
+ let tail = c.split_off(1);
+ assert_eq!(c.text(), "a");
+ assert_eq!(tail.text(), "Xb");
+}
+
+#[test]
+fn set_attr_splits_and_merges() {
+ let mut c = Content::new();
+ c.push("hello world", Attrs::empty());
+ c.set_attr(0, 5, "r:w:b", Some("<w:b/>"));
+ assert_eq!(c.spans().len(), 2);
+ c.set_attr(0, 5, "r:w:b", None);
+ assert_eq!(c.spans().len(), 1);
+}
+
+#[test]
+fn deltas_round_trip() {
+ let mut c = Content::new();
+ c.push("Hello ", Attrs::empty());
+ c.push("world", bold());
+ let d = c.to_delta();
+ assert_eq!(Content::from_delta(&d), c);
+ let json = serde_json::to_string(&d).unwrap();
+ let back: Vec<DeltaOp> = serde_json::from_str(&json).unwrap();
+ assert_eq!(back, d);
+
+ let mut edited = c.clone();
+ edited.apply_delta(&insert_delta(6, "big ", &bold()));
+ assert_eq!(edited.text(), "Hello big world");
+ edited.apply_delta(&delete_delta(0, 6));
+ assert_eq!(edited.text(), "big world");
+ // Attribute changes as retains.
+ let mut plain = edited.clone();
+ plain.set_attr(0, 9, "r:w:b", None);
+ let ad = attr_delta(&edited, &plain);
+ let mut applied = edited.clone();
+ applied.apply_delta(&ad);
+ assert_eq!(applied, plain);
+}
+
+#[test]
+fn typing_inherits_formatting_but_not_objects() {
+ let mut c = Content::new();
+ c.push("ab", bold());
+ c.push("\u{FFFC}", bold().with(key::OBJ, Some("<w:fldChar/>")));
+ assert_eq!(c.typing_attrs(3), bold());
+ assert_eq!(c.typing_attrs(0), bold());
+ assert_eq!(Content::new().typing_attrs(0), Attrs::empty());
+}
+
+#[test]
+fn wrappers_round_trip() {
+ let stack = vec![Wrapper {
+ open: "<w:hyperlink r:id=\"rId1\">".into(),
+ close: "</w:hyperlink>".into(),
+ }];
+ let encoded = encode_wrappers(&stack).unwrap();
+ let attrs = Attrs::from_pairs([(key::WRAP, encoded)]);
+ assert_eq!(attrs.wrappers(), stack);
+ assert_eq!(stack[0].qname(), "w:hyperlink");
+ assert_eq!(stack[0].local(), "hyperlink");
+}
diff --git a/crates/docx_engine/src/model/numbering.rs b/crates/docx_engine/src/model/numbering.rs
new file mode 100644
index 0000000000..3f1e3d4b20
--- /dev/null
+++ b/crates/docx_engine/src/model/numbering.rs
@@ -0,0 +1,375 @@
+//! List numbering (`word/numbering.xml`): definitions, counters and labels.
+
+mod format;
+
+use super::props::{Align, PPr, RPr, ThemeInfo};
+use super::styles::Styles;
+use crate::xml::{NodeId, Ns, XmlTree, parse_int, parse_on_off};
+pub use format::{NumFmt, format_number};
+use std::collections::HashMap;
+
+/// What follows a list label.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum Suffix {
+ /// A tab to the next stop.
+ #[default]
+ Tab,
+ /// A space.
+ Space,
+ /// Nothing.
+ Nothing,
+}
+
+/// One level of a list definition.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Level {
+ /// Start value.
+ pub start: i64,
+ /// Number format.
+ pub fmt: NumFmt,
+ /// Label template (`%1.`), `None` when absent.
+ pub text: Option<String>,
+ /// Label alignment.
+ pub jc: Align,
+ /// What follows the label.
+ pub suffix: Suffix,
+ /// Show every level as decimal (legal numbering).
+ pub is_legal: bool,
+ /// Restart after this level (0-based); `None` = after any higher level,
+ /// `Some(-1)` = never.
+ pub restart: Option<i64>,
+ /// Paragraph properties (indents, tabs).
+ pub ppr: PPr,
+ /// Label run properties.
+ pub rpr: RPr,
+ /// Paragraph style linked to the level.
+ pub style: Option<String>,
+}
+
+impl Default for Level {
+ fn default() -> Self {
+ Self {
+ start: 1,
+ fmt: NumFmt::Decimal,
+ text: None,
+ jc: Align::Left,
+ suffix: Suffix::Tab,
+ is_legal: false,
+ restart: None,
+ ppr: PPr::default(),
+ rpr: RPr::default(),
+ style: None,
+ }
+ }
+}
+
+/// An abstract list definition.
+#[derive(Clone, Debug, Default)]
+pub struct AbstractNum {
+ /// Levels 0-8.
+ pub levels: Vec<Option<Level>>,
+ /// A numbering style whose definition this one uses instead.
+ pub num_style_link: Option<String>,
+}
+
+/// A level override of a list instance.
+#[derive(Clone, Debug, Default)]
+pub struct LevelOverride {
+ /// Restart value.
+ pub start: Option<i64>,
+ /// Replacement level definition.
+ pub level: Option<Level>,
+}
+
+/// A list instance (`w:num`).
+#[derive(Clone, Debug, Default)]
+pub struct Num {
+ /// The definition it instantiates.
+ pub abstract_id: i64,
+ /// Per-level overrides.
+ pub overrides: HashMap<u8, LevelOverride>,
+}
+
+/// The numbering part.
+#[derive(Clone, Debug, Default)]
+pub struct Numbering {
+ abstracts: HashMap<i64, AbstractNum>,
+ nums: HashMap<i64, Num>,
+}
+
+fn read_level(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> Level {
+ let mut l = Level::default();
+ for c in t.children(n) {
+ if t.ns(c) != Ns::W {
+ continue;
+ }
+ match t.local(c) {
+ "start" => l.start = t.val(c).and_then(parse_int).unwrap_or(1),
+ "numFmt" => {
+ l.fmt = NumFmt::parse(t.val(c).unwrap_or("decimal"), t.w_attr(c, "format"));
+ }
+ "lvlText" => l.text = Some(t.val(c).unwrap_or("").to_owned()),
+ "lvlJc" => {
+ l.jc = match t.val(c) {
+ Some("center") => Align::Center,
+ Some("right" | "end") => Align::Right,
+ _ => Align::Left,
+ }
+ }
+ "suff" => {
+ l.suffix = match t.val(c) {
+ Some("space") => Suffix::Space,
+ Some("nothing") => Suffix::Nothing,
+ _ => Suffix::Tab,
+ }
+ }
+ "isLgl" => l.is_legal = parse_on_off(t.val(c)),
+ "lvlRestart" => {
+ l.restart = t.val(c).and_then(parse_int).map(|v| v - 1);
+ }
+ "pPr" => l.ppr = PPr::read(t, c, theme),
+ "rPr" => l.rpr = RPr::read(t, c, theme),
+ "pStyle" => l.style = t.val(c).map(str::to_owned),
+ _ => {}
+ }
+ }
+ l
+}
+
+impl Numbering {
+ /// Parses `numbering.xml`.
+ pub fn parse(t: &XmlTree, theme: &ThemeInfo) -> Self {
+ let root = t.root();
+ let mut n = Numbering::default();
+ for a in t.children_named(root, Ns::W, "abstractNum") {
+ let Some(id) = t.w_attr(a, "abstractNumId").and_then(parse_int) else {
+ continue;
+ };
+ let mut def = AbstractNum {
+ levels: vec![None; 9],
+ num_style_link: t.child_val(a, "numStyleLink").map(str::to_owned),
+ };
+ for lvl in t.children_named(a, Ns::W, "lvl") {
+ let i = t.w_attr(lvl, "ilvl").and_then(parse_int).unwrap_or(0);
+ if (0..9).contains(&i) {
+ def.levels[i as usize] = Some(read_level(t, lvl, theme));
+ }
+ }
+ n.abstracts.insert(id, def);
+ }
+ for num in t.children_named(root, Ns::W, "num") {
+ let Some(id) = t.w_attr(num, "numId").and_then(parse_int) else {
+ continue;
+ };
+ let mut inst = Num {
+ abstract_id: t
+ .child_val(num, "abstractNumId")
+ .and_then(parse_int)
+ .unwrap_or(-1),
+ overrides: HashMap::new(),
+ };
+ for o in t.children_named(num, Ns::W, "lvlOverride") {
+ let i = t.w_attr(o, "ilvl").and_then(parse_int).unwrap_or(0);
+ if !(0..9).contains(&i) {
+ continue;
+ }
+ let mut lo = LevelOverride::default();
+ if let Some(s) = t.child_val(o, "startOverride").and_then(parse_int) {
+ lo.start = Some(s);
+ }
+ if let Some(lvl) = t.w_child(o, "lvl") {
+ lo.level = Some(read_level(t, lvl, theme));
+ }
+ inst.overrides.insert(i as u8, lo);
+ }
+ n.nums.insert(id, inst);
+ }
+ n
+ }
+
+ /// Ids of every list instance.
+ pub fn num_ids(&self) -> impl Iterator<Item = i64> + '_ {
+ self.nums.keys().copied()
+ }
+
+ /// Ids of every abstract definition.
+ pub fn abstract_ids(&self) -> impl Iterator<Item = i64> + '_ {
+ self.abstracts.keys().copied()
+ }
+
+ /// The abstract definition a list instance names directly.
+ pub fn abstract_of(&self, num_id: i64) -> Option<i64> {
+ self.nums.get(&num_id).map(|n| n.abstract_id)
+ }
+
+ /// An abstract definition.
+ pub fn abstract_num(&self, id: i64) -> Option<&AbstractNum> {
+ self.abstracts.get(&id)
+ }
+
+ /// Whether the instance exists.
+ pub fn has_num(&self, num_id: i64) -> bool {
+ self.nums.contains_key(&num_id)
+ }
+
+ /// The abstract definition behind a list instance, following numbering
+ /// style links.
+ fn abstract_for(&self, num_id: i64, styles: &Styles) -> Option<(i64, &AbstractNum)> {
+ let num = self.nums.get(&num_id)?;
+ let mut id = num.abstract_id;
+ for _ in 0..4 {
+ let a = self.abstracts.get(&id)?;
+ let Some(link) = &a.num_style_link else {
+ return Some((id, a));
+ };
+ // The numbering style names a list instance in its paragraph properties.
+ let linked = styles
+ .get(link)
+ .and_then(|s| s.ppr.num.num_id)
+ .and_then(|n| self.nums.get(&n))
+ .map(|n| n.abstract_id);
+ match linked {
+ Some(next) if next != id => id = next,
+ _ => return Some((id, a)),
+ }
+ }
+ None
+ }
+
+ /// The effective level definition of a list instance.
+ pub fn level(&self, num_id: i64, ilvl: u8, styles: &Styles) -> Option<&Level> {
+ let num = self.nums.get(&num_id)?;
+ if let Some(l) = num.overrides.get(&ilvl).and_then(|o| o.level.as_ref()) {
+ return Some(l);
+ }
+ let (_, a) = self.abstract_for(num_id, styles)?;
+ a.levels.get(usize::from(ilvl)).and_then(Option::as_ref)
+ }
+
+ /// Paragraph properties a list level contributes.
+ pub fn level_ppr(&self, num_id: i64, ilvl: u8, styles: &Styles) -> Option<PPr> {
+ self.level(num_id, ilvl, styles).map(|l| l.ppr.clone())
+ }
+}
+
+/// A computed list label.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Label {
+ /// The label text.
+ pub text: String,
+ /// What follows it.
+ pub suffix: Suffix,
+ /// Alignment of the label at its position.
+ pub jc: Align,
+ /// Label run properties (overlaid on the paragraph mark's).
+ pub rpr: RPr,
+}
+
+/// Running list counters, advanced paragraph by paragraph in document order.
+#[derive(Clone, Debug, Default)]
+pub struct Counters {
+ /// Counter values per list (abstract id, or instance id when it overrides
+ /// a start value) and level; `None` = not used yet.
+ values: HashMap<ListKey, [Option<i64>; 9]>,
+ /// Instances whose start overrides have been applied, per level.
+ started: HashMap<i64, [bool; 9]>,
+}
+
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+enum ListKey {
+ Abstract(i64),
+ Instance(i64),
+}
+
+impl Counters {
+ /// Advances the counters for a numbered paragraph and returns its label.
+ pub fn next(
+ &mut self,
+ numbering: &Numbering,
+ styles: &Styles,
+ num_id: i64,
+ ilvl: u8,
+ ) -> Option<Label> {
+ let num = numbering.nums.get(&num_id)?;
+ let (abs_id, _) = numbering.abstract_for(num_id, styles)?;
+ let level = numbering.level(num_id, ilvl, styles)?;
+ let overrides_start = num
+ .overrides
+ .values()
+ .any(|o| o.start.is_some() || o.level.is_some());
+ let key = if overrides_start {
+ ListKey::Instance(num_id)
+ } else {
+ ListKey::Abstract(abs_id)
+ };
+ let started = self.started.entry(num_id).or_insert([false; 9]);
+ let override_start = num.overrides.get(&ilvl).and_then(|o| o.start);
+ let restart_with = if !started[usize::from(ilvl)] {
+ started[usize::from(ilvl)] = true;
+ override_start
+ } else {
+ None
+ };
+ let values = self.values.entry(key).or_insert([None; 9]);
+ let i = usize::from(ilvl);
+ values[i] = Some(match (restart_with, values[i]) {
+ (Some(s), _) => s,
+ (None, Some(v)) => v + 1,
+ (None, None) => level.start,
+ });
+ // Deeper levels restart after this one (unless told otherwise).
+ for (d, value) in values.iter_mut().enumerate().skip(i + 1) {
+ let deeper = numbering.level(num_id, d as u8, styles);
+ let restarts = match deeper.as_ref().and_then(|l| l.restart) {
+ None => true,
+ Some(r) if r < 0 => false,
+ Some(r) => (i as i64) <= r,
+ };
+ if restarts {
+ *value = None;
+ }
+ }
+ let snapshot = *values;
+ let template = level.text.as_deref().unwrap_or_default();
+ let mut text = String::new();
+ let mut chars = template.chars().peekable();
+ while let Some(c) = chars.next() {
+ if c == '%'
+ && let Some(&d) = chars.peek()
+ && let Some(n) = d.to_digit(10)
+ && (1..=9).contains(&n)
+ {
+ chars.next();
+ let li = (n - 1) as usize;
+ let lv = if li == i {
+ Some(level)
+ } else {
+ numbering.level(num_id, li as u8, styles)
+ };
+ let value = snapshot[li].unwrap_or_else(|| lv.map_or(1, |l| l.start));
+ let own = lv.map_or(NumFmt::Decimal, |l| l.fmt.clone());
+ // Legal numbering shows every level's number as decimal.
+ let fmt = if level.is_legal && !matches!(own, NumFmt::Bullet | NumFmt::None) {
+ NumFmt::Decimal
+ } else {
+ own
+ };
+ text.push_str(&format_number(value, &fmt));
+ } else {
+ text.push(c);
+ }
+ }
+ if level.fmt == NumFmt::Bullet && level.text.is_none() {
+ text.push('\u{2022}');
+ }
+ Some(Label {
+ text,
+ suffix: level.suffix,
+ jc: level.jc,
+ rpr: level.rpr.clone(),
+ })
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/model/numbering/format.rs b/crates/docx_engine/src/model/numbering/format.rs
new file mode 100644
index 0000000000..dd9bfc8311
--- /dev/null
+++ b/crates/docx_engine/src/model/numbering/format.rs
@@ -0,0 +1,262 @@
+//! Number formats for list labels, page numbers and notes.
+
+/// A number format (`w:numFmt`).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum NumFmt {
+ /// 1, 2, 3.
+ Decimal,
+ /// 01, 02 ... 10.
+ DecimalZero,
+ /// I, II, III.
+ UpperRoman,
+ /// i, ii, iii.
+ LowerRoman,
+ /// A, B ... Z, AA, BB.
+ UpperLetter,
+ /// a, b ... z, aa, bb.
+ LowerLetter,
+ /// 1st, 2nd, 3rd.
+ Ordinal,
+ /// One, Two, Three.
+ CardinalText,
+ /// First, Second, Third.
+ OrdinalText,
+ /// *, †, ‡, §, then doubled.
+ Chicago,
+ /// Hexadecimal.
+ Hex,
+ /// ①, ②...
+ DecimalEnclosedCircle,
+ /// (1), (2)...
+ DecimalEnclosedParen,
+ /// Full-width digits.
+ DecimalFullWidth,
+ /// A bullet: the label text is shown as is.
+ Bullet,
+ /// No number.
+ None,
+ /// A custom pattern (`w:format`, e.g. `001`).
+ Custom(String),
+}
+
+impl NumFmt {
+ /// Parses a `w:numFmt` value (and its `w:format` attribute for `custom`).
+ pub fn parse(v: &str, format: Option<&str>) -> Self {
+ match v {
+ "decimal" => NumFmt::Decimal,
+ "decimalZero" => NumFmt::DecimalZero,
+ "upperRoman" => NumFmt::UpperRoman,
+ "lowerRoman" => NumFmt::LowerRoman,
+ "upperLetter" => NumFmt::UpperLetter,
+ "lowerLetter" => NumFmt::LowerLetter,
+ "ordinal" => NumFmt::Ordinal,
+ "cardinalText" => NumFmt::CardinalText,
+ "ordinalText" => NumFmt::OrdinalText,
+ "chicago" => NumFmt::Chicago,
+ "hex" => NumFmt::Hex,
+ "decimalEnclosedCircle" | "decimalEnclosedCircleChinese" => {
+ NumFmt::DecimalEnclosedCircle
+ }
+ "decimalEnclosedParen" => NumFmt::DecimalEnclosedParen,
+ "decimalFullWidth" | "decimalFullWidth2" => NumFmt::DecimalFullWidth,
+ "bullet" => NumFmt::Bullet,
+ "none" => NumFmt::None,
+ "custom" => match format {
+ Some(f) => NumFmt::Custom(f.to_owned()),
+ None => NumFmt::Decimal,
+ },
+ _ => NumFmt::Decimal,
+ }
+ }
+}
+
+fn roman(mut n: i64) -> String {
+ if n <= 0 || n >= 4000 {
+ return n.to_string();
+ }
+ const TABLE: &[(i64, &str)] = &[
+ (1000, "M"),
+ (900, "CM"),
+ (500, "D"),
+ (400, "CD"),
+ (100, "C"),
+ (90, "XC"),
+ (50, "L"),
+ (40, "XL"),
+ (10, "X"),
+ (9, "IX"),
+ (5, "V"),
+ (4, "IV"),
+ (1, "I"),
+ ];
+ let mut out = String::new();
+ for &(v, s) in TABLE {
+ while n >= v {
+ out.push_str(s);
+ n -= v;
+ }
+ }
+ out
+}
+
+fn letters(n: i64) -> String {
+ if n <= 0 {
+ return String::new();
+ }
+ // Word repeats the letter: 27 = AA, 28 = BB.
+ let idx = ((n - 1) % 26) as u8;
+ let count = ((n - 1) / 26 + 1) as usize;
+ std::iter::repeat_n((b'A' + idx) as char, count).collect()
+}
+
+const ONES: [&str; 20] = [
+ "Zero",
+ "One",
+ "Two",
+ "Three",
+ "Four",
+ "Five",
+ "Six",
+ "Seven",
+ "Eight",
+ "Nine",
+ "Ten",
+ "Eleven",
+ "Twelve",
+ "Thirteen",
+ "Fourteen",
+ "Fifteen",
+ "Sixteen",
+ "Seventeen",
+ "Eighteen",
+ "Nineteen",
+];
+const TENS: [&str; 10] = [
+ "", "", "Twenty", "Thirty", "Forty", "Fifty", "Sixty", "Seventy", "Eighty", "Ninety",
+];
+
+fn cardinal(n: i64) -> String {
+ if !(0..1_000_000).contains(&n) {
+ return n.to_string();
+ }
+ if n < 20 {
+ return ONES[n as usize].to_owned();
+ }
+ if n < 100 {
+ let t = TENS[(n / 10) as usize];
+ return if n % 10 == 0 {
+ t.to_owned()
+ } else {
+ format!("{t}-{}", ONES[(n % 10) as usize].to_lowercase())
+ };
+ }
+ if n < 1000 {
+ let rest = n % 100;
+ let head = format!("{} Hundred", ONES[(n / 100) as usize]);
+ return if rest == 0 {
+ head
+ } else {
+ format!("{head} {}", cardinal(rest).to_lowercase())
+ };
+ }
+ let rest = n % 1000;
+ let head = format!("{} Thousand", cardinal(n / 1000));
+ if rest == 0 {
+ head
+ } else {
+ format!("{head} {}", cardinal(rest).to_lowercase())
+ }
+}
+
+fn ordinal_text(n: i64) -> String {
+ let c = cardinal(n);
+ let irregular = [
+ ("One", "First"),
+ ("Two", "Second"),
+ ("Three", "Third"),
+ ("Five", "Fifth"),
+ ("Eight", "Eighth"),
+ ("Nine", "Ninth"),
+ ("Twelve", "Twelfth"),
+ ("one", "first"),
+ ("two", "second"),
+ ("three", "third"),
+ ("five", "fifth"),
+ ("eight", "eighth"),
+ ("nine", "ninth"),
+ ];
+ for (from, to) in irregular {
+ if let Some(stem) = c.strip_suffix(from) {
+ return format!("{stem}{to}");
+ }
+ }
+ if let Some(stem) = c.strip_suffix('y') {
+ return format!("{stem}ieth");
+ }
+ format!("{c}th")
+}
+
+fn ordinal_suffix(n: i64) -> &'static str {
+ match (n % 10, n % 100) {
+ (_, 11..=13) => "th",
+ (1, _) => "st",
+ (2, _) => "nd",
+ (3, _) => "rd",
+ _ => "th",
+ }
+}
+
+/// Formats `n` in format `fmt`.
+pub fn format_number(n: i64, fmt: &NumFmt) -> String {
+ match fmt {
+ NumFmt::Decimal => n.to_string(),
+ NumFmt::DecimalZero => {
+ if (0..10).contains(&n) {
+ format!("0{n}")
+ } else {
+ n.to_string()
+ }
+ }
+ NumFmt::UpperRoman => roman(n),
+ NumFmt::LowerRoman => roman(n).to_lowercase(),
+ NumFmt::UpperLetter => letters(n),
+ NumFmt::LowerLetter => letters(n).to_lowercase(),
+ NumFmt::Ordinal => format!("{n}{}", ordinal_suffix(n)),
+ NumFmt::CardinalText => cardinal(n),
+ NumFmt::OrdinalText => ordinal_text(n),
+ NumFmt::Chicago => {
+ if n <= 0 {
+ return n.to_string();
+ }
+ let symbols = ['*', '\u{2020}', '\u{2021}', '\u{00A7}'];
+ let s = symbols[((n - 1) % 4) as usize];
+ std::iter::repeat_n(s, ((n - 1) / 4 + 1) as usize).collect()
+ }
+ NumFmt::Hex => format!("{n:X}"),
+ NumFmt::DecimalEnclosedCircle => match n {
+ 1..=20 => {
+ char::from_u32(0x2460 + (n as u32 - 1)).map_or_else(|| n.to_string(), String::from)
+ }
+ _ => n.to_string(),
+ },
+ NumFmt::DecimalEnclosedParen => format!("({n})"),
+ NumFmt::DecimalFullWidth => n
+ .to_string()
+ .chars()
+ .map(|c| match c.to_digit(10) {
+ Some(d) => char::from_u32(0xFF10 + d).unwrap_or(c),
+ None => c,
+ })
+ .collect(),
+ NumFmt::Bullet | NumFmt::None => String::new(),
+ NumFmt::Custom(pattern) => {
+ // Zero-padded patterns (`001`) pad to their width; others decimal.
+ let digits = pattern.chars().filter(|c| c.is_ascii_digit()).count();
+ if digits > 1 && pattern.chars().all(|c| c.is_ascii_digit()) {
+ format!("{n:0digits$}")
+ } else {
+ n.to_string()
+ }
+ }
+ }
+}
diff --git a/crates/docx_engine/src/model/numbering/test.rs b/crates/docx_engine/src/model/numbering/test.rs
new file mode 100644
index 0000000000..c6406b31c8
--- /dev/null
+++ b/crates/docx_engine/src/model/numbering/test.rs
@@ -0,0 +1,46 @@
+use super::*;
+
+#[test]
+fn formats_numbers() {
+ assert_eq!(format_number(4, &NumFmt::UpperRoman), "IV");
+ assert_eq!(format_number(1994, &NumFmt::LowerRoman), "mcmxciv");
+ assert_eq!(format_number(1, &NumFmt::LowerLetter), "a");
+ assert_eq!(format_number(27, &NumFmt::UpperLetter), "AA");
+ assert_eq!(format_number(28, &NumFmt::UpperLetter), "BB");
+ assert_eq!(format_number(2, &NumFmt::Ordinal), "2nd");
+ assert_eq!(format_number(13, &NumFmt::Ordinal), "13th");
+ assert_eq!(format_number(21, &NumFmt::CardinalText), "Twenty-one");
+ assert_eq!(format_number(3, &NumFmt::OrdinalText), "Third");
+ assert_eq!(format_number(5, &NumFmt::DecimalZero), "05");
+ assert_eq!(format_number(4, &NumFmt::Chicago), "\u{00A7}");
+ assert_eq!(format_number(5, &NumFmt::Chicago), "**");
+ assert_eq!(format_number(6, &NumFmt::Chicago), "\u{2020}\u{2020}");
+}
+
+#[test]
+fn counts_levels_and_restarts() {
+ let xml = r#"<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+ <w:abstractNum w:abstractNumId="0">
+ <w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/></w:lvl>
+ <w:lvl w:ilvl="1"><w:start w:val="1"/><w:numFmt w:val="lowerLetter"/><w:lvlText w:val="(%2)"/></w:lvl>
+ <w:lvl w:ilvl="2"><w:start w:val="1"/><w:numFmt w:val="lowerRoman"/><w:lvlText w:val="%1.%2.%3"/><w:isLgl/></w:lvl>
+ </w:abstractNum>
+ <w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>
+ <w:num w:numId="2"><w:abstractNumId w:val="0"/><w:lvlOverride w:ilvl="0"><w:startOverride w:val="5"/></w:lvlOverride></w:num>
+ </w:numbering>"#;
+ let t = XmlTree::parse(xml.as_bytes(), "n").unwrap();
+ let n = Numbering::parse(&t, &ThemeInfo::default());
+ let styles = Styles::default();
+ let mut c = Counters::default();
+ let mut label = |id: i64, l: u8| c.next(&n, &styles, id, l).unwrap().text;
+ assert_eq!(label(1, 0), "1.");
+ assert_eq!(label(1, 1), "(a)");
+ assert_eq!(label(1, 1), "(b)");
+ assert_eq!(label(1, 2), "1.2.1");
+ assert_eq!(label(1, 0), "2.");
+ assert_eq!(label(1, 1), "(a)");
+ // A restarted instance counts on its own.
+ assert_eq!(label(2, 0), "5.");
+ assert_eq!(label(2, 0), "6.");
+ assert_eq!(label(1, 0), "3.");
+}
diff --git a/crates/docx_engine/src/model/parse.rs b/crates/docx_engine/src/model/parse.rs
new file mode 100644
index 0000000000..04b2f3d630
--- /dev/null
+++ b/crates/docx_engine/src/model/parse.rs
@@ -0,0 +1,410 @@
+//! Reads story XML (the body, headers, notes...) into blocks.
+
+use super::block::{Block, BlockId, BlockKind, IdGen, Story, initial_keys};
+use super::content::{Attrs, Content, OBJECT_CHAR, Wrapper, encode_wrappers, key};
+use crate::xml::{NodeId, Ns, XmlTree};
+
+/// Elements that wrap runs inside a paragraph.
+const RUN_WRAPPERS: &[&str] = &[
+ "hyperlink",
+ "smartTag",
+ "customXml",
+ "fldSimple",
+ "ins",
+ "del",
+ "moveFrom",
+ "moveTo",
+ "dir",
+ "bdo",
+ "sdt",
+];
+
+/// Paragraph children dropped on reading: proofing marks Word regenerates.
+const DROPPED: &[&str] = &["proofErr"];
+
+/// Run run attributes that only record editing sessions.
+const DROPPED_RUN_ATTRS: &[&str] = &["rsidR", "rsidRPr", "rsidDel"];
+
+/// Builds blocks from parsed story XML.
+pub struct StoryReader<'a> {
+ tree: &'a XmlTree,
+ ids: &'a mut IdGen,
+ story: Story,
+}
+
+/// A story read from XML.
+pub struct ReadStory {
+ /// The blocks.
+ pub story: Story,
+ /// The body's last `w:sectPr` (the final section's properties), verbatim.
+ pub final_sect_pr: Option<String>,
+}
+
+impl<'a> StoryReader<'a> {
+ /// A reader over `tree`.
+ pub fn new(tree: &'a XmlTree, ids: &'a mut IdGen) -> Self {
+ Self {
+ tree,
+ ids,
+ story: Story::new(),
+ }
+ }
+
+ /// Reads the block-level children of `container` (`w:body`, `w:hdr`,
+ /// `w:footnote`, `w:txbxContent`...).
+ pub fn read(mut self, container: NodeId) -> ReadStory {
+ let t = self.tree;
+ let mut kids: Vec<NodeId> = t.children(container).collect();
+ // The body's own sectPr belongs last, but producers sometimes put
+ // content after it; the last one wherever it is describes the final section.
+ let final_sect_pr = match kids.iter().rposition(|&k| t.is_w(k, "sectPr")) {
+ Some(i) => {
+ let n = kids.remove(i);
+ Some(t.snippet(n))
+ }
+ None => None,
+ };
+ self.blocks(&kids, None);
+ ReadStory {
+ story: self.story,
+ final_sect_pr,
+ }
+ }
+
+ /// Adds blocks for `nodes` under `parent`, with evenly spread keys.
+ fn blocks(&mut self, nodes: &[NodeId], parent: Option<&BlockId>) -> usize {
+ let mut made: Vec<Block> = Vec::with_capacity(nodes.len());
+ for &n in nodes {
+ if let Some(b) = self.block(n, parent) {
+ made.push(b);
+ }
+ }
+ let count = made.len();
+ let keys = initial_keys(count);
+ for (mut b, k) in made.into_iter().zip(keys) {
+ b.order = k;
+ self.story.insert(b);
+ }
+ count
+ }
+
+ fn new_block(&mut self, kind: BlockKind, parent: Option<&BlockId>, node: NodeId) -> Block {
+ let mut b = Block::new(self.ids.next_id(), kind, parent.cloned(), String::new());
+ b.attrs = self.tree.raw_attrs(node).to_owned();
+ b
+ }
+
+ fn block(&mut self, n: NodeId, parent: Option<&BlockId>) -> Option<Block> {
+ let t = self.tree;
+ if t.ns(n) == Ns::W {
+ match t.local(n) {
+ "p" => return Some(self.paragraph(n, parent)),
+ "tbl" => return Some(self.table(n, parent)),
+ "sdt" => {
+ let content = t.w_child(n, "sdtContent");
+ let mut open = t.start_tag(n).to_owned();
+ for c in t.children(n) {
+ if t.is_w(c, "sdtPr") || t.is_w(c, "sdtEndPr") {
+ open.push_str(&t.snippet(c));
+ }
+ }
+ let (content_open, content_close) = match content {
+ Some(c) => (t.start_tag(c).to_owned(), format!("</{}>", t.qname(c))),
+ None => (String::new(), String::new()),
+ };
+ open.push_str(&content_open);
+ let close = format!("{content_close}</{}>", t.qname(n));
+ let mut b = self.new_block(BlockKind::Container, parent, n);
+ b.attrs.clear();
+ b.props = serde_json::to_string(&(open, close)).unwrap_or_default();
+ let id = b.id.clone();
+ let kids: Vec<NodeId> =
+ content.map(|c| t.children(c).collect()).unwrap_or_default();
+ self.blocks(&kids, Some(&id));
+ return Some(b);
+ }
+ "customXml" => {
+ let mut open = t.start_tag(n).to_owned();
+ if let Some(pr) = t.w_child(n, "customXmlPr") {
+ open.push_str(&t.snippet(pr));
+ }
+ let close = format!("</{}>", t.qname(n));
+ let mut b = self.new_block(BlockKind::Container, parent, n);
+ b.attrs.clear();
+ b.props = serde_json::to_string(&(open, close)).unwrap_or_default();
+ let id = b.id.clone();
+ let kids: Vec<NodeId> = t
+ .children(n)
+ .filter(|&c| !t.is_w(c, "customXmlPr"))
+ .collect();
+ self.blocks(&kids, Some(&id));
+ return Some(b);
+ }
+ _ => {}
+ }
+ }
+ let mut b = self.new_block(BlockKind::Opaque, parent, n);
+ b.attrs.clear();
+ b.props = t.snippet(n);
+ Some(b)
+ }
+
+ fn paragraph(&mut self, p: NodeId, parent: Option<&BlockId>) -> Block {
+ let t = self.tree;
+ let mut b = self.new_block(BlockKind::Paragraph, parent, p);
+ if let Some(ppr) = t.w_child(p, "pPr") {
+ b.props = t.snippet(ppr);
+ }
+ let mut content = Content::new();
+ let mut stack: Vec<Wrapper> = Vec::new();
+ self.flatten(p, &mut stack, &mut content);
+ b.content = content;
+ b
+ }
+
+ fn wrap_attrs(stack: &[Wrapper]) -> Attrs {
+ match encode_wrappers(stack) {
+ Some(w) => Attrs::from_pairs([(key::WRAP, w)]),
+ None => Attrs::empty(),
+ }
+ }
+
+ /// Flattens the inline content of `node` (a paragraph or a wrapper).
+ fn flatten(&mut self, node: NodeId, stack: &mut Vec<Wrapper>, out: &mut Content) {
+ let t = self.tree;
+ for &c in t.child_nodes(node) {
+ if !t.is_element(c) || t.is_w(c, "pPr") || is_wrapper_prop(t, c) {
+ continue;
+ }
+ self.flatten_one(c, stack, out);
+ }
+ }
+
+ fn flatten_one(&mut self, c: NodeId, stack: &mut Vec<Wrapper>, out: &mut Content) {
+ let t = self.tree;
+ let local = t.local(c);
+ if t.ns(c) == Ns::W {
+ if DROPPED.contains(&local) {
+ return;
+ }
+ if local == "r" {
+ self.run(c, stack, out);
+ return;
+ }
+ if RUN_WRAPPERS.contains(&local) && t.children(c).any(|_| true) {
+ let (open, inner) = self.wrapper_open(c);
+ stack.push(Wrapper {
+ open,
+ close: self.wrapper_close(c, inner),
+ });
+ self.flatten(inner.unwrap_or(c), stack, out);
+ stack.pop();
+ return;
+ }
+ }
+ // Bookmarks, comment ranges, math, empty wrappers and anything
+ // unknown: a marker that keeps the element.
+ let attrs = Self::wrap_attrs(stack).with(key::MARK, Some(&t.snippet(c)));
+ out.push(&OBJECT_CHAR.to_string(), attrs);
+ }
+
+ /// Opening markup of a wrapper and, for content controls, the element
+ /// that holds its content.
+ fn wrapper_open(&self, w: NodeId) -> (String, Option<NodeId>) {
+ let t = self.tree;
+ let mut open = t.start_tag(w).to_owned();
+ let mut inner = None;
+ for c in t.children(w) {
+ if is_wrapper_prop(t, c) {
+ open.push_str(&t.snippet(c));
+ } else if t.is_w(c, "sdtContent") {
+ open.push_str(t.start_tag(c));
+ inner = Some(c);
+ }
+ }
+ (open, inner)
+ }
+
+ fn wrapper_close(&self, w: NodeId, inner: Option<NodeId>) -> String {
+ let t = self.tree;
+ match inner {
+ Some(i) => format!("</{}></{}>", t.qname(i), t.qname(w)),
+ None => format!("</{}>", t.qname(w)),
+ }
+ }
+
+ fn run(&mut self, r: NodeId, stack: &[Wrapper], out: &mut Content) {
+ let t = self.tree;
+ let mut pairs: Vec<(String, String)> = Vec::new();
+ if let Some(wrap) = encode_wrappers(stack) {
+ pairs.push((key::WRAP.to_owned(), wrap));
+ }
+ for a in t.attrs(r) {
+ if a.ns == Ns::W && DROPPED_RUN_ATTRS.contains(&&*a.local) {
+ continue;
+ }
+ pairs.push((format!("{}{}", key::RUN_ATTR, a.qname), a.value.to_string()));
+ }
+ if let Some(rpr) = t.w_child(r, "rPr") {
+ for c in t.children(rpr) {
+ pairs.push((format!("{}{}", key::RUN_PROP, t.qname(c)), t.snippet(c)));
+ }
+ }
+ let attrs = Attrs::from_pairs(pairs);
+ let mut instr_attrs: Option<Attrs> = None;
+ for c in t.children(r) {
+ let local = t.local(c);
+ if t.ns(c) == Ns::W {
+ match local {
+ "rPr" | "lastRenderedPageBreak" => continue,
+ "t" | "delText" => {
+ let text = t.text(c).replace(['\r', '\n'], " ");
+ out.push(&text, attrs.clone());
+ continue;
+ }
+ "instrText" | "delInstrText" => {
+ let ia =
+ instr_attrs.get_or_insert_with(|| attrs.with(key::INSTR, Some("1")));
+ let text = t.text(c).replace(['\r', '\n'], " ");
+ out.push(&text, ia.clone());
+ continue;
+ }
+ "tab" => {
+ out.push("\t", attrs.clone());
+ continue;
+ }
+ "br" if t
+ .attrs(c)
+ .iter()
+ .all(|a| &*a.local == "type" && &*a.value == "textWrapping") =>
+ {
+ out.push("\n", attrs.clone());
+ continue;
+ }
+ "cr" => {
+ out.push("\n", attrs.clone());
+ continue;
+ }
+ "noBreakHyphen" => {
+ out.push("\u{2011}", attrs.clone());
+ continue;
+ }
+ "softHyphen" => {
+ out.push("\u{00AD}", attrs.clone());
+ continue;
+ }
+ _ => {}
+ }
+ }
+ let obj = attrs.with(key::OBJ, Some(&t.snippet(c)));
+ out.push(&OBJECT_CHAR.to_string(), obj);
+ }
+ }
+
+ fn table(&mut self, tbl: NodeId, parent: Option<&BlockId>) -> Block {
+ let t = self.tree;
+ let mut b = self.new_block(BlockKind::Table, parent, tbl);
+ let mut props = String::new();
+ for c in t.children(tbl) {
+ if t.is_w(c, "tblPr") || t.is_w(c, "tblGrid") {
+ props.push_str(&t.snippet(c));
+ }
+ }
+ b.props = props;
+ let id = b.id.clone();
+ let mut rows: Vec<NodeId> = Vec::new();
+ collect_unwrapped(t, tbl, "tr", &mut rows);
+ let mut made = Vec::with_capacity(rows.len());
+ for r in rows {
+ made.push(self.row(r, &id));
+ }
+ let keys = initial_keys(made.len());
+ for (mut row, k) in made.into_iter().zip(keys) {
+ row.order = k;
+ self.story.insert(row);
+ }
+ b
+ }
+
+ fn row(&mut self, tr: NodeId, table: &BlockId) -> Block {
+ let t = self.tree;
+ let mut b = self.new_block(BlockKind::Row, Some(table), tr);
+ let mut props = String::new();
+ for c in t.children(tr) {
+ if t.is_w(c, "tblPrEx") || t.is_w(c, "trPr") {
+ props.push_str(&t.snippet(c));
+ }
+ }
+ b.props = props;
+ let id = b.id.clone();
+ let mut cells: Vec<NodeId> = Vec::new();
+ collect_unwrapped(t, tr, "tc", &mut cells);
+ let mut made = Vec::with_capacity(cells.len());
+ for c in cells {
+ made.push(self.cell(c, &id));
+ }
+ let keys = initial_keys(made.len());
+ for (mut cell, k) in made.into_iter().zip(keys) {
+ cell.order = k;
+ self.story.insert(cell);
+ }
+ b
+ }
+
+ fn cell(&mut self, tc: NodeId, row: &BlockId) -> Block {
+ let t = self.tree;
+ let mut b = self.new_block(BlockKind::Cell, Some(row), tc);
+ if let Some(pr) = t.w_child(tc, "tcPr") {
+ b.props = t.snippet(pr);
+ }
+ let id = b.id.clone();
+ let kids: Vec<NodeId> = t.children(tc).filter(|&c| !t.is_w(c, "tcPr")).collect();
+ let made = self.blocks(&kids, Some(&id));
+ let has_paragraph = self.story.children(Some(&id)).iter().any(|k| {
+ self.story
+ .get(k)
+ .is_some_and(|x| x.kind == BlockKind::Paragraph)
+ });
+ if made == 0 || !has_paragraph {
+ // A cell must end with a paragraph.
+ let after = self.story.children(Some(&id)).last().cloned();
+ let order = self.story.key_after(Some(&id), after.as_ref());
+ let p = Block::new(
+ self.ids.next_id(),
+ BlockKind::Paragraph,
+ Some(id.clone()),
+ order,
+ );
+ self.story.insert(p);
+ }
+ b
+ }
+}
+
+/// Property children of a run wrapper, kept in its opening markup.
+fn is_wrapper_prop(t: &XmlTree, c: NodeId) -> bool {
+ t.ns(c) == Ns::W
+ && matches!(
+ t.local(c),
+ "sdtPr" | "sdtEndPr" | "smartTagPr" | "customXmlPr" | "fldData"
+ )
+}
+
+/// Children named `w:{local}` of `node`, looking through content controls and
+/// custom XML that wrap them (whose own markup is not kept).
+fn collect_unwrapped(t: &XmlTree, node: NodeId, local: &str, out: &mut Vec<NodeId>) {
+ for c in t.children(node) {
+ if t.is_w(c, local) {
+ out.push(c);
+ } else if t.is_w(c, "sdt") {
+ if let Some(content) = t.w_child(c, "sdtContent") {
+ collect_unwrapped(t, content, local, out);
+ }
+ } else if t.is_w(c, "customXml") {
+ collect_unwrapped(t, c, local, out);
+ }
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/model/parse/test.rs b/crates/docx_engine/src/model/parse/test.rs
new file mode 100644
index 0000000000..7e95b0641f
--- /dev/null
+++ b/crates/docx_engine/src/model/parse/test.rs
@@ -0,0 +1,89 @@
+use super::*;
+use crate::model::write::Writer;
+
+const NS: &str = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships""#;
+
+fn read(body: &str) -> (Story, Option<String>) {
+ let xml = format!("<w:document {NS}><w:body>{body}</w:body></w:document>");
+ let t = XmlTree::parse(xml.as_bytes(), "t").unwrap();
+ let body = t.w_child(t.root(), "body").unwrap();
+ let mut ids = IdGen::sequential();
+ let r = StoryReader::new(&t, &mut ids).read(body);
+ (r.story, r.final_sect_pr)
+}
+
+fn first_paragraph(s: &Story) -> &Block {
+ s.get(&s.paragraphs()[0]).unwrap()
+}
+
+#[test]
+fn flattens_runs_wrappers_and_objects() {
+ let (s, sect) = read(concat!(
+ r#"<w:p><w:pPr><w:jc w:val="center"/></w:pPr>"#,
+ r#"<w:r><w:rPr><w:b/><w:sz w:val="24"/></w:rPr><w:t>Bold</w:t></w:r>"#,
+ r#"<w:bookmarkStart w:id="0" w:name="x"/>"#,
+ r#"<w:hyperlink r:id="rId5"><w:r><w:t xml:space="preserve"> link</w:t></w:r></w:hyperlink>"#,
+ r#"<w:r><w:tab/><w:t>a</w:t><w:br/><w:fldChar w:fldCharType="begin"/><w:instrText> PAGE </w:instrText></w:r>"#,
+ r#"<w:proofErr w:type="spellStart"/><w:del w:id="1" w:author="A"><w:r><w:delText>gone</w:delText></w:r></w:del>"#,
+ r#"</w:p><w:sectPr><w:pgSz w:w="12240" w:h="15840"/></w:sectPr>"#
+ ));
+ assert!(sect.unwrap().contains("pgSz"));
+ let p = first_paragraph(&s);
+ assert_eq!(p.props, r#"<w:pPr><w:jc w:val="center"/></w:pPr>"#);
+ assert_eq!(p.content.text(), "Bold\u{FFFC} link\ta\n\u{FFFC} PAGE gone");
+ let spans = p.content.spans();
+ assert_eq!(spans[0].attrs.get("r:w:b"), Some("<w:b/>"));
+ assert_eq!(spans[0].attrs.get("r:w:sz"), Some(r#"<w:sz w:val="24"/>"#));
+ assert!(spans[1].attrs.marker().unwrap().contains("bookmarkStart"));
+ assert_eq!(spans[2].attrs.wrappers()[0].local(), "hyperlink");
+ assert!(p.content.spans().iter().any(|s| s.attrs.is_instr()));
+ assert!(
+ p.content
+ .spans()
+ .iter()
+ .any(|s| s.attrs.wrappers().iter().any(|w| w.local() == "del"))
+ );
+}
+
+#[test]
+fn writes_back_equivalent_xml() {
+ let body = concat!(
+ r#"<w:p w14:paraId="1" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"><w:r><w:rPr><w:sz w:val="24"/><w:b/></w:rPr><w:t>Bold</w:t></w:r>"#,
+ r#"<w:hyperlink r:id="rId5"><w:r><w:t xml:space="preserve"> link </w:t></w:r></w:hyperlink>"#,
+ r#"<w:del w:id="1" w:author="A"><w:r><w:delText>gone</w:delText></w:r></w:del>"#,
+ r#"<w:r><w:fldChar w:fldCharType="begin"/></w:r><w:r><w:instrText>PAGE</w:instrText></w:r></w:p>"#,
+ r#"<w:tbl><w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr><w:tblGrid><w:gridCol w:w="100"/></w:tblGrid>"#,
+ r#"<w:tr><w:tc><w:tcPr><w:tcW w:w="100" w:type="dxa"/></w:tcPr><w:p><w:r><w:t>cell</w:t></w:r></w:p></w:tc></w:tr></w:tbl>"#,
+ r#"<w:sdt><w:sdtPr><w:id w:val="5"/></w:sdtPr><w:sdtContent><w:p><w:r><w:t>in control</w:t></w:r></w:p></w:sdtContent></w:sdt>"#
+ );
+ let (s, _) = read(body);
+ let out = Writer { w: "w" }.story(&s);
+ // Run properties come out in schema order.
+ assert!(
+ out.contains(r#"<w:rPr><w:b/><w:sz w:val="24"/></w:rPr>"#),
+ "{out}"
+ );
+ assert!(out.contains(r#"<w:hyperlink r:id="rId5"><w:r><w:t xml:space="preserve"> link </w:t></w:r></w:hyperlink>"#), "{out}");
+ assert!(out.contains("<w:delText>gone</w:delText>"), "{out}");
+ assert!(out.contains("<w:instrText>PAGE</w:instrText>"), "{out}");
+ assert!(
+ out.contains("<w:sdtContent><w:p><w:r><w:t>in control</w:t></w:r></w:p></w:sdtContent>"),
+ "{out}"
+ );
+ // Reading the output again gives the same model.
+ let (again, _) = read(&out);
+ let texts = |s: &Story| -> Vec<String> {
+ s.paragraphs()
+ .iter()
+ .map(|p| s.get(p).unwrap().content.text())
+ .collect()
+ };
+ assert_eq!(texts(&s), texts(&again));
+ assert_eq!(Writer { w: "w" }.story(&again), out);
+}
+
+#[test]
+fn empty_cells_get_a_paragraph() {
+ let (s, _) = read(r#"<w:tbl><w:tr><w:tc><w:tcPr/></w:tc></w:tr></w:tbl>"#);
+ assert_eq!(s.paragraphs().len(), 1);
+}
diff --git a/crates/docx_engine/src/model/props.rs b/crates/docx_engine/src/model/props.rs
new file mode 100644
index 0000000000..e1117d0666
--- /dev/null
+++ b/crates/docx_engine/src/model/props.rs
@@ -0,0 +1,20 @@
+//! Formatting properties: run, paragraph, table, row and cell properties as
+//! each level of the style hierarchy states them, and resolved.
+
+mod border;
+mod color;
+mod para;
+mod run;
+mod table;
+
+pub use border::{Border, LineStyle, read_border};
+pub use color::{ColorRef, ThemeInfo, highlight_color, read_color, read_shading};
+pub use para::{
+ Align, FramePr, LineSpacing, NumPr, PPr, ParaBorders, ParaBordersPr, ParaProps, TabAlign,
+ TabLeader, TabStop,
+};
+pub use run::{DEFAULT_FONT, DEFAULT_SIZE, RPr, RunProps, Underline, UnderlineStyle, VertAlign};
+pub use table::{
+ BordersPr, HeightRule, MarginsPr, TableLook, TablePosition, TblPr, TcPr, TrPr, VMerge, Width,
+ read_width,
+};
diff --git a/crates/docx_engine/src/model/props/border.rs b/crates/docx_engine/src/model/props/border.rs
new file mode 100644
index 0000000000..3b19730040
--- /dev/null
+++ b/crates/docx_engine/src/model/props/border.rs
@@ -0,0 +1,90 @@
+//! Borders of paragraphs, tables, cells, runs and pages.
+
+use super::color::{ColorRef, ThemeInfo, read_color};
+use crate::units::eighth_points;
+use crate::xml::{NodeId, XmlTree, parse_int};
+
+/// A border line style, reduced to what drawing needs.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LineStyle {
+ /// One line.
+ Single,
+ /// A thick line.
+ Thick,
+ /// Two lines.
+ Double,
+ /// Three lines.
+ Triple,
+ /// Dots.
+ Dotted,
+ /// Dashes.
+ Dashed,
+ /// Dash-dot pattern.
+ DotDash,
+ /// Two lines of different weights.
+ ThinThick,
+ /// A wavy line.
+ Wave,
+ /// Raised or sunken 3-D effect, drawn as a single line.
+ ThreeD,
+}
+
+/// One border edge.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct Border {
+ /// Style.
+ pub style: LineStyle,
+ /// Line width in points.
+ pub width: f32,
+ /// Distance from the text in points.
+ pub space: f32,
+ /// Color (`Auto` = black).
+ pub color: ColorRef,
+}
+
+impl Border {
+ /// Total width the border occupies, counting all its lines.
+ pub fn total_width(&self) -> f32 {
+ match self.style {
+ LineStyle::Double => self.width * 3.0,
+ LineStyle::Triple => self.width * 5.0,
+ LineStyle::ThinThick => self.width * 2.0,
+ _ => self.width,
+ }
+ }
+}
+
+/// Reads a border element (`w:top`, `w:bottom`...). `None` for `nil`/`none`.
+pub fn read_border(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> Option<Border> {
+ let val = t.val(n).unwrap_or("none");
+ let style = match val {
+ "nil" | "none" => return None,
+ "single" | "hairline" => LineStyle::Single,
+ "thick" => LineStyle::Thick,
+ "double" | "doubleWave" => LineStyle::Double,
+ "triple" => LineStyle::Triple,
+ "dotted" => LineStyle::Dotted,
+ "dashed" | "dashSmallGap" => LineStyle::Dashed,
+ "dotDash" | "dotDotDash" | "dashDotStroked" => LineStyle::DotDash,
+ "wave" => LineStyle::Wave,
+ "threeDEmboss" | "threeDEngrave" | "outset" | "inset" => LineStyle::ThreeD,
+ v if v.starts_with("thinThick") || v.starts_with("thickThin") => LineStyle::ThinThick,
+ // Art borders (apples, stars...) and anything else: a plain line.
+ _ => LineStyle::Single,
+ };
+ // `sz` is in eighths of a point; Word clamps to 1/4..12 points.
+ let size = t.w_attr(n, "sz").and_then(parse_int).unwrap_or(4);
+ let width = eighth_points(size).clamp(0.25, 12.0);
+ let width = if val == "hairline" { 0.25 } else { width };
+ let space = t
+ .w_attr(n, "space")
+ .and_then(parse_int)
+ .map_or(0.0, |v| v as f32);
+ let color = read_color(t, n, "color", "theme", theme).unwrap_or(ColorRef::Auto);
+ Some(Border {
+ style,
+ width,
+ space,
+ color,
+ })
+}
diff --git a/crates/docx_engine/src/model/props/color.rs b/crates/docx_engine/src/model/props/color.rs
new file mode 100644
index 0000000000..84069987e9
--- /dev/null
+++ b/crates/docx_engine/src/model/props/color.rs
@@ -0,0 +1,173 @@
+//! Colors, shading and highlighting.
+
+use crate::xml::{NodeId, XmlTree};
+use pptx_engine::model::color::{ColorScheme, Rgba};
+
+/// The theme colors and fonts property parsing needs.
+#[derive(Clone, Debug, Default)]
+pub struct ThemeInfo {
+ /// Theme color scheme.
+ pub colors: ColorScheme,
+ /// Heading (major) fonts.
+ pub major: pptx_engine::model::theme::FontCollection,
+ /// Body (minor) fonts.
+ pub minor: pptx_engine::model::theme::FontCollection,
+}
+
+impl ThemeInfo {
+ /// A WordprocessingML theme color name (`accent1`, `text1`, `background2`...).
+ pub fn color(&self, name: &str) -> Option<Rgba> {
+ let slot = match name {
+ "dark1" | "text1" => "dk1",
+ "light1" | "background1" => "lt1",
+ "dark2" | "text2" => "dk2",
+ "light2" | "background2" => "lt2",
+ "hyperlink" => "hlink",
+ "followedHyperlink" => "folHlink",
+ other => other,
+ };
+ self.colors.slot(slot)
+ }
+
+ /// Resolves a theme font slot (`majorHAnsi`, `minorEastAsia`...).
+ pub fn font(&self, slot: &str) -> Option<&str> {
+ let (collection, kind) = match slot {
+ "majorAscii" | "majorHAnsi" => (&self.major, 0),
+ "majorEastAsia" => (&self.major, 1),
+ "majorBidi" => (&self.major, 2),
+ "minorAscii" | "minorHAnsi" => (&self.minor, 0),
+ "minorEastAsia" => (&self.minor, 1),
+ "minorBidi" => (&self.minor, 2),
+ _ => return None,
+ };
+ let face = match kind {
+ 0 => &collection.latin,
+ 1 => &collection.ea,
+ _ => &collection.cs,
+ };
+ (!face.is_empty()).then_some(face.as_str())
+ }
+}
+
+/// Applies `w:themeTint` / `w:themeShade` (hex bytes) to a theme color.
+fn tint_shade(mut c: Rgba, tint: Option<&str>, shade: Option<&str>) -> Rgba {
+ let byte = |v: Option<&str>| v.and_then(|s| u8::from_str_radix(s.trim(), 16).ok());
+ if let Some(t) = byte(tint) {
+ let k = f32::from(t) / 255.0;
+ c.r = c.r * k + (1.0 - k);
+ c.g = c.g * k + (1.0 - k);
+ c.b = c.b * k + (1.0 - k);
+ }
+ if let Some(s) = byte(shade) {
+ let k = f32::from(s) / 255.0;
+ c.r *= k;
+ c.g *= k;
+ c.b *= k;
+ }
+ c
+}
+
+/// A run or border color: `auto` (context decides) or a value.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum ColorRef {
+ /// Automatic (black text, or white on dark shading).
+ Auto,
+ /// An explicit color.
+ Rgb(Rgba),
+}
+
+impl ColorRef {
+ /// The color, `None` for automatic.
+ pub fn rgb(self) -> Option<Rgba> {
+ match self {
+ ColorRef::Auto => None,
+ ColorRef::Rgb(c) => Some(c),
+ }
+ }
+}
+
+/// Reads a color from `val`-style attributes: `attr` (hex or `auto`) and the
+/// theme attributes `{prefix}Color`, `{prefix}Tint`, `{prefix}Shade`.
+pub fn read_color(
+ t: &XmlTree,
+ n: NodeId,
+ attr: &str,
+ theme_prefix: &str,
+ theme: &ThemeInfo,
+) -> Option<ColorRef> {
+ let theme_name = t.w_attr(n, &format!("{theme_prefix}Color"));
+ if let Some(name) = theme_name
+ && let Some(c) = theme.color(name)
+ {
+ return Some(ColorRef::Rgb(tint_shade(
+ c,
+ t.w_attr(n, &format!("{theme_prefix}Tint")),
+ t.w_attr(n, &format!("{theme_prefix}Shade")),
+ )));
+ }
+ let v = t.w_attr(n, attr)?;
+ if v.eq_ignore_ascii_case("auto") {
+ return Some(ColorRef::Auto);
+ }
+ Rgba::from_hex(v).map(ColorRef::Rgb)
+}
+
+/// The effective background of a `w:shd` element (`None` = no shading).
+pub fn read_shading(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> Option<Rgba> {
+ let pattern = t.val(n).unwrap_or("clear");
+ let fill = match t.w_attr(n, "themeFill").and_then(|name| theme.color(name)) {
+ Some(c) => Some(tint_shade(
+ c,
+ t.w_attr(n, "themeFillTint"),
+ t.w_attr(n, "themeFillShade"),
+ )),
+ None => t
+ .w_attr(n, "fill")
+ .filter(|v| !v.eq_ignore_ascii_case("auto"))
+ .and_then(Rgba::from_hex),
+ };
+ let color = match read_color(t, n, "color", "theme", theme) {
+ Some(ColorRef::Rgb(c)) => Some(c),
+ _ => None,
+ };
+ let pct = |p: f32| {
+ let fg = color.unwrap_or(Rgba::BLACK);
+ let bg = fill.unwrap_or(Rgba::WHITE);
+ Some(bg.lerp(fg, p))
+ };
+ match pattern {
+ "nil" => None,
+ "clear" => fill,
+ "solid" => color.or(Some(Rgba::BLACK)),
+ p if p.starts_with("pct") => {
+ let v: f32 = p[3..].parse().unwrap_or(0.0);
+ pct(v / 100.0)
+ }
+ // Stripes and grids average to roughly a quarter coverage.
+ _ => pct(0.25),
+ }
+}
+
+/// A highlight color name (`w:highlight`).
+pub fn highlight_color(name: &str) -> Option<Rgba> {
+ let hex = match name {
+ "black" => "000000",
+ "blue" => "0000FF",
+ "cyan" => "00FFFF",
+ "green" => "00FF00",
+ "magenta" => "FF00FF",
+ "red" => "FF0000",
+ "yellow" => "FFFF00",
+ "white" => "FFFFFF",
+ "darkBlue" => "000080",
+ "darkCyan" => "008080",
+ "darkGreen" => "008000",
+ "darkMagenta" => "800080",
+ "darkRed" => "800000",
+ "darkYellow" => "808000",
+ "darkGray" => "808080",
+ "lightGray" => "C0C0C0",
+ _ => return None,
+ };
+ Rgba::from_hex(hex)
+}
diff --git a/crates/docx_engine/src/model/props/para.rs b/crates/docx_engine/src/model/props/para.rs
new file mode 100644
index 0000000000..abfead8a86
--- /dev/null
+++ b/crates/docx_engine/src/model/props/para.rs
@@ -0,0 +1,577 @@
+//! Paragraph properties.
+
+use super::border::{Border, read_border};
+use super::color::{ThemeInfo, read_shading};
+use super::run::RPr;
+use crate::units::twips;
+use crate::xml::{NodeId, Ns, XmlTree, parse_int, parse_on_off};
+use pptx_engine::model::color::Rgba;
+
+/// Horizontal alignment of a paragraph.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum Align {
+ /// Left (start).
+ #[default]
+ Left,
+ /// Centered.
+ Center,
+ /// Right (end).
+ Right,
+ /// Justified: lines but the last stretch to both margins.
+ Justify,
+ /// Distributed: every line, including the last, stretches by spacing characters.
+ Distribute,
+}
+
+/// Line spacing rule.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum LineSpacing {
+ /// A multiple of the natural line height (1.0 = single).
+ Auto(f32),
+ /// Exactly this height (points).
+ Exact(f32),
+ /// At least this height (points).
+ AtLeast(f32),
+}
+
+impl Default for LineSpacing {
+ fn default() -> Self {
+ LineSpacing::Auto(1.0)
+ }
+}
+
+/// Alignment of a tab stop.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TabAlign {
+ /// Text starts at the stop.
+ Left,
+ /// Text centers on the stop.
+ Center,
+ /// Text ends at the stop.
+ Right,
+ /// The decimal separator aligns on the stop.
+ Decimal,
+ /// A vertical line at the stop; text is not moved.
+ Bar,
+}
+
+/// What fills the space before a tab stop.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum TabLeader {
+ /// Nothing.
+ #[default]
+ None,
+ /// Dots.
+ Dot,
+ /// Hyphens.
+ Hyphen,
+ /// An underline.
+ Underscore,
+ /// A heavy line.
+ Heavy,
+ /// Middle dots.
+ MiddleDot,
+}
+
+/// A custom tab stop.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct TabStop {
+ /// Position from the start of the text area (points; may be negative).
+ pub pos: f32,
+ /// Alignment.
+ pub align: TabAlign,
+ /// Leader.
+ pub leader: TabLeader,
+}
+
+/// A paragraph's numbering reference (`w:numPr`), as a level states it.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct NumPr {
+ /// Numbering instance (`0` removes numbering).
+ pub num_id: Option<i64>,
+ /// List level.
+ pub ilvl: Option<u8>,
+}
+
+/// Paragraph borders, as a level states them.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct ParaBordersPr {
+ /// Top.
+ pub top: Option<Option<Border>>,
+ /// Left.
+ pub left: Option<Option<Border>>,
+ /// Bottom.
+ pub bottom: Option<Option<Border>>,
+ /// Right.
+ pub right: Option<Option<Border>>,
+ /// Between paragraphs with the same borders.
+ pub between: Option<Option<Border>>,
+ /// Bar beside the paragraph.
+ pub bar: Option<Option<Border>>,
+}
+
+/// Paragraph borders, resolved.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct ParaBorders {
+ /// Top.
+ pub top: Option<Border>,
+ /// Left.
+ pub left: Option<Border>,
+ /// Bottom.
+ pub bottom: Option<Border>,
+ /// Right.
+ pub right: Option<Border>,
+ /// Between paragraphs with the same borders.
+ pub between: Option<Border>,
+}
+
+impl ParaBorders {
+ /// Whether any border is set.
+ pub fn any(&self) -> bool {
+ self.top.is_some()
+ || self.left.is_some()
+ || self.bottom.is_some()
+ || self.right.is_some()
+ || self.between.is_some()
+ }
+}
+
+/// A text frame or drop cap (`w:framePr`).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct FramePr {
+ /// Drop cap style (`drop`, `margin`), when this is a drop cap.
+ pub drop_cap: Option<String>,
+ /// Lines the drop cap spans.
+ pub lines: u32,
+ /// Width (points).
+ pub w: Option<f32>,
+ /// Height (points).
+ pub h: Option<f32>,
+ /// How the height applies (`None`: at least the given height, as Word
+ /// reads frames without a rule).
+ pub h_rule: Option<super::table::HeightRule>,
+ /// Horizontal position (points).
+ pub x: Option<f32>,
+ /// Vertical position (points).
+ pub y: Option<f32>,
+ /// Horizontal anchor (`margin`, `page`, `text`).
+ pub h_anchor: Option<String>,
+ /// Vertical anchor.
+ pub v_anchor: Option<String>,
+ /// Horizontal alignment keyword.
+ pub x_align: Option<String>,
+ /// Vertical alignment keyword.
+ pub y_align: Option<String>,
+ /// Wrap mode.
+ pub wrap: Option<String>,
+ /// Horizontal distance from text (points).
+ pub h_space: f32,
+ /// Vertical distance from text (points).
+ pub v_space: f32,
+}
+
+/// Paragraph properties as one level of the hierarchy states them.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct PPr {
+ /// Paragraph style.
+ pub style: Option<String>,
+ /// Keep with the next paragraph.
+ pub keep_next: Option<bool>,
+ /// Keep lines together.
+ pub keep_lines: Option<bool>,
+ /// Start on a new page.
+ pub page_break_before: Option<bool>,
+ /// Widow and orphan control.
+ pub widow_control: Option<bool>,
+ /// Exclude from line numbering.
+ pub suppress_line_numbers: Option<bool>,
+ /// Ignore spacing between paragraphs of the same style.
+ pub contextual_spacing: Option<bool>,
+ /// Swap indents on even pages.
+ pub mirror_indents: Option<bool>,
+ /// Right-to-left paragraph.
+ pub bidi: Option<bool>,
+ /// Snap to the document grid.
+ pub snap_to_grid: Option<bool>,
+ /// Numbering.
+ pub num: NumPr,
+ /// Borders.
+ pub borders: ParaBordersPr,
+ /// Shading.
+ pub shading: Option<Option<Rgba>>,
+ /// Tab stops added (and cleared: `None` alignment) by this level.
+ pub tabs: Vec<(f32, Option<TabStop>)>,
+ /// Space before (points).
+ pub before: Option<f32>,
+ /// Space before in lines (hundredths of a line), overriding `before`.
+ pub before_lines: Option<f32>,
+ /// HTML-style automatic space before.
+ pub before_auto: Option<bool>,
+ /// Space after (points).
+ pub after: Option<f32>,
+ /// Space after in lines.
+ pub after_lines: Option<f32>,
+ /// Automatic space after.
+ pub after_auto: Option<bool>,
+ /// Line spacing.
+ pub line: Option<LineSpacing>,
+ /// Left (start) indent (points).
+ pub ind_left: Option<f32>,
+ /// Right (end) indent (points).
+ pub ind_right: Option<f32>,
+ /// First-line offset (points; negative = hanging).
+ pub ind_first: Option<f32>,
+ /// Alignment.
+ pub jc: Option<Align>,
+ /// Outline level (0-8; 9 = body text).
+ pub outline_lvl: Option<u8>,
+ /// Frame or drop cap.
+ pub frame: Option<Option<FramePr>>,
+ /// Properties of the paragraph mark.
+ pub mark: RPr,
+ /// Whether this paragraph ends a section (`w:sectPr` inside `w:pPr`).
+ pub ends_section: bool,
+}
+
+fn twips_attr(t: &XmlTree, n: NodeId, name: &str) -> Option<f32> {
+ t.w_attr(n, name).and_then(parse_int).map(twips)
+}
+
+impl PPr {
+ /// Reads a `w:pPr` element.
+ pub fn read(t: &XmlTree, ppr: NodeId, theme: &ThemeInfo) -> Self {
+ let mut p = PPr::default();
+ for c in t.children(ppr) {
+ p.read_child(t, c, theme);
+ }
+ p
+ }
+
+ /// Reads one property element.
+ pub fn read_child(&mut self, t: &XmlTree, c: NodeId, theme: &ThemeInfo) {
+ if t.ns(c) != Ns::W {
+ return;
+ }
+ let flag = || parse_on_off(t.val(c));
+ match t.local(c) {
+ "pStyle" => self.style = t.val(c).map(str::to_owned),
+ "keepNext" => self.keep_next = Some(flag()),
+ "keepLines" => self.keep_lines = Some(flag()),
+ "pageBreakBefore" => self.page_break_before = Some(flag()),
+ "widowControl" => self.widow_control = Some(flag()),
+ "suppressLineNumbers" => self.suppress_line_numbers = Some(flag()),
+ "contextualSpacing" => self.contextual_spacing = Some(flag()),
+ "mirrorIndents" => self.mirror_indents = Some(flag()),
+ "bidi" => self.bidi = Some(flag()),
+ "snapToGrid" => self.snap_to_grid = Some(flag()),
+ "numPr" => {
+ if let Some(id) = t.child_val(c, "numId").and_then(parse_int) {
+ self.num.num_id = Some(id);
+ }
+ if let Some(l) = t.child_val(c, "ilvl").and_then(parse_int) {
+ self.num.ilvl = Some(l.clamp(0, 8) as u8);
+ }
+ }
+ "pBdr" => {
+ for b in t.children(c) {
+ let border = Some(read_border(t, b, theme));
+ match t.local(b) {
+ "top" => self.borders.top = border,
+ "left" | "start" => self.borders.left = border,
+ "bottom" => self.borders.bottom = border,
+ "right" | "end" => self.borders.right = border,
+ "between" => self.borders.between = border,
+ "bar" => self.borders.bar = border,
+ _ => {}
+ }
+ }
+ }
+ "shd" => self.shading = Some(read_shading(t, c, theme)),
+ "tabs" => {
+ for tab in t.children_named(c, Ns::W, "tab") {
+ let Some(pos) = twips_attr(t, tab, "pos") else {
+ continue;
+ };
+ let align = match t.val(tab).unwrap_or("left") {
+ "clear" => None,
+ "center" => Some(TabAlign::Center),
+ "right" | "end" => Some(TabAlign::Right),
+ "decimal" => Some(TabAlign::Decimal),
+ "bar" => Some(TabAlign::Bar),
+ // `num` stops are list stops; they act as left stops.
+ _ => Some(TabAlign::Left),
+ };
+ let leader = match t.w_attr(tab, "leader").unwrap_or("none") {
+ "dot" => TabLeader::Dot,
+ "hyphen" => TabLeader::Hyphen,
+ "underscore" => TabLeader::Underscore,
+ "heavy" => TabLeader::Heavy,
+ "middleDot" => TabLeader::MiddleDot,
+ _ => TabLeader::None,
+ };
+ self.tabs
+ .push((pos, align.map(|align| TabStop { pos, align, leader })));
+ }
+ }
+ "spacing" => {
+ if let Some(v) = twips_attr(t, c, "before") {
+ self.before = Some(v);
+ }
+ if let Some(v) = t.w_attr(c, "beforeLines").and_then(parse_int) {
+ self.before_lines = Some(v as f32 / 100.0);
+ }
+ if let Some(v) = t.w_attr(c, "beforeAutospacing") {
+ self.before_auto = Some(parse_on_off(Some(v)));
+ }
+ if let Some(v) = twips_attr(t, c, "after") {
+ self.after = Some(v);
+ }
+ if let Some(v) = t.w_attr(c, "afterLines").and_then(parse_int) {
+ self.after_lines = Some(v as f32 / 100.0);
+ }
+ if let Some(v) = t.w_attr(c, "afterAutospacing") {
+ self.after_auto = Some(parse_on_off(Some(v)));
+ }
+ if let Some(line) = t.w_attr(c, "line").and_then(parse_int) {
+ self.line = Some(match t.w_attr(c, "lineRule").unwrap_or("auto") {
+ "exact" => LineSpacing::Exact(twips(line.abs())),
+ "atLeast" => LineSpacing::AtLeast(twips(line)),
+ _ => LineSpacing::Auto(line as f32 / 240.0),
+ });
+ }
+ }
+ "ind" => {
+ if let Some(v) = twips_attr(t, c, "left").or_else(|| twips_attr(t, c, "start")) {
+ self.ind_left = Some(v);
+ }
+ if let Some(v) = twips_attr(t, c, "right").or_else(|| twips_attr(t, c, "end")) {
+ self.ind_right = Some(v);
+ }
+ if let Some(v) = twips_attr(t, c, "hanging") {
+ self.ind_first = Some(-v);
+ } else if let Some(v) = twips_attr(t, c, "firstLine") {
+ self.ind_first = Some(v);
+ }
+ }
+ "jc" => {
+ self.jc = Some(match t.val(c).unwrap_or("left") {
+ "center" => Align::Center,
+ "right" | "end" => Align::Right,
+ "both" | "lowKashida" | "mediumKashida" | "highKashida" | "thaiDistribute" => {
+ Align::Justify
+ }
+ "distribute" => Align::Distribute,
+ _ => Align::Left,
+ });
+ }
+ "outlineLvl" => {
+ self.outline_lvl = t.val(c).and_then(parse_int).map(|v| v.clamp(0, 9) as u8);
+ }
+ "framePr" => {
+ let drop_cap = t
+ .w_attr(c, "dropCap")
+ .filter(|v| *v != "none")
+ .map(str::to_owned);
+ self.frame = Some(Some(FramePr {
+ drop_cap,
+ lines: t
+ .w_attr(c, "lines")
+ .and_then(parse_int)
+ .map_or(1, |v| v.clamp(1, 10) as u32),
+ w: twips_attr(t, c, "w"),
+ h: twips_attr(t, c, "h"),
+ h_rule: t.w_attr(c, "hRule").map(|r| match r {
+ "exact" => super::table::HeightRule::Exact,
+ "auto" => super::table::HeightRule::Auto,
+ _ => super::table::HeightRule::AtLeast,
+ }),
+ x: twips_attr(t, c, "x"),
+ y: twips_attr(t, c, "y"),
+ h_anchor: t.w_attr(c, "hAnchor").map(str::to_owned),
+ v_anchor: t.w_attr(c, "vAnchor").map(str::to_owned),
+ x_align: t.w_attr(c, "xAlign").map(str::to_owned),
+ y_align: t.w_attr(c, "yAlign").map(str::to_owned),
+ wrap: t.w_attr(c, "wrap").map(str::to_owned),
+ h_space: twips_attr(t, c, "hSpace").unwrap_or(0.0),
+ v_space: twips_attr(t, c, "vSpace").unwrap_or(0.0),
+ }));
+ }
+ "rPr" => self.mark = RPr::read(t, c, theme),
+ "sectPr" => self.ends_section = true,
+ _ => {}
+ }
+ }
+
+ /// Overlays a later level onto these properties.
+ pub fn apply(&mut self, o: &PPr) {
+ macro_rules! set {
+ ($($f:ident),*) => {$(
+ if o.$f.is_some() {
+ self.$f = o.$f.clone();
+ }
+ )*};
+ }
+ set!(
+ style,
+ keep_next,
+ keep_lines,
+ page_break_before,
+ widow_control,
+ suppress_line_numbers,
+ contextual_spacing,
+ mirror_indents,
+ bidi,
+ snap_to_grid,
+ shading,
+ before,
+ before_lines,
+ before_auto,
+ after,
+ after_lines,
+ after_auto,
+ line,
+ ind_left,
+ ind_right,
+ ind_first,
+ jc,
+ outline_lvl,
+ frame
+ );
+ if o.num.num_id.is_some() {
+ self.num.num_id = o.num.num_id;
+ }
+ if o.num.ilvl.is_some() {
+ self.num.ilvl = o.num.ilvl;
+ }
+ macro_rules! border {
+ ($($f:ident),*) => {$(
+ if o.borders.$f.is_some() {
+ self.borders.$f = o.borders.$f;
+ }
+ )*};
+ }
+ border!(top, left, bottom, right, between, bar);
+ self.tabs.extend(o.tabs.iter().copied());
+ self.mark.apply(&o.mark, false);
+ self.ends_section |= o.ends_section;
+ }
+}
+
+/// Paragraph properties fully resolved.
+#[derive(Clone, Debug, PartialEq)]
+pub struct ParaProps {
+ /// Paragraph style id.
+ pub style: Option<String>,
+ /// Keep with next.
+ pub keep_next: bool,
+ /// Keep lines together.
+ pub keep_lines: bool,
+ /// Page break before.
+ pub page_break_before: bool,
+ /// Widow/orphan control.
+ pub widow_control: bool,
+ /// Not line-numbered.
+ pub suppress_line_numbers: bool,
+ /// Contextual spacing.
+ pub contextual_spacing: bool,
+ /// Mirror indents.
+ pub mirror_indents: bool,
+ /// Right to left.
+ pub bidi: bool,
+ /// Snap to grid.
+ pub snap_to_grid: bool,
+ /// Numbering instance and level (`None` when not numbered).
+ pub num: Option<(i64, u8)>,
+ /// Borders.
+ pub borders: ParaBorders,
+ /// Bar border.
+ pub bar: Option<Border>,
+ /// Shading.
+ pub shading: Option<Rgba>,
+ /// Tab stops, sorted by position.
+ pub tabs: Vec<TabStop>,
+ /// Space before (points).
+ pub before: f32,
+ /// Space before in lines, when set.
+ pub before_lines: Option<f32>,
+ /// Automatic space before.
+ pub before_auto: bool,
+ /// Space after (points).
+ pub after: f32,
+ /// Space after in lines, when set.
+ pub after_lines: Option<f32>,
+ /// Automatic space after.
+ pub after_auto: bool,
+ /// Line spacing.
+ pub line: LineSpacing,
+ /// Left indent (points).
+ pub ind_left: f32,
+ /// Right indent (points).
+ pub ind_right: f32,
+ /// First-line offset (points; negative = hanging).
+ pub ind_first: f32,
+ /// Alignment.
+ pub jc: Align,
+ /// Outline level.
+ pub outline_lvl: Option<u8>,
+ /// Frame or drop cap.
+ pub frame: Option<FramePr>,
+ /// Paragraph mark run properties (merged).
+ pub mark: RPr,
+}
+
+impl PPr {
+ /// Resolves fully merged properties.
+ pub fn resolve(&self) -> ParaProps {
+ let mut tabs: Vec<TabStop> = Vec::new();
+ for (pos, stop) in &self.tabs {
+ tabs.retain(|s| (s.pos - pos).abs() > 0.05);
+ if let Some(s) = stop {
+ tabs.push(*s);
+ }
+ }
+ tabs.sort_by(|a, b| a.pos.total_cmp(&b.pos));
+ let num = match (self.num.num_id, self.num.ilvl) {
+ (Some(id), lvl) if id > 0 => Some((id, lvl.unwrap_or(0))),
+ _ => None,
+ };
+ ParaProps {
+ style: self.style.clone(),
+ keep_next: self.keep_next.unwrap_or(false),
+ keep_lines: self.keep_lines.unwrap_or(false),
+ page_break_before: self.page_break_before.unwrap_or(false),
+ // Word applies widow control unless a level turns it off.
+ widow_control: self.widow_control.unwrap_or(true),
+ suppress_line_numbers: self.suppress_line_numbers.unwrap_or(false),
+ contextual_spacing: self.contextual_spacing.unwrap_or(false),
+ mirror_indents: self.mirror_indents.unwrap_or(false),
+ bidi: self.bidi.unwrap_or(false),
+ snap_to_grid: self.snap_to_grid.unwrap_or(true),
+ num,
+ borders: ParaBorders {
+ top: self.borders.top.flatten(),
+ left: self.borders.left.flatten(),
+ bottom: self.borders.bottom.flatten(),
+ right: self.borders.right.flatten(),
+ between: self.borders.between.flatten(),
+ },
+ bar: self.borders.bar.flatten(),
+ shading: self.shading.flatten(),
+ tabs,
+ before: self.before.unwrap_or(0.0),
+ before_lines: self.before_lines,
+ before_auto: self.before_auto.unwrap_or(false),
+ after: self.after.unwrap_or(0.0),
+ after_lines: self.after_lines,
+ after_auto: self.after_auto.unwrap_or(false),
+ line: self.line.unwrap_or_default(),
+ ind_left: self.ind_left.unwrap_or(0.0),
+ ind_right: self.ind_right.unwrap_or(0.0),
+ ind_first: self.ind_first.unwrap_or(0.0),
+ jc: self.jc.unwrap_or_default(),
+ outline_lvl: self.outline_lvl,
+ frame: self.frame.clone().flatten(),
+ mark: self.mark.clone(),
+ }
+ }
+}
diff --git a/crates/docx_engine/src/model/props/run.rs b/crates/docx_engine/src/model/props/run.rs
new file mode 100644
index 0000000000..dace9de184
--- /dev/null
+++ b/crates/docx_engine/src/model/props/run.rs
@@ -0,0 +1,445 @@
+//! Run (character) properties.
+
+use super::border::{Border, read_border};
+use super::color::{ColorRef, ThemeInfo, highlight_color, read_color, read_shading};
+use crate::units::{half_points, twips};
+use crate::xml::{NodeId, Ns, XmlTree, parse_int, parse_on_off};
+use pptx_engine::model::color::Rgba;
+
+/// Underline styles, reduced to what drawing needs.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum UnderlineStyle {
+ /// One line.
+ Single,
+ /// Under words only (not spaces).
+ Words,
+ /// Two lines.
+ Double,
+ /// A thick line.
+ Thick,
+ /// Dots.
+ Dotted,
+ /// Thick dots.
+ DottedHeavy,
+ /// Dashes.
+ Dash,
+ /// Thick dashes.
+ DashHeavy,
+ /// Long dashes.
+ DashLong,
+ /// Dash-dot.
+ DotDash,
+ /// Dash-dot-dot.
+ DotDotDash,
+ /// Wavy.
+ Wave,
+ /// Double wave.
+ WavyDouble,
+ /// Thick wave.
+ WavyHeavy,
+}
+
+/// An underline with its color (`None` = the text color).
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct Underline {
+ /// Style.
+ pub style: UnderlineStyle,
+ /// Color.
+ pub color: Option<Rgba>,
+}
+
+/// Vertical alignment of a run.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum VertAlign {
+ /// On the baseline.
+ #[default]
+ Baseline,
+ /// Superscript.
+ Super,
+ /// Subscript.
+ Sub,
+}
+
+/// Run properties as one level of the style hierarchy states them: every
+/// field is optional, and levels are merged in order.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct RPr {
+ /// Character style (`w:rStyle`).
+ pub style: Option<String>,
+ /// Font for ASCII characters.
+ pub ascii: Option<String>,
+ /// Font for other Latin, Greek, Cyrillic... characters.
+ pub h_ansi: Option<String>,
+ /// Font for East Asian characters.
+ pub east_asia: Option<String>,
+ /// Font for complex-script characters.
+ pub cs: Option<String>,
+ /// Which slot ambiguous characters use (`eastAsia`, `cs`).
+ pub hint: Option<String>,
+ /// Bold.
+ pub bold: Option<bool>,
+ /// Bold (complex script).
+ pub bold_cs: Option<bool>,
+ /// Italic.
+ pub italic: Option<bool>,
+ /// Italic (complex script).
+ pub italic_cs: Option<bool>,
+ /// All capitals.
+ pub caps: Option<bool>,
+ /// Small capitals.
+ pub small_caps: Option<bool>,
+ /// Strikethrough.
+ pub strike: Option<bool>,
+ /// Double strikethrough.
+ pub dstrike: Option<bool>,
+ /// Outline.
+ pub outline: Option<bool>,
+ /// Shadow.
+ pub shadow: Option<bool>,
+ /// Embossed.
+ pub emboss: Option<bool>,
+ /// Engraved.
+ pub imprint: Option<bool>,
+ /// Hidden.
+ pub vanish: Option<bool>,
+ /// Hidden paragraph mark that joins paragraphs (`w:specVanish`).
+ pub spec_vanish: Option<bool>,
+ /// Right-to-left run.
+ pub rtl: Option<bool>,
+ /// Treat as complex script.
+ pub cs_flag: Option<bool>,
+ /// Text color.
+ pub color: Option<ColorRef>,
+ /// Extra spacing between characters (points).
+ pub spacing: Option<f32>,
+ /// Horizontal scale (1.0 = 100%).
+ pub scale: Option<f32>,
+ /// Kerning threshold font size (points, 0 = off).
+ pub kern: Option<f32>,
+ /// Raise (positive) or lower (points).
+ pub position: Option<f32>,
+ /// Font size (points).
+ pub size: Option<f32>,
+ /// Font size, complex script (points).
+ pub size_cs: Option<f32>,
+ /// Highlight (`Some(None)` = explicitly none).
+ pub highlight: Option<Option<Rgba>>,
+ /// Underline (`Some(None)` = explicitly none).
+ pub underline: Option<Option<Underline>>,
+ /// Run border.
+ pub border: Option<Option<Border>>,
+ /// Run shading.
+ pub shading: Option<Option<Rgba>>,
+ /// Superscript/subscript.
+ pub vert_align: Option<VertAlign>,
+ /// Inserted paragraph mark (tracked change), on a paragraph's mark properties.
+ pub mark_inserted: Option<bool>,
+ /// Deleted paragraph mark (tracked change).
+ pub mark_deleted: Option<bool>,
+}
+
+fn on_off(t: &XmlTree, n: NodeId) -> bool {
+ parse_on_off(t.val(n))
+}
+
+impl RPr {
+ /// Reads the children of a `w:rPr` element.
+ pub fn read(t: &XmlTree, rpr: NodeId, theme: &ThemeInfo) -> Self {
+ let mut p = RPr::default();
+ for c in t.children(rpr) {
+ p.read_child(t, c, theme);
+ }
+ p
+ }
+
+ /// Reads one property element.
+ pub fn read_child(&mut self, t: &XmlTree, c: NodeId, theme: &ThemeInfo) {
+ if t.ns(c) != Ns::W {
+ return;
+ }
+ match t.local(c) {
+ "rStyle" => self.style = t.val(c).map(str::to_owned),
+ "rFonts" => {
+ let slot = |name: &str, theme_attr: &str| -> Option<String> {
+ t.w_attr(c, theme_attr)
+ .and_then(|s| theme.font(s))
+ .map(str::to_owned)
+ .or_else(|| t.w_attr(c, name).map(str::to_owned))
+ };
+ if let Some(v) = slot("ascii", "asciiTheme") {
+ self.ascii = Some(v);
+ }
+ if let Some(v) = slot("hAnsi", "hAnsiTheme") {
+ self.h_ansi = Some(v);
+ }
+ if let Some(v) = slot("eastAsia", "eastAsiaTheme") {
+ self.east_asia = Some(v);
+ }
+ if let Some(v) = slot("cs", "cstheme") {
+ self.cs = Some(v);
+ }
+ if let Some(h) = t.w_attr(c, "hint") {
+ self.hint = Some(h.to_owned());
+ }
+ }
+ "b" => self.bold = Some(on_off(t, c)),
+ "bCs" => self.bold_cs = Some(on_off(t, c)),
+ "i" => self.italic = Some(on_off(t, c)),
+ "iCs" => self.italic_cs = Some(on_off(t, c)),
+ "caps" => self.caps = Some(on_off(t, c)),
+ "smallCaps" => self.small_caps = Some(on_off(t, c)),
+ "strike" => self.strike = Some(on_off(t, c)),
+ "dstrike" => self.dstrike = Some(on_off(t, c)),
+ "outline" => self.outline = Some(on_off(t, c)),
+ "shadow" => self.shadow = Some(on_off(t, c)),
+ "emboss" => self.emboss = Some(on_off(t, c)),
+ "imprint" => self.imprint = Some(on_off(t, c)),
+ "vanish" => self.vanish = Some(on_off(t, c)),
+ "specVanish" => self.spec_vanish = Some(on_off(t, c)),
+ "rtl" => self.rtl = Some(on_off(t, c)),
+ "cs" => self.cs_flag = Some(on_off(t, c)),
+ "color" => {
+ if let Some(col) = read_color(t, c, "val", "theme", theme) {
+ self.color = Some(col);
+ }
+ }
+ "spacing" => self.spacing = t.val(c).and_then(parse_int).map(twips),
+ "w" => {
+ self.scale = t
+ .val(c)
+ .and_then(|v| v.trim_end_matches('%').trim().parse::<f32>().ok())
+ .map(|v| (v / 100.0).clamp(0.01, 6.0));
+ }
+ "kern" => self.kern = t.val(c).and_then(parse_int).map(half_points),
+ "position" => self.position = t.val(c).and_then(parse_int).map(half_points),
+ "sz" => self.size = t.val(c).and_then(parse_int).map(half_points),
+ "szCs" => self.size_cs = t.val(c).and_then(parse_int).map(half_points),
+ "highlight" => self.highlight = Some(t.val(c).and_then(highlight_color)),
+ "u" => {
+ let val = t.val(c).unwrap_or("single");
+ let style = match val {
+ "none" => None,
+ "words" => Some(UnderlineStyle::Words),
+ "double" => Some(UnderlineStyle::Double),
+ "thick" => Some(UnderlineStyle::Thick),
+ "dotted" => Some(UnderlineStyle::Dotted),
+ "dottedHeavy" => Some(UnderlineStyle::DottedHeavy),
+ "dash" => Some(UnderlineStyle::Dash),
+ "dashedHeavy" => Some(UnderlineStyle::DashHeavy),
+ "dashLong" | "dashLongHeavy" => Some(UnderlineStyle::DashLong),
+ "dotDash" | "dashDotHeavy" => Some(UnderlineStyle::DotDash),
+ "dotDotDash" | "dashDotDotHeavy" => Some(UnderlineStyle::DotDotDash),
+ "wave" => Some(UnderlineStyle::Wave),
+ "wavyDouble" => Some(UnderlineStyle::WavyDouble),
+ "wavyHeavy" => Some(UnderlineStyle::WavyHeavy),
+ _ => Some(UnderlineStyle::Single),
+ };
+ let color = match read_color(t, c, "color", "theme", theme) {
+ Some(ColorRef::Rgb(rgb)) => Some(rgb),
+ _ => None,
+ };
+ self.underline = Some(style.map(|style| Underline { style, color }));
+ }
+ "bdr" => self.border = Some(read_border(t, c, theme)),
+ "shd" => self.shading = Some(read_shading(t, c, theme)),
+ "vertAlign" => {
+ self.vert_align = Some(match t.val(c) {
+ Some("superscript") => VertAlign::Super,
+ Some("subscript") => VertAlign::Sub,
+ _ => VertAlign::Baseline,
+ });
+ }
+ "ins" | "moveTo" => self.mark_inserted = Some(true),
+ "del" | "moveFrom" => self.mark_deleted = Some(true),
+ _ => {}
+ }
+ }
+
+ /// Overlays `other` (a later level) onto these properties.
+ ///
+ /// With `toggle`, the on/off properties Word treats as toggles (bold,
+ /// italic, caps...) flip when `other` turns them on, as style levels do;
+ /// otherwise later values simply win, as direct formatting does.
+ pub fn apply(&mut self, other: &RPr, toggle: bool) {
+ macro_rules! set {
+ ($($f:ident),*) => {$(
+ if other.$f.is_some() {
+ self.$f = other.$f.clone();
+ }
+ )*};
+ }
+ macro_rules! toggles {
+ ($($f:ident),*) => {$(
+ match other.$f {
+ Some(true) if toggle => self.$f = Some(!self.$f.unwrap_or(false)),
+ Some(v) if !toggle => self.$f = Some(v),
+ _ => {}
+ }
+ )*};
+ }
+ set!(
+ style,
+ ascii,
+ h_ansi,
+ east_asia,
+ cs,
+ hint,
+ spec_vanish,
+ rtl,
+ cs_flag,
+ color,
+ spacing,
+ scale,
+ kern,
+ position,
+ size,
+ size_cs,
+ highlight,
+ underline,
+ border,
+ shading,
+ vert_align,
+ mark_inserted,
+ mark_deleted
+ );
+ toggles!(
+ bold, bold_cs, italic, italic_cs, caps, small_caps, strike, dstrike, outline, shadow,
+ emboss, imprint, vanish
+ );
+ }
+
+ /// Overlays within one style's `basedOn` chain: later values win.
+ pub fn inherit(&mut self, child: &RPr) {
+ self.apply(child, false);
+ }
+}
+
+/// Fully resolved run properties.
+#[derive(Clone, Debug, PartialEq)]
+pub struct RunProps {
+ /// Font for ASCII characters.
+ pub ascii: String,
+ /// Font for other Latin text.
+ pub h_ansi: String,
+ /// Font for East Asian text.
+ pub east_asia: String,
+ /// Font for complex scripts.
+ pub cs: String,
+ /// Which slot ambiguous characters use.
+ pub hint: Option<String>,
+ /// Bold.
+ pub bold: bool,
+ /// Italic.
+ pub italic: bool,
+ /// Bold (complex script).
+ pub bold_cs: bool,
+ /// Italic (complex script).
+ pub italic_cs: bool,
+ /// All caps.
+ pub caps: bool,
+ /// Small caps.
+ pub small_caps: bool,
+ /// Strikethrough.
+ pub strike: bool,
+ /// Double strikethrough.
+ pub dstrike: bool,
+ /// Outline.
+ pub outline: bool,
+ /// Shadow.
+ pub shadow: bool,
+ /// Embossed.
+ pub emboss: bool,
+ /// Engraved.
+ pub imprint: bool,
+ /// Hidden.
+ pub vanish: bool,
+ /// Hidden mark joining paragraphs.
+ pub spec_vanish: bool,
+ /// Right to left.
+ pub rtl: bool,
+ /// Complex script.
+ pub cs_flag: bool,
+ /// Text color (`None` = automatic).
+ pub color: Option<Rgba>,
+ /// Character spacing (points).
+ pub spacing: f32,
+ /// Horizontal scale.
+ pub scale: f32,
+ /// Kerning threshold (points; 0 = off).
+ pub kern: f32,
+ /// Baseline shift (points, positive = up).
+ pub position: f32,
+ /// Size (points).
+ pub size: f32,
+ /// Size, complex script (points).
+ pub size_cs: f32,
+ /// Highlight.
+ pub highlight: Option<Rgba>,
+ /// Underline.
+ pub underline: Option<Underline>,
+ /// Border around the run.
+ pub border: Option<Border>,
+ /// Shading behind the run.
+ pub shading: Option<Rgba>,
+ /// Superscript/subscript.
+ pub vert_align: VertAlign,
+ /// Tracked insertion of a paragraph mark.
+ pub mark_inserted: bool,
+ /// Tracked deletion of a paragraph mark.
+ pub mark_deleted: bool,
+}
+
+/// Word's last-resort font and size when no level names one.
+pub const DEFAULT_FONT: &str = "Times New Roman";
+/// Word's last-resort font size.
+pub const DEFAULT_SIZE: f32 = 10.0;
+
+impl RPr {
+ /// Resolves these (fully merged) properties.
+ pub fn resolve(&self) -> RunProps {
+ let ascii = self
+ .ascii
+ .clone()
+ .or_else(|| self.h_ansi.clone())
+ .unwrap_or_else(|| DEFAULT_FONT.to_owned());
+ let h_ansi = self.h_ansi.clone().unwrap_or_else(|| ascii.clone());
+ let size = self.size.unwrap_or(DEFAULT_SIZE).max(1.0);
+ RunProps {
+ east_asia: self.east_asia.clone().unwrap_or_else(|| h_ansi.clone()),
+ cs: self.cs.clone().unwrap_or_else(|| h_ansi.clone()),
+ ascii,
+ h_ansi,
+ hint: self.hint.clone(),
+ bold: self.bold.unwrap_or(false),
+ italic: self.italic.unwrap_or(false),
+ bold_cs: self.bold_cs.unwrap_or(false),
+ italic_cs: self.italic_cs.unwrap_or(false),
+ caps: self.caps.unwrap_or(false),
+ small_caps: self.small_caps.unwrap_or(false),
+ strike: self.strike.unwrap_or(false),
+ dstrike: self.dstrike.unwrap_or(false),
+ outline: self.outline.unwrap_or(false),
+ shadow: self.shadow.unwrap_or(false),
+ emboss: self.emboss.unwrap_or(false),
+ imprint: self.imprint.unwrap_or(false),
+ vanish: self.vanish.unwrap_or(false),
+ spec_vanish: self.spec_vanish.unwrap_or(false),
+ rtl: self.rtl.unwrap_or(false),
+ cs_flag: self.cs_flag.unwrap_or(false),
+ color: self.color.and_then(ColorRef::rgb),
+ spacing: self.spacing.unwrap_or(0.0),
+ scale: self.scale.unwrap_or(1.0),
+ kern: self.kern.unwrap_or(0.0),
+ position: self.position.unwrap_or(0.0),
+ size,
+ size_cs: self.size_cs.unwrap_or(size).max(1.0),
+ highlight: self.highlight.flatten(),
+ underline: self.underline.flatten(),
+ border: self.border.flatten(),
+ shading: self.shading.flatten(),
+ vert_align: self.vert_align.unwrap_or_default(),
+ mark_inserted: self.mark_inserted.unwrap_or(false),
+ mark_deleted: self.mark_deleted.unwrap_or(false),
+ }
+ }
+}
diff --git a/crates/docx_engine/src/model/props/table.rs b/crates/docx_engine/src/model/props/table.rs
new file mode 100644
index 0000000000..08efb158d4
--- /dev/null
+++ b/crates/docx_engine/src/model/props/table.rs
@@ -0,0 +1,540 @@
+//! Table, row and cell properties.
+
+use super::border::{Border, read_border};
+use super::color::{ThemeInfo, read_shading};
+use crate::units::twips;
+use crate::xml::{NodeId, Ns, XmlTree, parse_int, parse_on_off};
+use pptx_engine::model::color::Rgba;
+
+/// A table or cell width.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Width {
+ /// Automatic.
+ Auto,
+ /// Absolute (points).
+ Abs(f32),
+ /// A fraction of the available width (0.5 = 50%).
+ Pct(f32),
+}
+
+/// Reads a `w:tblW`/`w:tcW`-style width element.
+pub fn read_width(t: &XmlTree, n: NodeId) -> Option<Width> {
+ let ty = t.w_attr(n, "type").unwrap_or("dxa");
+ let raw = t.w_attr(n, "w")?;
+ match ty {
+ "nil" => Some(Width::Abs(0.0)),
+ "auto" => Some(Width::Auto),
+ "pct" => {
+ // Fiftieths of a percent, or a literal percentage.
+ let v = if let Some(p) = raw.strip_suffix('%') {
+ p.trim().parse::<f32>().ok()? / 100.0
+ } else {
+ parse_int(raw)? as f32 / 5000.0
+ };
+ Some(Width::Pct(v))
+ }
+ _ => parse_int(raw).map(|v| Width::Abs(twips(v))),
+ }
+}
+
+/// Margins (cell margins).
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct MarginsPr {
+ /// Top (points).
+ pub top: Option<f32>,
+ /// Left (points).
+ pub left: Option<f32>,
+ /// Bottom (points).
+ pub bottom: Option<f32>,
+ /// Right (points).
+ pub right: Option<f32>,
+}
+
+impl MarginsPr {
+ fn read(t: &XmlTree, n: NodeId) -> Self {
+ let mut m = MarginsPr::default();
+ for c in t.children(n) {
+ let v = match read_width(t, c) {
+ Some(Width::Abs(v)) => Some(v),
+ _ => None,
+ };
+ match t.local(c) {
+ "top" => m.top = v,
+ "left" | "start" => m.left = v,
+ "bottom" => m.bottom = v,
+ "right" | "end" => m.right = v,
+ _ => {}
+ }
+ }
+ m
+ }
+
+ fn apply(&mut self, o: &MarginsPr) {
+ if o.top.is_some() {
+ self.top = o.top;
+ }
+ if o.left.is_some() {
+ self.left = o.left;
+ }
+ if o.bottom.is_some() {
+ self.bottom = o.bottom;
+ }
+ if o.right.is_some() {
+ self.right = o.right;
+ }
+ }
+}
+
+/// Table or cell borders, as a level states them.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct BordersPr {
+ /// Top.
+ pub top: Option<Option<Border>>,
+ /// Left.
+ pub left: Option<Option<Border>>,
+ /// Bottom.
+ pub bottom: Option<Option<Border>>,
+ /// Right.
+ pub right: Option<Option<Border>>,
+ /// Between rows.
+ pub inside_h: Option<Option<Border>>,
+ /// Between columns.
+ pub inside_v: Option<Option<Border>>,
+ /// Diagonal, top-left to bottom-right (cells).
+ pub tl2br: Option<Option<Border>>,
+ /// Diagonal, top-right to bottom-left (cells).
+ pub tr2bl: Option<Option<Border>>,
+}
+
+impl BordersPr {
+ fn read(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> Self {
+ let mut b = BordersPr::default();
+ for c in t.children(n) {
+ let v = Some(read_border(t, c, theme));
+ match t.local(c) {
+ "top" => b.top = v,
+ "left" | "start" => b.left = v,
+ "bottom" => b.bottom = v,
+ "right" | "end" => b.right = v,
+ "insideH" => b.inside_h = v,
+ "insideV" => b.inside_v = v,
+ "tl2br" => b.tl2br = v,
+ "tr2bl" => b.tr2bl = v,
+ _ => {}
+ }
+ }
+ b
+ }
+
+ /// Overlays a later level.
+ pub fn apply(&mut self, o: &BordersPr) {
+ macro_rules! set {
+ ($($f:ident),*) => {$(
+ if o.$f.is_some() {
+ self.$f = o.$f;
+ }
+ )*};
+ }
+ set!(top, left, bottom, right, inside_h, inside_v, tl2br, tr2bl);
+ }
+}
+
+/// Floating table position (`w:tblpPr`).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct TablePosition {
+ /// Distance from text, left (points).
+ pub left_from_text: f32,
+ /// Distance from text, right.
+ pub right_from_text: f32,
+ /// Distance from text, top.
+ pub top_from_text: f32,
+ /// Distance from text, bottom.
+ pub bottom_from_text: f32,
+ /// Horizontal anchor (`margin`, `page`, `text`).
+ pub h_anchor: String,
+ /// Vertical anchor.
+ pub v_anchor: String,
+ /// Horizontal alignment keyword.
+ pub x_align: Option<String>,
+ /// Vertical alignment keyword.
+ pub y_align: Option<String>,
+ /// Horizontal offset (points).
+ pub x: f32,
+ /// Vertical offset (points).
+ pub y: f32,
+}
+
+/// Which conditional formats of the table style apply (`w:tblLook`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct TableLook {
+ /// Header row formatting.
+ pub first_row: bool,
+ /// Total row formatting.
+ pub last_row: bool,
+ /// First column formatting.
+ pub first_col: bool,
+ /// Last column formatting.
+ pub last_col: bool,
+ /// Row banding.
+ pub h_band: bool,
+ /// Column banding.
+ pub v_band: bool,
+}
+
+impl Default for TableLook {
+ fn default() -> Self {
+ Self {
+ first_row: true,
+ last_row: false,
+ first_col: true,
+ last_col: false,
+ h_band: true,
+ v_band: false,
+ }
+ }
+}
+
+/// Table properties as one level states them.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct TblPr {
+ /// Table style.
+ pub style: Option<String>,
+ /// Preferred width.
+ pub width: Option<Width>,
+ /// Alignment (`left`, `center`, `right`).
+ pub jc: Option<String>,
+ /// Indent from the margin (points).
+ pub ind: Option<f32>,
+ /// Borders.
+ pub borders: BordersPr,
+ /// Shading.
+ pub shading: Option<Option<Rgba>>,
+ /// Fixed layout.
+ pub fixed: Option<bool>,
+ /// Default cell margins.
+ pub cell_margins: MarginsPr,
+ /// Spacing between cells (points).
+ pub cell_spacing: Option<f32>,
+ /// Conditional format switches.
+ pub look: Option<TableLook>,
+ /// Floating position.
+ pub position: Option<TablePosition>,
+ /// Rows per band.
+ pub row_band: Option<u32>,
+ /// Columns per band.
+ pub col_band: Option<u32>,
+ /// Right-to-left table.
+ pub bidi: Option<bool>,
+}
+
+impl TblPr {
+ /// Reads a `w:tblPr` (or `w:tblPrEx`) element.
+ pub fn read(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> Self {
+ let mut p = TblPr::default();
+ for c in t.children(n) {
+ if t.ns(c) != Ns::W {
+ continue;
+ }
+ match t.local(c) {
+ "tblStyle" => p.style = t.val(c).map(str::to_owned),
+ "tblW" => p.width = read_width(t, c),
+ "jc" => p.jc = t.val(c).map(str::to_owned),
+ "tblInd" => {
+ p.ind = match read_width(t, c) {
+ Some(Width::Abs(v)) => Some(v),
+ _ => Some(0.0),
+ }
+ }
+ "tblBorders" => p.borders = BordersPr::read(t, c, theme),
+ "shd" => p.shading = Some(read_shading(t, c, theme)),
+ "tblLayout" => p.fixed = Some(t.w_attr(c, "type") == Some("fixed")),
+ "tblCellMar" => p.cell_margins = MarginsPr::read(t, c),
+ "tblCellSpacing" => {
+ p.cell_spacing = match read_width(t, c) {
+ Some(Width::Abs(v)) => Some(v),
+ _ => None,
+ }
+ }
+ "tblLook" => {
+ let mut look = TableLook::default();
+ if let Some(v) = t.val(c).and_then(|v| u32::from_str_radix(v, 16).ok()) {
+ look.first_row = v & 0x20 != 0;
+ look.last_row = v & 0x40 != 0;
+ look.first_col = v & 0x80 != 0;
+ look.last_col = v & 0x100 != 0;
+ look.h_band = v & 0x200 == 0;
+ look.v_band = v & 0x400 == 0;
+ }
+ let flag = |name: &str, current: bool| {
+ t.w_attr(c, name).map_or(current, |v| parse_on_off(Some(v)))
+ };
+ look.first_row = flag("firstRow", look.first_row);
+ look.last_row = flag("lastRow", look.last_row);
+ look.first_col = flag("firstColumn", look.first_col);
+ look.last_col = flag("lastColumn", look.last_col);
+ look.h_band = !flag("noHBand", !look.h_band);
+ look.v_band = !flag("noVBand", !look.v_band);
+ p.look = Some(look);
+ }
+ "tblpPr" => {
+ let tw = |name: &str| t.w_attr(c, name).and_then(parse_int).map_or(0.0, twips);
+ p.position = Some(TablePosition {
+ left_from_text: tw("leftFromText"),
+ right_from_text: tw("rightFromText"),
+ top_from_text: tw("topFromText"),
+ bottom_from_text: tw("bottomFromText"),
+ h_anchor: t.w_attr(c, "horzAnchor").unwrap_or("text").to_owned(),
+ v_anchor: t.w_attr(c, "vertAnchor").unwrap_or("margin").to_owned(),
+ x_align: t.w_attr(c, "tblpXSpec").map(str::to_owned),
+ y_align: t.w_attr(c, "tblpYSpec").map(str::to_owned),
+ x: tw("tblpX"),
+ y: tw("tblpY"),
+ });
+ }
+ "tblStyleRowBandSize" => {
+ p.row_band = t.val(c).and_then(parse_int).map(|v| v.max(1) as u32);
+ }
+ "tblStyleColBandSize" => {
+ p.col_band = t.val(c).and_then(parse_int).map(|v| v.max(1) as u32);
+ }
+ "bidiVisual" => p.bidi = Some(parse_on_off(t.val(c))),
+ _ => {}
+ }
+ }
+ p
+ }
+
+ /// Overlays a later level.
+ pub fn apply(&mut self, o: &TblPr) {
+ macro_rules! set {
+ ($($f:ident),*) => {$(
+ if o.$f.is_some() {
+ self.$f = o.$f.clone();
+ }
+ )*};
+ }
+ set!(
+ style,
+ width,
+ jc,
+ ind,
+ shading,
+ fixed,
+ cell_spacing,
+ look,
+ position,
+ row_band,
+ col_band,
+ bidi
+ );
+ self.borders.apply(&o.borders);
+ self.cell_margins.apply(&o.cell_margins);
+ }
+
+ /// Resolved default cell margins (Word's defaults: 0.08" left and right).
+ pub fn margins(&self) -> (f32, f32, f32, f32) {
+ (
+ self.cell_margins.top.unwrap_or(0.0),
+ self.cell_margins.left.unwrap_or(5.4),
+ self.cell_margins.bottom.unwrap_or(0.0),
+ self.cell_margins.right.unwrap_or(5.4),
+ )
+ }
+}
+
+/// Row height rule.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum HeightRule {
+ /// At least the given height.
+ AtLeast,
+ /// Exactly the given height.
+ Exact,
+ /// Content height (the value is ignored).
+ Auto,
+}
+
+/// Row properties.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct TrPr {
+ /// Don't split the row across pages.
+ pub cant_split: Option<bool>,
+ /// Height and rule.
+ pub height: Option<(f32, HeightRule)>,
+ /// Repeat as a header row on each page.
+ pub header: Option<bool>,
+ /// Row alignment.
+ pub jc: Option<String>,
+ /// Hidden row.
+ pub hidden: Option<bool>,
+ /// Grid columns skipped before the first cell.
+ pub grid_before: Option<u32>,
+ /// Grid columns skipped after the last cell.
+ pub grid_after: Option<u32>,
+ /// Cell spacing override (points).
+ pub cell_spacing: Option<f32>,
+ /// Inserted row (tracked change).
+ pub inserted: bool,
+ /// Deleted row (tracked change).
+ pub deleted: bool,
+}
+
+impl TrPr {
+ /// Reads a `w:trPr` element.
+ pub fn read(t: &XmlTree, n: NodeId) -> Self {
+ let mut p = TrPr::default();
+ for c in t.children(n) {
+ if t.ns(c) != Ns::W {
+ continue;
+ }
+ match t.local(c) {
+ "cantSplit" => p.cant_split = Some(parse_on_off(t.val(c))),
+ "trHeight" => {
+ let v = t.val(c).and_then(parse_int).map_or(0.0, twips);
+ let rule = match t.w_attr(c, "hRule") {
+ Some("exact") => HeightRule::Exact,
+ Some("auto") => HeightRule::Auto,
+ _ => HeightRule::AtLeast,
+ };
+ p.height = Some((v, rule));
+ }
+ "tblHeader" => p.header = Some(parse_on_off(t.val(c))),
+ "jc" => p.jc = t.val(c).map(str::to_owned),
+ "hidden" => p.hidden = Some(parse_on_off(t.val(c))),
+ "gridBefore" => {
+ p.grid_before = t.val(c).and_then(parse_int).map(|v| v.max(0) as u32)
+ }
+ "gridAfter" => p.grid_after = t.val(c).and_then(parse_int).map(|v| v.max(0) as u32),
+ "tblCellSpacing" => {
+ p.cell_spacing = match read_width(t, c) {
+ Some(Width::Abs(v)) => Some(v),
+ _ => None,
+ }
+ }
+ "ins" => p.inserted = true,
+ "del" => p.deleted = true,
+ _ => {}
+ }
+ }
+ p
+ }
+
+ /// Overlays a later level.
+ pub fn apply(&mut self, o: &TrPr) {
+ macro_rules! set {
+ ($($f:ident),*) => {$(
+ if o.$f.is_some() {
+ self.$f = o.$f.clone();
+ }
+ )*};
+ }
+ set!(
+ cant_split,
+ height,
+ header,
+ jc,
+ hidden,
+ grid_before,
+ grid_after,
+ cell_spacing
+ );
+ self.inserted |= o.inserted;
+ self.deleted |= o.deleted;
+ }
+}
+
+/// Vertical merge state of a cell.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum VMerge {
+ /// Starts a merged region.
+ Restart,
+ /// Continues the region above.
+ Continue,
+}
+
+/// Cell properties.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct TcPr {
+ /// Preferred width.
+ pub width: Option<Width>,
+ /// Grid columns spanned.
+ pub grid_span: Option<u32>,
+ /// Legacy horizontal merge.
+ pub h_merge: Option<VMerge>,
+ /// Vertical merge.
+ pub v_merge: Option<VMerge>,
+ /// Borders.
+ pub borders: BordersPr,
+ /// Shading.
+ pub shading: Option<Option<Rgba>>,
+ /// No wrapping.
+ pub no_wrap: Option<bool>,
+ /// Margins.
+ pub margins: MarginsPr,
+ /// Text direction (`btLr`, `tbRl`...).
+ pub text_direction: Option<String>,
+ /// Vertical alignment (`top`, `center`, `bottom`).
+ pub v_align: Option<String>,
+ /// Ignore the end-of-cell mark's height.
+ pub hide_mark: Option<bool>,
+}
+
+impl TcPr {
+ /// Reads a `w:tcPr` element.
+ pub fn read(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> Self {
+ let mut p = TcPr::default();
+ for c in t.children(n) {
+ if t.ns(c) != Ns::W {
+ continue;
+ }
+ match t.local(c) {
+ "tcW" => p.width = read_width(t, c),
+ "gridSpan" => p.grid_span = t.val(c).and_then(parse_int).map(|v| v.max(1) as u32),
+ "hMerge" => {
+ p.h_merge = Some(match t.val(c) {
+ Some("restart") => VMerge::Restart,
+ _ => VMerge::Continue,
+ })
+ }
+ "vMerge" => {
+ p.v_merge = Some(match t.val(c) {
+ Some("restart") => VMerge::Restart,
+ _ => VMerge::Continue,
+ })
+ }
+ "tcBorders" => p.borders = BordersPr::read(t, c, theme),
+ "shd" => p.shading = Some(read_shading(t, c, theme)),
+ "noWrap" => p.no_wrap = Some(parse_on_off(t.val(c))),
+ "tcMar" => p.margins = MarginsPr::read(t, c),
+ "textDirection" => p.text_direction = t.val(c).map(str::to_owned),
+ "vAlign" => p.v_align = t.val(c).map(str::to_owned),
+ "hideMark" => p.hide_mark = Some(parse_on_off(t.val(c))),
+ _ => {}
+ }
+ }
+ p
+ }
+
+ /// Overlays a later level.
+ pub fn apply(&mut self, o: &TcPr) {
+ macro_rules! set {
+ ($($f:ident),*) => {$(
+ if o.$f.is_some() {
+ self.$f = o.$f.clone();
+ }
+ )*};
+ }
+ set!(
+ width,
+ grid_span,
+ h_merge,
+ v_merge,
+ shading,
+ no_wrap,
+ text_direction,
+ v_align,
+ hide_mark
+ );
+ self.borders.apply(&o.borders);
+ self.margins.apply(&o.margins);
+ }
+}
diff --git a/crates/docx_engine/src/model/section.rs b/crates/docx_engine/src/model/section.rs
new file mode 100644
index 0000000000..4a876af34f
--- /dev/null
+++ b/crates/docx_engine/src/model/section.rs
@@ -0,0 +1,365 @@
+//! Section properties (`w:sectPr`): page geometry, columns, headers and
+//! footers, page and line numbering.
+
+use super::numbering::NumFmt;
+use super::props::{Border, ThemeInfo, read_border};
+use crate::units::twips;
+use crate::xml::{NodeId, Ns, XmlTree, parse_int, parse_on_off};
+
+/// How a section starts.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum SectionStart {
+ /// On a new page.
+ #[default]
+ NextPage,
+ /// On the same page.
+ Continuous,
+ /// On the next even page.
+ EvenPage,
+ /// On the next odd page.
+ OddPage,
+ /// In the next column.
+ NextColumn,
+}
+
+/// Header or footer part references by page kind (relationship ids).
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct HeaderRefs {
+ /// Default (odd) pages.
+ pub default: Option<String>,
+ /// The first page (with a title page).
+ pub first: Option<String>,
+ /// Even pages (with different odd and even pages).
+ pub even: Option<String>,
+}
+
+/// One column of a section.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct Column {
+ /// Width (points).
+ pub width: f32,
+ /// Space after it (points).
+ pub space: f32,
+}
+
+/// Line numbering settings.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct LineNumbering {
+ /// Number every n-th line.
+ pub count_by: u32,
+ /// First number.
+ pub start: u32,
+ /// Distance from the text (points; `None` = automatic).
+ pub distance: Option<f32>,
+ /// When numbering restarts.
+ pub restart: LineNumberRestart,
+}
+
+/// When line numbering restarts.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LineNumberRestart {
+ /// On each page.
+ NewPage,
+ /// At each section.
+ NewSection,
+ /// Never.
+ Continuous,
+}
+
+/// Vertical alignment of text on the page.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum PageVAlign {
+ /// Top.
+ #[default]
+ Top,
+ /// Centered.
+ Center,
+ /// Justified.
+ Both,
+ /// Bottom.
+ Bottom,
+}
+
+/// The document grid.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct DocGrid {
+ /// Lines snap to the grid pitch.
+ pub snap_lines: bool,
+ /// Grid line pitch (points).
+ pub line_pitch: f32,
+}
+
+/// Page borders.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct PageBorders {
+ /// Top.
+ pub top: Option<Border>,
+ /// Left.
+ pub left: Option<Border>,
+ /// Bottom.
+ pub bottom: Option<Border>,
+ /// Right.
+ pub right: Option<Border>,
+ /// Offsets are measured from the page edge (else from the text).
+ pub from_page_edge: bool,
+}
+
+/// One section's properties.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Section {
+ /// Page width (points).
+ pub page_w: f32,
+ /// Page height (points).
+ pub page_h: f32,
+ /// Top margin (points).
+ pub top: f32,
+ /// Right margin.
+ pub right: f32,
+ /// Bottom margin.
+ pub bottom: f32,
+ /// Left margin.
+ pub left: f32,
+ /// Header distance from the page top.
+ pub header: f32,
+ /// Footer distance from the page bottom.
+ pub footer: f32,
+ /// Gutter.
+ pub gutter: f32,
+ /// Whether the top margin is a minimum (positive) or exact (negative in the file).
+ pub top_exact: bool,
+ /// Whether the bottom margin is exact.
+ pub bottom_exact: bool,
+ /// Columns (one entry per column).
+ pub columns: Vec<Column>,
+ /// Draw a line between columns.
+ pub column_separator: bool,
+ /// Header references.
+ pub headers: HeaderRefs,
+ /// Footer references.
+ pub footers: HeaderRefs,
+ /// Different first page.
+ pub title_page: bool,
+ /// How the section starts.
+ pub start: SectionStart,
+ /// Page number format.
+ pub page_fmt: NumFmt,
+ /// Page number restart value.
+ pub page_start: Option<i64>,
+ /// Line numbering.
+ pub line_numbers: Option<LineNumbering>,
+ /// Vertical alignment.
+ pub v_align: PageVAlign,
+ /// Document grid.
+ pub grid: DocGrid,
+ /// Page borders.
+ pub borders: Option<PageBorders>,
+ /// Right-to-left section.
+ pub bidi: bool,
+}
+
+impl Default for Section {
+ /// US Letter with one-inch margins, as a new Word document has.
+ fn default() -> Self {
+ Self {
+ page_w: 612.0,
+ page_h: 792.0,
+ top: 72.0,
+ right: 72.0,
+ bottom: 72.0,
+ left: 72.0,
+ header: 36.0,
+ footer: 36.0,
+ gutter: 0.0,
+ top_exact: false,
+ bottom_exact: false,
+ columns: vec![Column {
+ width: 468.0,
+ space: 0.0,
+ }],
+ column_separator: false,
+ headers: HeaderRefs::default(),
+ footers: HeaderRefs::default(),
+ title_page: false,
+ start: SectionStart::NextPage,
+ page_fmt: NumFmt::Decimal,
+ page_start: None,
+ line_numbers: None,
+ v_align: PageVAlign::Top,
+ grid: DocGrid::default(),
+ borders: None,
+ bidi: false,
+ }
+ }
+}
+
+impl Section {
+ /// Width of the text area (points).
+ pub fn text_width(&self) -> f32 {
+ (self.page_w - self.left - self.right - self.gutter).max(36.0)
+ }
+
+ /// Reads a `w:sectPr` element.
+ pub fn read(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> Self {
+ let mut s = Section::default();
+ let tw = |c: NodeId, name: &str| t.w_attr(c, name).and_then(parse_int);
+ let mut cols: Option<NodeId> = None;
+ for c in t.children(n) {
+ if t.ns(c) != Ns::W {
+ continue;
+ }
+ match t.local(c) {
+ "pgSz" => {
+ if let Some(w) = tw(c, "w") {
+ s.page_w = twips(w).max(72.0);
+ }
+ if let Some(h) = tw(c, "h") {
+ s.page_h = twips(h).max(72.0);
+ }
+ }
+ "pgMar" => {
+ if let Some(v) = tw(c, "top") {
+ s.top_exact = v < 0;
+ s.top = twips(v.abs());
+ }
+ if let Some(v) = tw(c, "bottom") {
+ s.bottom_exact = v < 0;
+ s.bottom = twips(v.abs());
+ }
+ if let Some(v) = tw(c, "left").or_else(|| tw(c, "start")) {
+ s.left = twips(v);
+ }
+ if let Some(v) = tw(c, "right").or_else(|| tw(c, "end")) {
+ s.right = twips(v);
+ }
+ if let Some(v) = tw(c, "header") {
+ s.header = twips(v);
+ }
+ if let Some(v) = tw(c, "footer") {
+ s.footer = twips(v);
+ }
+ if let Some(v) = tw(c, "gutter") {
+ s.gutter = twips(v);
+ }
+ }
+ "cols" => cols = Some(c),
+ "headerReference" | "footerReference" => {
+ let rid = t.attr(c, Ns::R, "id").map(str::to_owned);
+ let refs = if t.local(c) == "headerReference" {
+ &mut s.headers
+ } else {
+ &mut s.footers
+ };
+ match t.w_attr(c, "type").unwrap_or("default") {
+ "first" => refs.first = rid,
+ "even" => refs.even = rid,
+ _ => refs.default = rid,
+ }
+ }
+ "titlePg" => s.title_page = parse_on_off(t.val(c)),
+ "type" => {
+ s.start = match t.val(c) {
+ Some("continuous") => SectionStart::Continuous,
+ Some("evenPage") => SectionStart::EvenPage,
+ Some("oddPage") => SectionStart::OddPage,
+ Some("nextColumn") => SectionStart::NextColumn,
+ _ => SectionStart::NextPage,
+ }
+ }
+ "pgNumType" => {
+ if let Some(f) = t.w_attr(c, "fmt") {
+ s.page_fmt = NumFmt::parse(f, None);
+ }
+ s.page_start = tw(c, "start");
+ }
+ "lnNumType" => {
+ let count_by = tw(c, "countBy").unwrap_or(0);
+ if count_by > 0 {
+ s.line_numbers = Some(LineNumbering {
+ count_by: count_by as u32,
+ start: tw(c, "start").map_or(1, |v| (v + 1).max(1) as u32),
+ distance: tw(c, "distance").map(twips),
+ restart: match t.w_attr(c, "restart") {
+ Some("continuous") => LineNumberRestart::Continuous,
+ Some("newSection") => LineNumberRestart::NewSection,
+ _ => LineNumberRestart::NewPage,
+ },
+ });
+ }
+ }
+ "vAlign" => {
+ s.v_align = match t.val(c) {
+ Some("center") => PageVAlign::Center,
+ Some("both") => PageVAlign::Both,
+ Some("bottom") => PageVAlign::Bottom,
+ _ => PageVAlign::Top,
+ }
+ }
+ "docGrid" => {
+ let ty = t.w_attr(c, "type").unwrap_or("default");
+ s.grid = DocGrid {
+ snap_lines: matches!(ty, "lines" | "linesAndChars" | "snapToChars"),
+ line_pitch: tw(c, "linePitch").map_or(0.0, twips),
+ };
+ }
+ "pgBorders" => {
+ let mut b = PageBorders {
+ from_page_edge: t.w_attr(c, "offsetFrom") == Some("page"),
+ ..PageBorders::default()
+ };
+ for e in t.children(c) {
+ let border = read_border(t, e, theme);
+ match t.local(e) {
+ "top" => b.top = border,
+ "left" => b.left = border,
+ "bottom" => b.bottom = border,
+ "right" => b.right = border,
+ _ => {}
+ }
+ }
+ s.borders = Some(b);
+ }
+ "bidi" => s.bidi = parse_on_off(t.val(c)),
+ _ => {}
+ }
+ }
+ let text_w = s.text_width();
+ s.columns = match cols {
+ Some(c) => {
+ let num = tw(c, "num").unwrap_or(1).clamp(1, 45) as usize;
+ let space = tw(c, "space").map_or(36.0, twips);
+ s.column_separator = t.w_attr(c, "sep").is_some_and(|v| parse_on_off(Some(v)));
+ let equal = t
+ .w_attr(c, "equalWidth")
+ .is_none_or(|v| parse_on_off(Some(v)));
+ let explicit: Vec<Column> = t
+ .children_named(c, Ns::W, "col")
+ .map(|col| Column {
+ width: tw(col, "w").map_or(0.0, twips),
+ space: tw(col, "space").map_or(0.0, twips),
+ })
+ .collect();
+ if !equal && explicit.len() > 1 {
+ explicit
+ } else if num > 1 {
+ let w = ((text_w - space * (num - 1) as f32) / num as f32).max(18.0);
+ (0..num)
+ .map(|i| Column {
+ width: w,
+ space: if i + 1 < num { space } else { 0.0 },
+ })
+ .collect()
+ } else {
+ vec![Column {
+ width: text_w,
+ space: 0.0,
+ }]
+ }
+ }
+ None => vec![Column {
+ width: text_w,
+ space: 0.0,
+ }],
+ };
+ s
+ }
+}
diff --git a/crates/docx_engine/src/model/settings.rs b/crates/docx_engine/src/model/settings.rs
new file mode 100644
index 0000000000..da903207dc
--- /dev/null
+++ b/crates/docx_engine/src/model/settings.rs
@@ -0,0 +1,165 @@
+//! Document settings (`word/settings.xml`) that affect layout.
+
+use super::numbering::NumFmt;
+use crate::units::twips;
+use crate::xml::{Ns, XmlTree, parse_int, parse_on_off};
+
+/// Where notes are numbered from and how.
+#[derive(Clone, Debug, PartialEq)]
+pub struct NoteSettings {
+ /// Number format.
+ pub fmt: NumFmt,
+ /// First number.
+ pub start: i64,
+ /// Restart numbering on each page or section.
+ pub restart: NoteRestart,
+}
+
+/// When note numbering restarts.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum NoteRestart {
+ /// Never.
+ #[default]
+ Continuous,
+ /// Each section.
+ EachSection,
+ /// Each page.
+ EachPage,
+}
+
+/// Layout-relevant settings.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Settings {
+ /// Default tab stop interval (points).
+ pub default_tab: f32,
+ /// Different headers for even and odd pages.
+ pub even_and_odd_headers: bool,
+ /// Mirror margins on facing pages.
+ pub mirror_margins: bool,
+ /// Word compatibility mode (11 = 2003, 12 = 2007, 14 = 2010, 15 = 2013+).
+ pub compat_mode: u32,
+ /// Lines ending in a manual break in justified paragraphs are not stretched.
+ pub do_not_expand_shift_return: bool,
+ /// Space before is dropped after a manual page or column break.
+ pub suppress_sp_bf_after_pg_brk: bool,
+ /// Automatic hyphenation.
+ pub auto_hyphenation: bool,
+ /// Footnote numbering.
+ pub footnotes: NoteSettings,
+ /// Endnote numbering.
+ pub endnotes: NoteSettings,
+ /// Changes are being tracked.
+ pub track_revisions: bool,
+ /// Grow autospacing like HTML (`doNotUseHTMLParagraphAutoSpacing` off).
+ pub html_auto_spacing: bool,
+ /// The paragraph mark after a page break goes to the next page with the
+ /// text after the break (`splitPgBreakAndParaMark`); otherwise it stays
+ /// with the break.
+ pub split_page_break_and_mark: bool,
+ /// The first line on a page drops the extra room its at-least line
+ /// spacing gives it (`suppressTopSpacing`).
+ pub suppress_top_spacing: bool,
+}
+
+impl Default for Settings {
+ fn default() -> Self {
+ Self {
+ default_tab: 36.0,
+ even_and_odd_headers: false,
+ mirror_margins: false,
+ compat_mode: 12,
+ do_not_expand_shift_return: false,
+ suppress_sp_bf_after_pg_brk: false,
+ auto_hyphenation: false,
+ footnotes: NoteSettings {
+ fmt: NumFmt::Decimal,
+ start: 1,
+ restart: NoteRestart::Continuous,
+ },
+ endnotes: NoteSettings {
+ fmt: NumFmt::LowerRoman,
+ start: 1,
+ restart: NoteRestart::Continuous,
+ },
+ track_revisions: false,
+ html_auto_spacing: true,
+ split_page_break_and_mark: false,
+ suppress_top_spacing: false,
+ }
+ }
+}
+
+fn read_notes(t: &XmlTree, n: crate::xml::NodeId, into: &mut NoteSettings) {
+ for c in t.children(n) {
+ match t.local(c) {
+ "numFmt" => into.fmt = NumFmt::parse(t.val(c).unwrap_or("decimal"), None),
+ "numStart" => into.start = t.val(c).and_then(parse_int).unwrap_or(1),
+ "numRestart" => {
+ into.restart = match t.val(c) {
+ Some("eachSect") => NoteRestart::EachSection,
+ Some("eachPage") => NoteRestart::EachPage,
+ _ => NoteRestart::Continuous,
+ }
+ }
+ _ => {}
+ }
+ }
+}
+
+impl Settings {
+ /// Parses `settings.xml`.
+ pub fn parse(t: &XmlTree) -> Self {
+ let mut s = Settings::default();
+ let root = t.root();
+ for c in t.children(root) {
+ if t.ns(c) != Ns::W {
+ continue;
+ }
+ match t.local(c) {
+ "defaultTabStop" => {
+ if let Some(v) = t.val(c).and_then(parse_int).filter(|v| *v > 0) {
+ s.default_tab = twips(v);
+ }
+ }
+ "evenAndOddHeaders" => s.even_and_odd_headers = parse_on_off(t.val(c)),
+ "mirrorMargins" => s.mirror_margins = parse_on_off(t.val(c)),
+ "autoHyphenation" => s.auto_hyphenation = parse_on_off(t.val(c)),
+ "trackRevisions" => s.track_revisions = parse_on_off(t.val(c)),
+ "footnotePr" => read_notes(t, c, &mut s.footnotes),
+ "endnotePr" => read_notes(t, c, &mut s.endnotes),
+ "compat" => {
+ for k in t.children(c) {
+ match t.local(k) {
+ "compatSetting" => {
+ if t.w_attr(k, "name") == Some("compatibilityMode") {
+ s.compat_mode = t
+ .w_attr(k, "val")
+ .and_then(parse_int)
+ .map_or(12, |v| v.clamp(11, 99) as u32);
+ }
+ }
+ "doNotExpandShiftReturn" => {
+ s.do_not_expand_shift_return = parse_on_off(t.val(k));
+ }
+ "suppressSpBfAfterPgBrk" => {
+ s.suppress_sp_bf_after_pg_brk = parse_on_off(t.val(k));
+ }
+ "doNotUseHTMLParagraphAutoSpacing" => {
+ s.html_auto_spacing = !parse_on_off(t.val(k));
+ }
+ "splitPgBreakAndParaMark" => {
+ s.split_page_break_and_mark = parse_on_off(t.val(k));
+ }
+ "suppressTopSpacing" => {
+ s.suppress_top_spacing = parse_on_off(t.val(k));
+ }
+ _ => {}
+ }
+ }
+ }
+ _ => {}
+ }
+ }
+ s
+ }
+}
diff --git a/crates/docx_engine/src/model/styles.rs b/crates/docx_engine/src/model/styles.rs
new file mode 100644
index 0000000000..f2bc4775ae
--- /dev/null
+++ b/crates/docx_engine/src/model/styles.rs
@@ -0,0 +1,407 @@
+//! The style sheet (`word/styles.xml`) and property resolution.
+//!
+//! Formatting is resolved the way Word layers it: document defaults, then
+//! the table style (with the conditional formats that apply to the cell),
+//! then the paragraph style, numbering, the character style, and finally
+//! direct formatting. Within one style's `basedOn` chain later levels
+//! simply win; between style levels the toggle properties (bold, italic,
+//! caps...) flip, so a bold character style in a bold heading reads normal.
+
+use super::props::{PPr, RPr, TblPr, TcPr, TrPr};
+use crate::model::props::ThemeInfo;
+use crate::xml::{NodeId, Ns, XmlTree, parse_on_off};
+use std::collections::HashMap;
+
+/// What a style applies to.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StyleKind {
+ /// Paragraph style.
+ Paragraph,
+ /// Character style.
+ Character,
+ /// Table style.
+ Table,
+ /// Numbering style.
+ Numbering,
+}
+
+/// Formatting of one table-style condition (`w:tblStylePr`).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct CondFormat {
+ /// Paragraph properties.
+ pub ppr: PPr,
+ /// Run properties.
+ pub rpr: RPr,
+ /// Table properties.
+ pub tbl: TblPr,
+ /// Row properties.
+ pub tr: TrPr,
+ /// Cell properties.
+ pub tc: TcPr,
+}
+
+impl CondFormat {
+ fn apply(&mut self, o: &CondFormat) {
+ self.ppr.apply(&o.ppr);
+ self.rpr.inherit(&o.rpr);
+ self.tbl.apply(&o.tbl);
+ self.tr.apply(&o.tr);
+ self.tc.apply(&o.tc);
+ }
+}
+
+/// One style definition, with its `basedOn` chain already merged in.
+#[derive(Clone, Debug)]
+pub struct Style {
+ /// Style id.
+ pub id: String,
+ /// Display name.
+ pub name: String,
+ /// Kind.
+ pub kind: StyleKind,
+ /// Parent style.
+ pub based_on: Option<String>,
+ /// Style for the next paragraph.
+ pub next: Option<String>,
+ /// The default style of its kind.
+ pub is_default: bool,
+ /// Hidden from the user interface.
+ pub hidden: bool,
+ /// Shown in the quick style gallery.
+ pub q_format: bool,
+ /// Sort priority in the user interface.
+ pub ui_priority: Option<i64>,
+ /// Paragraph properties (merged chain).
+ pub ppr: PPr,
+ /// Run properties (merged chain).
+ pub rpr: RPr,
+ /// Table properties (merged chain).
+ pub tbl: TblPr,
+ /// Row properties (merged chain).
+ pub tr: TrPr,
+ /// Cell properties (merged chain).
+ pub tc: TcPr,
+ /// Conditional formats by type (merged chain).
+ pub cond: Vec<(String, CondFormat)>,
+}
+
+/// The parsed style sheet.
+#[derive(Clone, Debug, Default)]
+pub struct Styles {
+ /// Document default run properties.
+ pub doc_rpr: RPr,
+ /// Document default paragraph properties.
+ pub doc_ppr: PPr,
+ styles: HashMap<String, Style>,
+ /// Lower-cased name → id.
+ by_name: HashMap<String, String>,
+ default_paragraph: Option<String>,
+ default_character: Option<String>,
+ default_table: Option<String>,
+}
+
+struct RawStyle {
+ id: String,
+ name: String,
+ kind: StyleKind,
+ based_on: Option<String>,
+ next: Option<String>,
+ is_default: bool,
+ hidden: bool,
+ q_format: bool,
+ ui_priority: Option<i64>,
+ ppr: PPr,
+ rpr: RPr,
+ tbl: TblPr,
+ tr: TrPr,
+ tc: TcPr,
+ cond: Vec<(String, CondFormat)>,
+}
+
+fn read_cond(t: &XmlTree, n: NodeId, theme: &ThemeInfo) -> CondFormat {
+ let mut c = CondFormat::default();
+ for k in t.children(n) {
+ match t.local(k) {
+ "pPr" => c.ppr = PPr::read(t, k, theme),
+ "rPr" => c.rpr = RPr::read(t, k, theme),
+ "tblPr" => c.tbl = TblPr::read(t, k, theme),
+ "trPr" => c.tr = TrPr::read(t, k),
+ "tcPr" => c.tc = TcPr::read(t, k, theme),
+ _ => {}
+ }
+ }
+ c
+}
+
+impl Styles {
+ /// Parses `styles.xml`.
+ pub fn parse(t: &XmlTree, theme: &ThemeInfo) -> Self {
+ let root = t.root();
+ let mut s = Styles::default();
+ if let Some(dd) = t.w_child(root, "docDefaults") {
+ if let Some(rpr) = t
+ .w_child(dd, "rPrDefault")
+ .and_then(|r| t.w_child(r, "rPr"))
+ {
+ s.doc_rpr = RPr::read(t, rpr, theme);
+ }
+ if let Some(ppr) = t
+ .w_child(dd, "pPrDefault")
+ .and_then(|r| t.w_child(r, "pPr"))
+ {
+ s.doc_ppr = PPr::read(t, ppr, theme);
+ }
+ }
+ let mut raw: HashMap<String, RawStyle> = HashMap::new();
+ for n in t.children_named(root, Ns::W, "style") {
+ let Some(id) = t.w_attr(n, "styleId") else {
+ continue;
+ };
+ let kind = match t.w_attr(n, "type").unwrap_or("paragraph") {
+ "character" => StyleKind::Character,
+ "table" => StyleKind::Table,
+ "numbering" => StyleKind::Numbering,
+ _ => StyleKind::Paragraph,
+ };
+ let mut r = RawStyle {
+ id: id.to_owned(),
+ name: t.child_val(n, "name").unwrap_or(id).to_owned(),
+ kind,
+ based_on: t.child_val(n, "basedOn").map(str::to_owned),
+ next: t.child_val(n, "next").map(str::to_owned),
+ is_default: t
+ .w_attr(n, "default")
+ .is_some_and(|v| parse_on_off(Some(v))),
+ hidden: t.w_child(n, "hidden").is_some()
+ || t.w_child(n, "semiHidden")
+ .is_some_and(|h| parse_on_off(t.val(h))),
+ q_format: t.w_child(n, "qFormat").is_some(),
+ ui_priority: t.child_val(n, "uiPriority").and_then(crate::xml::parse_int),
+ ppr: PPr::default(),
+ rpr: RPr::default(),
+ tbl: TblPr::default(),
+ tr: TrPr::default(),
+ tc: TcPr::default(),
+ cond: Vec::new(),
+ };
+ for c in t.children(n) {
+ match t.local(c) {
+ "pPr" => r.ppr = PPr::read(t, c, theme),
+ "rPr" => r.rpr = RPr::read(t, c, theme),
+ "tblPr" => r.tbl = TblPr::read(t, c, theme),
+ "trPr" => r.tr = TrPr::read(t, c),
+ "tcPr" => r.tc = TcPr::read(t, c, theme),
+ "tblStylePr" => {
+ if let Some(ty) = t.w_attr(c, "type") {
+ r.cond.push((ty.to_owned(), read_cond(t, c, theme)));
+ }
+ }
+ _ => {}
+ }
+ }
+ if r.is_default {
+ match kind {
+ StyleKind::Paragraph => s.default_paragraph = Some(id.to_owned()),
+ StyleKind::Character => s.default_character = Some(id.to_owned()),
+ StyleKind::Table => s.default_table = Some(id.to_owned()),
+ StyleKind::Numbering => {}
+ }
+ }
+ raw.insert(id.to_owned(), r);
+ }
+ // Merge each style's basedOn chain (root first), guarding cycles.
+ let ids: Vec<String> = raw.keys().cloned().collect();
+ for id in ids {
+ let mut chain: Vec<&RawStyle> = Vec::new();
+ let mut at = raw.get(&id);
+ while let Some(r) = at {
+ if chain.iter().any(|c| c.id == r.id) || chain.len() > 32 {
+ break;
+ }
+ chain.push(r);
+ at = r.based_on.as_ref().and_then(|b| raw.get(b));
+ }
+ chain.reverse();
+ let Some(own) = chain.last() else {
+ continue;
+ };
+ let mut style = Style {
+ id: own.id.clone(),
+ name: own.name.clone(),
+ kind: own.kind,
+ based_on: own.based_on.clone(),
+ next: own.next.clone(),
+ is_default: own.is_default,
+ hidden: own.hidden,
+ q_format: own.q_format,
+ ui_priority: own.ui_priority,
+ ppr: PPr::default(),
+ rpr: RPr::default(),
+ tbl: TblPr::default(),
+ tr: TrPr::default(),
+ tc: TcPr::default(),
+ cond: Vec::new(),
+ };
+ for level in &chain {
+ // Styles of another kind in the chain are ignored, as Word does.
+ if level.kind != own.kind {
+ continue;
+ }
+ style.ppr.apply(&level.ppr);
+ style.rpr.inherit(&level.rpr);
+ style.tbl.apply(&level.tbl);
+ style.tr.apply(&level.tr);
+ style.tc.apply(&level.tc);
+ for (ty, c) in &level.cond {
+ match style.cond.iter_mut().find(|(t, _)| t == ty) {
+ Some((_, existing)) => existing.apply(c),
+ None => style.cond.push((ty.clone(), c.clone())),
+ }
+ }
+ }
+ // A style's own pStyle reference is meaningless for resolution.
+ style.ppr.style = None;
+ style.rpr.style = None;
+ s.by_name
+ .insert(style.name.to_lowercase(), style.id.clone());
+ s.styles.insert(style.id.clone(), style);
+ }
+ s
+ }
+
+ /// A style by id.
+ pub fn get(&self, id: &str) -> Option<&Style> {
+ self.styles.get(id)
+ }
+
+ /// A style id by display name (case-insensitive).
+ pub fn id_by_name(&self, name: &str) -> Option<&str> {
+ self.by_name.get(&name.to_lowercase()).map(String::as_str)
+ }
+
+ /// Every style.
+ pub fn all(&self) -> impl Iterator<Item = &Style> {
+ self.styles.values()
+ }
+
+ /// The paragraph style a paragraph uses (its own, or the default).
+ pub fn paragraph_style(&self, id: Option<&str>) -> Option<&Style> {
+ id.and_then(|i| self.styles.get(i))
+ .filter(|s| s.kind == StyleKind::Paragraph)
+ .or_else(|| {
+ self.default_paragraph
+ .as_ref()
+ .and_then(|d| self.styles.get(d))
+ })
+ }
+
+ /// The table style a table uses (its own, or the default).
+ pub fn table_style(&self, id: Option<&str>) -> Option<&Style> {
+ id.and_then(|i| self.styles.get(i))
+ .filter(|s| s.kind == StyleKind::Table)
+ .or_else(|| self.default_table.as_ref().and_then(|d| self.styles.get(d)))
+ }
+
+ /// A character style.
+ pub fn character_style(&self, id: Option<&str>) -> Option<&Style> {
+ id.and_then(|i| self.styles.get(i))
+ .filter(|s| s.kind == StyleKind::Character)
+ .or_else(|| {
+ self.default_character
+ .as_ref()
+ .and_then(|d| self.styles.get(d))
+ })
+ }
+
+ /// The default paragraph style id.
+ pub fn default_paragraph_id(&self) -> Option<&str> {
+ self.default_paragraph.as_deref()
+ }
+}
+
+/// Where a cell sits in its table, as table-style conditions see it.
+#[derive(Clone, Copy, Debug)]
+pub struct CellPlace {
+ /// The cell's row.
+ pub row: usize,
+ /// The table's row count.
+ pub rows: usize,
+ /// The cell's place in its row.
+ pub col: usize,
+ /// The row's cell count.
+ pub cols: usize,
+ /// The table's leading header rows.
+ pub header_rows: usize,
+ /// Rows per horizontal band.
+ pub row_band: usize,
+ /// Columns per vertical band.
+ pub col_band: usize,
+}
+
+/// Which table-style conditions apply to a cell, in Word's precedence order
+/// (later entries override earlier ones).
+pub fn cell_conditions(look: &super::props::TableLook, at: CellPlace) -> Vec<&'static str> {
+ let CellPlace {
+ row,
+ rows,
+ col,
+ cols,
+ header_rows,
+ row_band,
+ col_band,
+ } = at;
+ let mut out = vec!["wholeTable"];
+ let first_row = look.first_row && row < header_rows.max(1);
+ let last_row = look.last_row && row + 1 == rows;
+ let first_col = look.first_col && col == 0;
+ let last_col = look.last_col && col + 1 == cols;
+ if look.v_band && !first_col && !last_col {
+ let c = col - usize::from(look.first_col);
+ out.push(if (c / col_band.max(1)).is_multiple_of(2) {
+ "band1Vert"
+ } else {
+ "band2Vert"
+ });
+ }
+ if look.h_band && !first_row && !last_row {
+ let skipped = if look.first_row {
+ header_rows.max(1)
+ } else {
+ 0
+ };
+ let r = row.saturating_sub(skipped);
+ out.push(if (r / row_band.max(1)).is_multiple_of(2) {
+ "band1Horz"
+ } else {
+ "band2Horz"
+ });
+ }
+ if first_col {
+ out.push("firstCol");
+ }
+ if last_col {
+ out.push("lastCol");
+ }
+ if first_row {
+ out.push("firstRow");
+ }
+ if last_row {
+ out.push("lastRow");
+ }
+ if first_row && first_col {
+ out.push("nwCell");
+ }
+ if first_row && last_col {
+ out.push("neCell");
+ }
+ if last_row && first_col {
+ out.push("swCell");
+ }
+ if last_row && last_col {
+ out.push("seCell");
+ }
+ out
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/model/styles/test.rs b/crates/docx_engine/src/model/styles/test.rs
new file mode 100644
index 0000000000..afa23a0867
--- /dev/null
+++ b/crates/docx_engine/src/model/styles/test.rs
@@ -0,0 +1,64 @@
+use super::*;
+
+const XML: &str = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+ <w:docDefaults><w:rPrDefault><w:rPr><w:sz w:val="22"/></w:rPr></w:rPrDefault>
+ <w:pPrDefault><w:pPr><w:spacing w:after="200"/></w:pPr></w:pPrDefault></w:docDefaults>
+ <w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>
+ <w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/><w:basedOn w:val="Normal"/>
+ <w:pPr><w:keepNext/><w:spacing w:before="480"/></w:pPr><w:rPr><w:b/><w:sz w:val="28"/></w:rPr></w:style>
+ <w:style w:type="paragraph" w:styleId="Heading2"><w:name w:val="heading 2"/><w:basedOn w:val="Heading1"/>
+ <w:rPr><w:sz w:val="26"/></w:rPr></w:style>
+ <w:style w:type="character" w:styleId="Strong"><w:name w:val="Strong"/><w:rPr><w:b/></w:rPr></w:style>
+</w:styles>"#;
+
+#[test]
+fn merges_based_on_chains() {
+ let t = XmlTree::parse(XML.as_bytes(), "s").unwrap();
+ let s = Styles::parse(&t, &ThemeInfo::default());
+ let h2 = s.get("Heading2").unwrap();
+ assert_eq!(h2.rpr.size, Some(13.0));
+ assert_eq!(h2.rpr.bold, Some(true));
+ assert_eq!(h2.ppr.keep_next, Some(true));
+ assert_eq!(h2.ppr.before, Some(24.0));
+ assert_eq!(s.paragraph_style(None).unwrap().id, "Normal");
+ assert_eq!(s.id_by_name("Heading 1"), Some("Heading1"));
+}
+
+#[test]
+fn toggles_between_style_levels() {
+ let t = XmlTree::parse(XML.as_bytes(), "s").unwrap();
+ let s = Styles::parse(&t, &ThemeInfo::default());
+ let mut r = s.doc_rpr.clone();
+ r.apply(&s.get("Heading1").unwrap().rpr, true);
+ assert_eq!(r.bold, Some(true));
+ // A bold character style in a bold paragraph style reads normal.
+ r.apply(&s.get("Strong").unwrap().rpr, true);
+ assert_eq!(r.bold, Some(false));
+ // Direct formatting is absolute.
+ let direct = RPr {
+ bold: Some(true),
+ ..RPr::default()
+ };
+ r.apply(&direct, false);
+ assert_eq!(r.bold, Some(true));
+}
+
+#[test]
+fn table_conditions_follow_look() {
+ let look = crate::model::props::TableLook::default();
+ let at = |row, col| CellPlace {
+ row,
+ rows: 3,
+ col,
+ cols: 2,
+ header_rows: 1,
+ row_band: 1,
+ col_band: 1,
+ };
+ let c = cell_conditions(&look, at(0, 0));
+ assert!(c.contains(&"firstRow") && c.contains(&"firstCol") && c.contains(&"nwCell"));
+ let c = cell_conditions(&look, at(1, 1));
+ assert!(c.contains(&"band1Horz"));
+ let c = cell_conditions(&look, at(2, 1));
+ assert!(c.contains(&"band2Horz"));
+}
diff --git a/crates/docx_engine/src/model/write.rs b/crates/docx_engine/src/model/write.rs
new file mode 100644
index 0000000000..17fa35cd73
--- /dev/null
+++ b/crates/docx_engine/src/model/write.rs
@@ -0,0 +1,320 @@
+//! Writes blocks back to WordprocessingML.
+
+use super::block::{Block, BlockId, BlockKind, Story};
+use super::content::{Content, Span, Wrapper, key};
+use crate::xml::{escape_attr, escape_text};
+
+/// Schema order of run property elements (CT_RPr); unknown elements follow,
+/// and `rPrChange` always comes last.
+const RPR_ORDER: &[&str] = &[
+ "rStyle",
+ "rFonts",
+ "b",
+ "bCs",
+ "i",
+ "iCs",
+ "caps",
+ "smallCaps",
+ "strike",
+ "dstrike",
+ "outline",
+ "shadow",
+ "emboss",
+ "imprint",
+ "noProof",
+ "snapToGrid",
+ "vanish",
+ "webHidden",
+ "color",
+ "spacing",
+ "w",
+ "kern",
+ "position",
+ "sz",
+ "szCs",
+ "highlight",
+ "u",
+ "effect",
+ "bdr",
+ "shd",
+ "fitText",
+ "vertAlign",
+ "rtl",
+ "cs",
+ "em",
+ "lang",
+ "eastAsianLayout",
+ "specVanish",
+ "oMath",
+];
+
+fn rpr_rank(qname: &str) -> usize {
+ let (prefix, local) = qname.split_once(':').unwrap_or(("", qname));
+ if local == "rPrChange" {
+ return usize::MAX;
+ }
+ // Extension elements (w14:, w15:...) follow the base properties.
+ let base = prefix.is_empty() || !prefix.starts_with('w') || prefix.len() == 1;
+ match RPR_ORDER.iter().position(|n| *n == local) {
+ Some(i) if base => i,
+ _ => RPR_ORDER.len() + 1,
+ }
+}
+
+/// The `rPr` of a run's formatting attributes, in schema order, without
+/// its tracked formatting change.
+pub(crate) fn rpr_xml(attrs: &crate::model::content::Attrs, w: &str) -> String {
+ let mut props: Vec<(&str, &str)> = attrs
+ .run_props()
+ .filter(|(q, _)| !q.ends_with("rPrChange"))
+ .collect();
+ props.sort_by_key(|(q, _)| rpr_rank(q));
+ let tag = if w.is_empty() {
+ "rPr".to_owned()
+ } else {
+ format!("{w}:rPr")
+ };
+ let mut out = format!("<{tag}>");
+ for (_, xml) in props {
+ out.push_str(xml);
+ }
+ out.push_str(&format!("</{tag}>"));
+ out
+}
+
+/// Serializes stories with the document's WordprocessingML prefix.
+pub struct Writer<'a> {
+ /// Prefix bound to the WordprocessingML namespace (`w` in practice).
+ pub w: &'a str,
+}
+
+impl Writer<'_> {
+ fn tag(&self, local: &str) -> String {
+ if self.w.is_empty() {
+ local.to_owned()
+ } else {
+ format!("{}:{local}", self.w)
+ }
+ }
+
+ /// The top-level blocks of a story, concatenated.
+ pub fn story(&self, story: &Story) -> String {
+ let mut out = String::new();
+ for id in story.children(None) {
+ self.block(story, id, &mut out);
+ }
+ out
+ }
+
+ /// One block and its descendants.
+ pub fn block(&self, story: &Story, id: &BlockId, out: &mut String) {
+ let Some(b) = story.get(id) else {
+ return;
+ };
+ match b.kind {
+ BlockKind::Paragraph => self.paragraph(b, out),
+ BlockKind::Table => self.element(story, b, "tbl", out),
+ BlockKind::Row => self.element(story, b, "tr", out),
+ BlockKind::Cell => {
+ let tag = self.tag("tc");
+ out.push('<');
+ out.push_str(&tag);
+ out.push_str(&b.attrs);
+ out.push('>');
+ out.push_str(&b.props);
+ let kids = story.children(Some(id));
+ for k in kids {
+ self.block(story, k, out);
+ }
+ let ends_with_paragraph = kids
+ .last()
+ .and_then(|k| story.get(k))
+ .is_some_and(|k| k.kind == BlockKind::Paragraph);
+ if !ends_with_paragraph {
+ out.push('<');
+ out.push_str(&self.tag("p"));
+ out.push_str("/>");
+ }
+ out.push_str("</");
+ out.push_str(&tag);
+ out.push('>');
+ }
+ BlockKind::Container => {
+ let (open, close) = b.container_markup();
+ out.push_str(&open);
+ for k in story.children(Some(id)) {
+ self.block(story, k, out);
+ }
+ out.push_str(&close);
+ }
+ BlockKind::Opaque => out.push_str(&b.props),
+ }
+ }
+
+ fn element(&self, story: &Story, b: &Block, local: &str, out: &mut String) {
+ let tag = self.tag(local);
+ out.push('<');
+ out.push_str(&tag);
+ out.push_str(&b.attrs);
+ out.push('>');
+ out.push_str(&b.props);
+ for k in story.children(Some(&b.id)) {
+ self.block(story, k, out);
+ }
+ out.push_str("</");
+ out.push_str(&tag);
+ out.push('>');
+ }
+
+ /// A paragraph.
+ pub fn paragraph(&self, b: &Block, out: &mut String) {
+ let tag = self.tag("p");
+ out.push('<');
+ out.push_str(&tag);
+ out.push_str(&b.attrs);
+ if b.props.is_empty() && b.content.is_empty() {
+ out.push_str("/>");
+ return;
+ }
+ out.push('>');
+ out.push_str(&b.props);
+ self.content(&b.content, out);
+ out.push_str("</");
+ out.push_str(&tag);
+ out.push('>');
+ }
+
+ /// Paragraph content: runs inside their wrappers.
+ pub fn content(&self, content: &Content, out: &mut String) {
+ let mut open: Vec<Wrapper> = Vec::new();
+ for span in content.spans() {
+ let wrappers = span.attrs.wrappers();
+ let common = open
+ .iter()
+ .zip(&wrappers)
+ .take_while(|(a, b)| a == b)
+ .count();
+ while open.len() > common {
+ if let Some(w) = open.pop() {
+ out.push_str(&w.close);
+ }
+ }
+ for w in &wrappers[common..] {
+ out.push_str(&w.open);
+ open.push(w.clone());
+ }
+ let deleted = wrappers
+ .iter()
+ .any(|w| matches!(w.local(), "del" | "moveFrom"));
+ self.span(span, deleted, out);
+ }
+ while let Some(w) = open.pop() {
+ out.push_str(&w.close);
+ }
+ }
+
+ fn run_open(&self, span: &Span, out: &mut String) {
+ out.push('<');
+ out.push_str(&self.tag("r"));
+ for (k, v) in span.attrs.iter() {
+ if let Some(name) = k.strip_prefix(key::RUN_ATTR) {
+ out.push(' ');
+ out.push_str(name);
+ out.push_str("=\"");
+ escape_attr(out, v);
+ out.push('"');
+ }
+ }
+ out.push('>');
+ let mut props: Vec<(&str, &str)> = span.attrs.run_props().collect();
+ if !props.is_empty() {
+ props.sort_by_key(|(q, _)| rpr_rank(q));
+ out.push('<');
+ out.push_str(&self.tag("rPr"));
+ out.push('>');
+ for (_, xml) in props {
+ out.push_str(xml);
+ }
+ out.push_str("</");
+ out.push_str(&self.tag("rPr"));
+ out.push('>');
+ }
+ }
+
+ fn run_close(&self, out: &mut String) {
+ out.push_str("</");
+ out.push_str(&self.tag("r"));
+ out.push('>');
+ }
+
+ fn span(&self, span: &Span, deleted: bool, out: &mut String) {
+ if let Some(mark) = span.attrs.marker() {
+ for _ in span.text.chars() {
+ out.push_str(mark);
+ }
+ return;
+ }
+ self.run_open(span, out);
+ if let Some(obj) = span.attrs.object() {
+ for _ in span.text.chars() {
+ out.push_str(obj);
+ }
+ self.run_close(out);
+ return;
+ }
+ let text_tag = match (span.attrs.is_instr(), deleted) {
+ (false, false) => "t",
+ (false, true) => "delText",
+ (true, false) => "instrText",
+ (true, true) => "delInstrText",
+ };
+ let mut buf = String::new();
+ let flush = |buf: &mut String, out: &mut String| {
+ if buf.is_empty() {
+ return;
+ }
+ let tag = self.tag(text_tag);
+ out.push('<');
+ out.push_str(&tag);
+ if buf.starts_with(char::is_whitespace) || buf.ends_with(char::is_whitespace) {
+ out.push_str(" xml:space=\"preserve\"");
+ }
+ out.push('>');
+ escape_text(out, buf);
+ out.push_str("</");
+ out.push_str(&tag);
+ out.push('>');
+ buf.clear();
+ };
+ for c in span.text.chars() {
+ let element = match c {
+ '\t' => Some("tab"),
+ '\n' => Some("br"),
+ '\u{2011}' => Some("noBreakHyphen"),
+ '\u{00AD}' => Some("softHyphen"),
+ _ => None,
+ };
+ match element {
+ Some(local) => {
+ flush(&mut buf, out);
+ out.push('<');
+ out.push_str(&self.tag(local));
+ out.push_str("/>");
+ }
+ None => buf.push(c),
+ }
+ }
+ flush(&mut buf, out);
+ self.run_close(out);
+ }
+}
+
+/// Escapes text for element content (re-exported for callers building XML).
+pub fn text_xml(s: &str) -> String {
+ let mut out = String::with_capacity(s.len());
+ escape_text(&mut out, s);
+ out
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/model/write/test.rs b/crates/docx_engine/src/model/write/test.rs
new file mode 100644
index 0000000000..49d7b96380
--- /dev/null
+++ b/crates/docx_engine/src/model/write/test.rs
@@ -0,0 +1,28 @@
+use super::*;
+
+#[test]
+fn run_properties_sort_in_schema_order() {
+ let mut order: Vec<&str> = vec![
+ "w:rPrChange",
+ "w14:ligatures",
+ "w:sz",
+ "w:rFonts",
+ "w:rStyle",
+ ];
+ order.sort_by_key(|q| rpr_rank(q));
+ assert_eq!(
+ order,
+ vec![
+ "w:rStyle",
+ "w:rFonts",
+ "w:sz",
+ "w14:ligatures",
+ "w:rPrChange"
+ ]
+ );
+}
+
+#[test]
+fn escapes_text() {
+ assert_eq!(text_xml("a<b&c"), "a&lt;b&amp;c");
+}
diff --git a/crates/docx_engine/src/render.rs b/crates/docx_engine/src/render.rs
new file mode 100644
index 0000000000..f0a7ce8313
--- /dev/null
+++ b/crates/docx_engine/src/render.rs
@@ -0,0 +1,327 @@
+//! Drawing pages: display lists and rasterization.
+//!
+//! A page becomes the shared display list (`pptx_engine::render::scene`):
+//! text as glyph outlines (one path per run of same-colored glyphs),
+//! decorations as rectangles and strokes, pictures as image paints. The same
+//! list rasterizes natively (tests, the corpus tool) and in the browser.
+
+mod drawing;
+mod shapes;
+mod text;
+
+use crate::document::Document;
+use crate::layout::inline::Revision;
+use crate::layout::{Item, Layout, Page, PlacedLine};
+use crate::model::props::{Border, LineStyle};
+use pptx_engine::font::FontDb;
+use pptx_engine::model::color::Rgba;
+use pptx_engine::path::{Path, Point, Rect};
+use pptx_engine::render::raster;
+use pptx_engine::render::scene::{Group, LineCap, LineJoin, Node, Paint, Raster, Stroke};
+use std::collections::HashMap;
+use std::sync::Arc;
+
+/// Decoded pictures by part name (`None` = not decodable).
+#[derive(Default)]
+pub struct ImageCache {
+ images: HashMap<String, Option<Arc<Raster>>>,
+ metafiles: HashMap<String, Option<Arc<pptx_engine::render::metafile::Metafile>>>,
+}
+
+impl ImageCache {
+ /// An empty cache.
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// A decoded raster picture.
+ pub fn raster(&mut self, doc: &Document, part: &str, fonts: &FontDb) -> Option<Arc<Raster>> {
+ if let Some(r) = self.images.get(part) {
+ return r.clone();
+ }
+ let decoded = doc.package().read(part).ok().and_then(|bytes| {
+ use pptx_engine::render::image::{Format, decode_raster, sniff};
+ match sniff(&bytes) {
+ Format::Emf | Format::Wmf => pptx_engine::render::metafile::parse(&bytes, fonts)
+ .ok()
+ .map(|m| Arc::new(metafile_raster(&m))),
+ _ => decode_raster(&bytes).ok().map(Arc::new),
+ }
+ });
+ self.images.insert(part.to_owned(), decoded.clone());
+ decoded
+ }
+
+ /// A parsed metafile picture (drawn as vectors).
+ pub fn metafile(
+ &mut self,
+ doc: &Document,
+ part: &str,
+ fonts: &FontDb,
+ ) -> Option<Arc<pptx_engine::render::metafile::Metafile>> {
+ if let Some(m) = self.metafiles.get(part) {
+ return m.clone();
+ }
+ let parsed = doc.package().read(part).ok().and_then(|bytes| {
+ use pptx_engine::render::image::{Format, sniff};
+ match sniff(&bytes) {
+ Format::Emf | Format::Wmf => pptx_engine::render::metafile::parse(&bytes, fonts)
+ .ok()
+ .map(Arc::new),
+ _ => None,
+ }
+ });
+ self.metafiles.insert(part.to_owned(), parsed.clone());
+ parsed
+ }
+}
+
+fn metafile_raster(m: &pptx_engine::render::metafile::Metafile) -> Raster {
+ let scale = (150.0 / 72.0f32).min(2048.0 / m.width_pt.max(m.height_pt).max(1.0));
+ let w = ((m.width_pt * scale).ceil() as u32).max(1);
+ let h = ((m.height_pt * scale).ceil() as u32).max(1);
+ raster::rasterize(&m.nodes, w, h, scale)
+}
+
+/// Renders pages of one layout.
+pub struct Renderer<'a> {
+ /// The document.
+ pub doc: &'a Document,
+ /// Fonts.
+ pub fonts: &'a FontDb,
+ /// Picture cache.
+ pub images: &'a mut ImageCache,
+}
+
+/// The stroke for a border.
+pub(crate) fn border_stroke(b: &Border) -> Stroke {
+ let dash = match b.style {
+ LineStyle::Dotted => Some(vec![b.width, b.width * 2.0]),
+ LineStyle::Dashed => Some(vec![b.width * 4.0, b.width * 3.0]),
+ LineStyle::DotDash => Some(vec![b.width * 4.0, b.width * 2.0, b.width, b.width * 2.0]),
+ _ => None,
+ };
+ Stroke {
+ width: b.width.max(0.25),
+ cap: LineCap::Butt,
+ join: LineJoin::Miter,
+ miter_limit: 4.0,
+ dash,
+ }
+}
+
+fn border_color(b: &Border) -> Rgba {
+ b.color.rgb().unwrap_or(Rgba::BLACK)
+}
+
+/// Strokes a border line from (x0, y0) to (x1, y1), drawing double and
+/// triple styles as parallel lines.
+pub(crate) fn rule_nodes(x0: f32, y0: f32, x1: f32, y1: f32, b: &Border, out: &mut Vec<Node>) {
+ let color = border_color(b);
+ let lines: Vec<(f32, f32)> = match b.style {
+ LineStyle::Double => vec![(-b.width, b.width * 0.8), (b.width, b.width * 0.8)],
+ LineStyle::Triple => vec![
+ (-2.0 * b.width, b.width * 0.7),
+ (0.0, b.width * 0.7),
+ (2.0 * b.width, b.width * 0.7),
+ ],
+ LineStyle::ThinThick => vec![(-b.width * 0.75, b.width * 0.5), (b.width * 0.5, b.width)],
+ LineStyle::Thick => vec![(0.0, b.width * 1.5)],
+ _ => vec![(0.0, b.width)],
+ };
+ let (dx, dy) = (x1 - x0, y1 - y0);
+ let len = (dx * dx + dy * dy).sqrt().max(1e-6);
+ let (nx, ny) = (-dy / len, dx / len);
+ for (off, w) in lines {
+ let mut p = Path::new();
+ p.move_to(Point::new(x0 + nx * off, y0 + ny * off));
+ p.line_to(Point::new(x1 + nx * off, y1 + ny * off));
+ let mut stroke = border_stroke(b);
+ stroke.width = w.max(0.25);
+ out.push(Node::Stroke {
+ path: p,
+ paint: Paint::Solid(color),
+ stroke,
+ });
+ }
+}
+
+/// Gap between a change bar and the body's left edge (points).
+const CHANGE_BAR_GAP: f32 = 7.0;
+/// Width of a change bar (points).
+const CHANGE_BAR_WIDTH: f32 = 0.75;
+
+/// Whether a placed line holds a tracked change shown with markup.
+fn line_changed(l: &PlacedLine) -> bool {
+ let inline = &l.para.inline;
+ let line = l.line();
+ let last = l.line + 1 == l.para.lines.lines.len();
+ inline.props_changed
+ || (last && inline.mark_changed)
+ || inline.clusters[line.start..line.end]
+ .iter()
+ .any(|c| inline.runs[c.run as usize].revision != Revision::None)
+}
+
+/// Change bars: a rule in the left margin beside every line holding a
+/// tracked change, as Word and LibreOffice draw them with markup.
+fn change_bars(page: &Page, out: &mut Vec<Node>) {
+ let x = page.body.x - CHANGE_BAR_GAP - CHANGE_BAR_WIDTH / 2.0;
+ let mut path = Path::new();
+ for item in &page.items {
+ if let Item::Line(l) = item
+ && line_changed(l)
+ {
+ let rect = Rect::from_xywh(x, l.y, CHANGE_BAR_WIDTH, l.line().height);
+ path.extend(&Path::rect(rect));
+ }
+ }
+ if !path.is_empty() {
+ out.push(Node::Fill {
+ path,
+ paint: Paint::Solid(Rgba::BLACK),
+ even_odd: false,
+ });
+ }
+}
+
+impl Renderer<'_> {
+ /// The display list of a page (scene units are points).
+ pub fn page_nodes(&mut self, page: &Page) -> Vec<Node> {
+ let mut out = Vec::new();
+ out.push(Node::Fill {
+ path: Path::rect(Rect::from_xywh(0.0, 0.0, page.width, page.height)),
+ paint: Paint::Solid(Rgba::WHITE),
+ even_odd: false,
+ });
+ for item in &page.behind {
+ self.item(item, &mut out);
+ }
+ // Shading and borders go under every line of text.
+ for item in &page.items {
+ if matches!(item, Item::Fill { .. }) {
+ self.item(item, &mut out);
+ }
+ }
+ for item in &page.items {
+ if !matches!(item, Item::Fill { .. }) {
+ self.item(item, &mut out);
+ }
+ }
+ change_bars(page, &mut out);
+ for item in &page.front {
+ self.item(item, &mut out);
+ }
+ out
+ }
+
+ fn item(&mut self, item: &Item, out: &mut Vec<Node>) {
+ match item {
+ Item::Fill { rect, color } => out.push(Node::Fill {
+ path: Path::rect(*rect),
+ paint: Paint::Solid(*color),
+ even_odd: false,
+ }),
+ Item::Rule {
+ x0,
+ y0,
+ x1,
+ y1,
+ border,
+ } => rule_nodes(*x0, *y0, *x1, *y1, border, out),
+ Item::Line(l) => {
+ let mut nodes = Vec::new();
+ text::line_nodes(self, l, &mut nodes);
+ match l.clip {
+ Some(clip) => out.push(
+ Group {
+ children: nodes,
+ opacity: 1.0,
+ clip: Some(Path::rect(clip)),
+ effects: Vec::new(),
+ }
+ .into_node(),
+ ),
+ None => out.extend(nodes),
+ }
+ }
+ Item::Drawing(d) => drawing::drawing_nodes(self, &d.drawing, d.rect, &d.story, out),
+ Item::LineNumber {
+ text,
+ right,
+ baseline,
+ size,
+ font,
+ } => text::plain_text(self, text, *right, *baseline, *size, font, out),
+ }
+ }
+
+ /// Renders one page at `scale` pixels per point.
+ pub fn render_page(&mut self, page: &Page, scale: f32) -> Raster {
+ let nodes = self.page_nodes(page);
+ let w = (page.width * scale).round().max(1.0) as u32;
+ let h = (page.height * scale).round().max(1.0) as u32;
+ raster::rasterize(&nodes, w, h, scale)
+ }
+
+ /// Renders a horizontal band of a page (`top..bottom` in points).
+ pub fn render_band(&mut self, page: &Page, scale: f32, top: f32, bottom: f32) -> Raster {
+ let nodes = self.page_nodes(page);
+ let shifted: Vec<Node> = nodes
+ .iter()
+ .map(|n| n.transformed(&pptx_engine::path::Affine::translate(0.0, -f64::from(top))))
+ .collect();
+ let w = (page.width * scale).round().max(1.0) as u32;
+ let h = ((bottom - top) * scale).round().max(1.0) as u32;
+ raster::rasterize(&shifted, w, h, scale)
+ }
+}
+
+impl Document {
+ /// Renders a strip (`top..bottom` points) of page `index` of `layout`,
+ /// at the scale that makes the page `width_px` pixels wide.
+ #[allow(clippy::too_many_arguments)]
+ pub fn render_band(
+ &self,
+ layout: &Layout,
+ index: usize,
+ width_px: u32,
+ top: f32,
+ bottom: f32,
+ fonts: &FontDb,
+ images: &mut ImageCache,
+ ) -> Option<Raster> {
+ let page = layout.pages.get(index)?;
+ let scale = width_px.clamp(16, 16_384) as f32 / page.width.max(1.0);
+ let top = top.clamp(0.0, page.height);
+ let bottom = bottom.clamp(top + 1.0 / scale, page.height.max(top + 1.0 / scale));
+ let mut r = Renderer {
+ doc: self,
+ fonts,
+ images,
+ };
+ Some(r.render_band(page, scale, top, bottom))
+ }
+
+ /// Renders page `index` of `layout` `width_px` pixels wide.
+ pub fn render_page(
+ &self,
+ layout: &Layout,
+ index: usize,
+ width_px: u32,
+ fonts: &FontDb,
+ images: &mut ImageCache,
+ ) -> Option<Raster> {
+ let page = layout.pages.get(index)?;
+ let scale = width_px.clamp(16, 16_384) as f32 / page.width.max(1.0);
+ let mut r = Renderer {
+ doc: self,
+ fonts,
+ images,
+ };
+ Some(r.render_page(page, scale))
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/render/drawing.rs b/crates/docx_engine/src/render/drawing.rs
new file mode 100644
index 0000000000..31f1b21542
--- /dev/null
+++ b/crates/docx_engine/src/render/drawing.rs
@@ -0,0 +1,216 @@
+//! Drawings: pictures (DrawingML and VML), and the other graphics.
+
+use super::Renderer;
+use crate::layout::StoryRef;
+use crate::layout::drawing::{Drawing, Graphic};
+use crate::xml::{NodeId, Ns, XmlTree, parse_int};
+use pptx_engine::path::{Affine, Path, Rect};
+use pptx_engine::render::scene::{Node, Paint};
+use std::sync::Arc;
+
+/// The part whose relationships a story's drawings use.
+pub(super) fn story_part(r: &Renderer<'_>, story: &StoryRef) -> String {
+ match story {
+ StoryRef::Body | StoryRef::TextBox(..) => r.doc.main_part().to_owned(),
+ StoryRef::Part(p) => p.clone(),
+ StoryRef::Footnote(_) => r
+ .doc
+ .footnotes()
+ .part
+ .clone()
+ .unwrap_or_else(|| r.doc.main_part().to_owned()),
+ StoryRef::Endnote(_) => r
+ .doc
+ .endnotes()
+ .part
+ .clone()
+ .unwrap_or_else(|| r.doc.main_part().to_owned()),
+ }
+}
+
+/// Resolves a relationship id of `part` to a target part.
+pub(super) fn target(r: &Renderer<'_>, part: &str, rid: &str) -> Option<String> {
+ r.doc.package().rels(part).ok()?.target_part(rid)
+}
+
+/// A picture's image relationship, crop (left, top, right, bottom
+/// fractions), rotation (degrees) and flips.
+pub(super) type Blip = (String, [f32; 4], f32, bool, bool);
+
+/// The `a:blip` of the picture in `root`.
+fn blip(t: &XmlTree, root: NodeId) -> Option<Blip> {
+ pic_blip(t, t.find(root, Ns::PIC, "pic")?)
+}
+
+/// The `a:blip` of picture `pic` (`pic:pic`).
+pub(super) fn pic_blip(t: &XmlTree, pic: NodeId) -> Option<Blip> {
+ let fill = t.child(pic, Ns::PIC, "blipFill")?;
+ let blip = t.child(fill, Ns::A, "blip")?;
+ let rid = t
+ .attr(blip, Ns::R, "embed")
+ .or_else(|| t.attr(blip, Ns::R, "link"))?
+ .to_owned();
+ let crop = t.child(fill, Ns::A, "srcRect").map_or([0.0; 4], |s| {
+ let v = |n: &str| {
+ t.attr(s, Ns::NONE, n)
+ .and_then(parse_int)
+ .map_or(0.0, |v| v as f32 / 100_000.0)
+ };
+ [v("l"), v("t"), v("r"), v("b")]
+ });
+ let xfrm = t
+ .child(pic, Ns::PIC, "spPr")
+ .and_then(|sp| t.child(sp, Ns::A, "xfrm"));
+ let rot = xfrm
+ .and_then(|x| t.attr(x, Ns::NONE, "rot"))
+ .and_then(parse_int)
+ .map_or(0.0, |v| v as f32 / 60_000.0);
+ let flip_h = xfrm
+ .and_then(|x| t.attr(x, Ns::NONE, "flipH"))
+ .is_some_and(|v| v == "1" || v == "true");
+ let flip_v = xfrm
+ .and_then(|x| t.attr(x, Ns::NONE, "flipV"))
+ .is_some_and(|v| v == "1" || v == "true");
+ Some((rid, crop, rot, flip_h, flip_v))
+}
+
+/// The VML image of a shape (`v:imagedata`).
+fn vml_image(t: &XmlTree, shape: NodeId) -> Option<(String, [f32; 4])> {
+ let data = t
+ .descendants(shape)
+ .into_iter()
+ .find(|&d| t.is(d, Ns::V, "imagedata"))?;
+ let rid = t
+ .attr(data, Ns::R, "id")
+ .or_else(|| t.attr(data, Ns::O, "relid"))?
+ .to_owned();
+ let frac = |n: &str| {
+ t.attr(data, Ns::NONE, n).map_or(0.0, |v| {
+ let v = v.trim();
+ match v.strip_suffix('f') {
+ Some(f) => f.parse::<f32>().unwrap_or(0.0) / 65_536.0,
+ None => v.parse::<f32>().unwrap_or(0.0),
+ }
+ })
+ };
+ Some((
+ rid,
+ [
+ frac("cropleft"),
+ frac("croptop"),
+ frac("cropright"),
+ frac("cropbottom"),
+ ],
+ ))
+}
+
+/// Draws a picture part into `rect` with a crop.
+pub(super) fn picture(
+ r: &mut Renderer<'_>,
+ part: &str,
+ rect: Rect,
+ crop: [f32; 4],
+ rot: f32,
+ flip: (bool, bool),
+ out: &mut Vec<Node>,
+) {
+ let center = (rect.x + rect.w / 2.0, rect.y + rect.h / 2.0);
+ let mut world = Affine::IDENTITY;
+ if rot.abs() > 0.01 || flip.0 || flip.1 {
+ world = Affine::translate(f64::from(center.0), f64::from(center.1))
+ .pre_concat(&Affine::rotate(f64::from(rot)))
+ .pre_concat(&Affine::scale(
+ if flip.0 { -1.0 } else { 1.0 },
+ if flip.1 { -1.0 } else { 1.0 },
+ ))
+ .pre_concat(&Affine::translate(
+ -f64::from(center.0),
+ -f64::from(center.1),
+ ));
+ }
+ // Vector metafiles keep their sharpness.
+ if let Some(m) = r.images.metafile(r.doc, part, r.fonts) {
+ let (vw, vh) = (1.0 - crop[0] - crop[2], 1.0 - crop[1] - crop[3]);
+ if vw > 0.01 && vh > 0.01 && m.width_pt > 0.0 && m.height_pt > 0.0 {
+ let sx = rect.w / (m.width_pt * vw);
+ let sy = rect.h / (m.height_pt * vh);
+ let t = world
+ .pre_concat(&Affine::translate(
+ f64::from(rect.x - crop[0] * m.width_pt * sx),
+ f64::from(rect.y - crop[1] * m.height_pt * sy),
+ ))
+ .pre_concat(&Affine::scale(f64::from(sx), f64::from(sy)));
+ let nodes: Vec<Node> = m.nodes.iter().map(|n| n.transformed(&t)).collect();
+ out.push(
+ pptx_engine::render::scene::Group {
+ children: nodes,
+ opacity: 1.0,
+ clip: Some(Path::rect(rect).transform(&world)),
+ effects: Vec::new(),
+ }
+ .into_node(),
+ );
+ return;
+ }
+ }
+ let Some(img) = r.images.raster(r.doc, part, r.fonts) else {
+ return;
+ };
+ let (w, h) = (img.width as f32, img.height as f32);
+ let (vw, vh) = ((1.0 - crop[0] - crop[2]) * w, (1.0 - crop[1] - crop[3]) * h);
+ if vw <= 0.5 || vh <= 0.5 {
+ return;
+ }
+ let sx = rect.w / vw;
+ let sy = rect.h / vh;
+ let transform = world
+ .pre_concat(&Affine::translate(
+ f64::from(rect.x - crop[0] * w * sx),
+ f64::from(rect.y - crop[1] * h * sy),
+ ))
+ .pre_concat(&Affine::scale(f64::from(sx), f64::from(sy)));
+ out.push(Node::Fill {
+ path: Path::rect(rect).transform(&world),
+ paint: Paint::Image {
+ image: img,
+ transform,
+ repeat: false,
+ opacity: 1.0,
+ },
+ even_odd: false,
+ });
+}
+
+/// Draws a drawing in `rect`.
+pub(super) fn drawing_nodes(
+ r: &mut Renderer<'_>,
+ d: &Drawing,
+ rect: Rect,
+ story: &StoryRef,
+ out: &mut Vec<Node>,
+) {
+ let part = story_part(r, story);
+ let t: &Arc<XmlTree> = &d.tree;
+ if d.vml {
+ if let Some((rid, crop)) = vml_image(t, d.node)
+ && let Some(target) = target(r, &part, &rid)
+ {
+ picture(r, &target, rect, crop, 0.0, (false, false), out);
+ } else if d.graphic == Graphic::Shape {
+ super::shapes::graphic_nodes(r, d, rect, &part, out);
+ }
+ return;
+ }
+ match &d.graphic {
+ Graphic::Picture => {
+ if let Some((rid, crop, rot, fh, fv)) = blip(t, d.node)
+ && let Some(target) = target(r, &part, &rid)
+ {
+ picture(r, &target, rect, crop, rot, (fh, fv), out);
+ }
+ }
+ Graphic::Shape | Graphic::Group | Graphic::Chart(_) | Graphic::Other => {
+ super::shapes::graphic_nodes(r, d, rect, &part, out);
+ }
+ }
+}
diff --git a/crates/docx_engine/src/render/shapes.rs b/crates/docx_engine/src/render/shapes.rs
new file mode 100644
index 0000000000..3b74a3cb46
--- /dev/null
+++ b/crates/docx_engine/src/render/shapes.rs
@@ -0,0 +1,413 @@
+//! DrawingML and VML shapes: outlines and fills. (Their text is laid out
+//! with the page; charts and diagrams are not drawn.)
+
+mod group;
+
+use super::Renderer;
+use crate::layout::drawing::{Drawing, Graphic, css_length};
+use crate::xml::{NodeId, Ns, XmlTree};
+use pptx_engine::geometry::{self, PathFill, ShapeGeometry};
+use pptx_engine::model::color::{ColorContext, ColorMap, Rgba, find_color, preset_color};
+use pptx_engine::model::fill::{Fill, LineProps, find_fill, parse_line};
+use pptx_engine::path::{Affine, Path, Point, Rect};
+use pptx_engine::render::paint::{ImageSource, fill_paint, line_stroke, shade_paint};
+use pptx_engine::render::scene::{LineCap, LineJoin, Node, Paint, Raster, Stroke};
+use pptx_engine::xml::{NodeId as DmlNode, Ns as DmlNs, XmlDoc};
+use std::sync::Arc;
+
+/// EMU per point.
+const EMU_PER_PT: f64 = 12_700.0;
+/// DrawingML angles are in 60000ths of a degree.
+const ANGLE_UNITS: f64 = 60_000.0;
+/// VML's default outline width (points).
+const VML_STROKE: f32 = 0.75;
+/// The VML shape type of text boxes.
+const VML_TEXT_BOX: &str = "_x0000_t202";
+/// The VML shape type of rectangles.
+const VML_RECT: &str = "_x0000_t1";
+
+/// Draws a non-picture graphic in `rect`; `part` resolves the pictures of
+/// groups.
+pub(super) fn graphic_nodes(
+ r: &mut Renderer<'_>,
+ d: &Drawing,
+ rect: Rect,
+ part: &str,
+ out: &mut Vec<Node>,
+) {
+ let t = &d.tree;
+ if d.graphic == Graphic::Group && !d.vml {
+ if let Some(g) = t
+ .descendants(d.node)
+ .into_iter()
+ .find(|&n| t.is(n, Ns::WPG, "wgp") || t.is(n, Ns::WPC, "wpc"))
+ {
+ group::group_nodes(r, t, g, rect, part, out);
+ }
+ return;
+ }
+ if d.graphic != Graphic::Shape {
+ return;
+ }
+ if d.vml {
+ vml_shape(t, d.node, rect, out);
+ return;
+ }
+ let Some(wsp) = t
+ .descendants(d.node)
+ .into_iter()
+ .find(|&n| t.is(n, Ns::WPS, "wsp"))
+ else {
+ return;
+ };
+ let Some((doc, sp)) = drawingml(t, wsp) else {
+ return;
+ };
+ shape_nodes(r, &doc, sp, rect, out);
+}
+
+/// Re-reads a DrawingML element with the DrawingML model's reader.
+fn drawingml(t: &XmlTree, node: NodeId) -> Option<(XmlDoc, DmlNode)> {
+ let mut s = String::from("<_x");
+ for d in t.root_decls() {
+ if d.prefix.is_empty() {
+ s.push_str(" xmlns=\"");
+ } else {
+ s.push_str(" xmlns:");
+ s.push_str(&d.prefix);
+ s.push_str("=\"");
+ }
+ s.push_str(&d.uri.replace('"', "&quot;"));
+ s.push('"');
+ }
+ s.push('>');
+ s.push_str(&t.snippet(node));
+ s.push_str("</_x>");
+ let doc = XmlDoc::parse(s.as_bytes(), "shape").ok()?;
+ let sp = doc.children(doc.root()).next()?;
+ Some((doc, sp))
+}
+
+/// Shapes need no pictures.
+struct NoImages;
+
+impl ImageSource for NoImages {
+ fn raster(&mut self, _part: &str) -> Option<Arc<Raster>> {
+ None
+ }
+}
+
+/// Draws a `wps:wsp` shape `rect` large.
+fn shape_nodes(r: &Renderer<'_>, doc: &XmlDoc, sp: DmlNode, rect: Rect, out: &mut Vec<Node>) {
+ let parts = r.doc.parts();
+ let map = ColorMap::default();
+ let colors = ColorContext {
+ scheme: &parts.theme.colors,
+ map: &map,
+ ph_clr: None,
+ };
+ let no_rels = |_: &str| None;
+ let sp_pr = doc.children(sp).find(|&c| doc.local(c) == "spPr");
+ let style = doc.children(sp).find(|&c| doc.local(c) == "style");
+ let style_ref = |name: &str| -> Option<(u32, Option<Rgba>)> {
+ let s = doc.child(style?, DmlNs::A, name)?;
+ let idx = doc.attr_f64(s, "idx").unwrap_or(0.0).max(0.0) as u32;
+ Some((idx, find_color(doc, s, &colors)))
+ };
+ let theme = parts.theme_full.as_deref();
+ // Fill: the shape's own, else its style's.
+ let fill = sp_pr
+ .and_then(|s| find_fill(doc, s, &colors, &no_rels))
+ .or_else(|| {
+ let (idx, color) = style_ref("fillRef")?;
+ let theme = theme?;
+ let node = theme.fill_style(idx)?;
+ Some(pptx_engine::model::fill::parse_fill(
+ &theme.doc,
+ node,
+ &colors.with_ph(color),
+ &|_| None,
+ ))
+ })
+ .unwrap_or(Fill::None);
+ // Outline: the shape's own settings over its style's.
+ let mut line = sp_pr
+ .and_then(|s| doc.child(s, DmlNs::A, "ln"))
+ .map(|ln| parse_line(doc, ln, &colors, &no_rels))
+ .unwrap_or_default();
+ if let Some((idx, color)) = style_ref("lnRef")
+ && let Some(theme) = theme
+ && let Some(ln) = theme.line_style(idx)
+ {
+ line.inherit(&parse_line(&theme.doc, ln, &colors.with_ph(color), &|_| {
+ None
+ }));
+ }
+ let (w, h) = (f64::from(rect.w), f64::from(rect.h));
+ let geom = sp_pr
+ .and_then(|s| {
+ if let Some(p) = doc.child(s, DmlNs::A, "prstGeom") {
+ let name = doc.attr(p, "prst").unwrap_or("rect");
+ geometry::preset(
+ name,
+ w * EMU_PER_PT,
+ h * EMU_PER_PT,
+ &geometry::adjust_values(doc, p),
+ )
+ } else {
+ doc.child(s, DmlNs::A, "custGeom")
+ .map(|c| geometry::custom(doc, c, w * EMU_PER_PT, h * EMU_PER_PT))
+ }
+ })
+ .or_else(|| geometry::preset("rect", w * EMU_PER_PT, h * EMU_PER_PT, &[]));
+ let Some(geom) = geom else {
+ return;
+ };
+ let xfrm = sp_pr.and_then(|s| doc.child(s, DmlNs::A, "xfrm"));
+ let flag = |name: &str| {
+ xfrm.and_then(|x| doc.attr(x, name))
+ .is_some_and(|v| v == "1" || v == "true")
+ };
+ let rot = xfrm.and_then(|x| doc.attr_f64(x, "rot")).unwrap_or(0.0) / ANGLE_UNITS;
+ let world = placement(rect, rot, flag("flipH"), flag("flipV"));
+ paint_geometry(&geom, &fill, &line, rect, &world, out);
+}
+
+/// The transform from shape-local points to the page: rotated and flipped
+/// about the shape's center.
+fn placement(rect: Rect, rot: f64, flip_h: bool, flip_v: bool) -> Affine {
+ let (cx, cy) = (f64::from(rect.w) / 2.0, f64::from(rect.h) / 2.0);
+ Affine::translate(f64::from(rect.x) + cx, f64::from(rect.y) + cy)
+ .pre_concat(&Affine::rotate(rot))
+ .pre_concat(&Affine::scale(
+ if flip_h { -1.0 } else { 1.0 },
+ if flip_v { -1.0 } else { 1.0 },
+ ))
+ .pre_concat(&Affine::translate(-cx, -cy))
+}
+
+/// Fills and strokes a shape's sub-paths.
+fn paint_geometry(
+ geom: &ShapeGeometry,
+ fill: &Fill,
+ line: &LineProps,
+ rect: Rect,
+ world: &Affine,
+ out: &mut Vec<Node>,
+) {
+ let bbox = Rect::from_xywh(0.0, 0.0, rect.w, rect.h);
+ if let Some(paint) = fill_paint(fill, bbox, world, &mut NoImages) {
+ for gp in &geom.paths {
+ let paint = match gp.fill {
+ PathFill::None => continue,
+ PathFill::Norm => paint.clone(),
+ PathFill::Lighten => shade_paint(paint.clone(), 0.4, true),
+ PathFill::LightenLess => shade_paint(paint.clone(), 0.2, true),
+ PathFill::Darken => shade_paint(paint.clone(), 0.6, false),
+ PathFill::DarkenLess => shade_paint(paint.clone(), 0.8, false),
+ };
+ out.push(Node::Fill {
+ path: gp.path.transform(world),
+ paint,
+ even_odd: false,
+ });
+ }
+ }
+ let Some(line) = line.resolve() else {
+ return;
+ };
+ let Some(paint) = fill_paint(&line.fill, bbox, world, &mut NoImages) else {
+ return;
+ };
+ let stroke = line_stroke(&line, 1.0);
+ for gp in geom.paths.iter().filter(|p| p.stroke) {
+ out.push(Node::Stroke {
+ path: gp.path.transform(world),
+ paint: paint.clone(),
+ stroke: stroke.clone(),
+ });
+ }
+}
+
+/// A VML color (`#rrggbb`, `#rgb`, a color name, maybe followed by a
+/// `[index]` or a transformation).
+fn vml_color(v: &str) -> Option<Rgba> {
+ let v = v.split_whitespace().next()?.split('[').next()?.trim();
+ if let Some(hex) = v.strip_prefix('#') {
+ if hex.len() == 3 {
+ let long: String = hex.chars().flat_map(|c| [c, c]).collect();
+ return Rgba::from_hex(&long);
+ }
+ return Rgba::from_hex(hex);
+ }
+ match v.to_ascii_lowercase().as_str() {
+ "window" | "background" => Some(Rgba::WHITE),
+ "windowtext" | "black" => Some(Rgba::BLACK),
+ name => preset_color(name),
+ }
+}
+
+/// Whether a VML on/off attribute is on.
+fn vml_on(v: Option<&str>, default: bool) -> bool {
+ v.map_or(default, |v| {
+ !matches!(v.trim(), "f" | "false" | "0" | "off" | "False")
+ })
+}
+
+/// Draws a VML shape (rectangle, rounded rectangle, oval, line, text box).
+fn vml_shape(t: &XmlTree, node: NodeId, rect: Rect, out: &mut Vec<Node>) {
+ let attr = |n: NodeId, name: &str| t.attr(n, Ns::NONE, name);
+ let fill_el = t.children(node).find(|&c| t.is(c, Ns::V, "fill"));
+ let stroke_el = t.children(node).find(|&c| t.is(c, Ns::V, "stroke"));
+ let local = t.local(node);
+ let is_line = local == "line";
+ let filled = !is_line
+ && vml_on(attr(node, "filled"), true)
+ && fill_el.is_none_or(|f| vml_on(attr(f, "on"), true));
+ let stroked = vml_on(attr(node, "stroked"), true)
+ && stroke_el.is_none_or(|s| vml_on(attr(s, "on"), true));
+ let path = match local {
+ "oval" => ellipse(rect),
+ "roundrect" => {
+ let arc = attr(node, "arcsize")
+ .and_then(|a| {
+ let a = a.trim();
+ match a.strip_suffix('f') {
+ Some(f) => f.parse::<f32>().ok().map(|v| v / 65_536.0),
+ None => a
+ .trim_end_matches('%')
+ .parse::<f32>()
+ .ok()
+ .map(|v| if v > 1.0 { v / 100.0 } else { v }),
+ }
+ })
+ .unwrap_or(0.2);
+ rounded(rect, rect.w.min(rect.h) * arc / 2.0 * 2.0)
+ }
+ "line" => {
+ let point = |name: &str, default: (f32, f32)| {
+ attr(node, name).map_or(default, |v| {
+ let mut it = v.split(',').map(|p| css_length(p).unwrap_or(0.0));
+ (it.next().unwrap_or(0.0), it.next().unwrap_or(0.0))
+ })
+ };
+ let (x0, y0) = point("from", (0.0, 0.0));
+ let (x1, y1) = point("to", (rect.w, 0.0));
+ let mut p = Path::new();
+ p.move_to(Point::new(rect.x + x0, rect.y + y0));
+ p.line_to(Point::new(rect.x + x1, rect.y + y1));
+ p
+ }
+ "rect" => Path::rect(rect),
+ "shape" if plain_box(t, node) => Path::rect(rect),
+ // Paths, WordArt and other presets are not drawn.
+ _ => return,
+ };
+ if filled {
+ let color = attr(node, "fillcolor")
+ .or_else(|| fill_el.and_then(|f| attr(f, "color")))
+ .map_or(Some(Rgba::WHITE), vml_color);
+ if let Some(c) = color {
+ out.push(Node::Fill {
+ path: path.clone(),
+ paint: Paint::Solid(c),
+ even_odd: false,
+ });
+ }
+ }
+ if stroked {
+ let color = attr(node, "strokecolor")
+ .or_else(|| stroke_el.and_then(|s| attr(s, "color")))
+ .map_or(Some(Rgba::BLACK), vml_color);
+ let width = attr(node, "strokeweight")
+ .or_else(|| stroke_el.and_then(|s| attr(s, "weight")))
+ .and_then(css_length)
+ .unwrap_or(VML_STROKE);
+ let dashed = stroke_el
+ .and_then(|s| attr(s, "dashstyle"))
+ .is_some_and(|d| d != "solid");
+ if let Some(c) = color {
+ out.push(Node::Stroke {
+ path,
+ paint: Paint::Solid(c),
+ stroke: Stroke {
+ width,
+ cap: LineCap::Butt,
+ join: LineJoin::Miter,
+ miter_limit: 4.0,
+ dash: dashed.then(|| vec![width * 4.0, width * 3.0]),
+ },
+ });
+ }
+ }
+}
+
+/// Whether a `v:shape` is a plain box (a text box or a rectangle) rather
+/// than a path, WordArt or another preset shape.
+fn plain_box(t: &XmlTree, node: NodeId) -> bool {
+ let kind = t.attr(node, Ns::NONE, "type").unwrap_or("");
+ matches!(kind.trim_start_matches('#'), "" | VML_TEXT_BOX | VML_RECT)
+ && t.attr(node, Ns::NONE, "path").is_none()
+ && !t.children(node).any(|c| t.is(c, Ns::V, "textpath"))
+}
+
+/// An ellipse inscribed in `r`.
+fn ellipse(r: Rect) -> Path {
+ // Four cubic arcs with the usual control distance.
+ const K: f32 = 0.552_284_8;
+ let (cx, cy) = (r.x + r.w / 2.0, r.y + r.h / 2.0);
+ let (rx, ry) = (r.w / 2.0, r.h / 2.0);
+ let mut p = Path::new();
+ p.move_to(Point::new(cx + rx, cy));
+ p.cubic_to(
+ Point::new(cx + rx, cy + ry * K),
+ Point::new(cx + rx * K, cy + ry),
+ Point::new(cx, cy + ry),
+ );
+ p.cubic_to(
+ Point::new(cx - rx * K, cy + ry),
+ Point::new(cx - rx, cy + ry * K),
+ Point::new(cx - rx, cy),
+ );
+ p.cubic_to(
+ Point::new(cx - rx, cy - ry * K),
+ Point::new(cx - rx * K, cy - ry),
+ Point::new(cx, cy - ry),
+ );
+ p.cubic_to(
+ Point::new(cx + rx * K, cy - ry),
+ Point::new(cx + rx, cy - ry * K),
+ Point::new(cx + rx, cy),
+ );
+ p.close();
+ p
+}
+
+/// A rectangle with corners rounded by `radius`.
+fn rounded(r: Rect, radius: f32) -> Path {
+ let w = f64::from(r.w);
+ let h = f64::from(r.h);
+ let rad = f64::from(radius).min(w / 2.0).min(h / 2.0).max(0.0);
+ let geom = geometry::preset(
+ "roundRect",
+ w * EMU_PER_PT,
+ h * EMU_PER_PT,
+ &[(
+ "adj".to_owned(),
+ if w.min(h) > 0.0 {
+ rad / w.min(h) * 100_000.0
+ } else {
+ 0.0
+ },
+ )],
+ );
+ match geom.and_then(|g| g.paths.into_iter().next()) {
+ Some(gp) => gp
+ .path
+ .transform(&Affine::translate(f64::from(r.x), f64::from(r.y))),
+ None => Path::rect(r),
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/render/shapes/group.rs b/crates/docx_engine/src/render/shapes/group.rs
new file mode 100644
index 0000000000..06a155a354
--- /dev/null
+++ b/crates/docx_engine/src/render/shapes/group.rs
@@ -0,0 +1,135 @@
+//! Groups of shapes and pictures (`wpg:wgp`) and drawing canvases
+//! (`wpc:wpc`), drawn child by child.
+
+use super::{EMU_PER_PT, drawingml, shape_nodes};
+use crate::render::Renderer;
+use crate::render::drawing::{pic_blip, picture, target};
+use crate::xml::{NodeId, Ns, XmlTree, parse_int};
+use pptx_engine::path::Rect;
+use pptx_engine::render::scene::Node;
+
+/// How a group's child coordinates map to the page.
+#[derive(Clone, Copy, Debug)]
+struct Space {
+ /// The child coordinates at `origin`.
+ from: (f64, f64),
+ /// Page points per child unit.
+ scale: (f64, f64),
+ /// The page point of `from` (points).
+ origin: (f64, f64),
+}
+
+impl Space {
+ /// The space of a group drawn in `rect` whose children span `ext` from
+ /// `off`.
+ fn within(rect: Rect, off: (f64, f64), ext: (f64, f64)) -> Self {
+ let scale = |page: f32, ext: f64| {
+ if ext > 0.0 {
+ f64::from(page) / ext
+ } else {
+ 1.0 / EMU_PER_PT
+ }
+ };
+ Space {
+ from: off,
+ scale: (scale(rect.w, ext.0), scale(rect.h, ext.1)),
+ origin: (f64::from(rect.x), f64::from(rect.y)),
+ }
+ }
+
+ /// The page rectangle of a child at `off` sized `ext`.
+ fn rect(&self, off: (f64, f64), ext: (f64, f64)) -> Rect {
+ Rect::from_xywh(
+ (self.origin.0 + (off.0 - self.from.0) * self.scale.0) as f32,
+ (self.origin.1 + (off.1 - self.from.1) * self.scale.1) as f32,
+ (ext.0 * self.scale.0) as f32,
+ (ext.1 * self.scale.1) as f32,
+ )
+ }
+}
+
+/// An `a:xfrm`: offset and extent, and the span of a group's children.
+#[derive(Clone, Copy, Debug)]
+struct Xfrm {
+ off: (f64, f64),
+ ext: (f64, f64),
+ child_off: (f64, f64),
+ child_ext: (f64, f64),
+}
+
+/// The transform in a child's shape properties (`spPr`, `grpSpPr`).
+fn xfrm(t: &XmlTree, node: NodeId) -> Option<Xfrm> {
+ let props = t
+ .children(node)
+ .find(|&c| matches!(t.local(c), "spPr" | "grpSpPr"))?;
+ let x = t.child(props, Ns::A, "xfrm")?;
+ let pair = |name: &str, a: &str, b: &str| {
+ t.child(x, Ns::A, name).map(|n| {
+ let v = |k: &str| t.attr(n, Ns::NONE, k).and_then(parse_int).unwrap_or(0) as f64;
+ (v(a), v(b))
+ })
+ };
+ let off = pair("off", "x", "y").unwrap_or_default();
+ let ext = pair("ext", "cx", "cy").unwrap_or_default();
+ Some(Xfrm {
+ off,
+ ext,
+ child_off: pair("chOff", "x", "y").unwrap_or(off),
+ child_ext: pair("chExt", "cx", "cy").unwrap_or(ext),
+ })
+}
+
+/// Draws group or canvas `node` in `rect`; `part` resolves its pictures.
+pub(super) fn group_nodes(
+ r: &mut Renderer<'_>,
+ t: &XmlTree,
+ node: NodeId,
+ rect: Rect,
+ part: &str,
+ out: &mut Vec<Node>,
+) {
+ let space = match xfrm(t, node) {
+ // A group spreads its children's span over its extent.
+ Some(x) => Space::within(rect, x.child_off, x.child_ext),
+ // A canvas places its children in EMU from its corner.
+ None => Space::within(
+ rect,
+ (0.0, 0.0),
+ (
+ f64::from(rect.w) * EMU_PER_PT,
+ f64::from(rect.h) * EMU_PER_PT,
+ ),
+ ),
+ };
+ children(r, t, node, space, part, out);
+}
+
+/// Draws the shapes, pictures and groups in `node`.
+fn children(
+ r: &mut Renderer<'_>,
+ t: &XmlTree,
+ node: NodeId,
+ space: Space,
+ part: &str,
+ out: &mut Vec<Node>,
+) {
+ for c in t.children(node) {
+ let Some(x) = xfrm(t, c) else {
+ continue;
+ };
+ let rect = space.rect(x.off, x.ext);
+ if t.is(c, Ns::WPS, "wsp") {
+ if let Some((doc, sp)) = drawingml(t, c) {
+ shape_nodes(r, &doc, sp, rect, out);
+ }
+ } else if t.is(c, Ns::WPG, "grpSp") {
+ let inner = Space::within(rect, x.child_off, x.child_ext);
+ children(r, t, c, inner, part, out);
+ } else if t.is(c, Ns::PIC, "pic")
+ && let Some((rid, crop, rot, flip_h, flip_v)) = pic_blip(t, c)
+ && let Some(image) = target(r, part, &rid)
+ {
+ picture(r, &image, rect, crop, rot, (flip_h, flip_v), out);
+ }
+ }
+}
diff --git a/crates/docx_engine/src/render/shapes/test.rs b/crates/docx_engine/src/render/shapes/test.rs
new file mode 100644
index 0000000000..d44b90318d
--- /dev/null
+++ b/crates/docx_engine/src/render/shapes/test.rs
@@ -0,0 +1,86 @@
+use super::*;
+use crate::Document;
+use crate::render::ImageCache;
+use crate::test_support::{Parts, docx, fonts, shape_paragraph};
+
+#[test]
+fn vml_colors_read_hex_and_names() {
+ assert_eq!(vml_color("#ff0000"), Rgba::from_hex("ff0000"));
+ assert_eq!(vml_color("#0f0"), Rgba::from_hex("00ff00"));
+ assert_eq!(vml_color("black [3213]"), Some(Rgba::BLACK));
+ assert_eq!(vml_color("window"), Some(Rgba::WHITE));
+ assert!(vml_on(None, true));
+ assert!(!vml_on(Some("f"), true));
+}
+
+/// The RGB of pixel (x, y) of a page rendered one pixel per point.
+fn pixel(r: &pptx_engine::render::scene::Raster, x: u32, y: u32) -> [u8; 3] {
+ let i = ((y * r.width + x) * 4) as usize;
+ [r.pixels[i], r.pixels[i + 1], r.pixels[i + 2]]
+}
+
+/// The first page of a Letter document with `content` in its body,
+/// rendered one pixel per point.
+fn render(content: &str) -> pptx_engine::render::scene::Raster {
+ let body = format!(
+ r#"{content}<w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720"/></w:sectPr>"#
+ );
+ let doc = Document::open(docx(&body, &Parts::default())).unwrap();
+ let layout = doc.layout(fonts());
+ let mut images = ImageCache::new();
+ doc.render_page(&layout, 0, 612, fonts(), &mut images)
+ .expect("a page")
+}
+
+#[test]
+fn shapes_draw_their_fill_and_outline() {
+ let page = render(&shape_paragraph("page", 200, 300, None));
+ // Red inside the 200x100pt box at (200, 300), black along its 2pt edge.
+ assert_eq!(pixel(&page, 300, 350), [255, 0, 0]);
+ let edge = pixel(&page, 200, 350);
+ assert!(edge.iter().all(|&c| c < 64), "{edge:?}");
+ assert_eq!(pixel(&page, 150, 350), [255, 255, 255]);
+}
+
+/// A paragraph with VML element `el` at (x, y) points on the page, 200x100pt
+/// large, with `rest` as its attributes and content.
+fn vml_paragraph(el: &str, x: u32, y: u32, rest: &str) -> String {
+ format!(
+ r#"<w:p><w:r><w:pict><v:{el} style="position:absolute;margin-left:{x}pt;margin-top:{y}pt;width:200pt;height:100pt;mso-position-horizontal-relative:page;mso-position-vertical-relative:page" fillcolor="red" strokecolor="black" strokeweight="2pt" {rest}</v:{el}></w:pict></w:r></w:p>"#
+ )
+}
+
+#[test]
+fn vml_boxes_are_drawn_but_not_word_art() {
+ let page = render(&format!(
+ "{}{}",
+ vml_paragraph("rect", 200, 100, ">"),
+ vml_paragraph(
+ "shape",
+ 200,
+ 400,
+ r##"type="#_x0000_t136"><v:textpath string="Draft"/>"##
+ ),
+ ));
+ assert_eq!(pixel(&page, 300, 150), [255, 0, 0]);
+ let edge = pixel(&page, 200, 150);
+ assert!(edge.iter().all(|&c| c < 64), "{edge:?}");
+ // WordArt fills its letters, not its box.
+ assert_eq!(pixel(&page, 300, 450), [255, 255, 255]);
+}
+
+#[test]
+fn group_children_are_scaled_into_the_group() {
+ // A 200x100pt group at (100, 100) whose children span 2000x1000 units
+ // from (1000, 1000): a child at (2000, 1500) sized 1000x500 covers
+ // (200, 150) to (300, 200) on the page.
+ let child = r#"<wps:wsp><wps:cNvSpPr/><wps:spPr><a:xfrm><a:off x="2000" y="1500"/><a:ext cx="1000" cy="500"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom><a:solidFill><a:srgbClr val="FF0000"/></a:solidFill></wps:spPr><wps:bodyPr/></wps:wsp>"#;
+ let group = format!(
+ r#"<w:p><w:r><w:drawing><wp:anchor distT="0" distB="0" distL="0" distR="0" simplePos="0" relativeHeight="1" behindDoc="0" locked="0" layoutInCell="1" allowOverlap="1"><wp:simplePos x="0" y="0"/><wp:positionH relativeFrom="page"><wp:posOffset>1270000</wp:posOffset></wp:positionH><wp:positionV relativeFrom="page"><wp:posOffset>1270000</wp:posOffset></wp:positionV><wp:extent cx="2540000" cy="1270000"/><wp:wrapNone/><wp:docPr id="1" name="Group"/><a:graphic><a:graphicData uri="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup"><wpg:wgp><wpg:cNvGrpSpPr/><wpg:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="2540000" cy="1270000"/><a:chOff x="1000" y="1000"/><a:chExt cx="2000" cy="1000"/></a:xfrm></wpg:grpSpPr>{child}</wpg:wgp></a:graphicData></a:graphic></wp:anchor></w:drawing></w:r></w:p>"#
+ );
+ let page = render(&group);
+ assert_eq!(pixel(&page, 250, 175), [255, 0, 0]);
+ assert_eq!(pixel(&page, 197, 175), [255, 255, 255]);
+ assert_eq!(pixel(&page, 250, 203), [255, 255, 255]);
+ assert_eq!(pixel(&page, 150, 120), [255, 255, 255]);
+}
diff --git a/crates/docx_engine/src/render/test.rs b/crates/docx_engine/src/render/test.rs
new file mode 100644
index 0000000000..69f80cfd1b
--- /dev/null
+++ b/crates/docx_engine/src/render/test.rs
@@ -0,0 +1,50 @@
+use super::*;
+use crate::layout::LayoutOptions;
+use crate::test_support::{Parts, docx, fonts};
+
+/// The height of the change bars drawn on the first page (0 for none).
+fn bars(body: &str, markup: bool) -> f32 {
+ let doc = Document::open(docx(body, &Parts::default())).expect("open");
+ let options = LayoutOptions {
+ markup,
+ ..LayoutOptions::default()
+ };
+ let layout = doc.layout_with(fonts(), &options);
+ let page = &layout.pages[0];
+ let x = page.body.x - CHANGE_BAR_GAP - CHANGE_BAR_WIDTH / 2.0;
+ let mut images = ImageCache::new();
+ let mut r = Renderer {
+ doc: &doc,
+ fonts: fonts(),
+ images: &mut images,
+ };
+ r.page_nodes(page)
+ .iter()
+ .filter_map(|n| match n {
+ Node::Fill { path, .. } => path.bounds(),
+ _ => None,
+ })
+ .filter(|b| (b.x - x).abs() < 0.01 && (b.w - CHANGE_BAR_WIDTH).abs() < 0.01)
+ .map(|b| b.h)
+ .sum()
+}
+
+const PLAIN: &str = r#"<w:p><w:r><w:t>Plain</w:t></w:r></w:p>"#;
+
+#[test]
+fn change_bars_mark_lines_with_tracked_changes() {
+ assert_eq!(bars(PLAIN, true), 0.0);
+ let inserted = format!(
+ r#"{PLAIN}<w:p><w:ins w:id="1" w:author="A"><w:r><w:t>New</w:t></w:r></w:ins></w:p>"#
+ );
+ let one_line = bars(&inserted, true);
+ assert!(one_line > 10.0 && one_line < 20.0, "{one_line}");
+ // Formatting and paragraph property changes get a bar too.
+ let formatted = r#"<w:p><w:r><w:rPr><w:b/><w:rPrChange w:id="2" w:author="A"><w:rPr/></w:rPrChange></w:rPr><w:t>Bold</w:t></w:r></w:p>"#;
+ assert_eq!(bars(formatted, true), one_line);
+ let para = r#"<w:p><w:pPr><w:jc w:val="center"/><w:pPrChange w:id="3" w:author="A"><w:pPr/></w:pPrChange></w:pPr><w:r><w:t>Centered</w:t></w:r></w:p>"#;
+ assert_eq!(bars(para, true), one_line);
+ // Without markup the document shows as if the changes were accepted.
+ assert_eq!(bars(&inserted, false), 0.0);
+ assert_eq!(bars(formatted, false), 0.0);
+}
diff --git a/crates/docx_engine/src/render/text.rs b/crates/docx_engine/src/render/text.rs
new file mode 100644
index 0000000000..476fffd659
--- /dev/null
+++ b/crates/docx_engine/src/render/text.rs
@@ -0,0 +1,526 @@
+//! Text lines: glyphs, highlights, underlines, strikethrough, tab leaders.
+
+use super::Renderer;
+use crate::layout::PlacedLine;
+use crate::layout::fonts::{is_wide, missing_advance};
+use crate::layout::inline::{Kind, Revision, RunStyle};
+use crate::model::props::{TabLeader, UnderlineStyle};
+use pptx_engine::font::FaceId;
+use pptx_engine::model::color::Rgba;
+use pptx_engine::path::{Affine, Path, Point, Rect};
+use pptx_engine::render::scene::{LineCap, LineJoin, Node, Paint, Stroke};
+
+/// Slant of synthesized italics.
+const SYNTHETIC_SLANT: f64 = 0.2;
+
+/// Inset of the box drawn for an East Asian character no face has (em).
+const PLACEHOLDER_INSET: f32 = 0.1;
+/// Top of that box above the baseline (em).
+const PLACEHOLDER_RISE: f32 = 0.8;
+/// Its opacity relative to the text color.
+const PLACEHOLDER_ALPHA: f32 = 0.25;
+/// Inset of the bar drawn for a letter no face has (em).
+const LETTER_INSET: f32 = 0.02;
+/// Height of that bar above the baseline (em).
+const LETTER_RISE: f32 = 0.45;
+
+/// Glyphs collected into one path per color.
+struct GlyphBatch {
+ color: Rgba,
+ path: Path,
+ bold: Option<f32>,
+}
+
+impl GlyphBatch {
+ fn flush(&mut self, out: &mut Vec<Node>) {
+ if self.path.is_empty() {
+ return;
+ }
+ let path = std::mem::take(&mut self.path);
+ if let Some(w) = self.bold.take() {
+ out.push(Node::Stroke {
+ path: path.clone(),
+ paint: Paint::Solid(self.color),
+ stroke: Stroke {
+ width: w,
+ cap: LineCap::Round,
+ join: LineJoin::Round,
+ miter_limit: 4.0,
+ dash: None,
+ },
+ });
+ }
+ out.push(Node::Fill {
+ path,
+ paint: Paint::Solid(self.color),
+ even_odd: false,
+ });
+ }
+}
+
+/// A glyph's outline with its origin at `(x, y)`.
+fn glyph_path(
+ r: &Renderer<'_>,
+ face: FaceId,
+ glyph: u16,
+ (x, y): (f32, f32),
+ size: f32,
+ scale_x: f32,
+ italic: bool,
+) -> Option<Path> {
+ let outline = r.fonts.outline(face, glyph)?;
+ let mut t = Affine::translate(f64::from(x), f64::from(y))
+ .pre_concat(&Affine::scale(f64::from(size * scale_x), f64::from(size)));
+ if italic {
+ t = t.pre_concat(&Affine {
+ a: 1.0,
+ b: 0.0,
+ c: -SYNTHETIC_SLANT,
+ d: 1.0,
+ e: 0.0,
+ f: 0.0,
+ });
+ }
+ Some(outline.transform(&t))
+}
+
+fn hline(
+ x0: f32,
+ x1: f32,
+ y: f32,
+ width: f32,
+ color: Rgba,
+ dash: Option<Vec<f32>>,
+ out: &mut Vec<Node>,
+) {
+ if x1 - x0 < 0.05 {
+ return;
+ }
+ let mut p = Path::new();
+ p.move_to(Point::new(x0, y));
+ p.line_to(Point::new(x1, y));
+ out.push(Node::Stroke {
+ path: p,
+ paint: Paint::Solid(color),
+ stroke: Stroke {
+ width: width.max(0.3),
+ cap: LineCap::Butt,
+ join: LineJoin::Miter,
+ miter_limit: 4.0,
+ dash,
+ },
+ });
+}
+
+/// A run of clusters on one line that share a style, for decorations.
+struct Segment {
+ run: u16,
+ x0: f32,
+ x1: f32,
+ /// Ends of words (for word-only underlines): (x0, x1) of non-space parts.
+ words: Vec<(f32, f32)>,
+}
+
+/// Draws one placed line.
+pub(super) fn line_nodes(r: &mut Renderer<'_>, pl: &PlacedLine, out: &mut Vec<Node>) {
+ let pb = &pl.para;
+ let line = pl.line();
+ let inline = &pb.inline;
+ let lines = &pb.lines;
+ let baseline = pl.y + line.baseline;
+ // Trailing spaces are not decorated.
+ let mut last_visible = line.start;
+ for k in line.start..line.end {
+ if matches!(
+ inline.clusters[k].kind,
+ Kind::Text | Kind::Object(_) | Kind::Tab
+ ) {
+ last_visible = k + 1;
+ }
+ }
+ // Segments by run.
+ let mut segments: Vec<Segment> = Vec::new();
+ for k in line.start..last_visible {
+ let c = &inline.clusters[k];
+ if !matches!(
+ c.kind,
+ Kind::Text | Kind::Space | Kind::Tab | Kind::Object(_)
+ ) {
+ continue;
+ }
+ let x0 = pl.x + lines.x[k];
+ let x1 = x0 + lines.adv[k];
+ // Right-to-left text runs leftwards: a segment grows on either side.
+ let touches = |a: f32, b: f32| (b - x0).abs() < 0.5 || (x1 - a).abs() < 0.5;
+ match segments.last_mut() {
+ Some(s) if s.run == c.run && touches(s.x0, s.x1) => {
+ s.x0 = s.x0.min(x0);
+ s.x1 = s.x1.max(x1);
+ if c.kind == Kind::Text {
+ match s.words.last_mut() {
+ Some(w) if touches(w.0, w.1) => {
+ w.0 = w.0.min(x0);
+ w.1 = w.1.max(x1);
+ }
+ _ => s.words.push((x0, x1)),
+ }
+ }
+ }
+ _ => segments.push(Segment {
+ run: c.run,
+ x0,
+ x1,
+ words: if c.kind == Kind::Text {
+ vec![(x0, x1)]
+ } else {
+ Vec::new()
+ },
+ }),
+ }
+ }
+ // Backgrounds: shading and highlight.
+ for s in &segments {
+ let style = &inline.runs[s.run as usize];
+ let bg = style.props.highlight.or(style.props.shading);
+ if let Some(color) = bg {
+ let top = baseline - style.ascent - style.leading;
+ out.push(Node::Fill {
+ path: Path::rect(Rect::from_xywh(
+ s.x0,
+ top,
+ s.x1 - s.x0,
+ style.ascent + style.leading + style.descent,
+ )),
+ paint: Paint::Solid(color),
+ even_odd: false,
+ });
+ }
+ }
+ // Glyphs.
+ let mut batch = GlyphBatch {
+ color: Rgba::BLACK,
+ path: Path::new(),
+ bold: None,
+ };
+ for k in line.start..line.end {
+ let c = &inline.clusters[k];
+ let style: &RunStyle = &inline.runs[c.run as usize];
+ match c.kind {
+ Kind::Text => {
+ let Some(font) = c.font else {
+ continue;
+ };
+ if c.glyph == 0 {
+ if missing_advance(c.ch).is_some_and(|a| a > 0.0) {
+ // No face has the character: a light box shows
+ // where it is (an em square for East Asian text, a
+ // low bar for letters).
+ batch.flush(out);
+ let size = if c.size > 0.0 { c.size } else { style.size };
+ let (inset, rise, height) = if is_wide(c.ch) {
+ (
+ PLACEHOLDER_INSET,
+ PLACEHOLDER_RISE,
+ 1.0 - 2.0 * PLACEHOLDER_INSET,
+ )
+ } else {
+ (LETTER_INSET, LETTER_RISE, LETTER_RISE)
+ };
+ let rect = Rect::from_xywh(
+ pl.x + lines.x[k] + size * inset,
+ baseline - style.shift - size * rise,
+ (lines.adv[k] - 2.0 * size * inset).max(0.0),
+ size * height,
+ );
+ out.push(Node::Fill {
+ path: Path::rect(rect),
+ paint: Paint::Solid(style.color.with_alpha_mul(PLACEHOLDER_ALPHA)),
+ even_odd: false,
+ });
+ }
+ continue;
+ }
+ let size = if c.size > 0.0 { c.size } else { style.size };
+ let x = pl.x + lines.x[k];
+ let y = baseline - style.shift;
+ let color = style.color;
+ let bold = font.synthetic_bold.then_some(size * 0.035);
+ if batch.color != color || batch.bold.is_some() != bold.is_some() {
+ batch.flush(out);
+ batch.color = color;
+ }
+ batch.bold = bold;
+ if let Some(p) = glyph_path(
+ r,
+ font.face,
+ c.glyph,
+ (x, y),
+ size,
+ style.props.scale,
+ font.synthetic_italic,
+ ) {
+ batch.path.extend(&p);
+ }
+ }
+ Kind::Tab => {
+ if let Some(&(_, leader)) = lines.leaders.iter().find(|(i, _)| *i == k) {
+ batch.flush(out);
+ leader_nodes(
+ r,
+ style,
+ leader,
+ pl.x + lines.x[k],
+ pl.x + lines.x[k] + lines.adv[k],
+ baseline,
+ out,
+ );
+ }
+ }
+ Kind::SoftHyphen if k + 1 == line.end || (line.hyphen && k + 1 >= line.end) => {
+ if let Some(font) = style.font {
+ let g = r.fonts.glyph(font.face, '-');
+ if let Some(g) = g
+ && let Some(p) = glyph_path(
+ r,
+ font.face,
+ g,
+ (pl.x + lines.x[k], baseline - style.shift),
+ style.size,
+ 1.0,
+ false,
+ )
+ {
+ if batch.color != style.color {
+ batch.flush(out);
+ batch.color = style.color;
+ }
+ batch.path.extend(&p);
+ }
+ }
+ }
+ Kind::Object(o) => {
+ batch.flush(out);
+ let d = &inline.objects[o as usize];
+ let x = pl.x + lines.x[k] + d.effect[0];
+ let y = baseline - d.height - d.effect[3];
+ super::drawing::drawing_nodes(
+ r,
+ d,
+ Rect::from_xywh(x, y, d.width, d.height),
+ &pb.story,
+ out,
+ );
+ }
+ Kind::Separator(_) => {
+ batch.flush(out);
+ let y = pl.y + line.height / 2.0;
+ hline(
+ pl.x + lines.x[k],
+ pl.x + lines.x[k] + lines.adv[k],
+ y,
+ 0.5,
+ Rgba::BLACK,
+ None,
+ out,
+ );
+ }
+ _ => {}
+ }
+ }
+ batch.flush(out);
+ // Underline and strikethrough.
+ for s in &segments {
+ let style = &inline.runs[s.run as usize];
+ let Some(font) = style.font else {
+ continue;
+ };
+ let m = r.fonts.metrics(font.face);
+ let size = style.size;
+ let y_base = baseline - style.shift;
+ let mut underline = style.props.underline;
+ if style.revision == Revision::Inserted && underline.is_none() {
+ underline = Some(crate::model::props::Underline {
+ style: UnderlineStyle::Single,
+ color: None,
+ });
+ }
+ if let Some(u) = underline {
+ let color = u.color.unwrap_or(style.color);
+ let thick = (m.underline_thickness * size).max(0.5);
+ let y = y_base + m.underline_pos * size;
+ let spans: Vec<(f32, f32)> = if u.style == UnderlineStyle::Words {
+ s.words.clone()
+ } else {
+ vec![(s.x0, s.x1)]
+ };
+ for (x0, x1) in spans {
+ match u.style {
+ UnderlineStyle::Double | UnderlineStyle::WavyDouble => {
+ hline(x0, x1, y, thick, color, None, out);
+ hline(x0, x1, y + thick * 2.0, thick, color, None, out);
+ }
+ UnderlineStyle::Thick | UnderlineStyle::WavyHeavy => {
+ hline(x0, x1, y + thick / 2.0, thick * 2.0, color, None, out);
+ }
+ UnderlineStyle::Dotted | UnderlineStyle::DottedHeavy => {
+ hline(x0, x1, y, thick, color, Some(vec![thick, thick * 2.0]), out);
+ }
+ UnderlineStyle::Dash | UnderlineStyle::DashHeavy | UnderlineStyle::DashLong => {
+ hline(
+ x0,
+ x1,
+ y,
+ thick,
+ color,
+ Some(vec![thick * 4.0, thick * 3.0]),
+ out,
+ );
+ }
+ UnderlineStyle::DotDash | UnderlineStyle::DotDotDash => {
+ hline(
+ x0,
+ x1,
+ y,
+ thick,
+ color,
+ Some(vec![thick * 4.0, thick * 2.0, thick, thick * 2.0]),
+ out,
+ );
+ }
+ _ => hline(x0, x1, y, thick, color, None, out),
+ }
+ }
+ }
+ let strike = style.props.strike || style.revision == Revision::Deleted;
+ if strike || style.props.dstrike {
+ let thick = (m.strike_thickness * size).max(0.5);
+ let y = y_base - m.strike_pos * size;
+ if style.props.dstrike {
+ hline(s.x0, s.x1, y - thick, thick, style.color, None, out);
+ hline(s.x0, s.x1, y + thick, thick, style.color, None, out);
+ } else {
+ hline(s.x0, s.x1, y, thick, style.color, None, out);
+ }
+ }
+ if let Some(b) = style.props.border {
+ let top = baseline - style.ascent - style.leading - b.space;
+ let bottom = baseline + style.descent + b.space;
+ for (x0, y0, x1, y1) in [
+ (s.x0, top, s.x1, top),
+ (s.x0, bottom, s.x1, bottom),
+ (s.x0, top, s.x0, bottom),
+ (s.x1, top, s.x1, bottom),
+ ] {
+ super::rule_nodes(x0, y0, x1, y1, &b, out);
+ }
+ }
+ }
+}
+
+fn leader_nodes(
+ r: &Renderer<'_>,
+ style: &RunStyle,
+ leader: TabLeader,
+ x0: f32,
+ x1: f32,
+ baseline: f32,
+ out: &mut Vec<Node>,
+) {
+ let size = style.size;
+ match leader {
+ TabLeader::Underscore => {
+ hline(
+ x0,
+ x1,
+ baseline + size * 0.1,
+ size * 0.05,
+ style.color,
+ None,
+ out,
+ );
+ }
+ TabLeader::Heavy => {
+ hline(
+ x0,
+ x1,
+ baseline + size * 0.1,
+ size * 0.1,
+ style.color,
+ None,
+ out,
+ );
+ }
+ TabLeader::None => {}
+ TabLeader::Dot | TabLeader::Hyphen | TabLeader::MiddleDot => {
+ let ch = match leader {
+ TabLeader::Dot => '.',
+ TabLeader::Hyphen => '-',
+ _ => '\u{00B7}',
+ };
+ let Some(font) = style.font else {
+ return;
+ };
+ let Some(g) = r.fonts.glyph(font.face, ch) else {
+ return;
+ };
+ let adv = r.fonts.advance(font.face, g) * size;
+ if adv <= 0.1 {
+ return;
+ }
+ // Word aligns leader dots to a grid so stacked leaders line up.
+ let mut x = (x0 / adv).ceil() * adv;
+ let mut path = Path::new();
+ while x + adv <= x1 - adv * 0.5 {
+ if let Some(p) = glyph_path(r, font.face, g, (x, baseline), size, 1.0, false) {
+ path.extend(&p);
+ }
+ x += adv;
+ }
+ if !path.is_empty() {
+ out.push(Node::Fill {
+ path,
+ paint: Paint::Solid(style.color),
+ even_odd: false,
+ });
+ }
+ }
+ }
+}
+
+/// Draws a short string (line numbers) ending at `right`.
+pub(super) fn plain_text(
+ r: &mut Renderer<'_>,
+ text: &str,
+ right: f32,
+ baseline: f32,
+ size: f32,
+ font: &str,
+ out: &mut Vec<Node>,
+) {
+ let Some(choice) = r.fonts.select(font, false, false) else {
+ return;
+ };
+ let face = choice.face;
+ let glyphs: Vec<(u16, f32)> = text
+ .chars()
+ .filter_map(|c| {
+ r.fonts
+ .glyph(face, c)
+ .map(|g| (g, r.fonts.advance(face, g) * size))
+ })
+ .collect();
+ let width: f32 = glyphs.iter().map(|(_, a)| a).sum();
+ let mut pen = right - width;
+ let mut path = Path::new();
+ for (g, adv) in glyphs {
+ if let Some(p) = glyph_path(r, face, g, (pen, baseline), size, 1.0, false) {
+ path.extend(&p);
+ }
+ pen += adv;
+ }
+ out.push(Node::Fill {
+ path,
+ paint: Paint::Solid(Rgba::BLACK),
+ even_odd: false,
+ });
+}
diff --git a/crates/docx_engine/src/test_support.rs b/crates/docx_engine/src/test_support.rs
new file mode 100644
index 0000000000..56b0e2783f
--- /dev/null
+++ b/crates/docx_engine/src/test_support.rs
@@ -0,0 +1,282 @@
+//! Helpers for tests: in-memory packages, the bundled fonts and comparing
+//! layouts.
+
+use crate::layout::{Item, Layout, Page, PlacedDrawing, PlacedLine};
+use pptx_engine::font::FontDb;
+use pptx_engine::zip::{WriteData, Writer};
+use std::sync::OnceLock;
+
+/// The bundled fonts, read from the PPTX engine's font directory.
+pub fn fonts() -> &'static FontDb {
+ static DB: OnceLock<FontDb> = OnceLock::new();
+ DB.get_or_init(|| {
+ let mut db = FontDb::new();
+ let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../pptx_engine/fonts");
+ let mut files: Vec<_> = std::fs::read_dir(&dir)
+ .map(|d| d.filter_map(|e| e.ok()).map(|e| e.path()).collect())
+ .unwrap_or_default();
+ files.sort();
+ for f in files {
+ if f.extension().is_some_and(|e| e == "ttf")
+ && let Ok(bytes) = std::fs::read(&f)
+ {
+ db.register(bytes);
+ }
+ }
+ db
+ })
+}
+
+/// The namespaces test documents declare.
+pub const NS: &str = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:v="urn:schemas-microsoft-com:vml""#;
+
+/// Parts of a test document besides the body.
+#[derive(Default)]
+pub struct Parts<'a> {
+ /// `w:styles` children.
+ pub styles: Option<&'a str>,
+ /// `w:numbering` children.
+ pub numbering: Option<&'a str>,
+ /// `w:settings` children.
+ pub settings: Option<&'a str>,
+ /// Header part body (`w:hdr` children), referenced as rIdH1.
+ pub header: Option<&'a str>,
+ /// Footnotes (`w:footnotes` children).
+ pub footnotes: Option<&'a str>,
+ /// Endnotes (`w:endnotes` children).
+ pub endnotes: Option<&'a str>,
+ /// Comments (`w:comments` children).
+ pub comments: Option<&'a str>,
+ /// Comment threads (`w15:commentsEx` children).
+ pub comments_extended: Option<&'a str>,
+}
+
+/// A `.docx` with `body` as the content of `w:body`.
+pub fn docx(body: &str, parts: &Parts<'_>) -> Vec<u8> {
+ let mut files: Vec<(String, String)> = Vec::new();
+ let mut rels = String::from(
+ r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">"#,
+ );
+ let mut overrides = String::new();
+ let mut add = |name: &str, rel_type: &str, id: &str, ct: &str, xml: String| {
+ let rel_type = if rel_type.contains("://") {
+ rel_type.to_owned()
+ } else {
+ format!(
+ "http://schemas.openxmlformats.org/officeDocument/2006/relationships/{rel_type}"
+ )
+ };
+ rels.push_str(&format!(
+ r#"<Relationship Id="{id}" Type="{rel_type}" Target="{name}"/>"#
+ ));
+ overrides.push_str(&format!(
+ r#"<Override PartName="/word/{name}" ContentType="{ct}"/>"#
+ ));
+ files.push((format!("word/{name}"), xml));
+ };
+ let ct = "application/vnd.openxmlformats-officedocument.wordprocessingml.";
+ if let Some(s) = parts.styles {
+ add(
+ "styles.xml",
+ "styles",
+ "rIdS",
+ &format!("{ct}styles+xml"),
+ format!("<w:styles {NS}>{s}</w:styles>"),
+ );
+ }
+ if let Some(s) = parts.numbering {
+ add(
+ "numbering.xml",
+ "numbering",
+ "rIdN",
+ &format!("{ct}numbering+xml"),
+ format!("<w:numbering {NS}>{s}</w:numbering>"),
+ );
+ }
+ if let Some(s) = parts.settings {
+ add(
+ "settings.xml",
+ "settings",
+ "rIdT",
+ &format!("{ct}settings+xml"),
+ format!("<w:settings {NS}>{s}</w:settings>"),
+ );
+ }
+ if let Some(s) = parts.header {
+ add(
+ "header1.xml",
+ "header",
+ "rIdH1",
+ &format!("{ct}header+xml"),
+ format!("<w:hdr {NS}>{s}</w:hdr>"),
+ );
+ }
+ if let Some(s) = parts.footnotes {
+ add(
+ "footnotes.xml",
+ "footnotes",
+ "rIdF",
+ &format!("{ct}footnotes+xml"),
+ format!("<w:footnotes {NS}>{s}</w:footnotes>"),
+ );
+ }
+ if let Some(s) = parts.endnotes {
+ add(
+ "endnotes.xml",
+ "endnotes",
+ "rIdE",
+ &format!("{ct}endnotes+xml"),
+ format!("<w:endnotes {NS}>{s}</w:endnotes>"),
+ );
+ }
+ if let Some(s) = parts.comments {
+ add(
+ "comments.xml",
+ "comments",
+ "rIdC",
+ &format!("{ct}comments+xml"),
+ format!("<w:comments {NS}>{s}</w:comments>"),
+ );
+ }
+ if let Some(s) = parts.comments_extended {
+ add(
+ "commentsExtended.xml",
+ "http://schemas.microsoft.com/office/2011/relationships/commentsExtended",
+ "rIdCX",
+ &format!("{ct}commentsExtended+xml"),
+ format!(
+ r#"<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">{s}</w15:commentsEx>"#
+ ),
+ );
+ }
+ rels.push_str("</Relationships>");
+ let content_types = format!(
+ r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Default Extension="png" ContentType="image/png"/><Override PartName="/word/document.xml" ContentType="{ct}document.main+xml"/>{overrides}</Types>"#
+ );
+ let package_rels = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>"#;
+ let document = format!(
+ r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document {NS}><w:body>{body}</w:body></w:document>"#
+ );
+ let mut w = Writer::new();
+ let entries: Vec<(String, String)> = [
+ ("[Content_Types].xml".to_owned(), content_types),
+ ("_rels/.rels".to_owned(), package_rels.to_owned()),
+ ("word/document.xml".to_owned(), document),
+ ("word/_rels/document.xml.rels".to_owned(), rels),
+ ]
+ .into_iter()
+ .chain(files)
+ .collect();
+ for (name, data) in &entries {
+ w.add(
+ name,
+ WriteData::Fresh {
+ data: data.as_bytes(),
+ compress: true,
+ },
+ )
+ .expect("zip entry");
+ }
+ w.finish().expect("zip")
+}
+
+/// A paragraph anchoring a 200x100pt shape positioned `from` at (x, y)
+/// points, holding the text `text` when given.
+pub fn shape_paragraph(from: &str, x: i64, y: i64, text: Option<&str>) -> String {
+ const EMU: i64 = 12_700;
+ let txbx = text.map_or(String::new(), |t| {
+ format!("<wps:txbx><w:txbxContent><w:p><w:r><w:t>{t}</w:t></w:r></w:p></w:txbxContent></wps:txbx>")
+ });
+ format!(
+ r#"<w:p><w:r><w:drawing><wp:anchor distT="0" distB="0" distL="0" distR="0" simplePos="0" relativeHeight="1" behindDoc="0" locked="0" layoutInCell="1" allowOverlap="1"><wp:simplePos x="0" y="0"/><wp:positionH relativeFrom="{from}"><wp:posOffset>{}</wp:posOffset></wp:positionH><wp:positionV relativeFrom="{from}"><wp:posOffset>{}</wp:posOffset></wp:positionV><wp:extent cx="{}" cy="{}"/><wp:wrapNone/><wp:docPr id="1" name="Box"/><a:graphic><a:graphicData uri="http://schemas.microsoft.com/office/word/2010/wordprocessingShape"><wps:wsp><wps:spPr><a:prstGeom prst="rect"><a:avLst/></a:prstGeom><a:solidFill><a:srgbClr val="FF0000"/></a:solidFill><a:ln w="25400"><a:solidFill><a:srgbClr val="000000"/></a:solidFill></a:ln></wps:spPr>{txbx}<wps:bodyPr/></wps:wsp></a:graphicData></a:graphic></wp:anchor></w:drawing></w:r></w:p>"#,
+ x * EMU,
+ y * EMU,
+ 200 * EMU,
+ 100 * EMU
+ )
+}
+
+/// Where two layouts differ, if they do: page geometry and every item, a
+/// line with its clusters, their positions and run styles.
+pub fn layout_diff(a: &Layout, b: &Layout) -> Option<String> {
+ if a.pages.len() != b.pages.len() {
+ return Some(format!("{} pages, then {}", a.pages.len(), b.pages.len()));
+ }
+ for (i, (pa, pb)) in a.pages.iter().zip(&b.pages).enumerate() {
+ let (ga, gb) = (page_key(pa), page_key(pb));
+ if ga != gb {
+ return Some(format!("page {i}: {ga} then {gb}"));
+ }
+ let lists = [
+ ("behind", &pa.behind, &pb.behind),
+ ("items", &pa.items, &pb.items),
+ ("front", &pa.front, &pb.front),
+ ];
+ for (name, xa, xb) in lists {
+ if xa.len() != xb.len() {
+ return Some(format!(
+ "page {i} {name}: {} items, then {}",
+ xa.len(),
+ xb.len()
+ ));
+ }
+ for (k, (ia, ib)) in xa.iter().zip(xb).enumerate() {
+ let (sa, sb) = (item_key(ia), item_key(ib));
+ if sa != sb {
+ return Some(format!("page {i} {name} {k}: {sa}\nthen\n{sb}"));
+ }
+ }
+ }
+ }
+ None
+}
+
+fn page_key(p: &Page) -> String {
+ format!(
+ "{:?} {:?} {:?} {:?} {:?} {:?} {:?}",
+ p.width, p.height, p.section, p.number, p.body, p.header, p.footer
+ )
+}
+
+fn item_key(item: &Item) -> String {
+ match item {
+ Item::Line(l) => line_key(l),
+ Item::Drawing(d) => drawing_key(d),
+ other => format!("{other:?}"),
+ }
+}
+
+fn line_key(l: &PlacedLine) -> String {
+ let pb = &l.para;
+ let line = l.line();
+ let mut out = format!(
+ "{:?} {:?} line {} at ({:?}, {:?}) clip {:?} {line:?}",
+ pb.story, pb.block, l.line, l.x, l.y, l.clip
+ );
+ for c in line.start..line.end {
+ let cl = &pb.inline.clusters[c];
+ out.push_str(&format!(
+ "\n{cl:?} x {:?} adv {:?} run {:?} level {:?}",
+ pb.lines.x.get(c),
+ pb.lines.adv.get(c),
+ pb.inline.runs.get(usize::from(cl.run)),
+ pb.inline.levels.get(c)
+ ));
+ }
+ let leaders: Vec<_> = pb
+ .lines
+ .leaders
+ .iter()
+ .filter(|(c, _)| (line.start..line.end).contains(c))
+ .collect();
+ out.push_str(&format!("\nleaders {leaders:?}"));
+ out
+}
+
+fn drawing_key(d: &PlacedDrawing) -> String {
+ let g = &d.drawing;
+ format!(
+ "drawing {:?} {:?} {:?} {:?} {:?} {:?} {:?} {:?}",
+ d.rect, d.story, g.width, g.height, g.effect, g.anchor, g.node, g.vml
+ )
+}
diff --git a/crates/docx_engine/src/units.rs b/crates/docx_engine/src/units.rs
new file mode 100644
index 0000000000..54dee49c62
--- /dev/null
+++ b/crates/docx_engine/src/units.rs
@@ -0,0 +1,34 @@
+//! Unit conversions. Layout works in points (1/72 inch).
+
+/// Twentieths of a point (twips) → points.
+pub fn twips(v: i64) -> f32 {
+ v as f32 / 20.0
+}
+
+/// Half-points (font sizes) → points.
+pub fn half_points(v: i64) -> f32 {
+ v as f32 / 2.0
+}
+
+/// Eighths of a point (border widths) → points.
+pub fn eighth_points(v: i64) -> f32 {
+ v as f32 / 8.0
+}
+
+/// EMU → points.
+pub fn emu(v: i64) -> f32 {
+ (v as f64 / 12_700.0) as f32
+}
+
+/// Points → twips (rounded).
+pub fn to_twips(pt: f32) -> i64 {
+ (f64::from(pt) * 20.0).round() as i64
+}
+
+/// Points → EMU (rounded).
+pub fn to_emu(pt: f32) -> i64 {
+ (f64::from(pt) * 12_700.0).round() as i64
+}
+
+/// Points per CSS pixel (96 DPI).
+pub const PT_PER_PX: f32 = 0.75;
diff --git a/crates/docx_engine/src/wasm.rs b/crates/docx_engine/src/wasm.rs
new file mode 100644
index 0000000000..53e1de5c95
--- /dev/null
+++ b/crates/docx_engine/src/wasm.rs
@@ -0,0 +1,321 @@
+//! The WebAssembly API used by the browser editor's worker.
+//!
+//! Structured values cross the boundary as JSON strings (parsed once on the
+//! JavaScript side) and pixels as straight-alpha RGBA bytes ready for
+//! `ImageData`. Positions and sizes are in points.
+
+use crate::Document;
+use crate::collab::{CollabState, V1State};
+use crate::edit::{EditOp, FindOptions, Pos, RemoteChange, Session};
+use crate::render::ImageCache;
+use pptx_engine::font::FontDb;
+use serde::Serialize;
+use std::cell::RefCell;
+use wasm_bindgen::prelude::*;
+
+thread_local! {
+ /// Fonts shared by every open document (the bundled set plus registered extras).
+ static FONTS: RefCell<FontDb> = RefCell::new(bundled_fonts());
+}
+
+fn bundled_fonts() -> FontDb {
+ let mut db = FontDb::new();
+ for data in pptx_engine::font::embedded::FONTS {
+ db.register(data.to_vec());
+ }
+ db
+}
+
+fn js_err(e: impl std::fmt::Display) -> JsError {
+ JsError::new(&e.to_string())
+}
+
+fn to_json(v: &impl Serialize) -> Result<String, JsError> {
+ serde_json::to_string(v).map_err(js_err)
+}
+
+/// Registers an extra font file (TTF, OTF, or TTC) for every document.
+/// The current time as Word writes revision dates (whole seconds, UTC).
+fn now_iso() -> String {
+ let iso: String = js_sys::Date::new_0().to_iso_string().into();
+ match iso.split_once('.') {
+ Some((head, _)) => format!("{head}Z"),
+ None => iso,
+ }
+}
+
+#[wasm_bindgen(js_name = registerFont)]
+pub fn register_font(bytes: Vec<u8>) -> usize {
+ FONTS.with(|f| f.borrow_mut().register(bytes).len())
+}
+
+/// A paragraph style offered in the style picker.
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct StyleInfo {
+ id: String,
+ name: String,
+ quick: bool,
+ priority: i64,
+}
+
+/// An open document with its editing session.
+#[wasm_bindgen]
+pub struct DocxDocument {
+ session: Session,
+ images: ImageCache,
+}
+
+impl DocxDocument {
+ fn wrap(session: Session) -> Self {
+ Self {
+ session,
+ images: ImageCache::new(),
+ }
+ }
+}
+
+#[wasm_bindgen]
+impl DocxDocument {
+ /// Opens a `.docx` file.
+ #[wasm_bindgen(constructor)]
+ pub fn new(bytes: Vec<u8>) -> Result<DocxDocument, JsError> {
+ console_error_panic_hook::set_once();
+ let doc = Document::open(bytes).map_err(js_err)?;
+ Ok(Self::wrap(Session::new(doc)))
+ }
+
+ /// Opens the document shared state describes (`CollabState` JSON).
+ /// `seed` makes this peer's new ids unique.
+ #[wasm_bindgen(js_name = fromCollab)]
+ pub fn from_collab(state: &str, seed: f64) -> Result<DocxDocument, JsError> {
+ console_error_panic_hook::set_once();
+ let state: CollabState = serde_json::from_str(state).map_err(js_err)?;
+ let session = Session::from_collab(&state, seed as u64).map_err(js_err)?;
+ Ok(Self::wrap(session))
+ }
+
+ /// Opens a document stored in the first shared format (`V1State` JSON).
+ #[wasm_bindgen(js_name = fromV1)]
+ pub fn from_v1(state: &str) -> Result<DocxDocument, JsError> {
+ console_error_panic_hook::set_once();
+ let state: V1State = serde_json::from_str(state).map_err(js_err)?;
+ let doc = Document::from_v1(&state).map_err(js_err)?;
+ Ok(Self::wrap(Session::new(doc)))
+ }
+
+ /// The shared state of the document (`CollabState` JSON).
+ #[wasm_bindgen(js_name = collabState)]
+ pub fn collab_state(&self) -> Result<String, JsError> {
+ to_json(&self.session.collab_state().map_err(js_err)?)
+ }
+
+ /// Leaves undo history to the caller (the shared document's).
+ #[wasm_bindgen(js_name = setExternalUndo)]
+ pub fn set_external_undo(&mut self, external: bool) {
+ self.session.set_external_undo(external);
+ }
+
+ /// The name tracked changes are recorded under.
+ #[wasm_bindgen(js_name = setAuthor)]
+ pub fn set_author(&mut self, author: &str) {
+ self.session.set_author(author);
+ }
+
+ /// Applies a JSON array of operations; returns the `EditResult` JSON.
+ /// Batches with the same `group` merge into one undo step (typing).
+ pub fn apply(&mut self, ops: &str, group: Option<String>) -> Result<String, JsError> {
+ let ops: Vec<EditOp> = serde_json::from_str(ops).map_err(js_err)?;
+ self.session.set_now(&now_iso());
+ let result = FONTS
+ .with(|f| self.session.apply(&ops, group.as_deref(), &f.borrow()))
+ .map_err(js_err)?;
+ to_json(&result)
+ }
+
+ /// Applies other peers' changes (`RemoteChange[]` JSON); returns the
+ /// `EditResult` JSON.
+ #[wasm_bindgen(js_name = applyRemote)]
+ pub fn apply_remote(&mut self, changes: &str) -> Result<String, JsError> {
+ let changes: Vec<RemoteChange> = serde_json::from_str(changes).map_err(js_err)?;
+ let result = FONTS
+ .with(|f| self.session.apply_remote(&changes, &f.borrow()))
+ .map_err(js_err)?;
+ to_json(&result)
+ }
+
+ /// The selection, its geometry and the pages (`EditResult` JSON).
+ pub fn state(&mut self) -> Result<String, JsError> {
+ let result = FONTS.with(|f| self.session.state(&f.borrow()));
+ to_json(&result)
+ }
+
+ /// Pages with sizes and fingerprints (`PageInfo[]` JSON).
+ pub fn pages(&mut self) -> Result<String, JsError> {
+ let pages = FONTS.with(|f| self.session.pages(&f.borrow()));
+ to_json(&pages)
+ }
+
+ /// Renders a page; returns straight-alpha RGBA rows (`width × height × 4`).
+ pub fn render(&mut self, page: usize, width: u32) -> Result<Vec<u8>, JsError> {
+ let width = width.clamp(16, 8192);
+ FONTS.with(|f| {
+ let fonts = f.borrow();
+ let layout = self.session.layout(&fonts);
+ let raster = self
+ .session
+ .document()
+ .render_page(&layout, page, width, &fonts, &mut self.images)
+ .ok_or_else(|| JsError::new("no such page"))?;
+ Ok(raster.to_straight_rgba())
+ })
+ }
+
+ /// The position at a point on a page (`Pos` JSON or `null`).
+ #[wasm_bindgen(js_name = hitTest)]
+ pub fn hit_test(&mut self, page: usize, x: f32, y: f32) -> Result<String, JsError> {
+ let pos = FONTS.with(|f| self.session.hit_test(page, x, y, &f.borrow()));
+ to_json(&pos)
+ }
+
+ /// The caret rectangle for a position (`CaretRect` JSON or `null`).
+ #[wasm_bindgen(js_name = caretAt)]
+ pub fn caret_at(&mut self, pos: &str) -> Result<String, JsError> {
+ let pos: Pos = serde_json::from_str(pos).map_err(js_err)?;
+ let caret = FONTS.with(|f| self.session.caret_at(&pos, &f.borrow()));
+ to_json(&caret)
+ }
+
+ /// Highlight rectangles between two positions (`PageRect[]` JSON).
+ #[wasm_bindgen(js_name = rangeRects)]
+ pub fn range_rects(&mut self, from: &str, to: &str) -> Result<String, JsError> {
+ let a: Pos = serde_json::from_str(from).map_err(js_err)?;
+ let b: Pos = serde_json::from_str(to).map_err(js_err)?;
+ let rects = FONTS.with(|f| self.session.range_rects(&a, &b, &f.borrow()));
+ to_json(&rects)
+ }
+
+ /// The selection for the clipboard (`Clip` JSON: paragraphs, HTML, text).
+ #[wasm_bindgen(js_name = copySelection)]
+ pub fn copy_selection(&mut self) -> Result<String, JsError> {
+ to_json(&self.session.copy_selection())
+ }
+
+ /// The matches of a search in the body (`FindResult` JSON); `options`
+ /// is `FindOptions` JSON.
+ pub fn find(&mut self, query: &str, options: &str) -> Result<String, JsError> {
+ let options: FindOptions = serde_json::from_str(options).map_err(js_err)?;
+ let result = FONTS.with(|f| self.session.find(query, &options, &f.borrow()));
+ to_json(&result)
+ }
+
+ /// The selected text, for the clipboard.
+ #[wasm_bindgen(js_name = selectedText)]
+ pub fn selected_text(&mut self) -> String {
+ self.session.selected_text()
+ }
+
+ /// The comments stored in the document, Word's (`DocComment[]` JSON).
+ #[wasm_bindgen(js_name = documentComments)]
+ pub fn document_comments(&self) -> Result<String, JsError> {
+ to_json(&self.session.document_comments())
+ }
+
+ /// Paragraph ids and texts in document order (`ParagraphText[]` JSON).
+ pub fn paragraphs(&self) -> Result<String, JsError> {
+ to_json(&self.session.paragraphs())
+ }
+
+ /// Paragraph styles for the style picker (JSON).
+ pub fn styles(&self) -> Result<String, JsError> {
+ let styles = &self.session.document().parts().styles;
+ let mut out: Vec<StyleInfo> = styles
+ .all()
+ .filter(|s| s.kind == crate::model::styles::StyleKind::Paragraph && !s.hidden)
+ .map(|s| StyleInfo {
+ id: s.id.clone(),
+ name: s.name.clone(),
+ quick: s.q_format,
+ priority: s.ui_priority.unwrap_or(99),
+ })
+ .collect();
+ out.sort_by(|a, b| (a.priority, &a.name).cmp(&(b.priority, &b.name)));
+ to_json(&out)
+ }
+
+ /// Shows tracked changes inline (`true`) or the final text; returns the
+ /// `EditResult` JSON.
+ #[wasm_bindgen(js_name = setMarkup)]
+ pub fn set_markup(&mut self, markup: bool) -> Result<String, JsError> {
+ self.session.set_markup(markup);
+ self.state()
+ }
+
+ /// Renders a strip of a page (`top..bottom` in points) at the page width
+ /// `width`; returns straight-alpha RGBA rows.
+ #[wasm_bindgen(js_name = renderBand)]
+ pub fn render_band(
+ &mut self,
+ page: usize,
+ width: u32,
+ top: f32,
+ bottom: f32,
+ ) -> Result<Vec<u8>, JsError> {
+ let width = width.clamp(16, 8192);
+ FONTS.with(|f| {
+ let fonts = f.borrow();
+ let layout = self.session.layout(&fonts);
+ let raster = self
+ .session
+ .document()
+ .render_band(&layout, page, width, top, bottom, &fonts, &mut self.images)
+ .ok_or_else(|| JsError::new("no such page"))?;
+ Ok(raster.to_straight_rgba())
+ })
+ }
+
+ /// Ends the current typing group.
+ #[wasm_bindgen(js_name = breakGroup)]
+ pub fn break_group(&mut self) {
+ self.session.break_group();
+ }
+
+ /// Undoes one step (`EditResult` JSON), or `None` when there is none.
+ pub fn undo(&mut self) -> Result<Option<String>, JsError> {
+ FONTS
+ .with(|f| self.session.undo(&f.borrow()))
+ .map(|r| to_json(&r))
+ .transpose()
+ }
+
+ /// Redoes one step.
+ pub fn redo(&mut self) -> Result<Option<String>, JsError> {
+ FONTS
+ .with(|f| self.session.redo(&f.borrow()))
+ .map(|r| to_json(&r))
+ .transpose()
+ }
+
+ /// Whether undo is possible.
+ #[wasm_bindgen(js_name = canUndo)]
+ pub fn can_undo(&self) -> bool {
+ self.session.can_undo()
+ }
+
+ /// Whether redo is possible.
+ #[wasm_bindgen(js_name = canRedo)]
+ pub fn can_redo(&self) -> bool {
+ self.session.can_redo()
+ }
+
+ /// Serializes the current state to `.docx` bytes.
+ pub fn save(&mut self) -> Result<Vec<u8>, JsError> {
+ self.session.save().map_err(js_err)
+ }
+
+ /// Font families the document asked for that are not available (JSON array).
+ #[wasm_bindgen(js_name = missingFonts)]
+ pub fn missing_fonts(&self) -> Result<String, JsError> {
+ FONTS.with(|f| to_json(&f.borrow().missing_families()))
+ }
+}
diff --git a/crates/docx_engine/src/xml.rs b/crates/docx_engine/src/xml.rs
new file mode 100644
index 0000000000..04933a6e32
--- /dev/null
+++ b/crates/docx_engine/src/xml.rs
@@ -0,0 +1,836 @@
+//! A compact XML reader for WordprocessingML parts.
+//!
+//! Parts are parsed into a read-only tree that remembers where every element
+//! came from in the source text, so any subtree can be copied out verbatim
+//! (with the prefixes its producer chose). The document model keeps such
+//! snippets for everything it does not interpret, which is what makes saving
+//! lossless. Element and attribute names are resolved to [`Ns`] identifiers,
+//! so lookups never depend on prefixes.
+
+mod escape;
+mod ns;
+
+use crate::error::{Error, Result};
+pub use escape::{escape_attr, escape_text};
+pub use ns::Ns;
+use std::ops::Range;
+
+/// Index of a node in an [`XmlTree`].
+pub type NodeId = u32;
+
+/// One attribute of an element.
+#[derive(Clone, Debug)]
+pub struct Attr {
+ /// Namespace (`Ns::NONE` for unprefixed attributes).
+ pub ns: Ns,
+ /// Local name.
+ pub local: Box<str>,
+ /// Qualified name as written.
+ pub qname: Box<str>,
+ /// Decoded value.
+ pub value: Box<str>,
+}
+
+#[derive(Clone, Debug)]
+enum Kind {
+ Element {
+ ns: Ns,
+ local: Box<str>,
+ qname: Box<str>,
+ attrs: Vec<Attr>,
+ children: Vec<NodeId>,
+ /// Byte offset just past the start tag.
+ start_tag_end: u32,
+ },
+ Text(String),
+ /// Comments, processing instructions: kept only for spans.
+ Other,
+}
+
+#[derive(Clone, Debug)]
+struct Node {
+ kind: Kind,
+ parent: NodeId,
+ /// Byte range of the node in the source.
+ start: u32,
+ end: u32,
+}
+
+/// A namespace declaration (`xmlns:prefix="uri"`; empty prefix = default).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Decl {
+ /// Declared prefix (`""` for the default namespace).
+ pub prefix: String,
+ /// Namespace URI.
+ pub uri: String,
+}
+
+/// A parsed XML part.
+#[derive(Clone, Debug)]
+pub struct XmlTree {
+ src: String,
+ nodes: Vec<Node>,
+ root: NodeId,
+ dynamic: Vec<String>,
+ /// Declarations made on the root element, in order.
+ root_decls: Vec<Decl>,
+ /// Declarations made below the root: (element, declaration).
+ inner_decls: Vec<(NodeId, Decl)>,
+}
+
+/// Deepest nesting accepted (real documents stay far below).
+const MAX_DEPTH: usize = 512;
+/// Sentinel parent of the root.
+const NO_PARENT: NodeId = NodeId::MAX;
+
+fn decode_source(bytes: &[u8]) -> String {
+ if let Some(rest) = bytes.strip_prefix(&[0xEF, 0xBB, 0xBF]) {
+ return String::from_utf8_lossy(rest).into_owned();
+ }
+ let utf16 = |le: bool, body: &[u8]| -> String {
+ let units = body.chunks_exact(2).map(|c| {
+ if le {
+ u16::from_le_bytes([c[0], c[1]])
+ } else {
+ u16::from_be_bytes([c[0], c[1]])
+ }
+ });
+ char::decode_utf16(units)
+ .map(|r| r.unwrap_or('\u{FFFD}'))
+ .collect()
+ };
+ if let Some(rest) = bytes.strip_prefix(&[0xFF, 0xFE]) {
+ return utf16(true, rest);
+ }
+ if let Some(rest) = bytes.strip_prefix(&[0xFE, 0xFF]) {
+ return utf16(false, rest);
+ }
+ if bytes.starts_with(&[b'<', 0]) {
+ return utf16(true, bytes);
+ }
+ if bytes.starts_with(&[0, b'<']) {
+ return utf16(false, bytes);
+ }
+ String::from_utf8_lossy(bytes).into_owned()
+}
+
+struct Binding {
+ prefix: Box<str>,
+ ns: Ns,
+}
+
+struct Parser<'a> {
+ s: &'a str,
+ b: &'a [u8],
+ pos: usize,
+ part: &'a str,
+ tree: XmlTree,
+ scope: Vec<Binding>,
+}
+
+impl XmlTree {
+ /// Parses `bytes` (UTF-8 or UTF-16 with a byte order mark).
+ /// `part` names the source in error messages.
+ pub fn parse(bytes: &[u8], part: &str) -> Result<Self> {
+ Self::parse_str(decode_source(bytes), part)
+ }
+
+ /// Parses XML text.
+ pub fn parse_str(src: String, part: &str) -> Result<Self> {
+ let tree = XmlTree {
+ src: String::new(),
+ nodes: Vec::new(),
+ root: 0,
+ dynamic: Vec::new(),
+ root_decls: Vec::new(),
+ inner_decls: Vec::new(),
+ };
+ let mut p = Parser {
+ s: &src,
+ b: src.as_bytes(),
+ pos: 0,
+ part,
+ tree,
+ scope: Vec::new(),
+ };
+ p.skip_misc()?;
+ if p.pos >= p.b.len() || p.b[p.pos] != b'<' {
+ return Err(p.err("no root element"));
+ }
+ let root = p.element(NO_PARENT, 0)?;
+ p.tree.root = root;
+ let mut tree = p.tree;
+ tree.src = src;
+ Ok(tree)
+ }
+
+ /// Parses a standalone snippet, resolving prefixes it does not declare
+ /// against `context` (normally the declarations of the part's root).
+ pub fn parse_snippet(snippet: &str, context: &[Decl]) -> Result<Self> {
+ SnippetContext::new(context).parse(snippet)
+ }
+
+ /// The root element.
+ pub fn root(&self) -> NodeId {
+ self.root
+ }
+
+ /// The full source text.
+ pub fn source(&self) -> &str {
+ &self.src
+ }
+
+ /// Declarations made on the root element.
+ pub fn root_decls(&self) -> &[Decl] {
+ &self.root_decls
+ }
+
+ fn node(&self, id: NodeId) -> &Node {
+ &self.nodes[id as usize]
+ }
+
+ /// Whether the node is an element.
+ pub fn is_element(&self, id: NodeId) -> bool {
+ matches!(self.node(id).kind, Kind::Element { .. })
+ }
+
+ /// Text of a text node (`None` for elements).
+ pub fn text_node(&self, id: NodeId) -> Option<&str> {
+ match &self.node(id).kind {
+ Kind::Text(t) => Some(t),
+ _ => None,
+ }
+ }
+
+ /// Namespace of an element (`Ns::NONE` for other nodes).
+ pub fn ns(&self, id: NodeId) -> Ns {
+ match &self.node(id).kind {
+ Kind::Element { ns, .. } => *ns,
+ _ => Ns::NONE,
+ }
+ }
+
+ /// Local name of an element (empty for other nodes).
+ pub fn local(&self, id: NodeId) -> &str {
+ match &self.node(id).kind {
+ Kind::Element { local, .. } => local,
+ _ => "",
+ }
+ }
+
+ /// Qualified name as written.
+ pub fn qname(&self, id: NodeId) -> &str {
+ match &self.node(id).kind {
+ Kind::Element { qname, .. } => qname,
+ _ => "",
+ }
+ }
+
+ /// Whether `id` is the element `(ns, local)`.
+ pub fn is(&self, id: NodeId, ns: Ns, local: &str) -> bool {
+ match &self.node(id).kind {
+ Kind::Element {
+ ns: n, local: l, ..
+ } => *n == ns && &**l == local,
+ _ => false,
+ }
+ }
+
+ /// Whether `id` is a WordprocessingML element named `local`.
+ pub fn is_w(&self, id: NodeId, local: &str) -> bool {
+ self.is(id, Ns::W, local)
+ }
+
+ /// Parent element (`None` for the root).
+ pub fn parent(&self, id: NodeId) -> Option<NodeId> {
+ let p = self.node(id).parent;
+ (p != NO_PARENT).then_some(p)
+ }
+
+ /// All child nodes, including text.
+ pub fn child_nodes(&self, id: NodeId) -> &[NodeId] {
+ match &self.node(id).kind {
+ Kind::Element { children, .. } => children,
+ _ => &[],
+ }
+ }
+
+ /// Child elements in document order.
+ pub fn children(&self, id: NodeId) -> impl Iterator<Item = NodeId> + '_ {
+ self.child_nodes(id)
+ .iter()
+ .copied()
+ .filter(|&c| self.is_element(c))
+ }
+
+ /// The first child element named `(ns, local)`.
+ pub fn child(&self, id: NodeId, ns: Ns, local: &str) -> Option<NodeId> {
+ self.children(id).find(|&c| self.is(c, ns, local))
+ }
+
+ /// The first `w:` child named `local`.
+ pub fn w_child(&self, id: NodeId, local: &str) -> Option<NodeId> {
+ self.child(id, Ns::W, local)
+ }
+
+ /// Child elements named `(ns, local)`.
+ pub fn children_named<'a>(
+ &'a self,
+ id: NodeId,
+ ns: Ns,
+ local: &'a str,
+ ) -> impl Iterator<Item = NodeId> + 'a {
+ self.children(id).filter(move |&c| self.is(c, ns, local))
+ }
+
+ /// Attributes of an element (namespace declarations excluded).
+ pub fn attrs(&self, id: NodeId) -> &[Attr] {
+ match &self.node(id).kind {
+ Kind::Element { attrs, .. } => attrs,
+ _ => &[],
+ }
+ }
+
+ /// Value of attribute `(ns, local)`.
+ pub fn attr(&self, id: NodeId, ns: Ns, local: &str) -> Option<&str> {
+ self.attrs(id)
+ .iter()
+ .find(|a| a.ns == ns && &*a.local == local)
+ .map(|a| &*a.value)
+ }
+
+ /// Value of the `w:` attribute `local` (falling back to an unprefixed one,
+ /// which some producers write).
+ pub fn w_attr(&self, id: NodeId, local: &str) -> Option<&str> {
+ self.attr(id, Ns::W, local)
+ .or_else(|| self.attr(id, Ns::NONE, local))
+ }
+
+ /// `w:val` of the element.
+ pub fn val(&self, id: NodeId) -> Option<&str> {
+ self.w_attr(id, "val")
+ }
+
+ /// `w:val` of the `w:` child `local`.
+ pub fn child_val(&self, id: NodeId, local: &str) -> Option<&str> {
+ self.w_child(id, local).and_then(|c| self.val(c))
+ }
+
+ /// Concatenated text of all descendant text nodes.
+ pub fn text(&self, id: NodeId) -> String {
+ let mut out = String::new();
+ self.collect_text(id, &mut out);
+ out
+ }
+
+ fn collect_text(&self, id: NodeId, out: &mut String) {
+ match &self.node(id).kind {
+ Kind::Text(t) => out.push_str(t),
+ Kind::Element { children, .. } => {
+ for &c in children {
+ self.collect_text(c, out);
+ }
+ }
+ Kind::Other => {}
+ }
+ }
+
+ /// Byte range of a node in the source.
+ pub fn span(&self, id: NodeId) -> Range<usize> {
+ let n = self.node(id);
+ n.start as usize..n.end as usize
+ }
+
+ /// The node's exact source text.
+ pub fn raw(&self, id: NodeId) -> &str {
+ &self.src[self.span(id)]
+ }
+
+ /// The element's start tag as written (`<w:p w:rsidR="...">`).
+ pub fn start_tag(&self, id: NodeId) -> &str {
+ match &self.node(id).kind {
+ Kind::Element { start_tag_end, .. } => {
+ &self.src[self.node(id).start as usize..*start_tag_end as usize]
+ }
+ _ => "",
+ }
+ }
+
+ /// The text between an element's name and the end of its start tag:
+ /// its attributes as written, with a leading space (empty when none).
+ pub fn raw_attrs(&self, id: NodeId) -> &str {
+ let tag = self.start_tag(id);
+ let qname = self.qname(id);
+ let rest = &tag[1 + qname.len().min(tag.len().saturating_sub(1))..];
+ let rest = rest.strip_suffix("/>").or_else(|| rest.strip_suffix('>'));
+ rest.unwrap_or("").trim_end()
+ }
+
+ /// The element's source text, made standalone: declarations that an
+ /// ancestor below the root made, and that the snippet relies on, are
+ /// copied onto its start tag. Root declarations are left implicit (the
+ /// snippet is always read back in the context of its part's root).
+ pub fn snippet(&self, id: NodeId) -> String {
+ let raw = self.raw(id);
+ if self.inner_decls.is_empty() {
+ return raw.to_owned();
+ }
+ let mut extra: Vec<&Decl> = Vec::new();
+ let mut at = self.parent(id);
+ while let Some(a) = at {
+ if a == self.root {
+ break;
+ }
+ for (owner, d) in &self.inner_decls {
+ if *owner == a
+ && !extra.iter().any(|e| e.prefix == d.prefix)
+ && uses_prefix(raw, &d.prefix)
+ && !declares_prefix(self.start_tag(id), &d.prefix)
+ {
+ extra.push(d);
+ }
+ }
+ at = self.parent(a);
+ }
+ if extra.is_empty() {
+ return raw.to_owned();
+ }
+ let qname_end = 1 + self.qname(id).len();
+ let mut out = String::with_capacity(raw.len() + 80 * extra.len());
+ out.push_str(&raw[..qname_end]);
+ for d in extra {
+ if d.prefix.is_empty() {
+ out.push_str(" xmlns=\"");
+ } else {
+ out.push_str(" xmlns:");
+ out.push_str(&d.prefix);
+ out.push_str("=\"");
+ }
+ escape_attr(&mut out, &d.uri);
+ out.push('"');
+ }
+ out.push_str(&raw[qname_end..]);
+ out
+ }
+
+ /// The URI of a namespace identifier.
+ pub fn ns_uri(&self, ns: Ns) -> Option<&str> {
+ if ns.0 >= Ns::FIRST_DYNAMIC {
+ return self
+ .dynamic
+ .get(usize::from(ns.0 - Ns::FIRST_DYNAMIC))
+ .map(String::as_str);
+ }
+ ns::uri_of(ns)
+ }
+
+ /// Descendant elements in document order (pre-order, excluding `id`).
+ pub fn descendants(&self, id: NodeId) -> Vec<NodeId> {
+ let mut out = Vec::new();
+ let mut stack: Vec<NodeId> = self.children(id).collect();
+ stack.reverse();
+ while let Some(n) = stack.pop() {
+ out.push(n);
+ let before = stack.len();
+ stack.extend(self.children(n));
+ stack[before..].reverse();
+ }
+ out
+ }
+
+ /// The first descendant named `(ns, local)`.
+ pub fn find(&self, id: NodeId, ns: Ns, local: &str) -> Option<NodeId> {
+ let mut stack: Vec<NodeId> = self.children(id).collect();
+ stack.reverse();
+ while let Some(n) = stack.pop() {
+ if self.is(n, ns, local) {
+ return Some(n);
+ }
+ let before = stack.len();
+ stack.extend(self.children(n));
+ stack[before..].reverse();
+ }
+ None
+ }
+
+ fn intern(&mut self, uri: &str) -> Ns {
+ if uri.is_empty() {
+ return Ns::NONE;
+ }
+ if let Some(ns) = ns::known(uri) {
+ return ns;
+ }
+ if let Some(i) = self.dynamic.iter().position(|u| u == uri) {
+ return Ns(Ns::FIRST_DYNAMIC + i as u16);
+ }
+ self.dynamic.push(uri.to_owned());
+ Ns(Ns::FIRST_DYNAMIC + (self.dynamic.len() - 1) as u16)
+ }
+}
+
+/// Parses snippets in the context of a part's root declarations, reusing
+/// the synthetic wrapper that carries them.
+#[derive(Clone, Debug)]
+pub struct SnippetContext {
+ open: String,
+ decls: Vec<Decl>,
+}
+
+impl SnippetContext {
+ /// A context for `decls`.
+ pub fn new(decls: &[Decl]) -> Self {
+ let mut open = String::with_capacity(64 * decls.len() + 8);
+ open.push_str("<_x");
+ for d in decls {
+ if d.prefix.is_empty() {
+ open.push_str(" xmlns=\"");
+ } else {
+ open.push_str(" xmlns:");
+ open.push_str(&d.prefix);
+ open.push_str("=\"");
+ }
+ escape_attr(&mut open, &d.uri);
+ open.push('"');
+ }
+ open.push('>');
+ Self {
+ open,
+ decls: decls.to_vec(),
+ }
+ }
+
+ /// Parses one snippet (a single element).
+ pub fn parse(&self, snippet: &str) -> Result<XmlTree> {
+ let mut wrapped = String::with_capacity(self.open.len() + snippet.len() + 6);
+ wrapped.push_str(&self.open);
+ wrapped.push_str(snippet);
+ wrapped.push_str("</_x>");
+ let mut tree = XmlTree::parse_str(wrapped, "snippet")?;
+ let inner = tree.children(tree.root).next().ok_or_else(|| Error::Xml {
+ part: "snippet".into(),
+ message: "empty snippet".into(),
+ })?;
+ tree.root = inner;
+ tree.root_decls = self.decls.clone();
+ Ok(tree)
+ }
+
+ /// Parses a sequence of sibling elements; returns the tree and their ids.
+ pub fn parse_many(&self, snippets: &str) -> Result<(XmlTree, Vec<NodeId>)> {
+ let mut wrapped = String::with_capacity(self.open.len() + snippets.len() + 6);
+ wrapped.push_str(&self.open);
+ wrapped.push_str(snippets);
+ wrapped.push_str("</_x>");
+ let mut tree = XmlTree::parse_str(wrapped, "snippet")?;
+ let kids: Vec<NodeId> = tree.children(tree.root).collect();
+ tree.root_decls = self.decls.clone();
+ Ok((tree, kids))
+ }
+}
+
+fn uses_prefix(raw: &str, prefix: &str) -> bool {
+ if prefix.is_empty() {
+ return true;
+ }
+ let needle = format!("{prefix}:");
+ raw.match_indices(&needle).any(|(i, _)| {
+ i > 0 && {
+ let before = raw.as_bytes()[i - 1];
+ before == b'<' || before == b'/' || before.is_ascii_whitespace() || before == b'"'
+ }
+ })
+}
+
+fn declares_prefix(start_tag: &str, prefix: &str) -> bool {
+ if prefix.is_empty() {
+ start_tag.contains(" xmlns=")
+ } else {
+ start_tag.contains(&format!("xmlns:{prefix}="))
+ }
+}
+
+fn is_name_char(c: u8) -> bool {
+ c.is_ascii_alphanumeric() || matches!(c, b'_' | b'-' | b'.' | b':') || c >= 0x80
+}
+
+impl Parser<'_> {
+ fn err(&self, message: &str) -> Error {
+ Error::Xml {
+ part: self.part.to_owned(),
+ message: format!("{message} at byte {}", self.pos),
+ }
+ }
+
+ fn skip_ws(&mut self) {
+ while self.pos < self.b.len() && self.b[self.pos].is_ascii_whitespace() {
+ self.pos += 1;
+ }
+ }
+
+ /// Skips the prolog: declaration, comments, PIs, doctype, whitespace.
+ fn skip_misc(&mut self) -> Result<()> {
+ loop {
+ self.skip_ws();
+ let rest = &self.s[self.pos..];
+ if rest.starts_with("<?") {
+ let end = rest.find("?>").ok_or_else(|| self.err("unterminated PI"))?;
+ self.pos += end + 2;
+ } else if let Some(comment) = rest.strip_prefix("<!--") {
+ let end = comment
+ .find("-->")
+ .ok_or_else(|| self.err("unterminated comment"))?;
+ self.pos += end + 7;
+ } else if rest.starts_with("<!DOCTYPE") || rest.starts_with("<!doctype") {
+ let mut depth = 0i32;
+ let mut i = self.pos;
+ while i < self.b.len() {
+ match self.b[i] {
+ b'[' => depth += 1,
+ b']' => depth -= 1,
+ b'>' if depth <= 0 => break,
+ _ => {}
+ }
+ i += 1;
+ }
+ self.pos = (i + 1).min(self.b.len());
+ } else {
+ return Ok(());
+ }
+ }
+ }
+
+ fn name(&mut self) -> Result<&str> {
+ let start = self.pos;
+ while self.pos < self.b.len() && is_name_char(self.b[self.pos]) {
+ self.pos += 1;
+ }
+ if self.pos == start {
+ return Err(self.err("expected a name"));
+ }
+ Ok(&self.s[start..self.pos])
+ }
+
+ fn resolve(&self, prefix: &str) -> Option<Ns> {
+ self.scope
+ .iter()
+ .rev()
+ .find(|b| &*b.prefix == prefix)
+ .map(|b| b.ns)
+ }
+
+ fn push(&mut self, kind: Kind, parent: NodeId, start: usize, end: usize) -> NodeId {
+ let id = self.tree.nodes.len() as NodeId;
+ self.tree.nodes.push(Node {
+ kind,
+ parent,
+ start: start as u32,
+ end: end as u32,
+ });
+ id
+ }
+
+ fn element(&mut self, parent: NodeId, depth: usize) -> Result<NodeId> {
+ if depth > MAX_DEPTH {
+ return Err(self.err("elements nested too deeply"));
+ }
+ let start = self.pos;
+ self.pos += 1; // '<'
+ let qname: Box<str> = self.name()?.into();
+ let scope_len = self.scope.len();
+ let mut raw_attrs: Vec<(Box<str>, Box<str>)> = Vec::new();
+ let self_closing;
+ loop {
+ self.skip_ws();
+ match self.b.get(self.pos) {
+ Some(b'/') => {
+ if self.b.get(self.pos + 1) != Some(&b'>') {
+ return Err(self.err("expected '/>'"));
+ }
+ self.pos += 2;
+ self_closing = true;
+ break;
+ }
+ Some(b'>') => {
+ self.pos += 1;
+ self_closing = false;
+ break;
+ }
+ Some(_) => {
+ let name: Box<str> = self.name()?.into();
+ self.skip_ws();
+ if self.b.get(self.pos) != Some(&b'=') {
+ return Err(self.err("expected '='"));
+ }
+ self.pos += 1;
+ self.skip_ws();
+ let quote = *self.b.get(self.pos).ok_or_else(|| self.err("eof"))?;
+ if quote != b'"' && quote != b'\'' {
+ return Err(self.err("expected a quoted value"));
+ }
+ self.pos += 1;
+ let vstart = self.pos;
+ while self.pos < self.b.len() && self.b[self.pos] != quote {
+ self.pos += 1;
+ }
+ if self.pos >= self.b.len() {
+ return Err(self.err("unterminated attribute value"));
+ }
+ let value = escape::unescape(&self.s[vstart..self.pos], true);
+ self.pos += 1;
+ raw_attrs.push((name, value.into()));
+ }
+ None => return Err(self.err("unterminated start tag")),
+ }
+ }
+ let start_tag_end = self.pos;
+ // Namespace declarations come into scope first.
+ for (name, value) in &raw_attrs {
+ let prefix = if &**name == "xmlns" {
+ Some("")
+ } else {
+ name.strip_prefix("xmlns:")
+ };
+ if let Some(prefix) = prefix {
+ let ns = self.tree.intern(value);
+ self.scope.push(Binding {
+ prefix: prefix.into(),
+ ns,
+ });
+ let decl = Decl {
+ prefix: prefix.to_owned(),
+ uri: value.to_string(),
+ };
+ if parent == NO_PARENT {
+ self.tree.root_decls.push(decl);
+ } else {
+ // The id this element will get.
+ let id = self.tree.nodes.len() as NodeId;
+ self.tree.inner_decls.push((id, decl));
+ }
+ }
+ }
+ let (prefix, local) = match qname.split_once(':') {
+ Some((p, l)) => (p, l),
+ None => ("", &*qname),
+ };
+ let ns = self.resolve(prefix).unwrap_or(Ns::NONE);
+ let mut attrs = Vec::with_capacity(raw_attrs.len());
+ for (name, value) in raw_attrs {
+ if &*name == "xmlns" || name.starts_with("xmlns:") {
+ continue;
+ }
+ let (ans, alocal) = match name.split_once(':') {
+ Some(("xml", l)) => (Ns::XML, l),
+ Some((p, l)) => (self.resolve(p).unwrap_or(Ns::NONE), l),
+ None => (Ns::NONE, &*name),
+ };
+ attrs.push(Attr {
+ ns: ans,
+ local: alocal.into(),
+ qname: name.clone(),
+ value,
+ });
+ }
+ let id = self.push(
+ Kind::Element {
+ ns,
+ local: local.into(),
+ qname: qname.clone(),
+ attrs,
+ children: Vec::new(),
+ start_tag_end: start_tag_end as u32,
+ },
+ parent,
+ start,
+ start_tag_end,
+ );
+ // Re-key declarations recorded for this element (ids are now known).
+ if !self_closing {
+ let mut children = Vec::new();
+ loop {
+ if self.pos >= self.b.len() {
+ return Err(self.err(&format!("unterminated <{qname}>")));
+ }
+ if self.b[self.pos] == b'<' {
+ let rest = &self.s[self.pos..];
+ if rest.starts_with("</") {
+ self.pos += 2;
+ let close = self.name()?.to_owned();
+ if close != *qname {
+ return Err(
+ self.err(&format!("mismatched end tag </{close}> for <{qname}>"))
+ );
+ }
+ self.skip_ws();
+ if self.b.get(self.pos) != Some(&b'>') {
+ return Err(self.err("expected '>'"));
+ }
+ self.pos += 1;
+ break;
+ } else if let Some(comment) = rest.strip_prefix("<!--") {
+ let s = self.pos;
+ let end = comment
+ .find("-->")
+ .ok_or_else(|| self.err("unterminated comment"))?;
+ self.pos += end + 7;
+ let c = self.push(Kind::Other, id, s, self.pos);
+ children.push(c);
+ } else if let Some(cdata) = rest.strip_prefix("<![CDATA[") {
+ let s = self.pos;
+ let end = cdata
+ .find("]]>")
+ .ok_or_else(|| self.err("unterminated CDATA"))?;
+ let text = cdata[..end].to_owned();
+ self.pos += end + 12;
+ let c = self.push(Kind::Text(text), id, s, self.pos);
+ children.push(c);
+ } else if rest.starts_with("<?") {
+ let s = self.pos;
+ let end = rest.find("?>").ok_or_else(|| self.err("unterminated PI"))?;
+ self.pos += end + 2;
+ let c = self.push(Kind::Other, id, s, self.pos);
+ children.push(c);
+ } else {
+ let c = self.element(id, depth + 1)?;
+ children.push(c);
+ }
+ } else {
+ let s = self.pos;
+ while self.pos < self.b.len() && self.b[self.pos] != b'<' {
+ self.pos += 1;
+ }
+ let text = escape::unescape(&self.s[s..self.pos], false);
+ let c = self.push(Kind::Text(text), id, s, self.pos);
+ children.push(c);
+ }
+ }
+ if let Kind::Element { children: ch, .. } = &mut self.tree.nodes[id as usize].kind {
+ *ch = children;
+ }
+ }
+ self.tree.nodes[id as usize].end = self.pos as u32;
+ self.scope.truncate(scope_len);
+ Ok(id)
+ }
+}
+
+/// Parses a decimal integer attribute value (tolerating `+`, whitespace and a
+/// fractional part, which some producers write).
+pub fn parse_int(v: &str) -> Option<i64> {
+ let v = v.trim();
+ let v = v.strip_prefix('+').unwrap_or(v);
+ v.parse::<i64>().ok().or_else(|| {
+ v.parse::<f64>()
+ .ok()
+ .filter(|f| f.is_finite())
+ .map(|f| f.round() as i64)
+ })
+}
+
+/// Parses an ST_OnOff value. A missing value means "on".
+pub fn parse_on_off(v: Option<&str>) -> bool {
+ !matches!(v.map(str::trim), Some("0" | "false" | "off" | "none"))
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/docx_engine/src/xml/escape.rs b/crates/docx_engine/src/xml/escape.rs
new file mode 100644
index 0000000000..227f2ba27c
--- /dev/null
+++ b/crates/docx_engine/src/xml/escape.rs
@@ -0,0 +1,103 @@
+//! Entity decoding and escaping.
+
+/// Decodes the predefined entities and character references in `s`.
+/// Attribute values also normalize literal tabs and newlines to spaces, as
+/// XML attribute-value normalization requires.
+pub(super) fn unescape(s: &str, attribute: bool) -> String {
+ if !s.contains('&') && (!attribute || !s.contains(['\t', '\n', '\r'])) {
+ return s.to_owned();
+ }
+ let mut out = String::with_capacity(s.len());
+ let mut rest = s;
+ while let Some(i) = rest.find(['&', '\t', '\n', '\r']) {
+ out.push_str(&rest[..i]);
+ let c = rest.as_bytes()[i];
+ if c != b'&' {
+ // Only attributes reach here with whitespace to normalize; in text
+ // a CR LF pair becomes LF.
+ if attribute {
+ out.push(' ');
+ if c == b'\r' && rest.as_bytes().get(i + 1) == Some(&b'\n') {
+ rest = &rest[i + 2..];
+ continue;
+ }
+ } else if c == b'\r' {
+ out.push('\n');
+ if rest.as_bytes().get(i + 1) == Some(&b'\n') {
+ rest = &rest[i + 2..];
+ continue;
+ }
+ } else {
+ out.push(c as char);
+ }
+ rest = &rest[i + 1..];
+ continue;
+ }
+ let tail = &rest[i..];
+ let Some(semi) = tail[..tail.len().min(12)].find(';') else {
+ out.push('&');
+ rest = &rest[i + 1..];
+ continue;
+ };
+ let entity = &tail[1..semi];
+ let decoded = match entity {
+ "amp" => Some('&'),
+ "lt" => Some('<'),
+ "gt" => Some('>'),
+ "quot" => Some('"'),
+ "apos" => Some('\''),
+ _ => entity
+ .strip_prefix("#x")
+ .or_else(|| entity.strip_prefix("#X"))
+ .and_then(|h| u32::from_str_radix(h, 16).ok())
+ .or_else(|| entity.strip_prefix('#').and_then(|d| d.parse::<u32>().ok()))
+ .and_then(char::from_u32),
+ };
+ match decoded {
+ Some(ch) => {
+ out.push(ch);
+ rest = &tail[semi + 1..];
+ }
+ None => {
+ out.push('&');
+ rest = &rest[i + 1..];
+ }
+ }
+ }
+ out.push_str(rest);
+ out
+}
+
+/// Appends `s` escaped for element content.
+pub fn escape_text(out: &mut String, s: &str) {
+ for c in s.chars() {
+ match c {
+ '&' => out.push_str("&amp;"),
+ '<' => out.push_str("&lt;"),
+ '>' => out.push_str("&gt;"),
+ '\r' => out.push_str("&#13;"),
+ // Characters XML 1.0 cannot carry are dropped.
+ c if (c as u32) < 0x20 && !matches!(c, '\t' | '\n') => {}
+ '\u{FFFE}' | '\u{FFFF}' => {}
+ _ => out.push(c),
+ }
+ }
+}
+
+/// Appends `s` escaped for a double-quoted attribute value.
+pub fn escape_attr(out: &mut String, s: &str) {
+ for c in s.chars() {
+ match c {
+ '&' => out.push_str("&amp;"),
+ '<' => out.push_str("&lt;"),
+ '>' => out.push_str("&gt;"),
+ '"' => out.push_str("&quot;"),
+ '\t' => out.push_str("&#9;"),
+ '\n' => out.push_str("&#10;"),
+ '\r' => out.push_str("&#13;"),
+ c if (c as u32) < 0x20 => {}
+ '\u{FFFE}' | '\u{FFFF}' => {}
+ _ => out.push(c),
+ }
+ }
+}
diff --git a/crates/docx_engine/src/xml/ns.rs b/crates/docx_engine/src/xml/ns.rs
new file mode 100644
index 0000000000..c44bffa142
--- /dev/null
+++ b/crates/docx_engine/src/xml/ns.rs
@@ -0,0 +1,169 @@
+//! Namespace identifiers for the vocabularies a Word document uses.
+//!
+//! ISO 29500 "strict" URIs resolve to the same identifiers as their
+//! transitional counterparts.
+
+/// An interned namespace URI. Values below [`Ns::FIRST_DYNAMIC`] are the
+/// well-known namespaces listed here; others are document-specific.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct Ns(pub u16);
+
+impl Ns {
+ /// No namespace.
+ pub const NONE: Ns = Ns(0);
+ /// WordprocessingML main (`w:`).
+ pub const W: Ns = Ns(1);
+ /// Office document relationships (`r:`).
+ pub const R: Ns = Ns(2);
+ /// WordprocessingML drawing (`wp:`).
+ pub const WP: Ns = Ns(3);
+ /// DrawingML main (`a:`).
+ pub const A: Ns = Ns(4);
+ /// DrawingML picture (`pic:`).
+ pub const PIC: Ns = Ns(5);
+ /// Markup compatibility (`mc:`).
+ pub const MC: Ns = Ns(6);
+ /// Word 2010 extensions (`w14:`).
+ pub const W14: Ns = Ns(7);
+ /// Word 2012 extensions (`w15:`).
+ pub const W15: Ns = Ns(8);
+ /// Word processing shapes (`wps:`).
+ pub const WPS: Ns = Ns(9);
+ /// Word processing groups (`wpg:`).
+ pub const WPG: Ns = Ns(10);
+ /// Word processing canvas (`wpc:`).
+ pub const WPC: Ns = Ns(11);
+ /// VML (`v:`).
+ pub const V: Ns = Ns(12);
+ /// Office VML extensions (`o:`).
+ pub const O: Ns = Ns(13);
+ /// Word VML extensions (`w10:`).
+ pub const W10: Ns = Ns(14);
+ /// Office Math (`m:`).
+ pub const M: Ns = Ns(15);
+ /// DrawingML chart (`c:`).
+ pub const C: Ns = Ns(16);
+ /// The reserved `xml:` namespace.
+ pub const XML: Ns = Ns(17);
+ /// Word 2010 drawing extensions (`wp14:`).
+ pub const WP14: Ns = Ns(18);
+ /// Package relationships.
+ pub const PKG_REL: Ns = Ns(19);
+ /// Package content types.
+ pub const CONTENT_TYPES: Ns = Ns(20);
+ /// DrawingML diagram data (`dgm:`).
+ pub const DGM: Ns = Ns(21);
+ /// Word 2006 extensions (`wne:`).
+ pub const WNE: Ns = Ns(22);
+ /// DrawingML 2010 extensions (`a14:`).
+ pub const A14: Ns = Ns(23);
+ /// First identifier assigned to namespaces not listed here.
+ pub const FIRST_DYNAMIC: u16 = 64;
+}
+
+/// Well-known namespace URIs and their identifiers.
+const KNOWN: &[(&str, Ns)] = &[
+ (
+ "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+ Ns::W,
+ ),
+ ("http://purl.oclc.org/ooxml/wordprocessingml/main", Ns::W),
+ (
+ "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+ Ns::R,
+ ),
+ (
+ "http://purl.oclc.org/ooxml/officeDocument/relationships",
+ Ns::R,
+ ),
+ (
+ "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+ Ns::WP,
+ ),
+ (
+ "http://purl.oclc.org/ooxml/drawingml/wordprocessingDrawing",
+ Ns::WP,
+ ),
+ (
+ "http://schemas.openxmlformats.org/drawingml/2006/main",
+ Ns::A,
+ ),
+ ("http://purl.oclc.org/ooxml/drawingml/main", Ns::A),
+ (
+ "http://schemas.openxmlformats.org/drawingml/2006/picture",
+ Ns::PIC,
+ ),
+ ("http://purl.oclc.org/ooxml/drawingml/picture", Ns::PIC),
+ (
+ "http://schemas.openxmlformats.org/markup-compatibility/2006",
+ Ns::MC,
+ ),
+ (
+ "http://schemas.microsoft.com/office/word/2010/wordml",
+ Ns::W14,
+ ),
+ (
+ "http://schemas.microsoft.com/office/word/2012/wordml",
+ Ns::W15,
+ ),
+ (
+ "http://schemas.microsoft.com/office/word/2010/wordprocessingShape",
+ Ns::WPS,
+ ),
+ (
+ "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup",
+ Ns::WPG,
+ ),
+ (
+ "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas",
+ Ns::WPC,
+ ),
+ ("urn:schemas-microsoft-com:vml", Ns::V),
+ ("urn:schemas-microsoft-com:office:office", Ns::O),
+ ("urn:schemas-microsoft-com:office:word", Ns::W10),
+ (
+ "http://schemas.openxmlformats.org/officeDocument/2006/math",
+ Ns::M,
+ ),
+ ("http://purl.oclc.org/ooxml/officeDocument/math", Ns::M),
+ (
+ "http://schemas.openxmlformats.org/drawingml/2006/chart",
+ Ns::C,
+ ),
+ ("http://purl.oclc.org/ooxml/drawingml/chart", Ns::C),
+ ("http://www.w3.org/XML/1998/namespace", Ns::XML),
+ (
+ "http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing",
+ Ns::WP14,
+ ),
+ (
+ "http://schemas.openxmlformats.org/package/2006/relationships",
+ Ns::PKG_REL,
+ ),
+ (
+ "http://schemas.openxmlformats.org/package/2006/content-types",
+ Ns::CONTENT_TYPES,
+ ),
+ (
+ "http://schemas.openxmlformats.org/drawingml/2006/diagram",
+ Ns::DGM,
+ ),
+ (
+ "http://schemas.microsoft.com/office/word/2006/wordml",
+ Ns::WNE,
+ ),
+ (
+ "http://schemas.microsoft.com/office/drawing/2010/main",
+ Ns::A14,
+ ),
+];
+
+/// The identifier of a well-known namespace URI.
+pub(super) fn known(uri: &str) -> Option<Ns> {
+ KNOWN.iter().find(|(u, _)| *u == uri).map(|(_, ns)| *ns)
+}
+
+/// The canonical URI of a well-known namespace.
+pub(super) fn uri_of(ns: Ns) -> Option<&'static str> {
+ KNOWN.iter().find(|(_, n)| *n == ns).map(|(u, _)| *u)
+}
diff --git a/crates/docx_engine/src/xml/test.rs b/crates/docx_engine/src/xml/test.rs
new file mode 100644
index 0000000000..489f674c66
--- /dev/null
+++ b/crates/docx_engine/src/xml/test.rs
@@ -0,0 +1,88 @@
+use super::*;
+
+const W: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+
+fn doc(body: &str) -> String {
+ format!(
+ "<?xml version=\"1.0\"?><w:document xmlns:w=\"{W}\" xmlns:x=\"urn:x\"><w:body>{body}</w:body></w:document>"
+ )
+}
+
+#[test]
+fn resolves_namespaces_and_keeps_raw_spans() {
+ let src =
+ doc("<w:p w:rsidR=\"01\"><w:r><w:t xml:space=\"preserve\"> a &amp; b </w:t></w:r></w:p>");
+ let t = XmlTree::parse(src.as_bytes(), "t").unwrap();
+ let body = t.w_child(t.root(), "body").unwrap();
+ let p = t.w_child(body, "p").unwrap();
+ assert!(t.is_w(p, "p"));
+ assert_eq!(t.w_attr(p, "rsidR"), Some("01"));
+ assert_eq!(t.raw_attrs(p), " w:rsidR=\"01\"");
+ let r = t.w_child(p, "r").unwrap();
+ let text = t.w_child(r, "t").unwrap();
+ assert_eq!(t.text(text), " a & b ");
+ assert_eq!(t.raw(text), "<w:t xml:space=\"preserve\"> a &amp; b </w:t>");
+ assert_eq!(t.attr(text, Ns::XML, "space"), Some("preserve"));
+}
+
+#[test]
+fn snippets_carry_inner_declarations() {
+ let src = doc("<w:p><w:r xmlns:y=\"urn:y\"><y:thing/></w:r></w:p>");
+ let t = XmlTree::parse(src.as_bytes(), "t").unwrap();
+ let body = t.w_child(t.root(), "body").unwrap();
+ let p = t.w_child(body, "p").unwrap();
+ let r = t.w_child(p, "r").unwrap();
+ let thing = t.children(r).next().unwrap();
+ // The declaration on <w:r> is copied onto the snippet; root ones are not.
+ assert_eq!(t.snippet(thing), "<y:thing xmlns:y=\"urn:y\"/>");
+ let ctx = SnippetContext::new(t.root_decls());
+ let again = ctx.parse(&t.snippet(thing)).unwrap();
+ assert_eq!(again.ns_uri(again.ns(again.root())), Some("urn:y"));
+}
+
+#[test]
+fn parses_snippets_in_root_context() {
+ let ctx = SnippetContext::new(&[Decl {
+ prefix: "w".into(),
+ uri: W.into(),
+ }]);
+ let t = ctx.parse("<w:sz w:val=\"24\"/>").unwrap();
+ assert!(t.is_w(t.root(), "sz"));
+ assert_eq!(t.val(t.root()), Some("24"));
+ let (tree, kids) = ctx
+ .parse_many("<w:tblPr/><w:tblGrid><w:gridCol w:w=\"10\"/></w:tblGrid>")
+ .unwrap();
+ assert_eq!(kids.len(), 2);
+ assert!(tree.is_w(kids[1], "tblGrid"));
+}
+
+#[test]
+fn rejects_malformed_xml() {
+ assert!(XmlTree::parse(b"<a><b></a>", "t").is_err());
+ assert!(XmlTree::parse(b"<a attr=x/>", "t").is_err());
+ assert!(XmlTree::parse(b"", "t").is_err());
+}
+
+#[test]
+fn decodes_entities_and_utf16() {
+ let t = XmlTree::parse(b"<a v=\"&#x41;&#66;&lt;\">&#x1F600;</a>", "t").unwrap();
+ assert_eq!(t.attr(t.root(), Ns::NONE, "v"), Some("AB<"));
+ assert_eq!(t.text(t.root()), "\u{1F600}");
+ let utf16: Vec<u8> = "\u{FEFF}<a>é</a>"
+ .encode_utf16()
+ .flat_map(|u| u.to_le_bytes())
+ .collect();
+ let t = XmlTree::parse(&utf16, "t").unwrap();
+ assert_eq!(t.text(t.root()), "é");
+}
+
+#[test]
+fn on_off_values() {
+ assert!(parse_on_off(None));
+ assert!(parse_on_off(Some("1")));
+ assert!(parse_on_off(Some("true")));
+ assert!(!parse_on_off(Some("0")));
+ assert!(!parse_on_off(Some("false")));
+ assert_eq!(parse_int(" +12 "), Some(12));
+ assert_eq!(parse_int("12.6"), Some(13));
+}
diff --git a/crates/docx_engine/tests/corpus/README.md b/crates/docx_engine/tests/corpus/README.md
new file mode 100644
index 0000000000..ab258b444d
--- /dev/null
+++ b/crates/docx_engine/tests/corpus/README.md
@@ -0,0 +1,31 @@
+# DOCX fidelity corpus
+
+`manifest.json` lists the documents the engine is scored on: 61 public
+`.docx` files, 36 of them legal (contracts, NVCA and YC financing forms,
+court forms, UN resolutions and treaties, constitutions, grant agreements),
+plus reports, forms and academic templates. Each entry records its source
+URL, licence and provenance, what it exercises (numbering, fields, tables,
+floats, sections, notes, tracked changes...) and, for 18 of them, a PDF that
+Word itself exported (`word_pdf`), which is the ground truth for layout. The
+files themselves stay with their publishers and are not committed.
+
+```sh
+S=/tmp/docx-corpus
+python3 crates/docx_engine/scripts/fetch_corpus.py $S/corpus
+cargo run --release -p docx_engine --features cli --bin docx_corpus -- fontconfig --out $S/fonts.conf
+python3 crates/docx_engine/scripts/render_references.py $S/refs $S/corpus/*.docx --fontconfig $S/fonts.conf --jobs 4
+cargo run --release -p docx_engine --features cli --bin docx_corpus -- score --refs $S/refs --out $S/score --jobs 4 $S/corpus/*.docx
+```
+
+`render_references.py` renders each document with LibreOffice (headless,
+PDF export, using the engine's bundled fonts through the generated
+fontconfig file so differences are layout rather than font choice) and
+rasterizes Word's PDFs where they exist. `score` renders every page with the
+engine, compares it with both references (SSIM per page, page counts) and
+writes `report.html` with side-by-side pages, plus `scores.json`. `lines`
+dumps the engine's text lines with positions for comparing line breaks
+with a reference PDF's.
+
+Scores as of this writing: against Word, mean SSIM 0.84 with equal page
+counts for all 18 documents; against LibreOffice 24.2, mean SSIM 0.66 with
+equal page counts for 42 of 61.
diff --git a/crates/docx_engine/tests/corpus/manifest.json b/crates/docx_engine/tests/corpus/manifest.json
new file mode 100644
index 0000000000..e4e9fe31f2
--- /dev/null
+++ b/crates/docx_engine/tests/corpus/manifest.json
@@ -0,0 +1,890 @@
+[
+ {
+ "file": "acm-interim-layout-two-column-template.docx",
+ "source_url": "https://www.acm.org/binaries/content/assets/publications/word_style/interim-template-style/interim-layout.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Association for Computing Machinery (ACM) - interim Word template (two-column layout)",
+ "license": "Freely distributed author template (ACM); no explicit open license",
+ "category": "academic",
+ "pages_hint": 2,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x1; list/heading numbering (30 abstractNums, numPr on 9 paras, 26 style-linked numbering, multi-level); DrawingML objects (inline x1); VML pict/shapes x2; OLE/embedded objects x4; multi-column sections (up to 3 cols); frames (framePr) x6; 4 sections; different first-page header/footer; even/odd headers; header parts 2, footer parts 2; hyperlinks x3; dot/leader tabs; compatibilityMode 14; ALT reference (not counted as word_pdf): acm-interim-layout-two-column-template.pdfmaker.pdf = Acrobat PDFMaker 25 for Word / Adobe PDF Library 25.1.51, 2 pages (= docx Pages); Acrobat PDFMaker prints Word's own layout; text check: 97.2% of 1358 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 3 pages (pages_hint 2)"
+ },
+ {
+ "file": "acm-taps-submission-template.docx",
+ "source_url": "https://www.acm.org/binaries/content/assets/publications/taps/acm_submission_template.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Association for Computing Machinery (ACM) - TAPS Word submission template",
+ "license": "Freely distributed author template (ACM); no explicit open license",
+ "category": "academic",
+ "pages_hint": 13,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x1; list/heading numbering (15 abstractNums, numPr on 48 paras, 7 style-linked numbering, multi-level); fields: PAGE x1; tables x2; DrawingML objects (inline x6); OMML equations x2; different first-page header/footer; header parts 0, footer parts 2; hyperlinks x13; compatibilityMode 15; LibreOffice 24.2.7.2 render: 14 pages (pages_hint 13)"
+ },
+ {
+ "file": "apache-poi-testdata-delins-tracked-changes.docx",
+ "source_url": "https://raw.githubusercontent.com/apache/poi/trunk/test-data/document/delins.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Apache POI project test-data (Word 2007 document; text from Wikipedia 'Tika' disambiguation page)",
+ "license": "Apache License 2.0 (Apache POI test data); article text CC BY-SA (Wikipedia)",
+ "category": "other",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 12.0000",
+ "word_pdf": null,
+ "notes": "TRACKED CHANGES (w:ins x32, w:del x4, formatting changes x46); list/heading numbering (4 abstractNums, numPr on 19 paras, multi-level); fields: HYPERLINK x11; hyperlinks x7; Fallback sample: real Word 2007 file with heavy tracked changes (insertions, deletions, formatting changes) - no public real-world legal docx with substantial tracked changes was found; LibreOffice 24.2.7.2 render: 1 pages (matches pages_hint)"
+ },
+ {
+ "file": "au-business-gov-regional-airports-program-sample-grant-agreement.docx",
+ "source_url": "https://business.gov.au/-/media/Grants-and-programs/RAP/Regional-Airports-Program-Sample-grant-agreement-DOCX.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Australian Government Department of Industry, Science and Resources via business.gov.au - Commonwealth Simple Grant Agreement (Regional Airports Program sample)",
+ "license": "Commonwealth of Australia; business.gov.au content generally CC BY 4.0 (verify)",
+ "category": "legal",
+ "pages_hint": 30,
+ "generator": "Microsoft Office Word 15.0000",
+ "word_pdf": null,
+ "notes": "footnotes x2; list/heading numbering (20 abstractNums, numPr on 56 paras, 17 style-linked numbering, multi-level); TOC field; fields: PAGEREF x17, PAGE x1, NUMPAGES x1; content controls (w:sdt) x3; tables x17; DrawingML objects (inline x1); VML pict/shapes x30; multi-column sections (up to 2 cols); 14 sections; header parts 15, footer parts 1; bookmarks x80 (cross-reference targets); hyperlinks x23; dot/leader tabs; watermark; glossary document part; compatibilityMode 15; PDF on site produced by Power PDF Create (not Word) - not kept; LibreOffice 24.2.7.2 render: 31 pages (pages_hint 30)"
+ },
+ {
+ "file": "binghamton-business-resume-template.docx",
+ "source_url": "https://cdn.uconnectlabs.com/wp-content/uploads/sites/60/2020/10/Binghamton-Business-Resume-Template.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Binghamton University Fleishman Center for Career and Professional Development (careertools.binghamton.edu)",
+ "license": "Freely downloadable career-center template (Binghamton University Fleishman Center); no explicit license",
+ "category": "other",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (2 abstractNums, numPr on 16 paras, multi-level); compatibilityMode 15; LibreOffice 24.2.7.2 render: 2 pages (pages_hint 1)"
+ },
+ {
+ "file": "binghamton-federal-resume-template-textbox.docx",
+ "source_url": "https://cdn.uconnectlabs.com/wp-content/uploads/sites/60/2025/10/Federal_Resume_Template.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Binghamton University Fleishman Center (careertools.binghamton.edu)",
+ "license": "Freely downloadable career-center template (Binghamton University Fleishman Center); no explicit license",
+ "category": "other",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (1 style-linked numbering); DrawingML objects (inline x1); wps shapes x1; text boxes (txbxContent) x2; VML pict/shapes x2; compatibilityMode 15; LibreOffice 24.2.7.2 render: 1 pages (matches pages_hint)"
+ },
+ {
+ "file": "binghamton-graduate-nursing-resume-gdocs-export.docx",
+ "source_url": "https://cdn.uconnectlabs.com/wp-content/uploads/sites/60/2026/07/Binghamton-Graduate-Nursing-Resume.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Binghamton University Fleishman Center (careertools.binghamton.edu)",
+ "license": "Freely downloadable career-center template (Binghamton University Fleishman Center); no explicit license",
+ "category": "other",
+ "pages_hint": null,
+ "generator": "Google Docs export (no docProps/app.xml; gDocsCustomXmlDataStorage + embedded fonts)",
+ "word_pdf": null,
+ "notes": "list/heading numbering (4 abstractNums, numPr on 20 paras, multi-level); different first-page header/footer; header parts 2, footer parts 0; embedded fonts x2; Google Docs export (gDocsCustomXmlDataStorage, embedded Noto Sans Symbols fonts, no docProps/app.xml); LibreOffice 24.2.7.2 render: 3 pages"
+ },
+ {
+ "file": "bonterms-cloud-terms-playbook.docx",
+ "source_url": "https://framerusercontent.com/assets/rdzuHZCF1waCbcKFMvpybND7pBg.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Bonterms (bonterms.com download center) - Playbook/Additional Terms for Bonterms Cloud Terms",
+ "license": "CC BY 4.0 (Bonterms standard forms are free to use under CC BY 4.0)",
+ "category": "legal",
+ "pages_hint": 4,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (1 abstractNums, numPr on 4 paras, multi-level); fields: PAGE x1; tables x5; header parts 0, footer parts 1; hyperlinks x1; compatibilityMode 15; LibreOffice 24.2.7.2 render: 6 pages (pages_hint 4)"
+ },
+ {
+ "file": "bonterms-dpa-v2-cover-page-example.docx",
+ "source_url": "https://framerusercontent.com/assets/XsMoez9PVySTjar2t6Iaz7dr1Y.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Bonterms (bonterms.com download center) - Example DPA cover page for Bonterms Data Protection Addendum v2",
+ "license": "CC BY 4.0 (Bonterms standard forms are free to use under CC BY 4.0)",
+ "category": "legal",
+ "pages_hint": 2,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "content controls (w:sdt) x7; tables x5; header parts 2, footer parts 2; hyperlinks x1; compatibilityMode 15; LibreOffice 24.2.7.2 render: 2 pages (matches pages_hint)"
+ },
+ {
+ "file": "bonterms-psa-sow-example.docx",
+ "source_url": "https://framerusercontent.com/assets/Q6ZSmhawLG442m9avBDO64ba70.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Bonterms (bonterms.com download center) - Example Statement of Work for Bonterms PSA",
+ "license": "CC BY 4.0 (Bonterms standard forms are free to use under CC BY 4.0)",
+ "category": "legal",
+ "pages_hint": 2,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "fields: PAGE x2; content controls (w:sdt) x2; tables x12; header parts 1, footer parts 3; compatibilityMode 15; LibreOffice 24.2.7.2 render: 3 pages (pages_hint 2)"
+ },
+ {
+ "file": "commonpaper-cloud-service-agreement-v2-1.docx",
+ "source_url": "https://commonpaper.com/wp-content/uploads/2024/11/Common-Paper-Cloud-Service-Agreement-v2.1-cover-page-and-standard-terms.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Common Paper (commonpaper.com standards) - Cloud Service Agreement v2.1 cover page + standard terms",
+ "license": "CC BY 4.0",
+ "category": "legal",
+ "pages_hint": 11,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (1 abstractNums, 9 style-linked numbering, multi-level); fields: PAGE x2; tables x7 (nested); DrawingML objects (anchored/floating x3); 3 sections; header parts 5, footer parts 3; hyperlinks x2; compatibilityMode 15; LibreOffice 24.2.7.2 render: 11 pages (matches pages_hint)"
+ },
+ {
+ "file": "commonpaper-mutual-nda-v1-0.docx",
+ "source_url": "https://commonpaper.com/wp-content/uploads/2021/12/Mutual-NDA-public-2page.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Common Paper (commonpaper.com standards) - Mutual NDA v1.0",
+ "license": "CC BY 4.0",
+ "category": "legal",
+ "pages_hint": 2,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (1 abstractNums, numPr on 11 paras, multi-level); tables x3; DrawingML objects (anchored/floating x2); 2 sections; header parts 2, footer parts 1; hyperlinks x1; compatibilityMode 15; LibreOffice 24.2.7.2 render: 2 pages (matches pages_hint)"
+ },
+ {
+ "file": "copernicus-word-manuscript-template-line-numbers.docx",
+ "source_url": "https://publications.copernicus.org/Copernicus_Word_template.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Copernicus Publications (publications.copernicus.org manuscript preparation) - MS Word manuscript template",
+ "license": "Freely distributed author template (Copernicus Publications); no explicit license",
+ "category": "academic",
+ "pages_hint": 5,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (2 abstractNums, 1 style-linked numbering, multi-level); fields: PAGE x1, SEQ x1; content controls (w:sdt) x1; DrawingML objects (inline x1); OMML equations x1; line numbering (w:lnNumType); header parts 0, footer parts 1; hyperlinks x5; compatibilityMode 14; Continuous line numbering every 5 lines (w:lnNumType countBy=5); LibreOffice 24.2.7.2 render: 5 pages (matches pages_hint)"
+ },
+ {
+ "file": "figshare-frontiers-pa-vs-eh-supplement-wps-office.docx",
+ "source_url": "https://ndownloader.figshare.com/files/69567852",
+ "retrieved": "2026-10-04",
+ "provenance": "figshare item 33514639 (Liu et al. 2026, supplementary material for a Frontiers systematic review/meta-analysis on primary aldosteronism vs essential hypertension)",
+ "license": "CC BY 4.0",
+ "category": "academic",
+ "pages_hint": 12,
+ "generator": "WPS Office_12.1.0.28505_F1E327BC-269C-435d-A152-05C5408002CA",
+ "word_pdf": null,
+ "notes": "list/heading numbering (6 abstractNums, 6 style-linked numbering); fields: HYPERLINK x1; tables x2; DrawingML objects (inline x3); CJK text; compatibilityMode 14; Produced by WPS Office (producer variety); images and tables; LibreOffice 24.2.7.2 render: 12 pages (matches pages_hint)"
+ },
+ {
+ "file": "figshare-latif-slr-prisma-flowchart-shapes.docx",
+ "source_url": "https://ndownloader.figshare.com/files/69244573",
+ "retrieved": "2026-10-04",
+ "provenance": "figshare item 33969382 (Latif, Das'ad 2026, 'Suplementary SLR_Dasad Latif', doi:10.6084/m9.figshare.33969382.v2) - Figure 1 PRISMA flowchart",
+ "license": "CC BY 4.0",
+ "category": "other",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "DrawingML objects (anchored/floating x21); wps shapes x21; text boxes (txbxContent) x26; VML pict/shapes x33; compatibilityMode 15; Flowchart drawn entirely with anchored Word shapes/text boxes (wps + VML fallback); LibreOffice 24.2.7.2 render: 1 pages (matches pages_hint)"
+ },
+ {
+ "file": "figshare-latif-slr-tables-landscape-sections.docx",
+ "source_url": "https://ndownloader.figshare.com/files/69244585",
+ "retrieved": "2026-10-04",
+ "provenance": "figshare item 33969382 (Latif, Das'ad 2026, doi:10.6084/m9.figshare.33969382.v2) - systematic review supplementary tables",
+ "license": "CC BY 4.0",
+ "category": "academic",
+ "pages_hint": 13,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "fields: PAGE x4; tables x4; 5 sections; landscape section(s) x5; header parts 0, footer parts 4; hyperlinks x48; compatibilityMode 15; Large tables in landscape sections; LibreOffice 24.2.7.2 render: 13 pages (matches pages_hint)"
+ },
+ {
+ "file": "govbr-agu-minuta-termo-de-compromisso-novo-pac-textboxes.docx",
+ "source_url": "https://www.gov.br/transferegov/pt-br/rede-parcerias/minutas-padronizadas-de-instrumentos/termo-de-compromisso-novo-pac/termo-de-compromisso-sem-obras-ou-servicos-de-engenharia-novo-pac.docx/@@download/file",
+ "retrieved": "2026-10-04",
+ "provenance": "Brazil Advocacia-Geral da União (AGU/CGU CNCIC) via gov.br Transferegov - model 'Termo de Compromisso' (Novo PAC, sem obras) (Portuguese)",
+ "license": "Brazilian official government model document (official acts not protected by copyright under Lei 9.610/98 art. 8)",
+ "category": "legal",
+ "pages_hint": 32,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (90 abstractNums, numPr on 132 paras, multi-level); fields: PAGE x4; DrawingML objects (inline x8, anchored/floating x28); wps shapes x278; text boxes (txbxContent) x64; shape groups x15; VML pict/shapes x312; multi-column sections (up to 2 cols); 37 sections; header parts 0, footer parts 2; hyperlinks x2; dot/leader tabs; compatibilityMode 15; Portuguese; explanatory notes in floating text boxes (VML + DrawingML), many sections, 2-column parts; LibreOffice 24.2.7.2 headless CRASHED (SIGABRT in SwTextFrame::FormatImpl) converting this file to PDF"
+ },
+ {
+ "file": "govbr-dnit-modelo-contrato-tic-compras-lei-14133.docx",
+ "source_url": "https://www.gov.br/dnit/pt-br/assuntos/licitacoes/minutas-de-edtais-padrao/lei-14-133-2021/pregao/modelo_contrato_tic_compras_lei_14_1331.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Brazil DNIT (Departamento Nacional de Infraestrutura de Transportes) via gov.br - standard IT purchase contract model under Lei 14.133/2021 (Portuguese; based on AGU model)",
+ "license": "Brazilian official government model document (official acts not protected by copyright under Lei 9.610/98 art. 8)",
+ "category": "legal",
+ "pages_hint": 14,
+ "generator": "Microsoft Office Word 15.0000",
+ "word_pdf": null,
+ "notes": "TRACKED CHANGES (w:ins x1, w:del x1, formatting changes x0); comments (anchors/refs x82); list/heading numbering (23 abstractNums, numPr on 39 paras, 16 style-linked numbering, multi-level); fields: REF x2, PAGE x1, NUMPAGES x1; content controls (w:sdt) x1; tables x1; DrawingML objects (anchored/floating x1); header parts 1, footer parts 1; hyperlinks x59; compatibilityMode 15; Portuguese; ~41 Word comments as drafting notes plus a real tracked insertion/deletion pair; LibreOffice 24.2.7.2 render: 14 pages (matches pages_hint)"
+ },
+ {
+ "file": "govuk-charity-commission-foundation-cio-model-constitution.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/65c6450dcc433b0011a90b83/Foundation_CIO_model_090224.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Charity Commission for England and Wales via GOV.UK (/government/publications/setting-up-a-charity-model-governing-documents) - Foundation CIO model constitution",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "legal",
+ "pages_hint": 50,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (78 abstractNums, numPr on 333 paras, 9 style-linked numbering, multi-level); DrawingML objects (anchored/floating x2); 5 sections; different first-page header/footer; header parts 0, footer parts 2; hyperlinks x13; dot/leader tabs; compatibilityMode 15; ALT reference (not counted as word_pdf): govuk-charity-commission-foundation-cio-model-constitution.pdfmaker.pdf = Acrobat PDFMaker 23 for Word / Adobe PDF Library 23.8.246, 50 pages (= docx Pages); Acrobat PDFMaker prints Word's own layout; text check: 99.9% of 12978 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 50 pages (matches pages_hint)"
+ },
+ {
+ "file": "govuk-charity-commission-gd3-model-constitution-unincorporated-charity.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/63456600d3bf7f618eda9482/GD3_Model_constitution_for_an_unincorporated_charity.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Charity Commission for England and Wales via GOV.UK (/government/publications/setting-up-a-charity-model-governing-documents) - GD3 model constitution",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "legal",
+ "pages_hint": 22,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "govuk-charity-commission-gd3-model-constitution-unincorporated-charity.word.pdf",
+ "notes": "list/heading numbering (9 abstractNums, numPr on 275 paras, multi-level); fields: PAGE x4; DrawingML objects (inline x2); text boxes (txbxContent) x8; VML pict/shapes x20; multi-column sections (up to 2 cols); 41 sections; even/odd headers; header parts 4, footer parts 5; hyperlinks x3; dot/leader tabs; compatibilityMode 14; Word reference PDF: Microsoft® Word 2013, 22 pages (= docx Pages), 596.04 x 842.04 pts (A4); source https://assets.publishing.service.gov.uk/media/5cf667e440f0b60a31e0aaf8/GD3.pdf; text check: 100.0% of 8852 docx body words found in PDF text; Word PDF (Word 2013, 2019) predates docx re-save (Word 16, 2022); identical text, both 22 pages; LibreOffice 24.2.7.2 render: 32 pages (pages_hint 22)"
+ },
+ {
+ "file": "govuk-dcms-taking-part-2012-13-q3-dashboard-landscape.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/5a7b494fe5274a34770eaace/Taking_Part_2012_13_Quarter_3_Dashboard.doc.DOCX",
+ "retrieved": "2026-10-04",
+ "provenance": "Department for Culture, Media and Sport via GOV.UK (/government/statistics/taking-part-2012-13-quarter-3-statistical-release) - statistics dashboard",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "report",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 14.0000",
+ "word_pdf": "govuk-dcms-taking-part-2012-13-q3-dashboard-landscape.word.pdf",
+ "notes": "DrawingML objects (anchored/floating x1); landscape section(s) x1; compatibilityMode 14; Word reference PDF: Microsoft® Word 2010, 1 pages (= docx Pages), 841.92 x 595.32 pts (A4); source https://assets.publishing.service.gov.uk/media/5a75b145e5274a545822d7bf/Taking_Part_2012_13_Quarter_3_Dashboard.pdf; text check: 100.0% of 0 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 1 pages (matches pages_hint)"
+ },
+ {
+ "file": "govuk-home-office-asylum-support-application-form-asf1.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/653122780b53920013a929ea/Asylum_Support_Application_Form_ASF1.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "UK Home Office via GOV.UK (/government/publications/application-for-asylum-support-form-asf1) - Form ASF1",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "form",
+ "pages_hint": 36,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "govuk-home-office-asylum-support-application-form-asf1.word.pdf",
+ "notes": "list/heading numbering (26 abstractNums, numPr on 72 paras, multi-level); fields: PAGE x2; tables x49 (nested); DrawingML objects (inline x20, anchored/floating x325); wps shapes x430; text boxes (txbxContent) x382; shape groups x30; VML pict/shapes x581; multi-column sections (up to 3 cols); 37 sections; header parts 0, footer parts 1; hyperlinks x7; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 36 pages (= docx Pages), 595.56 x 842.04 pts (A4); source https://assets.publishing.service.gov.uk/media/652e5016d86b1b00143a50c2/Asylum_Support_Application_Form_ASF1.pdf; text check: 99.9% of 5083 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 37 pages (pages_hint 36)"
+ },
+ {
+ "file": "govuk-lambert-model-research-collaboration-agreement-6.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/5b0686b1ed915d46713b204c/Collaboration_Agreement_6__May_2018_.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "UK Intellectual Property Office via GOV.UK (Lambert toolkit, /government/publications/university-and-business-collaboration-agreements-model-research-collaboration-agreements) - Model Research Collaboration Agreement 6",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "legal",
+ "pages_hint": 36,
+ "generator": "Microsoft Office Word 15.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (29 abstractNums, numPr on 275 paras, 20 style-linked numbering, multi-level); tables x4; header parts 3, footer parts 3; dot/leader tabs; compatibilityMode 15; ALT reference (not counted as word_pdf): govuk-lambert-model-research-collaboration-agreement-6.pdfmaker.pdf = Acrobat PDFMaker 18 for Word / Adobe PDF Library 15.0, 36 pages (= docx Pages); Acrobat PDFMaker prints Word's own layout; text check: 100.0% of 15651 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 36 pages (matches pages_hint)"
+ },
+ {
+ "file": "govuk-mod-maa-ra4806-camo-form-4-content-controls.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/6a194244b95db968c8f3bc14/RA4806_MAA_MAOS_CAMO_Form_4.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "UK Ministry of Defence - Military Aviation Authority via GOV.UK (/government/publications/regulatory-article-ra-4806-personnel-requirements-mrp-145a30) - MAA MAOS/CAMO Form 4",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "form",
+ "pages_hint": 2,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "govuk-mod-maa-ra4806-camo-form-4-content-controls.word.pdf",
+ "notes": "list/heading numbering (7 abstractNums, numPr on 26 paras, multi-level); fields: PAGE x2, NUMPAGES x1; content controls (w:sdt) x7; tables x1; DrawingML objects (inline x1); header parts 2, footer parts 2; hyperlinks x1; glossary document part; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 2 pages (= docx Pages), 595.32 x 841.92 pts (A4); source https://assets.publishing.service.gov.uk/media/6a194258c7335e2ca6daace0/RA4806_MAA_MAOS_CAMO_Form_4.pdf; text check: 100.0% of 260 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 2 pages (matches pages_hint)"
+ },
+ {
+ "file": "govuk-model-services-contract-core-terms-v2-2a.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/68af256b969253904d1558e5/MSC_-_Core_Terms_-_E_W_-_Word_v2.2A_2025.DOCX",
+ "retrieved": "2026-10-04",
+ "provenance": "UK Cabinet Office via GOV.UK - The Model Services Contract Core Terms (England & Wales) v2.2A",
+ "license": "Open Government Licence v3.0",
+ "category": "legal",
+ "pages_hint": 15,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (33 abstractNums, numPr on 12 paras, 28 style-linked numbering, multi-level); TOC field; fields: REF x329, PAGEREF x54, PAGE x1; content controls (w:sdt) x1; tables x3; DrawingML objects (inline x4); 2 sections; header parts 4, footer parts 4; bookmarks x779 (cross-reference targets); hyperlinks x60; dot/leader tabs; compatibilityMode 15; LibreOffice 24.2.7.2 render: 84 pages (pages_hint 15)"
+ },
+ {
+ "file": "govuk-ofsted-jtai-consultation-document.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/5a74f2da40f0b6399b2af76e/CONSULTATION_DOCUMENT_JTAI.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Ofsted via GOV.UK (/government/consultations/joint-targeted-area-inspections) - consultation document",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "report",
+ "pages_hint": 13,
+ "generator": "Microsoft Office Word 14.0000",
+ "word_pdf": "govuk-ofsted-jtai-consultation-document.word.pdf",
+ "notes": "footnotes x7; list/heading numbering (18 abstractNums, numPr on 6 paras, 8 style-linked numbering, multi-level); TOC field; fields: PAGEREF x9, PAGE x3; tables x11; DrawingML objects (anchored/floating x3); shape groups x1; VML pict/shapes x6; 4 sections; even/odd headers; header parts 12, footer parts 7; hyperlinks x13; compatibilityMode 14; Word reference PDF: Microsoft® Word 2010, 13 pages (= docx Pages), 595.2 x 841.92 pts (A4); source https://assets.publishing.service.gov.uk/media/5a80cac540f0b62305b8d2cb/CONSULTATION_DOCUMENT_JTAI.pdf; text check: 100.0% of 3063 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 13 pages (matches pages_hint)"
+ },
+ {
+ "file": "govuk-ofsted-state-funded-schools-inspection-statistics-dec-2018.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/5c9ca655e5274a5286955600/State_funded_schools_inspections_and_outcomes_as_at_31_December_2018_1.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Ofsted via GOV.UK (/government/statistics/state-funded-schools-inspections-and-outcomes-as-at-31-december-2018) - official statistics release",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "report",
+ "pages_hint": 16,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "govuk-ofsted-state-funded-schools-inspection-statistics-dec-2018.word.pdf",
+ "notes": "footnotes x9; list/heading numbering (35 abstractNums, numPr on 25 paras, 8 style-linked numbering, multi-level); TOC field; fields: PAGEREF x8, PAGE x2; tables x1; DrawingML objects (inline x8, anchored/floating x4); different first-page header/footer; header parts 3, footer parts 3; bookmarks x62 (cross-reference targets); hyperlinks x20; compatibilityMode 15; Word reference PDF: Microsoft® Word for Office 365, 16 pages (= docx Pages), 594.96 x 841.92 pts (A4); source https://assets.publishing.service.gov.uk/media/5f60b0f9d3bf7f72337b6e1f/State_funded_schools_inspections_and_outcomes_as_at_31_December_2018.pdf; text check: 99.8% of 3059 docx body words found in PDF text; Word PDF created in same session as docx save (PDF metadata later modified 2020); LibreOffice 24.2.7.2 render: 16 pages (matches pages_hint)"
+ },
+ {
+ "file": "govuk-ofsted-stc-consultation-questionnaire-form.docx",
+ "source_url": "https://assets.publishing.service.gov.uk/media/5a80c289e5274a2e8ab52005/STC_consultation_questionnaire_May_2015.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Ofsted via GOV.UK (/government/consultations/inspection-of-secure-training-centres) - consultation questionnaire",
+ "license": "Open Government Licence v3.0 (Crown copyright)",
+ "category": "form",
+ "pages_hint": 14,
+ "generator": "Microsoft Office Word 14.0000",
+ "word_pdf": "govuk-ofsted-stc-consultation-questionnaire-form.word.pdf",
+ "notes": "list/heading numbering (31 abstractNums, numPr on 6 paras, 10 style-linked numbering, multi-level); TOC field; fields: FORMCHECKBOX x193, FORMTEXT x20, PAGEREF x11, PAGE x3; legacy form fields x213; tables x25; DrawingML objects (inline x1, anchored/floating x4); 4 sections; even/odd headers; header parts 8, footer parts 7; bookmarks x64 (cross-reference targets); hyperlinks x12; compatibilityMode 14; Word reference PDF: Microsoft® Word 2010, 14 pages (= docx Pages), 595.32 x 841.92 pts (A4); source https://assets.publishing.service.gov.uk/media/5a748897e5274a7f9c586c04/STC_consultation_questionnaire_May_2015.pdf; text check: 100.0% of 1479 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 14 pages (matches pages_hint)"
+ },
+ {
+ "file": "jica-kusanone-contract-annex2-special-specifications-ja.docx",
+ "source_url": "https://www.jica.go.jp/announce/manual/guideline/kusanone/uurjcd000000feny-att/contract_ex02.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Japan International Cooperation Agency (JICA) - JICA Partnership Program (kusanone) contract template, Annex II special specifications (Japanese)",
+ "license": "Publicly provided template for program applicants (JICA website terms of use); no explicit open license",
+ "category": "legal",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "jica-kusanone-contract-annex2-special-specifications-ja.word.pdf",
+ "notes": "list/heading numbering (4 abstractNums, numPr on 2 paras, multi-level); header parts 1, footer parts 1; CJK text; compatibilityMode 15; Word reference PDF: Microsoft® Word 2016, 1 pages (= docx Pages), 595.2 x 841.92 pts (A4); source https://www.jica.go.jp/announce/manual/guideline/kusanone/uurjcd000000feny-att/contract_ex02.pdf; text check: 100.0% of 174 docx body chars found in PDF text; Japanese CJK text; Word 2016 PDF; LibreOffice 24.2.7.2 render: 1 pages (matches pages_hint)"
+ },
+ {
+ "file": "jica-kusanone-outsourcing-contract-training-ja.docx",
+ "source_url": "https://www.jica.go.jp/about/announce/manual/guideline/kusanone/__icsFiles/afieldfile/2023/08/14/contract_training_01.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Japan International Cooperation Agency (JICA) - JICA Partnership Program outsourcing contract template (training in Japan) (Japanese)",
+ "license": "Publicly provided template for program applicants (JICA website terms of use); no explicit open license",
+ "category": "legal",
+ "pages_hint": 3,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (4 abstractNums, numPr on 4 paras, multi-level); tables x3; header parts 0, footer parts 1; CJK text; compatibilityMode 15; ALT reference (not counted as word_pdf): jica-kusanone-outsourcing-contract-training-ja.pdfmaker.pdf = Word 用 Acrobat PDFMaker 23 / Adobe PDF Library 23.3.45, 3 pages (= docx Pages); Acrobat PDFMaker prints Word's own layout; text check: 100.0% of 1284 docx body chars found in PDF text; Japanese CJK text; LibreOffice 24.2.7.2 render: 3 pages (matches pages_hint)"
+ },
+ {
+ "file": "libreoffice-quick-reference-guide-7x-lo-export.docx",
+ "source_url": "https://documentation.libreoffice.org/assets/Uploads/Documentation/en/QR7/Quick-reference-guide-Libreoffice7.x-En.odt",
+ "retrieved": "2026-10-04",
+ "provenance": "The Document Foundation / LibreOffice Documentation Team - Quick Reference Guide 7.x (natively authored ODT, LibreOffice 7.0); converted to DOCX by the corpus builder with LibreOffice 24.2.7.2 headless (soffice --convert-to docx:'MS Word 2007 XML') on 2026-10-04",
+ "license": "GPLv3+ / CC BY 4.0 (LibreOffice documentation dual license)",
+ "category": "other",
+ "pages_hint": 2,
+ "generator": "LibreOffice/24.2.7.2$Linux_X86_64 LibreOffice_project/420$Build-2 15.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (1 abstractNums, 3 style-linked numbering, multi-level); tables x11; DrawingML objects (anchored/floating x4); multi-column sections (up to 3 cols); landscape section(s) x1; hyperlinks x3; compatibilityMode 12; LibreOffice-generated DOCX (producer variety); the original ODT is available at source_url; LibreOffice 24.2.7.2 render: 2 pages (matches pages_hint)"
+ },
+ {
+ "file": "nih-phs-6031-payback-agreement-form.docx",
+ "source_url": "https://grants.nih.gov/sites/default/files/uploaded/phs6031.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "U.S. National Institutes of Health (grants.nih.gov forms directory) - PHS 6031 Payback Agreement",
+ "license": "US federal government work (public domain)",
+ "category": "legal",
+ "pages_hint": 3,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (16 abstractNums, numPr on 2 paras, 2 style-linked numbering, multi-level); fields: FORMTEXT x8, PAGE x1; legacy form fields x8; tables x1; multi-column sections (up to 2 cols); 3 sections; header parts 0, footer parts 1; hyperlinks x4; compatibilityMode 15; ALT reference (not counted as word_pdf): nih-phs-6031-payback-agreement-form.pdfmaker.pdf = Acrobat PDFMaker 23 for Word / Adobe PDF Library 23.3.20, 3 pages (= docx Pages); Acrobat PDFMaker prints Word's own layout; text check: 99.9% of 1461 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 3 pages (matches pages_hint)"
+ },
+ {
+ "file": "nvca-2020-indemnification-agreement.docx",
+ "source_url": "https://nvca.org/wp-content/uploads/2021/12/NVCA-2020-Indemnification-Agreement.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "National Venture Capital Association (NVCA)",
+ "license": "NVCA model legal documents; free to download and use (NVCA terms; no explicit open license)",
+ "category": "legal",
+ "pages_hint": 29,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (13 abstractNums, 9 style-linked numbering, multi-level); fields: REF x108, PAGE x6, IF x3, DOCPROPERTY x3, SEQ x1; 3 sections; different first-page header/footer; header parts 5, footer parts 7; bookmarks x35 (cross-reference targets); compatibilityMode 15; LibreOffice 24.2.7.2 render: 29 pages (matches pages_hint)"
+ },
+ {
+ "file": "nvca-2020-management-rights-letter.docx",
+ "source_url": "https://nvca.org/wp-content/uploads/2025/12/NVCA-2020-Management-Rights-Letter-1-1.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "National Venture Capital Association (NVCA)",
+ "license": "NVCA model legal documents; free to download and use (NVCA terms; no explicit open license)",
+ "category": "legal",
+ "pages_hint": 5,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x5; list/heading numbering (2 abstractNums, 9 style-linked numbering, multi-level); fields: PAGE x2; 3 sections; different first-page header/footer; header parts 2, footer parts 5; compatibilityMode 15; LibreOffice 24.2.7.2 render: 5 pages (matches pages_hint)"
+ },
+ {
+ "file": "nvca-2025-certificate-of-incorporation.docx",
+ "source_url": "https://nvca.org/wp-content/uploads/2025/10/NVCA-Model-COI-10-1-2025.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "National Venture Capital Association (NVCA)",
+ "license": "NVCA model legal documents; free to download and use (NVCA terms; no explicit open license)",
+ "category": "legal",
+ "pages_hint": null,
+ "generator": "unknown (docProps/app.xml present but empty - metadata scrubbed); Word compatibilityMode 15",
+ "word_pdf": null,
+ "notes": "footnotes x94; list/heading numbering (16 abstractNums, numPr on 30 paras, 19 style-linked numbering, multi-level); fields: REF x165, PAGE x5, NOTEREF x4; 4 sections; different first-page header/footer; header parts 8, footer parts 10; bookmarks x392 (cross-reference targets); compatibilityMode 15; LibreOffice 24.2.7.2 render: 48 pages"
+ },
+ {
+ "file": "nvca-2025-investors-rights-agreement.docx",
+ "source_url": "https://nvca.org/wp-content/uploads/2025/10/NVCA-Model-IRA-10-1-2025-2-1.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "National Venture Capital Association (NVCA)",
+ "license": "NVCA model legal documents; free to download and use (NVCA terms; no explicit open license)",
+ "category": "legal",
+ "pages_hint": 14,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x92; list/heading numbering (11 abstractNums, numPr on 34 paras, 12 style-linked numbering, multi-level); fields: REF x155, PAGE x3; tables x6; 5 sections; different first-page header/footer; header parts 7, footer parts 8; bookmarks x422 (cross-reference targets); compatibilityMode 15; LibreOffice 24.2.7.2 render: 43 pages (pages_hint 14)"
+ },
+ {
+ "file": "nvca-2025-stock-purchase-agreement.docx",
+ "source_url": "https://nvca.org/wp-content/uploads/2025/10/NVCA-Model-SPA-10-28-2025-1.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "National Venture Capital Association (NVCA)",
+ "license": "NVCA model legal documents; free to download and use (NVCA terms; no explicit open license)",
+ "category": "legal",
+ "pages_hint": 27,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x108; list/heading numbering (125 abstractNums, numPr on 9 paras, 12 style-linked numbering, multi-level); fields: REF x90, PAGE x2; tables x3; 4 sections; different first-page header/footer; header parts 6, footer parts 8; bookmarks x192 (cross-reference targets); dot/leader tabs; compatibilityMode 15; LibreOffice 24.2.7.2 render: 50 pages (pages_hint 27)"
+ },
+ {
+ "file": "nvca-2026-rofr-co-sale-agreement.docx",
+ "source_url": "https://nvca.org/wp-content/uploads/2026/06/Right-of-First-Refusal-and-Co-Sale-Agreement-Updated-April-2026.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "National Venture Capital Association (NVCA)",
+ "license": "NVCA model legal documents; free to download and use (NVCA terms; no explicit open license)",
+ "category": "legal",
+ "pages_hint": 21,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x30; list/heading numbering (5 abstractNums, 11 style-linked numbering, multi-level); fields: REF x61, PAGE x2; tables x2; 3 sections; different first-page header/footer; header parts 5, footer parts 6; bookmarks x67 (cross-reference targets); compatibilityMode 15; LibreOffice 24.2.7.2 render: 20 pages (pages_hint 21)"
+ },
+ {
+ "file": "nvca-2026-voting-agreement.docx",
+ "source_url": "https://nvca.org/wp-content/uploads/2026/06/Voting-Agreement-Updated-June-2026.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "National Venture Capital Association (NVCA)",
+ "license": "NVCA model legal documents; free to download and use (NVCA terms; no explicit open license)",
+ "category": "legal",
+ "pages_hint": null,
+ "generator": "unknown (docProps/app.xml present but empty - metadata scrubbed); Word compatibilityMode 15",
+ "word_pdf": null,
+ "notes": "footnotes x39; list/heading numbering (7 abstractNums, 10 style-linked numbering, multi-level); fields: REF x64, PAGE x2; tables x2; 3 sections; different first-page header/footer; header parts 4, footer parts 6; bookmarks x142 (cross-reference targets); compatibilityMode 15; LibreOffice 24.2.7.2 render: 22 pages"
+ },
+ {
+ "file": "oasis-mqtt-v5-0-os-specification.docx",
+ "source_url": "https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "OASIS Open - MQTT Version 5.0 OASIS Standard (authoritative Word source)",
+ "license": "OASIS IPR policy copyright notice: may be copied and distributed in full, unmodified (OASIS Open 2019)",
+ "category": "report",
+ "pages_hint": 137,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "oasis-mqtt-v5-0-os-specification.word.pdf",
+ "notes": "list/heading numbering (66 abstractNums, numPr on 295 paras, 19 style-linked numbering, multi-level); TOC field; fields: PAGEREF x294, STYLEREF x47, SEQ x38, REF x13, HYPERLINK x5, PAGE x2, NUMPAGES x2; tables x59; DrawingML objects (inline x1); line numbering (w:lnNumType); 2 sections; header parts 2, footer parts 2; bookmarks x3106 (cross-reference targets); hyperlinks x642; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word 2016, 137 pages (= docx Pages), 612 x 792 pts (letter); source https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.pdf; text check: 99.9% of 52296 docx body words found in PDF text; Technical standard (137 pages); LibreOffice 24.2.7.2 render: 137 pages (matches pages_hint)"
+ },
+ {
+ "file": "onenda-v2-1-nda.docx",
+ "source_url": "https://storage.googleapis.com/lawinsider-public/assets/standards/onenda/oneNDA_v2.1.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "oneNDA (onenda.org, Law Insider)",
+ "license": "CC BY-ND 4.0",
+ "category": "legal",
+ "pages_hint": null,
+ "generator": "Google Docs export (no docProps/app.xml; gDocsCustomXmlDataStorage + embedded fonts)",
+ "word_pdf": null,
+ "notes": "list/heading numbering (9 abstractNums, numPr on 46 paras, 1 style-linked numbering, multi-level); fields: PAGE x3; tables x3; DrawingML objects (inline x1, anchored/floating x7); wps shapes x3; text boxes (txbxContent) x3; 2 sections; header parts 3, footer parts 3; embedded fonts x4; LibreOffice 24.2.7.2 render: 3 pages"
+ },
+ {
+ "file": "onesaas-v1-0-saas-agreement.docx",
+ "source_url": "https://storage.googleapis.com/lawinsider-public/assets/standards/onesaas/oneSaaS_v1.0.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "oneNDA/oneSaaS (onenda.org, Law Insider)",
+ "license": "CC BY-ND 4.0 (per onenda.org)",
+ "category": "legal",
+ "pages_hint": null,
+ "generator": "Google Docs export (no docProps/app.xml; gDocsCustomXmlDataStorage + embedded fonts)",
+ "word_pdf": null,
+ "notes": "list/heading numbering (3 abstractNums, numPr on 10 paras, multi-level); fields: PAGE x3; content controls (w:sdt) x14; tables x9; DrawingML objects (inline x1, anchored/floating x63); wps shapes x30; text boxes (txbxContent) x8; VML pict/shapes x1; 5 sections; header parts 5, footer parts 3; bookmarks x21 (cross-reference targets); hyperlinks x1; embedded fonts x4; LibreOffice 24.2.7.2 render: 25 pages"
+ },
+ {
+ "file": "preston-on-tees-parish-council-newsletter-autumn-2022.docx",
+ "source_url": "https://www.prestononteesparishcouncil.gov.uk/media/General/Newsletter/Preston%20Parish%20Council%20Newsletter%20Autumn%202022%20v-2%20(1).docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Preston-on-Tees Parish Council (UK local council website)",
+ "license": "Published by a UK parish council for public distribution; no explicit license",
+ "category": "other",
+ "pages_hint": 3,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (4 abstractNums, 2 style-linked numbering, multi-level); fields: PAGE x2; content controls (w:sdt) x1; DrawingML objects (anchored/floating x2); wps shapes x2; text boxes (txbxContent) x2; VML pict/shapes x3; header parts 0, footer parts 2; hyperlinks x1; compatibilityMode 15; Community newsletter with anchored text boxes; LibreOffice 24.2.7.2 render: 3 pages (matches pages_hint)"
+ },
+ {
+ "file": "royalsoc-biol-lett-2025-0630-manuscript-tracked-changes.docx",
+ "source_url": "https://ndownloader.figshare.com/files/62068040",
+ "retrieved": "2026-10-04",
+ "provenance": "The Royal Society (Biology Letters) via figshare item 31388027 - 'Track changes version from Attraction versus avoidance: Honey bees vary in response to ...' (author revision with tracked changes, published as supplementary material)",
+ "license": "CC BY 4.0",
+ "category": "academic",
+ "pages_hint": 17,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "TRACKED CHANGES (w:ins x552, w:del x401, formatting changes x68); list/heading numbering (11 abstractNums, 1 style-linked numbering, multi-level); tables x1; DrawingML objects (inline x2); line numbering (w:lnNumType); hyperlinks x2; compatibilityMode 15; Real author manuscript with ~550 tracked insertions, ~400 deletions and formatting changes; LibreOffice 24.2.7.2 render: 17 pages (matches pages_hint)"
+ },
+ {
+ "file": "tandf-visqual-t-hebrew-questionnaire-rtl.docx",
+ "source_url": "https://ndownloader.figshare.com/files/66213488",
+ "retrieved": "2026-10-04",
+ "provenance": "Taylor & Francis via figshare (tandf.figshare.com item 32868389) - supplementary Appendix A: Hebrew version of the Vision Quality of Life with Time Survey (VisQuaL-T), Eichler et al.",
+ "license": "CC BY 4.0",
+ "category": "form",
+ "pages_hint": 4,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (1 abstractNums, numPr on 16 paras, 1 style-linked numbering, multi-level); tables x2; Arabic/Hebrew RTL script; bidi/rtl markup x405; compatibilityMode 15; Hebrew RTL questionnaire: bidi paragraphs, rtl runs, RTL (bidiVisual) tables, mixed Hebrew/English; LibreOffice 24.2.7.2 render: 5 pages (pages_hint 4)"
+ },
+ {
+ "file": "un-a-79-10-international-law-commission-report.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/79/10&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - Report of the International Law Commission, seventy-fifth session (A/79/10)",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 170,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-79-10-international-law-commission-report.word.pdf",
+ "notes": "footnotes x508; list/heading numbering (4 abstractNums, 4 style-linked numbering, multi-level); tables x1; DrawingML objects (inline x2, anchored/floating x1); wps shapes x1; text boxes (txbxContent) x2; VML pict/shapes x1; 6 sections; different first-page header/footer; even/odd headers; header parts 8, footer parts 10; hyperlinks x55; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 170 pages (= docx Pages), 595 x 842 pts (A4); source https://documents.un.org/api/symbol/access?s=A/79/10&l=en&t=pdf; text check: 99.9% of 64509 docx body words found in PDF text"
+ },
+ {
+ "file": "un-a-79-305-mercenaries-working-group-report.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/79/305&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - Report of the Working Group on the use of mercenaries A/79/305",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "report",
+ "pages_hint": 20,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-79-305-mercenaries-working-group-report.word.pdf",
+ "notes": "footnotes x73; comments (anchors/refs x2); list/heading numbering (13 abstractNums, 22 style-linked numbering, multi-level); fields: PAGE x2, NUMPAGES x2, HYPERLINK x2; tables x1; DrawingML objects (inline x2, anchored/floating x3); wps shapes x2; VML pict/shapes x2; frames (framePr) x2; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x19; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 20 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=A/79/305&l=en&t=pdf; text check: 99.8% of 9134 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 21 pages (pages_hint 20)"
+ },
+ {
+ "file": "un-a-hrc-res-56-1-human-rights-council-resolution-a4.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/HRC/RES/56/1&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - Human Rights Council resolution 56/1",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 12,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-hrc-res-56-1-human-rights-council-resolution-a4.word.pdf",
+ "notes": "footnotes x6; list/heading numbering (8 abstractNums, 3 style-linked numbering, multi-level); tables x1; DrawingML objects (inline x1); different first-page header/footer; even/odd headers; header parts 2, footer parts 3; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 12 pages (= docx Pages), 595 x 842 pts (A4); source https://documents.un.org/api/symbol/access?s=A/HRC/RES/56/1&l=en&t=pdf; text check: 100.0% of 5599 docx body words found in PDF text"
+ },
+ {
+ "file": "un-a-res-78-253-programme-budget-special-subjects.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/RES/78/253&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - GA resolution 78/253",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 25,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-res-78-253-programme-budget-special-subjects.word.pdf",
+ "notes": "footnotes x59; comments (anchors/refs x2); list/heading numbering (13 abstractNums, 19 style-linked numbering, multi-level); fields: PAGE x2, NUMPAGES x2; tables x4; DrawingML objects (inline x2, anchored/floating x2); wps shapes x1; VML pict/shapes x1; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x132; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 25 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=A/RES/78/253&l=en&t=pdf; text check: 99.7% of 11147 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 26 pages (pages_hint 25)"
+ },
+ {
+ "file": "un-a-res-78-265-ai-resolution-arabic.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/RES/78/265&l=ar&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - GA resolution 78/265 (Arabic version)",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 9,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-res-78-265-ai-resolution-arabic.word.pdf",
+ "notes": "footnotes x10; comments (anchors/refs x2); list/heading numbering (12 abstractNums, 10 style-linked numbering, multi-level); fields: PAGE x2, NUMPAGES x2; DrawingML objects (inline x2, anchored/floating x2); wps shapes x1; VML pict/shapes x1; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x12; dot/leader tabs; Arabic/Hebrew RTL script; bidi/rtl markup x304; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 9 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=A/RES/78/265&l=ar&t=pdf; text check: 89.5% of 17588 docx body chars found in PDF text (Arabic PDF text extraction yields tatweel/presentation-form variants, so coverage understates the match); Arabic RTL text; LibreOffice 24.2.7.2 render: 11 pages (pages_hint 9)"
+ },
+ {
+ "file": "un-a-res-78-265-ai-resolution-chinese.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/RES/78/265&l=zh&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - GA resolution 78/265 (Chinese version)",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 7,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-res-78-265-ai-resolution-chinese.word.pdf",
+ "notes": "footnotes x10; comments (anchors/refs x2); list/heading numbering (3 abstractNums, 3 style-linked numbering, multi-level); fields: PAGE x2, NUMPAGES x2; tables x1; DrawingML objects (inline x2, anchored/floating x2); wps shapes x1; VML pict/shapes x1; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x13; dot/leader tabs; CJK text; compatibilityMode 15; Word reference PDF: Microsoft® Word 适用于 Microsoft 365, 7 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=A/RES/78/265&l=zh&t=pdf; text check: 100.0% of 6338 docx body chars found in PDF text; Chinese CJK text; LibreOffice 24.2.7.2 render: 8 pages (pages_hint 7)"
+ },
+ {
+ "file": "un-a-res-79-1-pact-for-the-future.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/RES/79/1&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (Official Document System) - GA resolution 79/1",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 56,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-res-79-1-pact-for-the-future.word.pdf",
+ "notes": "footnotes x26; comments (anchors/refs x2); list/heading numbering (13 abstractNums, 20 style-linked numbering, multi-level); fields: PAGE x2, NUMPAGES x2; DrawingML objects (inline x2, anchored/floating x2); wps shapes x1; VML pict/shapes x1; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x7; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 56 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=A/RES/79/1&l=en&t=pdf; text check: 99.9% of 27569 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 59 pages (pages_hint 56)"
+ },
+ {
+ "file": "un-a-res-79-243-convention-against-cybercrime.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/RES/79/243&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - General Assembly resolution 79/243 (United Nations Convention against Cybercrime)",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 46,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-a-res-79-243-convention-against-cybercrime.word.pdf",
+ "notes": "footnotes x1; list/heading numbering (17 abstractNums, 20 style-linked numbering, multi-level); tables x1; DrawingML objects (anchored/floating x1); wps shapes x1; VML pict/shapes x1; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x9; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 46 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=A/RES/79/243&l=en&t=pdf; text check: 100.0% of 16730 docx body words found in PDF text"
+ },
+ {
+ "file": "un-bbnj-agreement-a-conf-232-2023-4.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=A/CONF.232/2023/4&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - BBNJ Agreement treaty text A/CONF.232/2023/4",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 53,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-bbnj-agreement-a-conf-232-2023-4.word.pdf",
+ "notes": "comments (anchors/refs x2); list/heading numbering (19 abstractNums, 21 style-linked numbering, multi-level); fields: PAGE x2, NUMPAGES x2; DrawingML objects (inline x2, anchored/floating x3); wps shapes x2; VML pict/shapes x2; frames (framePr) x2; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; bookmarks x26 (cross-reference targets); dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 53 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=A/CONF.232/2023/4&l=en&t=pdf; text check: 99.6% of 21636 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 55 pages (pages_hint 53)"
+ },
+ {
+ "file": "un-e-2024-53-humanitarian-coordination-report.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=E/2024/53&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - Report of the Secretary-General on the coordination of emergency humanitarian assistance (A/79/78-E/2024/53)",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "report",
+ "pages_hint": 19,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-e-2024-53-humanitarian-coordination-report.word.pdf",
+ "notes": "footnotes x35; list/heading numbering (13 abstractNums, 19 style-linked numbering, multi-level); tables x2; DrawingML objects (anchored/floating x2); wps shapes x2; VML pict/shapes x2; text frames (framePr) x3; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x12; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 19 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=E/2024/53&l=en&t=pdf; text check: 99.9% of 7310 docx body words found in PDF text"
+ },
+ {
+ "file": "un-s-res-2720-2023-security-council.docx",
+ "source_url": "https://documents.un.org/api/symbol/access?s=S/RES/2720(2023)&l=en&t=docx",
+ "retrieved": "2026-10-04",
+ "provenance": "United Nations (ODS) - Security Council resolution 2720 (2023)",
+ "license": "UN official document (ODS); UN terms of use allow downloading/copying, official documents are routinely reproduced with attribution; verify before commercial redistribution",
+ "category": "legal",
+ "pages_hint": 4,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "un-s-res-2720-2023-security-council.word.pdf",
+ "notes": "comments (anchors/refs x2); list/heading numbering (13 abstractNums, 19 style-linked numbering, multi-level); fields: PAGE x2, NUMPAGES x2; DrawingML objects (inline x2, anchored/floating x2); wps shapes x1; VML pict/shapes x1; 2 sections; different first-page header/footer; even/odd headers; header parts 3, footer parts 3; hyperlinks x4; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 4 pages (= docx Pages), 612 x 792 pts (letter); source https://documents.un.org/api/symbol/access?s=S/RES/2720(2023)&l=en&t=pdf; text check: 99.6% of 1694 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 4 pages (matches pages_hint)"
+ },
+ {
+ "file": "uscourts-caed-pleading-paper-times-new-roman.docx",
+ "source_url": "https://www.caed.uscourts.gov/caednew/assets/File/TimesNewRomanPleadingPaper.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "U.S. District Court, Eastern District of California (caed.uscourts.gov, attorney info / Word format)",
+ "license": "US federal government work (public domain)",
+ "category": "legal",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 14.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (7 abstractNums, 6 style-linked numbering); fields: PAGE x2; tables x1; different first-page header/footer; header parts 3, footer parts 3; dot/leader tabs; compatibilityMode 14; 28-line pleading paper: line numbers built from an exact-height header table row with double right border; negative top/bottom page margins; LibreOffice 24.2.7.2 render: 1 pages (matches pages_hint)"
+ },
+ {
+ "file": "vic-dtf-2026-27-budget-paper-2-strategy-and-outlook.docx",
+ "source_url": "https://s3.ap-southeast-2.amazonaws.com/vicbudgetfiles2026.27vicbudget/2026-27+State+Budget+-+Strategy+and+Outlook.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Victorian Department of Treasury and Finance (dtf.vic.gov.au/2026-27-strategy-and-outlook) - 2026-27 Budget Paper No. 2",
+ "license": "CC BY 4.0 (State of Victoria, DTF)",
+ "category": "report",
+ "pages_hint": 100,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x5; list/heading numbering (17 abstractNums, numPr on 74 paras, 23 style-linked numbering, multi-level); TOC field; fields: PAGEREF x27, PAGE x7; tables x26; native charts x28; DrawingML objects (inline x33, anchored/floating x2); wps shapes x9; text boxes (txbxContent) x10; shape groups x1; VML pict/shapes x9; multi-column sections (up to 2 cols); 13 sections; even/odd headers; header parts 0, footer parts 20; bookmarks x78 (cross-reference targets); hyperlinks x28; dot/leader tabs; compatibilityMode 15; PDF on site is Acrobat PDFMaker 26 for Word with 102 pages vs docx Pages=100 (not kept); LibreOffice 24.2.7.2 render: 123 pages (pages_hint 100)"
+ },
+ {
+ "file": "wacourts-civil-case-cover-sheet-superior-court.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/Civil-Case%20Cover%20Sheet%20Superior%20Court%20%2804.2026%29.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - Superior Court civil case cover sheet",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "form",
+ "pages_hint": 9,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-civil-case-cover-sheet-superior-court.word.pdf",
+ "notes": "tables x4; 16 sections; multi-column sections x1; header parts 3, footer parts 10; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 9 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/Civil-Case%20Cover%20Sheet%20Superior%20Court%20%2804.2026%29%28Checked%29.pdf; text check: 99.9% of 1748 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-crrlj-04-1100-petition-for-deferred-prosecution.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/WPF%20CrRLJ%2004.1100%20Petition%20for%20Deferred%20Prosecution_2021%2012.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - criminal (CrRLJ) form 04.1100 (Petition for Deferred Prosecution)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 3,
+ "generator": "Microsoft Office Word 15.0000",
+ "word_pdf": "wacourts-crrlj-04-1100-petition-for-deferred-prosecution.word.pdf",
+ "notes": "list/heading numbering (1 abstractNums, multi-level); tables x1; header parts 3, footer parts 3; compatibilityMode 15; Word reference PDF: Microsoft® Word 2013, 3 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/WPF%20CrRLJ%2004.1100%20Petition%20for%20Deferred%20Prosecution_2021%2012.pdf; text check: 100.0% of 1150 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-crrlj-07-0110-judgment-and-sentence.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/CrRLJ%2007.0110%20Judgment%20and%20Sentence_2024%2001%20%28U%29.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - criminal (CrRLJ) form 07.0110 (Judgment and Sentence)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 5,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-crrlj-07-0110-judgment-and-sentence.word.pdf",
+ "notes": "list/heading numbering (2 abstractNums, multi-level); tables x2; header parts 0, footer parts 1; compatibilityMode 15; Word reference PDF: Microsoft® Word 2019, 5 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/CrRLJ%2007.0110%20Judgment%20and%20Sentence_2024%2001%20%28U%29.pdf; text check: 100.0% of 1028 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-fl-all-family-001-confidential-info-form.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/FL%20All%20Family%20001%20Confidential%20Info%20Form_202601.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - pattern form FL All Family 001 (Confidential Information Form)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "form",
+ "pages_hint": 2,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-fl-all-family-001-confidential-info-form.word.pdf",
+ "notes": "list/heading numbering (5 abstractNums, numPr on 10 paras, 13 style-linked numbering, multi-level); fields: PAGE x1, SECTIONPAGES x1; tables x8; DrawingML objects (anchored/floating x1); wps shapes x1; VML pict/shapes x2; header parts 0, footer parts 1; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 2 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/FL%20All%20Family%20001%20Confidential%20Info%20Form_2026_01.pdf; text check: 100.0% of 511 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 3 pages (pages_hint 2)"
+ },
+ {
+ "file": "wacourts-fl-all-family-130-child-support-order.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/FL%20All%20Family%20130%20Child%20Support%20Order%202026_01.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - pattern form FL All Family 130 (Child Support Order)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 18,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-fl-all-family-130-child-support-order.word.pdf",
+ "notes": "list/heading numbering (20 abstractNums, numPr on 61 paras, 21 style-linked numbering, multi-level); fields: PAGE x1, NUMPAGES x1; tables x18; DrawingML objects (anchored/floating x5); wps shapes x5; VML pict/shapes x10; 5 sections; header parts 1, footer parts 1; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 18 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/FL%20All%20Family%20130%20Child%20Support%20Order%202026_01.pdf; text check: 99.9% of 5436 docx body words found in PDF text; LibreOffice 24.2.7.2 render: 20 pages (pages_hint 18)"
+ },
+ {
+ "file": "wacourts-fl-all-family-140-parenting-plan.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/FL%20All%20Family%20140%20Parenting%20Plan%2007.2025.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - pattern form FL All Family 140 (Parenting Plan)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 28,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-fl-all-family-140-parenting-plan.word.pdf",
+ "notes": "list/heading numbering (38 abstractNums, numPr on 69 paras, 13 style-linked numbering, multi-level); tables x21; DrawingML objects (anchored/floating x7); wps shapes x7; VML pict/shapes x7; 6 sections; multi-column sections x1; header parts 0, footer parts 6; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 28 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/FL%20All%20Family%20140%20Parenting%20Plan%2007.2025.pdf; text check: 100.0% of 6560 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-gdn-c-104-order-appointing-guardian-conservator.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/GDN%20C%20104%20Or%20App%20Guardian%20Conservator_07.2025.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - guardianship form GDN C 104 (Order Appointing Full or Limited Guardian/Conservator)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 12,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-gdn-c-104-order-appointing-guardian-conservator.word.pdf",
+ "notes": "list/heading numbering (8 abstractNums, numPr on 1 paras, multi-level); tables x4 (nested); header parts 0, footer parts 1; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 12 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/GDN%20C%20104%20Or%20App%20Guardian%20Conservator_07.2025.pdf; text check: 100.0% of 2573 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-gdn-e-301-emergency-guardianship-petition.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/GDN%20E%20301%20Emergency%20Pt%20for%20Appt%20Gdn%20Con%202022%2001.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - guardianship form GDN E 301 (Emergency Guardianship/Conservatorship Petition)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 10,
+ "generator": "Microsoft Office Word 15.0000",
+ "word_pdf": "wacourts-gdn-e-301-emergency-guardianship-petition.word.pdf",
+ "notes": "list/heading numbering (38 abstractNums, numPr on 29 paras, 1 style-linked numbering, multi-level); tables x1; DrawingML objects (anchored/floating x2); wps shapes x2; VML pict/shapes x2; 3 sections; multi-column sections x2; header parts 0, footer parts 1; compatibilityMode 15; Word reference PDF: Microsoft® Word 2013, 10 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/GDN%20E%20301%20Emergency%20Pt%20for%20Appt%20Gdn%20Con%202022%2001.pdf; text check: 99.9% of 1481 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-ju-03-0400-order-of-dependency.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/JU03_0400%20Order%20of%20Dependency_2025%2007.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - juvenile form JU 03.0400 (Order of Dependency)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 12,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-ju-03-0400-order-of-dependency.word.pdf",
+ "notes": "list/heading numbering (10 abstractNums, numPr on 2 paras, multi-level); tables x2; header parts 0, footer parts 1; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 12 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/JU03_0400%20Order%20of%20Dependency_2025%2007.pdf; text check: 100.0% of 2413 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-ju-07-0800-order-on-adjudication-and-disposition.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/JU%2007_0800%20Order%20on%20Adjudication%20and%20Disposition_07.2025.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - juvenile offender form JU 07.0800 (Order on Adjudication and Disposition)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "legal",
+ "pages_hint": 14,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": "wacourts-ju-07-0800-order-on-adjudication-and-disposition.word.pdf",
+ "notes": "list/heading numbering (5 abstractNums, numPr on 2 paras, multi-level); tables x9; text frames (framePr) x5; header parts 0, footer parts 1; dot/leader tabs; compatibilityMode 15; Word reference PDF: Microsoft® Word for Microsoft 365, 14 pages (= docx Pages), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/JU%2007_0800%20Order%20on%20Adjudication%20and%20Disposition_07.2025.pdf; text check: 99.9% of 3428 docx body words found in PDF text"
+ },
+ {
+ "file": "wacourts-mpi-408-assisted-outpatient-treatment-user-guide.docx",
+ "source_url": "https://www.courts.wa.gov/forms/documents/MPi%20408%20%20AOT%20User%20Guide_2023%2001.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Washington State Courts - MPi 408 (Assisted Outpatient Treatment user guide)",
+ "license": "Washington State Courts (Administrative Office of the Courts) pattern form; public government form, free to use",
+ "category": "report",
+ "pages_hint": 6,
+ "generator": "Microsoft Office Word 15.0000",
+ "word_pdf": "wacourts-mpi-408-assisted-outpatient-treatment-user-guide.word.pdf",
+ "notes": "list/heading numbering (32 abstractNums, numPr on 21 paras, multi-level); tables x2; DrawingML objects (inline x1); 2 sections; header parts 0, footer parts 1; hyperlinks x2; compatibilityMode 15; Word reference PDF: Microsoft® Word 2013, 6 pages (docx Pages says 1), 612 x 792 pts (letter); source https://www.courts.wa.gov/forms/documents/MPi%20408%20%20AOT%20User%20Guide_2023%2001.pdf; text check: 99.8% of 1290 docx body words found in PDF text"
+ },
+ {
+ "file": "weconservepa-model-grant-of-conservation-easement-2025.docx",
+ "source_url": "https://library.weconservepa.org/library_items/323/files/2973",
+ "retrieved": "2026-10-04",
+ "provenance": "WeConservePA (Pennsylvania land trust association) - Model Grant of Conservation Easement (2025 edition, CE-model_250916Ae.docx)",
+ "license": "Model document published for free public use by WeConservePA; no explicit open license",
+ "category": "legal",
+ "pages_hint": 18,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (12 abstractNums, numPr on 9 paras, 9 style-linked numbering, multi-level); fields: PAGE x1; DrawingML objects (anchored/floating x2); wps shapes x1; text boxes (txbxContent) x2; VML pict/shapes x2; header parts 0, footer parts 1; embedded fonts x4; compatibilityMode 15; LibreOffice 24.2.7.2 render: 18 pages (matches pages_hint)"
+ },
+ {
+ "file": "wipo-wo-ga-57-2-iod-annual-report-charts.docx",
+ "source_url": "https://www.wipo.int/edocs/mdocs/govbody/en/wo_ga_57/wo_ga_57_2.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "World Intellectual Property Organization (WIPO) - WO/GA/57/2 Annual Report by the Director of the Internal Oversight Division (meeting document)",
+ "license": "WIPO meeting document, freely downloadable (WIPO terms of use; WIPO content generally CC BY 4.0 IGO - verify)",
+ "category": "report",
+ "pages_hint": 29,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "footnotes x25; list/heading numbering (20 abstractNums, numPr on 90 paras, 4 style-linked numbering, multi-level); TOC field; fields: PAGEREF x19, PAGE x1; tables x7 (nested); native charts x3; DrawingML objects (inline x10, anchored/floating x1); wps shapes x2; text boxes (txbxContent) x2; VML pict/shapes x3; 4 sections; different first-page header/footer; header parts 6, footer parts 3; bookmarks x56 (cross-reference targets); hyperlinks x19; dot/leader tabs; compatibilityMode 15; ALT reference (not counted as word_pdf): wipo-wo-ga-57-2-iod-annual-report-charts.pdfmaker.pdf = Acrobat PDFMaker 23 for Word / Adobe PDF Library 23.1.96, 29 pages (= docx Pages); Acrobat PDFMaker prints Word's own layout; text check: 99.9% of 9956 docx body words found in PDF text; Native Word charts; LibreOffice 24.2.7.2 render: 29 pages (matches pages_hint)"
+ },
+ {
+ "file": "yc-pro-rata-side-letter.docx",
+ "source_url": "https://bookface-static.ycombinator.com/assets/ycdc/Pro%20Rata%20Side%20Letter-d6dd8d827741862b18fba0f658da17fb4e787e5f2dda49584b9caea89bf42302.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Y Combinator (ycombinator.com/documents)",
+ "license": "Y Combinator standard SAFE documents; freely available for use (YC documents page)",
+ "category": "legal",
+ "pages_hint": 1,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "header parts 1, footer parts 1; hyperlinks x2; compatibilityMode 15; LibreOffice 24.2.7.2 render: 1 pages (matches pages_hint)"
+ },
+ {
+ "file": "yc-safe-post-money-mfn.docx",
+ "source_url": "https://bookface-static.ycombinator.com/assets/ycdc/Postmoney%20Safe%20-%20MFN%20Only%20-%20FINAL-2bc87fa3d2ec5072a60d653aec9a885fb43879781e44341fa720a8e7d1cc42ff.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Y Combinator (ycombinator.com/documents)",
+ "license": "Y Combinator standard SAFE documents; freely available for use (YC documents page)",
+ "category": "legal",
+ "pages_hint": 6,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (7 abstractNums, 18 style-linked numbering, multi-level); fields: PAGE x1; 2 sections; different first-page header/footer; header parts 3, footer parts 3; hyperlinks x1; dot/leader tabs; compatibilityMode 15; LibreOffice 24.2.7.2 render: 6 pages (matches pages_hint)"
+ },
+ {
+ "file": "yc-safe-post-money-valuation-cap.docx",
+ "source_url": "https://bookface-static.ycombinator.com/assets/ycdc/Postmoney%20Safe%20-%20Valuation%20Cap%20Only%20-%20FINAL-f2a64add6d21039ab347ee2e7194141a4239e364ffed54bad0fe9cf623bf1691.docx",
+ "retrieved": "2026-10-04",
+ "provenance": "Y Combinator (ycombinator.com/documents)",
+ "license": "Y Combinator standard SAFE documents; freely available for use (YC documents page)",
+ "category": "legal",
+ "pages_hint": 7,
+ "generator": "Microsoft Office Word 16.0000",
+ "word_pdf": null,
+ "notes": "list/heading numbering (9 abstractNums, numPr on 8 paras, 18 style-linked numbering, multi-level); fields: PAGE x1; 2 sections; different first-page header/footer; header parts 3, footer parts 3; hyperlinks x1; dot/leader tabs; compatibilityMode 15; LibreOffice 24.2.7.2 render: 7 pages (matches pages_hint)"
+ }
+]
\ No newline at end of file
diff --git a/crates/docx_engine/tests/fixtures/complex-msa.docx b/crates/docx_engine/tests/fixtures/complex-msa.docx
new file mode 100644
index 0000000000..70e1c17282
Binary files /dev/null and b/crates/docx_engine/tests/fixtures/complex-msa.docx differ
diff --git a/crates/docx_engine/tests/fixtures/mutual-nda.docx b/crates/docx_engine/tests/fixtures/mutual-nda.docx
new file mode 100644
index 0000000000..e87d7e8539
Binary files /dev/null and b/crates/docx_engine/tests/fixtures/mutual-nda.docx differ
diff --git a/crates/docx_engine/tests/fixtures/simple_test.docx b/crates/docx_engine/tests/fixtures/simple_test.docx
new file mode 100644
index 0000000000..caaaec9d94
Binary files /dev/null and b/crates/docx_engine/tests/fixtures/simple_test.docx differ
diff --git a/crates/pptx_engine/Cargo.toml b/crates/pptx_engine/Cargo.toml
index 899f9daa9b..c537c626c4 100644
--- a/crates/pptx_engine/Cargo.toml
+++ b/crates/pptx_engine/Cargo.toml
@@ -9,7 +9,12 @@ version = "0.1.0"
crate-type = ["cdylib", "rlib"]
[features]
-default = []
+default = ["wasm-bindings"]
+# The wasm-bindgen API in `wasm` (the presentation editor's worker module).
+# Crates that build their own wasm module on top of this one (the DOCX engine
+# reuses its containers, fonts and rasterizer) turn it off, so the
+# presentation exports are not linked into their module.
+wasm-bindings = []
# Compile the bundled font set into native builds (AI tools, the corpus CLI).
# The wasm build always includes it: the browser worker has no font directory.
embedded-fonts = []
diff --git a/crates/pptx_engine/fonts/LICENSE-Noto.txt b/crates/pptx_engine/fonts/LICENSE-Noto.txt
new file mode 100644
index 0000000000..f90970d2aa
--- /dev/null
+++ b/crates/pptx_engine/fonts/LICENSE-Noto.txt
@@ -0,0 +1,93 @@
+Copyright 2022 The Noto Project Authors (https://github.com/notofonts/arabic, https://github.com/notofonts/hebrew)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/crates/pptx_engine/fonts/NotoNaskhArabic-Bold.ttf b/crates/pptx_engine/fonts/NotoNaskhArabic-Bold.ttf
new file mode 100644
index 0000000000..9abf241204
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoNaskhArabic-Bold.ttf differ
diff --git a/crates/pptx_engine/fonts/NotoNaskhArabic-Regular.ttf b/crates/pptx_engine/fonts/NotoNaskhArabic-Regular.ttf
new file mode 100644
index 0000000000..3889e63e19
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoNaskhArabic-Regular.ttf differ
diff --git a/crates/pptx_engine/fonts/NotoSansArabic-Bold.ttf b/crates/pptx_engine/fonts/NotoSansArabic-Bold.ttf
new file mode 100644
index 0000000000..b18494c3b1
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoSansArabic-Bold.ttf differ
diff --git a/crates/pptx_engine/fonts/NotoSansArabic-Regular.ttf b/crates/pptx_engine/fonts/NotoSansArabic-Regular.ttf
new file mode 100644
index 0000000000..70479fd463
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoSansArabic-Regular.ttf differ
diff --git a/crates/pptx_engine/fonts/NotoSansHebrew-Bold.ttf b/crates/pptx_engine/fonts/NotoSansHebrew-Bold.ttf
new file mode 100644
index 0000000000..2c432eead4
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoSansHebrew-Bold.ttf differ
diff --git a/crates/pptx_engine/fonts/NotoSansHebrew-Regular.ttf b/crates/pptx_engine/fonts/NotoSansHebrew-Regular.ttf
new file mode 100644
index 0000000000..ceb0e5f308
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoSansHebrew-Regular.ttf differ
diff --git a/crates/pptx_engine/fonts/NotoSerifHebrew-Bold.ttf b/crates/pptx_engine/fonts/NotoSerifHebrew-Bold.ttf
new file mode 100644
index 0000000000..62cf656c49
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoSerifHebrew-Bold.ttf differ
diff --git a/crates/pptx_engine/fonts/NotoSerifHebrew-Regular.ttf b/crates/pptx_engine/fonts/NotoSerifHebrew-Regular.ttf
new file mode 100644
index 0000000000..8aafd2808a
Binary files /dev/null and b/crates/pptx_engine/fonts/NotoSerifHebrew-Regular.ttf differ
diff --git a/crates/pptx_engine/fonts/README.md b/crates/pptx_engine/fonts/README.md
index 8c7abf0723..bd5c9f0674 100644
--- a/crates/pptx_engine/fonts/README.md
+++ b/crates/pptx_engine/fonts/README.md
@@ -2,8 +2,9 @@
Metric-compatible, freely licensed stand-ins for the fonts most presentations use.
Each file is a subset (Latin, Greek, Cyrillic, punctuation, currency, arrows, math,
-box drawing, geometric shapes, dingbats) with hinting removed; kerning and the
-basic layout features are kept. Regenerate with `scripts/subset_fonts.sh`.
+box drawing, geometric shapes, dingbats; the Noto faces only Arabic or Hebrew) with
+hinting removed; kerning and the basic layout features are kept (for Arabic, the
+joining forms and required ligatures shaping uses). Regenerate with `scripts/subset_fonts.sh`.
| File | Stands in for | License |
| --- | --- | --- |
@@ -13,3 +14,7 @@ basic layout features are kept. Regenerate with `scripts/subset_fonts.sh`.
| `LiberationSerif-*.ttf` | Times New Roman | SIL OFL 1.1, `LICENSE-Liberation.txt` |
| `LiberationMono-*.ttf` | Courier New | SIL OFL 1.1, `LICENSE-Liberation.txt` |
| `DejaVuSans*.ttf` | Verdana-like fallback, symbols, Wingdings/Symbol remaps | Bitstream Vera / DejaVu, `LICENSE-DejaVu.txt` |
+| `NotoNaskhArabic-*.ttf` | Arabic in serif fonts (Times New Roman, Simplified/Traditional Arabic) | SIL OFL 1.1, `LICENSE-Noto.txt` |
+| `NotoSansArabic-*.ttf` | Arabic in sans-serif fonts (Arial, Tahoma, Segoe UI) | SIL OFL 1.1, `LICENSE-Noto.txt` |
+| `NotoSerifHebrew-*.ttf` | Hebrew in serif fonts (Times New Roman, David, Frank Ruehl) | SIL OFL 1.1, `LICENSE-Noto.txt` |
+| `NotoSansHebrew-*.ttf` | Hebrew in sans-serif fonts (Arial, Tahoma, Segoe UI) | SIL OFL 1.1, `LICENSE-Noto.txt` |
diff --git a/crates/pptx_engine/scripts/subset_fonts.sh b/crates/pptx_engine/scripts/subset_fonts.sh
index 31694f80db..971d9f4e94 100755
--- a/crates/pptx_engine/scripts/subset_fonts.sh
+++ b/crates/pptx_engine/scripts/subset_fonts.sh
@@ -1,7 +1,8 @@
#!/usr/bin/env bash
# Regenerates crates/pptx_engine/fonts from system font packages
-# (fonts-crosextra-carlito, fonts-crosextra-caladea, fonts-liberation, fonts-dejavu-core).
-# Requires fonttools: `pip install fonttools`.
+# (fonts-crosextra-carlito, fonts-crosextra-caladea, fonts-liberation, fonts-dejavu-core)
+# and the Noto Arabic and Hebrew fonts (downloaded from notofonts.github.io).
+# Requires fonttools (`pip install fonttools`) and curl.
set -euo pipefail
OUT="$(cd "$(dirname "$0")/../fonts" && pwd)"
UNI="U+0000-024F,U+0250-02FF,U+0300-036F,U+0370-03FF,U+0400-04FF,U+1E00-1EFF,U+2000-206F,U+2070-209F,U+20A0-20CF,U+2100-214F,U+2150-218F,U+2190-21FF,U+2200-22FF,U+2300-23FF,U+2460-24FF,U+2500-257F,U+2580-259F,U+25A0-25FF,U+2600-26FF,U+2700-27BF,U+2B00-2BFF,U+FB00-FB06,U+FFFD"
@@ -15,3 +16,27 @@ for f in /usr/share/fonts/truetype/crosextra/*.ttf \
--no-hinting --desubroutinize --name-IDs='*' --name-languages='*' \
--output-file="$OUT/$(basename "$f")"
done
+
+# Arabic and Hebrew: their own letters (with the Arabic presentation forms and
+# the layout features shaping uses); other text falls back to the faces above.
+NOTO="https://raw.githubusercontent.com/notofonts/notofonts.github.io/main/fonts"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+for f in NotoNaskhArabic NotoSansArabic; do
+ for w in Regular Bold; do
+ curl -sSfL -o "$TMP/$f-$w.ttf" "$NOTO/$f/hinted/ttf/$f-$w.ttf"
+ pyftsubset "$TMP/$f-$w.ttf" \
+ --unicodes='U+0020-007E,U+00A0,U+00AB,U+00BB,U+0600-06FF,U+0750-077F,U+08A0-08FF,U+FB50-FDFF,U+FE70-FEFF,U+200C-200F,U+2010-2027,U+25CC' \
+ --layout-features='ccmp,locl,isol,init,medi,fina,rlig,liga,calt,rtlm,kern,mark,mkmk,curs' \
+ --no-hinting --desubroutinize --name-IDs='*' --output-file="$OUT/$f-$w.ttf"
+ done
+done
+for f in NotoSansHebrew NotoSerifHebrew; do
+ for w in Regular Bold; do
+ curl -sSfL -o "$TMP/$f-$w.ttf" "$NOTO/$f/hinted/ttf/$f-$w.ttf"
+ pyftsubset "$TMP/$f-$w.ttf" \
+ --unicodes='U+0020-007E,U+00A0,U+0590-05FF,U+FB1D-FB4F,U+200C-200F,U+20AA,U+25CC' \
+ --layout-features='ccmp,locl,calt,rtlm,kern,mark,mkmk' \
+ --no-hinting --desubroutinize --name-IDs='*' --output-file="$OUT/$f-$w.ttf"
+ done
+done
diff --git a/crates/pptx_engine/src/font.rs b/crates/pptx_engine/src/font.rs
index 7a18c636b4..1c7f3f9299 100644
--- a/crates/pptx_engine/src/font.rs
+++ b/crates/pptx_engine/src/font.rs
@@ -4,6 +4,7 @@
//! request is mapped to a registered face through a substitution table of
//! metric-compatible replacements, so line breaks match the original layout.
+pub mod arabic;
mod symbols;
use crate::path::{Path, Point};
@@ -122,6 +123,28 @@ pub const SUBSTITUTES: &[(&str, &[&str])] = &[
("lucida sans", &["DejaVu Sans"]),
("lucida sans unicode", &["DejaVu Sans"]),
("dejavu sans", &["DejaVu Sans"]),
+ // Arabic and Hebrew families: their letters come from the Noto faces
+ // (other characters fall back as for any face).
+ ("simplified arabic", &["Noto Naskh Arabic"]),
+ ("simplified arabic fixed", &["Noto Naskh Arabic"]),
+ ("traditional arabic", &["Noto Naskh Arabic"]),
+ ("arabic typesetting", &["Noto Naskh Arabic"]),
+ ("sakkal majalla", &["Noto Naskh Arabic"]),
+ ("aldhabi", &["Noto Naskh Arabic"]),
+ ("urdu typesetting", &["Noto Naskh Arabic"]),
+ ("microsoft uighur", &["Noto Naskh Arabic"]),
+ ("andalus", &["Noto Naskh Arabic"]),
+ ("arabic transparent", &["Noto Sans Arabic"]),
+ ("geeza pro", &["Noto Sans Arabic"]),
+ ("dubai", &["Noto Sans Arabic"]),
+ ("david", &["Noto Serif Hebrew"]),
+ ("frank ruehl", &["Noto Serif Hebrew"]),
+ ("frankruehl", &["Noto Serif Hebrew"]),
+ ("narkisim", &["Noto Sans Hebrew"]),
+ ("miriam", &["Noto Sans Hebrew"]),
+ ("gisha", &["Noto Sans Hebrew"]),
+ ("levenim mt", &["Noto Sans Hebrew"]),
+ ("aharoni", &["Noto Sans Hebrew"]),
];
/// Replacement for unknown sans-serif families.
@@ -138,6 +161,44 @@ const GLYPH_FALLBACKS: &[&str] = &[
"Liberation Serif",
];
+/// A script's characters, with its faces for serif and for sans-serif
+/// text, each in order.
+type ScriptFaces = (
+ fn(char) -> bool,
+ &'static [&'static str],
+ &'static [&'static str],
+);
+
+/// Faces for Arabic and Hebrew letters, tried before the others.
+const SCRIPT_FALLBACKS: &[ScriptFaces] = &[
+ (
+ is_arabic,
+ &["Noto Naskh Arabic", "Noto Sans Arabic"],
+ &["Noto Sans Arabic", "Noto Naskh Arabic"],
+ ),
+ (
+ is_hebrew,
+ &["Noto Serif Hebrew", "Noto Sans Hebrew"],
+ &["Noto Sans Hebrew", "Noto Serif Hebrew"],
+ ),
+];
+
+fn is_arabic(c: char) -> bool {
+ matches!(c as u32, 0x0600..=0x06FF | 0x0750..=0x077F | 0x08A0..=0x08FF | 0xFB50..=0xFDFF | 0xFE70..=0xFEFF)
+}
+
+fn is_hebrew(c: char) -> bool {
+ matches!(c as u32, 0x0590..=0x05FF | 0xFB1D..=0xFB4F)
+}
+
+/// Whether a bundled family draws serif letters.
+fn is_serif_family(family_lower: &str) -> bool {
+ ["serif", "caladea", "tinos", "gelasio", "naskh"]
+ .iter()
+ .any(|k| family_lower.contains(k))
+ && !family_lower.contains("sans")
+}
+
fn read_metrics(face: &ttf_parser::Face<'_>) -> FaceMetrics {
let upem = f32::from(face.units_per_em().max(1));
let (win_ascent, win_descent) = face
@@ -378,7 +439,8 @@ impl FontDb {
.unwrap_or(0.0)
}
- /// A face (other than `prefer`) that has a glyph for `ch`.
+ /// A face (other than `prefer`) that has a glyph for `ch`: for Arabic
+ /// and Hebrew a face of the script in `prefer`'s style (serif or sans).
pub fn fallback_for(
&self,
ch: char,
@@ -386,7 +448,17 @@ impl FontDb {
bold: bool,
italic: bool,
) -> Option<FontChoice> {
- for fam in GLYPH_FALLBACKS {
+ let preferred = self.faces.get(prefer.0 as usize);
+ let serif = preferred.is_some_and(|f| is_serif_family(&f.family_lower));
+ // The fallback matches the preferred face's own weight and slant too
+ // (a bold face is not synthetic bold).
+ let bold = bold || preferred.is_some_and(|f| f.bold);
+ let italic = italic || preferred.is_some_and(|f| f.italic);
+ let script = SCRIPT_FALLBACKS
+ .iter()
+ .find(|(is, _, _)| is(ch))
+ .map_or(&[][..], |(_, s, sans)| if serif { *s } else { *sans });
+ for fam in script.iter().chain(GLYPH_FALLBACKS) {
if let Some(c) = self.best_in_family(&fam.to_lowercase(), bold, italic)
&& c.face != prefer
&& self.glyph(c.face, ch).is_some()
@@ -574,6 +646,14 @@ pub mod embedded {
include_bytes!("../fonts/LiberationMono-BoldItalic.ttf"),
include_bytes!("../fonts/DejaVuSans.ttf"),
include_bytes!("../fonts/DejaVuSans-Bold.ttf"),
+ include_bytes!("../fonts/NotoNaskhArabic-Regular.ttf"),
+ include_bytes!("../fonts/NotoNaskhArabic-Bold.ttf"),
+ include_bytes!("../fonts/NotoSansArabic-Regular.ttf"),
+ include_bytes!("../fonts/NotoSansArabic-Bold.ttf"),
+ include_bytes!("../fonts/NotoSerifHebrew-Regular.ttf"),
+ include_bytes!("../fonts/NotoSerifHebrew-Bold.ttf"),
+ include_bytes!("../fonts/NotoSansHebrew-Regular.ttf"),
+ include_bytes!("../fonts/NotoSansHebrew-Bold.ttf"),
];
}
@@ -601,6 +681,14 @@ pub const BUNDLED_FONT_FILES: &[(&str, &str)] = &[
("Liberation Mono", "LiberationMono-BoldItalic.ttf"),
("DejaVu Sans", "DejaVuSans.ttf"),
("DejaVu Sans", "DejaVuSans-Bold.ttf"),
+ ("Noto Naskh Arabic", "NotoNaskhArabic-Regular.ttf"),
+ ("Noto Naskh Arabic", "NotoNaskhArabic-Bold.ttf"),
+ ("Noto Sans Arabic", "NotoSansArabic-Regular.ttf"),
+ ("Noto Sans Arabic", "NotoSansArabic-Bold.ttf"),
+ ("Noto Serif Hebrew", "NotoSerifHebrew-Regular.ttf"),
+ ("Noto Serif Hebrew", "NotoSerifHebrew-Bold.ttf"),
+ ("Noto Sans Hebrew", "NotoSansHebrew-Regular.ttf"),
+ ("Noto Sans Hebrew", "NotoSansHebrew-Bold.ttf"),
];
/// The bundled family that will serve a requested family (for lazy loading hosts).
diff --git a/crates/pptx_engine/src/font/arabic.rs b/crates/pptx_engine/src/font/arabic.rs
new file mode 100644
index 0000000000..6c5b60e843
--- /dev/null
+++ b/crates/pptx_engine/src/font/arabic.rs
@@ -0,0 +1,258 @@
+//! Arabic joining through the Unicode presentation forms.
+//!
+//! An Arabic letter takes one of four shapes depending on whether it joins
+//! the letters around it. Rather than running a face's GSUB lookups (the
+//! bundled Noto faces build letters from separate dots positioned by GPOS),
+//! shaping picks the precomposed presentation form of each letter (the
+//! Arabic Presentation Forms-A and -B blocks, which those faces and most
+//! Arabic fonts map), and joins lam with a following alef into one of the
+//! lam-alef ligatures.
+
+/// How a character joins its neighbours (Unicode `Joining_Type`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Joining {
+ /// Joins on both sides (beh, seen, lam...).
+ Dual,
+ /// Joins only the preceding letter (alef, dal, reh, waw...).
+ Right,
+ /// Joins on both sides without changing shape (tatweel, ZWJ).
+ Causing,
+ /// Does not take part: joining continues across it (vowel marks).
+ Transparent,
+ /// Breaks joining.
+ None,
+}
+
+/// A letter's shape.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum JoinForm {
+ /// Joined on neither side.
+ Isolated,
+ /// Joined to the following letter only.
+ Initial,
+ /// Joined on both sides.
+ Medial,
+ /// Joined to the preceding letter only.
+ Final,
+}
+
+/// The joining type of a character.
+pub fn joining(c: char) -> Joining {
+ let u = c as u32;
+ match u {
+ 0x064B..=0x065F
+ | 0x0670
+ | 0x0610..=0x061A
+ | 0x06D6..=0x06DC
+ | 0x06DF..=0x06E4
+ | 0x06E7
+ | 0x06E8
+ | 0x06EA..=0x06ED
+ | 0x08D3..=0x08E1
+ | 0x08E3..=0x08FF => Joining::Transparent,
+ 0x0640 | 0x200D => Joining::Causing,
+ 0x0622..=0x0625
+ | 0x0627
+ | 0x0629
+ | 0x062F..=0x0632
+ | 0x0648
+ | 0x0671..=0x0673
+ | 0x0675..=0x0677
+ | 0x0688..=0x0699
+ | 0x06C0
+ | 0x06C3..=0x06CB
+ | 0x06CD
+ | 0x06CF
+ | 0x06D2
+ | 0x06D3
+ | 0x06D5
+ | 0x06EE
+ | 0x06EF
+ | 0x0759..=0x075B
+ | 0x076B
+ | 0x076C
+ | 0x0771
+ | 0x0773
+ | 0x0774
+ | 0x0778
+ | 0x0779 => Joining::Right,
+ 0x0626
+ | 0x0628
+ | 0x062A..=0x062E
+ | 0x0633..=0x063F
+ | 0x0641..=0x0647
+ | 0x0649
+ | 0x064A
+ | 0x066E
+ | 0x066F
+ | 0x0678..=0x0687
+ | 0x069A..=0x06BF
+ | 0x06C1
+ | 0x06C2
+ | 0x06CC
+ | 0x06CE
+ | 0x06D0
+ | 0x06D1
+ | 0x06FA..=0x06FC
+ | 0x06FF
+ | 0x0750..=0x0758
+ | 0x075C..=0x076A
+ | 0x076D..=0x0770
+ | 0x0772
+ | 0x0775..=0x0777
+ | 0x077A..=0x077F => Joining::Dual,
+ _ => Joining::None,
+ }
+}
+
+/// Presentation forms (isolated, final, initial, medial; 0 = none).
+const FORMS_B: [[u16; 4]; 42] = [
+ [0xFE80, 0, 0, 0], // 0621 hamza
+ [0xFE81, 0xFE82, 0, 0], // 0622 alef with madda
+ [0xFE83, 0xFE84, 0, 0], // 0623 alef with hamza above
+ [0xFE85, 0xFE86, 0, 0], // 0624 waw with hamza
+ [0xFE87, 0xFE88, 0, 0], // 0625 alef with hamza below
+ [0xFE89, 0xFE8A, 0xFE8B, 0xFE8C], // 0626 yeh with hamza
+ [0xFE8D, 0xFE8E, 0, 0], // 0627 alef
+ [0xFE8F, 0xFE90, 0xFE91, 0xFE92], // 0628 beh
+ [0xFE93, 0xFE94, 0, 0], // 0629 teh marbuta
+ [0xFE95, 0xFE96, 0xFE97, 0xFE98], // 062A teh
+ [0xFE99, 0xFE9A, 0xFE9B, 0xFE9C], // 062B theh
+ [0xFE9D, 0xFE9E, 0xFE9F, 0xFEA0], // 062C jeem
+ [0xFEA1, 0xFEA2, 0xFEA3, 0xFEA4], // 062D hah
+ [0xFEA5, 0xFEA6, 0xFEA7, 0xFEA8], // 062E khah
+ [0xFEA9, 0xFEAA, 0, 0], // 062F dal
+ [0xFEAB, 0xFEAC, 0, 0], // 0630 thal
+ [0xFEAD, 0xFEAE, 0, 0], // 0631 reh
+ [0xFEAF, 0xFEB0, 0, 0], // 0632 zain
+ [0xFEB1, 0xFEB2, 0xFEB3, 0xFEB4], // 0633 seen
+ [0xFEB5, 0xFEB6, 0xFEB7, 0xFEB8], // 0634 sheen
+ [0xFEB9, 0xFEBA, 0xFEBB, 0xFEBC], // 0635 sad
+ [0xFEBD, 0xFEBE, 0xFEBF, 0xFEC0], // 0636 dad
+ [0xFEC1, 0xFEC2, 0xFEC3, 0xFEC4], // 0637 tah
+ [0xFEC5, 0xFEC6, 0xFEC7, 0xFEC8], // 0638 zah
+ [0xFEC9, 0xFECA, 0xFECB, 0xFECC], // 0639 ain
+ [0xFECD, 0xFECE, 0xFECF, 0xFED0], // 063A ghain
+ [0, 0, 0, 0], // 063B
+ [0, 0, 0, 0], // 063C
+ [0, 0, 0, 0], // 063D
+ [0, 0, 0, 0], // 063E
+ [0, 0, 0, 0], // 063F
+ [0, 0, 0, 0], // 0640 tatweel
+ [0xFED1, 0xFED2, 0xFED3, 0xFED4], // 0641 feh
+ [0xFED5, 0xFED6, 0xFED7, 0xFED8], // 0642 qaf
+ [0xFED9, 0xFEDA, 0xFEDB, 0xFEDC], // 0643 kaf
+ [0xFEDD, 0xFEDE, 0xFEDF, 0xFEE0], // 0644 lam
+ [0xFEE1, 0xFEE2, 0xFEE3, 0xFEE4], // 0645 meem
+ [0xFEE5, 0xFEE6, 0xFEE7, 0xFEE8], // 0646 noon
+ [0xFEE9, 0xFEEA, 0xFEEB, 0xFEEC], // 0647 heh
+ [0xFEED, 0xFEEE, 0, 0], // 0648 waw
+ [0xFEEF, 0xFEF0, 0xFBE8, 0xFBE9], // 0649 alef maksura
+ [0xFEF1, 0xFEF2, 0xFEF3, 0xFEF4], // 064A yeh
+];
+
+/// Presentation forms of letters outside the basic range (Persian, Urdu).
+const FORMS_A: &[(u16, [u16; 4])] = &[
+ (0x0671, [0xFB50, 0xFB51, 0, 0]),
+ (0x0679, [0xFB66, 0xFB67, 0xFB68, 0xFB69]),
+ (0x067E, [0xFB56, 0xFB57, 0xFB58, 0xFB59]),
+ (0x0686, [0xFB7A, 0xFB7B, 0xFB7C, 0xFB7D]),
+ (0x0688, [0xFB88, 0xFB89, 0, 0]),
+ (0x0691, [0xFB8C, 0xFB8D, 0, 0]),
+ (0x0698, [0xFB8A, 0xFB8B, 0, 0]),
+ (0x06A9, [0xFB8E, 0xFB8F, 0xFB90, 0xFB91]),
+ (0x06AF, [0xFB92, 0xFB93, 0xFB94, 0xFB95]),
+ (0x06BA, [0xFB9E, 0xFB9F, 0, 0]),
+ (0x06BE, [0xFBAA, 0xFBAB, 0xFBAC, 0xFBAD]),
+ (0x06C0, [0xFBA4, 0xFBA5, 0, 0]),
+ (0x06C1, [0xFBA6, 0xFBA7, 0xFBA8, 0xFBA9]),
+ (0x06CC, [0xFBFC, 0xFBFD, 0xFBFE, 0xFBFF]),
+ (0x06D2, [0xFBAE, 0xFBAF, 0, 0]),
+ (0x06D3, [0xFBB0, 0xFBB1, 0, 0]),
+];
+
+fn index(form: JoinForm) -> usize {
+ match form {
+ JoinForm::Isolated => 0,
+ JoinForm::Final => 1,
+ JoinForm::Initial => 2,
+ JoinForm::Medial => 3,
+ }
+}
+
+/// The presentation form of a letter in a shape, when Unicode has one.
+pub fn presentation_form(c: char, form: JoinForm) -> Option<char> {
+ let u = c as u32;
+ let forms = if (0x0621..=0x064A).contains(&u) {
+ &FORMS_B[(u - 0x0621) as usize]
+ } else {
+ &FORMS_A.iter().find(|(base, _)| u32::from(*base) == u)?.1
+ };
+ let code = forms[index(form)];
+ (code != 0)
+ .then(|| char::from_u32(u32::from(code)))
+ .flatten()
+}
+
+/// The lam-alef ligature for lam followed by `alef`: joined to the letter
+/// before the lam (final form) or not (isolated).
+pub fn lam_alef(alef: char, joined_before: bool) -> Option<char> {
+ let isolated = match alef {
+ '\u{0622}' => 0xFEF5,
+ '\u{0623}' => 0xFEF7,
+ '\u{0625}' => 0xFEF9,
+ '\u{0627}' => 0xFEFB,
+ _ => return None,
+ };
+ char::from_u32(isolated + u32::from(joined_before))
+}
+
+/// The shape of each character of a run of text: `None` for characters
+/// that do not change, the form of each letter otherwise. Joining looks
+/// across transparent characters (vowel marks).
+pub fn forms(chars: &[char]) -> Vec<Option<JoinForm>> {
+ let types: Vec<Joining> = chars.iter().map(|&c| joining(c)).collect();
+ forms_of(&types)
+}
+
+/// [`forms`] for characters given by their joining types.
+pub fn forms_of(types: &[Joining]) -> Vec<Option<JoinForm>> {
+ let neighbour = |from: usize, step: isize| -> Joining {
+ let mut i = from as isize + step;
+ while i >= 0 && (i as usize) < types.len() {
+ match types[i as usize] {
+ Joining::Transparent => i += step,
+ t => return t,
+ }
+ }
+ Joining::None
+ };
+ types
+ .iter()
+ .enumerate()
+ .map(|(i, t)| {
+ let (dual, right) = match t {
+ Joining::Dual => (true, true),
+ Joining::Right => (false, true),
+ _ => return None,
+ };
+ // Joined to the preceding letter when that one joins forward.
+ let before = right && matches!(neighbour(i, -1), Joining::Dual | Joining::Causing);
+ // Joined to the following letter when it joins backward.
+ let after = dual
+ && matches!(
+ neighbour(i, 1),
+ Joining::Dual | Joining::Right | Joining::Causing
+ );
+ Some(match (before, after) {
+ (true, true) => JoinForm::Medial,
+ (true, false) => JoinForm::Final,
+ (false, true) => JoinForm::Initial,
+ (false, false) => JoinForm::Isolated,
+ })
+ })
+ .collect()
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/pptx_engine/src/font/arabic/test.rs b/crates/pptx_engine/src/font/arabic/test.rs
new file mode 100644
index 0000000000..a346ec73e5
--- /dev/null
+++ b/crates/pptx_engine/src/font/arabic/test.rs
@@ -0,0 +1,49 @@
+use super::*;
+
+fn shapes(text: &str) -> Vec<Option<JoinForm>> {
+ forms(&text.chars().collect::<Vec<_>>())
+}
+
+#[test]
+fn letters_join_their_neighbours() {
+ use JoinForm::*;
+ // beh seen meem: joined all through.
+ assert_eq!(
+ shapes("\u{0628}\u{0633}\u{0645}"),
+ vec![Some(Initial), Some(Medial), Some(Final)]
+ );
+ // dal, alef and reh join only what comes before them.
+ assert_eq!(
+ shapes("\u{062F}\u{0627}\u{0631}"),
+ vec![Some(Isolated), Some(Isolated), Some(Isolated)]
+ );
+ assert_eq!(shapes("\u{0628}\u{062F}"), vec![Some(Initial), Some(Final)]);
+ // A vowel mark between letters does not break the join; a space does.
+ assert_eq!(
+ shapes("\u{0628}\u{064E}\u{0628} \u{0628}"),
+ vec![Some(Initial), None, Some(Final), None, Some(Isolated)]
+ );
+ // Tatweel joins on both sides.
+ assert_eq!(shapes("\u{0628}\u{0640}"), vec![Some(Initial), None]);
+}
+
+#[test]
+fn presentation_forms_and_lam_alef() {
+ assert_eq!(
+ presentation_form('\u{0628}', JoinForm::Initial),
+ Some('\u{FE91}')
+ );
+ assert_eq!(
+ presentation_form('\u{0627}', JoinForm::Final),
+ Some('\u{FE8E}')
+ );
+ assert_eq!(presentation_form('\u{0627}', JoinForm::Initial), None);
+ assert_eq!(
+ presentation_form('\u{06CC}', JoinForm::Medial),
+ Some('\u{FBFF}')
+ );
+ assert_eq!(presentation_form('a', JoinForm::Final), None);
+ assert_eq!(lam_alef('\u{0627}', false), Some('\u{FEFB}'));
+ assert_eq!(lam_alef('\u{0627}', true), Some('\u{FEFC}'));
+ assert_eq!(lam_alef('\u{0628}', true), None);
+}
diff --git a/crates/pptx_engine/src/font/test.rs b/crates/pptx_engine/src/font/test.rs
index f5f037694a..a406d5ce19 100644
--- a/crates/pptx_engine/src/font/test.rs
+++ b/crates/pptx_engine/src/font/test.rs
@@ -4,7 +4,7 @@ use crate::test_support::fonts;
#[test]
fn registers_bundled_families() {
let db = fonts();
- assert_eq!(db.len(), 22);
+ assert_eq!(db.len(), 30);
for fam in [
"Carlito",
"Caladea",
@@ -12,6 +12,10 @@ fn registers_bundled_families() {
"Liberation Serif",
"Liberation Mono",
"DejaVu Sans",
+ "Noto Naskh Arabic",
+ "Noto Sans Arabic",
+ "Noto Serif Hebrew",
+ "Noto Sans Hebrew",
] {
assert!(db.has_family(fam), "{fam}");
}
@@ -89,3 +93,32 @@ fn symbol_fonts_remap() {
assert_eq!(bundled_family_for("Wingdings"), "DejaVu Sans");
assert_eq!(bundled_family_for("Unknown Font"), "Liberation Sans");
}
+
+#[test]
+fn arabic_and_hebrew_fall_back_to_a_face_in_the_same_style() {
+ let mut db = FontDb::new();
+ for file in [
+ "LiberationSerif-Regular.ttf",
+ "LiberationSans-Regular.ttf",
+ "NotoNaskhArabic-Regular.ttf",
+ "NotoSansArabic-Regular.ttf",
+ "NotoSerifHebrew-Regular.ttf",
+ "NotoSansHebrew-Regular.ttf",
+ ] {
+ let path = format!("{}/fonts/{file}", env!("CARGO_MANIFEST_DIR"));
+ db.register(std::fs::read(path).expect("font file"));
+ }
+ let serif = db.select("Times New Roman", false, false).unwrap().face;
+ let sans = db.select("Arial", false, false).unwrap().face;
+ let family = |prefer: FaceId, ch: char| {
+ let c = db.fallback_for(ch, prefer, false, false).unwrap();
+ db.family(c.face).to_owned()
+ };
+ assert_eq!(family(serif, '\u{0628}'), "Noto Naskh Arabic");
+ assert_eq!(family(sans, '\u{0628}'), "Noto Sans Arabic");
+ assert_eq!(family(serif, '\u{05D0}'), "Noto Serif Hebrew");
+ assert_eq!(family(sans, '\u{05D0}'), "Noto Sans Hebrew");
+ // Arabic families map to the matching Noto face.
+ let simplified = db.select("Simplified Arabic", false, false).unwrap().face;
+ assert_eq!(db.family(simplified), "Noto Naskh Arabic");
+}
diff --git a/crates/pptx_engine/src/lib.rs b/crates/pptx_engine/src/lib.rs
index ff33f9840c..74f8f69cea 100644
--- a/crates/pptx_engine/src/lib.rs
+++ b/crates/pptx_engine/src/lib.rs
@@ -22,7 +22,7 @@ pub mod render;
#[cfg(test)]
mod test_support;
pub mod units;
-#[cfg(target_arch = "wasm32")]
+#[cfg(all(target_arch = "wasm32", feature = "wasm-bindings"))]
mod wasm;
pub mod xml;
pub mod zip;
diff --git a/crates/pptx_engine/tests/corpus/baseline.json b/crates/pptx_engine/tests/corpus/baseline.json
index 9cba374ce0..5e4d057a8c 100644
--- a/crates/pptx_engine/tests/corpus/baseline.json
+++ b/crates/pptx_engine/tests/corpus/baseline.json
@@ -776,7 +776,7 @@
"mismatch": 0.01
},
{
- "fingerprint": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeeeefeeefeeefeeeeeefffffffffffffecddedcdddddedddddcdfffffffffffefffffffefffffffffffffffffffedddddefffffeffffffeeeedcdeeeeffffdddddddeeeefffffffffffffffffffeddeddeedeeeeefffffffffffffffffffffedddcdcdeeeffffffffffffffffffffffeeeeeeefffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffedfffffffcffffcefffbeffeddffffffeceffffffcefffdffffdefffecffffffedfffffffdffffeefffffffffeefffffeeeeeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ "fingerprint": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeeeefeeefeeefeeeeeefffffffffffffecddedcdddddedddddcdfffffffffffefffffffefffffffffffffffffffedddddefffffeffffffeeeedcdcdceffffdddddddeeeefffffffffffffffffffeddeddeedeeeeefffffffffffffffffffffedddcdcdeeeffffffffffffffffffffffeeeeeeefffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffedfffffffcffffcefffbeffeddffffffeceffffffcefffdffffdefffecffffffedfffffffdffffeefffffffffeefffffeeeeeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"ssim": 0.9479,
"mismatch": 0.0228
}
@@ -815,7 +815,7 @@
"mismatch": 0.0569
},
{
- "fingerprint": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeeefeeeeeeeeeeefffffffffffffffffccddddeddeddddddfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffedffffffffffffffffffffffddddddeffffddddeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffddffffffffffffffffffffffffffffffffffffffffffffffffefeeffffffffffffffffffffffffffeeeeedeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ "fingerprint": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeeefeeeeeeeeeeefffffffffffffffffccddddeddeddddddfffffffffffffffffffffffffffffffffffffffffffecccdcdcdcceccdeddddeddddddefffffffffffeeededceedeceddedeedfffffffffffffffeecccdccdeeddccdceffffffffffffffffffffffffefffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffccddccddceeddcccdcdddccefffffffffffffffffedddeeefedddddfffffffefeeffffffffeeefeffeeeeeefffffeeeeedeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"ssim": 0.8528,
"mismatch": 0.048
},
diff --git a/docs/AGENT_GUIDE/documents.md b/docs/AGENT_GUIDE/documents.md
index 2ac453726e..d965959922 100644
--- a/docs/AGENT_GUIDE/documents.md
+++ b/docs/AGENT_GUIDE/documents.md
@@ -806,35 +806,99 @@ shown as a bare highlight.
When `enable-docx-editor` is on, uploaded `.docx` files open at
`/app/write/<id>` in an editor instead of the PDF preview. The flag is a
PostHog flag that is on by default in dev mode; set `VITE_ENABLE_DOCX_EDITOR`
-to override it locally. The header label has a **Beta** badge. The page is the
-Docxodus WASM engine. Edits sync through the sync service, so every open copy
-updates live and shows each collaborator's caret with their name.
-
-- Editors get a toolbar labelled `Document formatting` with the following
- controls: `Undo`, `Redo`, a `Paragraph style` select, bold, italic,
- underline and strikethrough, `Bulleted list`, `Numbered list`, the alignment
- buttons, `Insert table` and `Track changes`.
-- Typing is committed after about a second of idle time, or on blur. Wait
- roughly 1.5 s before checking another tab for the text.
-- Mod+Z, Mod+Shift+Z and Ctrl+Y (or the toolbar buttons) undo and redo. They
- commit pending typing first, so an undo straight after typing removes it,
- and leave the caret at the end of the change.
+to override it locally. The header label has a **Beta** badge. Pages are laid
+out and drawn by Macro's own DOCX engine (Rust compiled to wasm, in a worker)
+as `<canvas>` sheets with Word's pagination, so the document's text is not
+in the DOM. Edits sync through the sync service as you type: every open copy
+updates live and shows each collaborator's caret with their name
+(`[data-docx-peer]`).
+
+- Pages are `[data-docx-page="<index>"]` elements. Click a page to place the
+ caret, drag to select, double-click for a word and triple-click for a
+ paragraph. On a touch screen a swipe scrolls, a tap places the caret, and
+ a double tap or a held press selects a word. Keystrokes go to a hidden textarea, `[data-docx-input]`
+ (labelled `Document text`); it must have focus, which a click on a page
+ gives it. Read text back from another tab or after a download, not from
+ the page.
+- Editors get a toolbar labelled `Document formatting`: `Undo`, `Redo`, the
+ `Paragraph style`, `Font` and `Font size` selects, `Bold`, `Italic`,
+ `Underline`, `Strikethrough`, `Superscript`, `Subscript`, the `Text color`
+ and `Highlight` menus (`[data-docx-menu="color"]`,
+ `[data-docx-menu="highlight"]`), `Clear formatting`, `Bulleted list`,
+ `Numbered list`, the alignment buttons, `Decrease indent`, `Increase
+ indent`, the `Line spacing` menu, `Insert table` (inside a table also the
+ `Table rows and columns` menu, `[data-docx-menu="table"]`, to insert or
+ delete rows and columns or the table), the `Insert footnote or endnote`
+ menu (`[data-docx-menu="notes"]`, in the body), `Track changes`, `Hide tracked
+ changes` / `Show tracked changes`, `Comment on selection`, `Find and
+ replace` and `Download .docx` (viewers get `Find and replace` and
+ `Download .docx`).
+ While tracking is on (or the caret is on a tracked change) it also shows
+ `Accept change`, `Reject change`, `Accept all changes` and `Reject all
+ changes`.
+- The browser's own find cannot see canvas text, so Mod+F in the document
+ (or `Find and replace`) opens the editor's find bar (`[data-docx-find]`) in
+ the top right; Ctrl+H (Cmd+Shift+H on a Mac) opens it with the replace
+ field. The `Find in document` field (`[data-docx-find-query]`) searches as
+ you type and shows `<n> of <total>` (`[data-docx-find-status]`); matches
+ are highlighted on the pages (`[data-docx-find-match]`). Enter and
+ Shift+Enter (or the arrow buttons, or Mod+G) move between matches and
+ select them; `Match case` and `Whole words only` narrow the search. Straight
+ and curly quotes match each other. The `Replace` toggle shows `Replace
+ with` (`[data-docx-find-replacement]`) with `Replace`
+ (`[data-docx-replace]`) and `Replace all` (`[data-docx-replace-all]`);
+ replacements follow tracked changes and one undo takes back a replace all.
+ Escape closes the bar with the current match selected.
+- Arabic and Hebrew paragraphs lay out right to left as in Word (joined
+ Arabic letters, mixed-direction lines in visual order); the left and
+ right arrow keys move left and right on the page.
+- Mod+Z, Mod+Shift+Z and Ctrl+Y (or the toolbar buttons) undo and redo your
+ own edits only, never a collaborator's. Mod+B/I/U format, Tab and
+ Shift+Tab indent list items, Enter splits paragraphs and Shift+Enter
+ inserts a line break.
+- `Track changes` turns tracking on for the whole document (it is saved in
+ the file, as in Word): every editor's typing then shows as an underlined
+ insertion and deletions stay visible struck through, each under its
+ author's name. Formatting changes (bold, alignment, lists, indents) are
+ recorded too: the text looks formatted, and Accept and Reject appear when
+ the caret is in it. A thin bar in the left margin marks every line that
+ holds a change. Accept and reject act on the selection, the change at
+ the caret, or every change.
+- Double-click a page's header or footer area to edit it. The body dims, the
+ area gets a dashed edge and a `Header` (or `Footer`) label with a `Close`
+ button; Escape or a click on the body returns to the body. Header and
+ footer edits reach collaborators and the download like body edits.
+- Click a footnote or endnote at the bottom of the page (or after the body)
+ to type in it, as in Word; nothing dims. Escape or a click on the body
+ returns to the body. Comments stay with the body text.
+- To add a footnote or endnote at the caret, use the toolbar's asterisk
+ menu (`Insert footnote or endnote` → `Footnote` / `Endnote`) or Word's
+ shortcuts (Ctrl+Alt+F / Ctrl+Alt+D; Cmd+Option+F / Cmd+Option+E on a
+ Mac). The number appears in the text and the caret moves into the new
+ note at the foot of the page (endnotes go after the body).
- Clicking a DOCX in the Home list opens the editor in the Home preview pane.
-- Editors see editable `Header` and `Footer` bands. Viewers and commenters get
- a read-only paginated rendering instead.
+ Viewers and commenters see the same paginated pages, read-only.
- To comment on any text, including table cells: select it, then click the
- floating `Comment` button beside the selection. You can also use the toolbar
- `Comment on selection` button or Mod+Alt+M. The draft opens a thread card in
- the right margin. Posting creates a normal document discussion (`markdown`
- anchor with `mark_id`), so it also appears in channels and notifications.
-- Highlighted text is drawn with the CSS Custom Highlight API rather than DOM
- marks: query `CSS.highlights`, not `<mark>` elements.
+ floating `Comment` button beside the selection
+ (`[data-docx-comment-button]`). You can also use the toolbar `Comment on
+ selection` button or Mod+Alt+M. The draft opens a thread card in the right
+ margin. Posting creates a normal document discussion (`markdown` anchor
+ with `mark_id`), so it also appears in channels and notifications.
+ Commented text is highlighted by overlay elements
+ (`[data-docx-comment-highlight]`) above the canvas. Comments anchor in the
+ body only, not in headers or footers.
+- Comments written in Word (stored in the file) show in the same margin as
+ read-only cards (`[data-docx-word-comment="<id>"]`): author, date, text and
+ replies, marked `In the document` (and `Resolved` when done). Their text is
+ highlighted too (`[data-docx-comment-highlight="word:<id>"]`). They stay in
+ the file on download; reply with a Macro comment.
- Threads whose text was deleted are listed under `Comments on text that has
changed`, above the `Discussion` composer.
- AI `CommentOnDocument` works on DOCX by quote. The editor pins each quote to
the first matching text the next time someone opens the file.
-- `Download .docx` exports the current collaborative state with every edit.
- Comments stay in Macro threads and are not written into the file.
+- `Download .docx` exports the current collaborative state with every edit,
+ including headers, footers and tracked changes. Comments stay in Macro
+ threads and are not written into the file.
- The stored upload is not rewritten yet. Search, the PDF export and AI
`ReadContent` still see the original file.
- AI `ReadWordDocument` and `EditWordDocument` read and edit the live copy, so
diff --git a/nix-support/node_modules-hashes.json b/nix-support/node_modules-hashes.json
index 5f6337d4fa..2248668a1c 100644
--- a/nix-support/node_modules-hashes.json
+++ b/nix-support/node_modules-hashes.json
@@ -1,6 +1,6 @@
{
"nodeModules": {
- "aarch64-darwin": "sha256-uXdx2uoDP1VH6NVNLZ1LLB2AwgNAjJRGPi8J89cKa/s=",
- "x86_64-linux": "sha256-ifhk7ye/msxcYFHHAYTiQPVrANLs8k4wltq5EMxjERE="
+ "aarch64-darwin": "sha256-gL0PRN6Mex+H14FR+axzcj85ivDJ5+5my9MakhmMMGI=",
+ "x86_64-linux": "sha256-q1A4pPjhAFzc2885Zjh3V4oe81a5pWU3J3c0EOPROZQ="
}
}
diff --git a/packages/collaboration/src/collab/manager.ts b/packages/collaboration/src/collab/manager.ts
index 04eb894636..259f1477c0 100644
--- a/packages/collaboration/src/collab/manager.ts
+++ b/packages/collaboration/src/collab/manager.ts
@@ -63,6 +63,13 @@ export type SnapshotIngest =
export type LoroManagerOptions = {
documentId: string;
+ /**
+ * Keep a JSON mirror of the schema's state and report it through
+ * `onStateChange` (the default). Editors that read the LoroDoc directly
+ * turn it off: the mirror re-reads the whole document on every change.
+ * State updates then carry no state, only the initialization signal.
+ */
+ mirror?: boolean;
};
/** Map Loro's {@link ImportStatus} onto our Result: ok(didChange), or
@@ -295,6 +302,18 @@ export class LoroManager<S extends GenericRootSchema = GenericRootSchema>
return err([{ code: error.code, message: error.message }]);
}
+ if (this.options.mirror === false) {
+ this.emitState({
+ state: {} as InferType<S>,
+ metadata: {
+ direction: SyncDirection.TO_LORO,
+ tags: ['INITIALIZE'],
+ },
+ });
+ this.setInitialized(true);
+ return ok(undefined);
+ }
+
const mirror = createMirror(this._doc, this.schema);
try {
@@ -331,7 +350,7 @@ export class LoroManager<S extends GenericRootSchema = GenericRootSchema>
getUpdateSince(
lastVersionVector: VersionVector
): Result<Uint8Array | undefined, ResultError<LoroManagerError>[]> {
- if (!this._initialized || !this._mirror) {
+ if (!this._initialized) {
return err([
{ code: LoroManagerError.NotInitialized, message: 'Not initialized' },
]);
@@ -459,6 +478,18 @@ export class LoroManager<S extends GenericRootSchema = GenericRootSchema>
return err(statusResult.error);
}
+ if (this.options.mirror === false) {
+ this.emitState({
+ state: {} as InferType<S>,
+ metadata: {
+ direction: SyncDirection.TO_LORO,
+ tags: [LoroStateTag.Initialize],
+ },
+ });
+ this.setInitialized(true);
+ return ok(undefined);
+ }
+
const newMirror = createMirror(newDoc, this.schema);
this.subscribeMirror(newMirror);
diff --git a/packages/collaboration/src/docx/agent-types.ts b/packages/collaboration/src/docx/agent-types.ts
new file mode 100644
index 0000000000..cb30c5f97d
--- /dev/null
+++ b/packages/collaboration/src/docx/agent-types.ts
@@ -0,0 +1,56 @@
+import type { RunFormat } from './paragraph';
+
+/** One change an agent asks for. Ids are the engine's paragraph and block ids. */
+export type DocxAgentOperation =
+ | {
+ type: 'replaceText';
+ paragraph: string;
+ find: string;
+ replace: string;
+ occurrence?: number;
+ }
+ | { type: 'setText'; paragraph: string; text: string }
+ | ({
+ type: 'formatText';
+ paragraph: string;
+ find?: string;
+ occurrence?: number;
+ } & RunFormat)
+ | {
+ type: 'insertParagraph';
+ after?: string;
+ before?: string;
+ text: string;
+ style?: string;
+ }
+ | { type: 'delete'; id: string }
+ | { type: 'setStyle'; paragraph: string; style: string };
+
+export type DocxAgentRequest =
+ | { action: 'read'; start?: number; count?: number }
+ | { action: 'edit'; operations: DocxAgentOperation[] };
+
+export type DocxAgentResult = { content: string };
+
+/** A request the document cannot satisfy; the message is for the agent. */
+export class DocxAgentError extends Error {}
+
+/** Most operations one edit may apply. */
+export const MAX_DOCX_OPERATIONS = 50;
+/** Characters a read returns before it asks to be continued. */
+export const READ_BUDGET = 60_000;
+
+export const preview = (text: string, limit = 200) =>
+ text.length > limit ? `${text.slice(0, limit)}…` : text;
+
+/** Where `find` occurs in `text`. */
+export function occurrences(text: string, find: string): number[] {
+ const found: number[] = [];
+ if (!find) return found;
+ let index = text.indexOf(find);
+ while (index >= 0) {
+ found.push(index);
+ index = text.indexOf(find, index + find.length);
+ }
+ return found;
+}
diff --git a/packages/collaboration/src/docx/agent.ts b/packages/collaboration/src/docx/agent.ts
index 4ae8aa0e08..8784206e01 100644
--- a/packages/collaboration/src/docx/agent.ts
+++ b/packages/collaboration/src/docx/agent.ts
@@ -5,6 +5,16 @@ import type {
LiveSyncSource,
TimeoutError,
} from '../collab/source';
+import {
+ DocxAgentError,
+ type DocxAgentOperation,
+ type DocxAgentRequest,
+ type DocxAgentResult,
+ MAX_DOCX_OPERATIONS,
+ occurrences,
+ preview,
+ READ_BUDGET,
+} from './agent-types';
import {
createParagraph,
formatRange,
@@ -17,7 +27,6 @@ import {
paragraphAlignment,
paragraphStyle,
paragraphText,
- type RunFormat,
replaceRange,
runFormat,
segments,
@@ -32,103 +41,35 @@ import {
readDocxState,
writeDocxChanges,
} from './schema';
+import {
+ findStyle,
+ type ParagraphStyleInfo,
+ paragraphStylesFromXml,
+ prefixFor,
+} from './styles';
+import { describeWord, editWord, isWordFormat } from './word-agent';
import {
elementChildren,
getAttribute,
- isElement,
- namespaceDeclarations,
parseElement,
- parseXml,
serializeXml,
setAttribute,
type XmlElement,
} from './xml';
-/** One change an agent asks for. Ids are the engine's paragraph and block ids. */
-export type DocxAgentOperation =
- | {
- type: 'replaceText';
- paragraph: string;
- find: string;
- replace: string;
- occurrence?: number;
- }
- | { type: 'setText'; paragraph: string; text: string }
- | ({
- type: 'formatText';
- paragraph: string;
- find?: string;
- occurrence?: number;
- } & RunFormat)
- | {
- type: 'insertParagraph';
- after?: string;
- before?: string;
- text: string;
- style?: string;
- }
- | { type: 'delete'; id: string }
- | { type: 'setStyle'; paragraph: string; style: string };
-
-export type DocxAgentRequest =
- | { action: 'read'; start?: number; count?: number }
- | { action: 'edit'; operations: DocxAgentOperation[] };
-
-export type DocxAgentResult = { content: string };
+export {
+ DocxAgentError,
+ type DocxAgentOperation,
+ type DocxAgentRequest,
+ type DocxAgentResult,
+ MAX_DOCX_OPERATIONS,
+} from './agent-types';
-/** A request the document cannot satisfy; the message is for the agent. */
-export class DocxAgentError extends Error {}
-
-/** Most operations one edit may apply. */
-export const MAX_DOCX_OPERATIONS = 50;
-/** Characters a read returns before it asks to be continued. */
-const READ_BUDGET = 60_000;
const STYLES_PART = 'word/styles.xml';
-type ParagraphStyleInfo = {
- id: string;
- name: string;
- next: string | null;
- /** The style paragraphs without a style of their own use. */
- isDefault: boolean;
-};
-
/** Paragraph styles the document defines, in definition order. */
export function paragraphStyles(state: DocxPackageState): ParagraphStyleInfo[] {
- const xml = state.parts.get(STYLES_PART);
- if (!xml) return [];
- const root = parseXml(xml).find(isElement);
- if (!root) return [];
- const w = prefixFor(root, WORDML_NS) ?? 'w';
- const val = (node: XmlElement, local: string) => {
- const child = elementChildren(node).find((c) => c.name === `${w}:${local}`);
- return child ? getAttribute(child, `${w}:val`) : null;
- };
- return elementChildren(root)
- .filter(
- (node) =>
- node.name === `${w}:style` &&
- getAttribute(node, `${w}:type`) === 'paragraph'
- )
- .flatMap((node) => {
- const id = getAttribute(node, `${w}:styleId`);
- return id
- ? [
- {
- id,
- name: val(node, 'name') ?? id,
- next: val(node, 'next'),
- isDefault: getAttribute(node, `${w}:default`) === '1',
- },
- ]
- : [];
- });
-}
-
-function prefixFor(node: XmlElement, uri: string): string | null {
- for (const [prefix, value] of namespaceDeclarations(node))
- if (value === uri && prefix) return prefix;
- return null;
+ return paragraphStylesFromXml(state.parts.get(STYLES_PART));
}
type Tree = { root: XmlElement; names: Names };
@@ -224,20 +165,6 @@ class Workspace {
}
}
-function occurrences(text: string, find: string): number[] {
- const found: number[] = [];
- if (!find) return found;
- let index = text.indexOf(find);
- while (index >= 0) {
- found.push(index);
- index = text.indexOf(find, index + find.length);
- }
- return found;
-}
-
-const preview = (text: string, limit = 200) =>
- text.length > limit ? `${text.slice(0, limit)}…` : text;
-
class Editor {
readonly workspace: Workspace;
readonly touched = new Set<string>();
@@ -293,23 +220,14 @@ class Editor {
}
private resolveStyle(style: string): string {
- const wanted = style.trim();
- const lower = wanted.toLowerCase();
- const found =
- this.styles.find((s) => s.id === wanted) ??
- this.styles.find((s) => s.name.toLowerCase() === lower) ??
- this.styles.find((s) => s.id.toLowerCase() === lower) ??
- this.styles.find(
- (s) =>
- s.name.replace(/\s+/g, '').toLowerCase() === lower.replace(/\s+/g, '')
- );
+ const found = findStyle(this.styles, style);
if (!found)
throw new DocxAgentError(
`The document has no paragraph style "${style}". Its paragraph styles are: ${this.styles
.map((s) => s.id)
.join(', ')}.`
);
- return found.id;
+ return found;
}
private static singleLine(text: string, what: string) {
@@ -800,6 +718,18 @@ export async function runDocxAgentRequest(
);
const doc = new LoroDoc();
if (initial.value.snapshot.length > 0) doc.import(initial.value.snapshot);
+ // The editor's shared format: blocks and rich text the engine writes.
+ if (isWordFormat(doc)) {
+ if (request.action === 'read')
+ return { content: describeWord(doc, request) };
+ const version = doc.version();
+ const content = editWord(doc, request.operations);
+ const update = doc.export({ mode: 'update', from: version });
+ source.registerPeerId(doc.peerId);
+ if (!(await source.pushUpdate([update])))
+ throw new Error('the sync service did not acknowledge the edit');
+ return { content };
+ }
if (!isDocxSeeded(doc))
throw new DocxAgentError(
"This Word document hasn't been opened in Macro's editor yet, so it has no live copy to read or edit. Ask the user to open it once in Macro, then try again."
diff --git a/packages/collaboration/src/docx/styles.ts b/packages/collaboration/src/docx/styles.ts
new file mode 100644
index 0000000000..bafc880051
--- /dev/null
+++ b/packages/collaboration/src/docx/styles.ts
@@ -0,0 +1,74 @@
+import { WORDML_NS } from './paragraph';
+import {
+ elementChildren,
+ getAttribute,
+ isElement,
+ namespaceDeclarations,
+ parseXml,
+ type XmlElement,
+} from './xml';
+
+export type ParagraphStyleInfo = {
+ id: string;
+ name: string;
+ next: string | null;
+ /** The style paragraphs without a style of their own use. */
+ isDefault: boolean;
+};
+
+export function prefixFor(node: XmlElement, uri: string): string | null {
+ for (const [prefix, value] of namespaceDeclarations(node))
+ if (value === uri && prefix) return prefix;
+ return null;
+}
+
+/** Paragraph styles a styles part defines, in definition order. */
+export function paragraphStylesFromXml(
+ xml: string | undefined
+): ParagraphStyleInfo[] {
+ if (!xml) return [];
+ const root = parseXml(xml).find(isElement);
+ if (!root) return [];
+ const w = prefixFor(root, WORDML_NS) ?? 'w';
+ const val = (node: XmlElement, local: string) => {
+ const child = elementChildren(node).find((c) => c.name === `${w}:${local}`);
+ return child ? getAttribute(child, `${w}:val`) : null;
+ };
+ return elementChildren(root)
+ .filter(
+ (node) =>
+ node.name === `${w}:style` &&
+ getAttribute(node, `${w}:type`) === 'paragraph'
+ )
+ .flatMap((node) => {
+ const id = getAttribute(node, `${w}:styleId`);
+ return id
+ ? [
+ {
+ id,
+ name: val(node, 'name') ?? id,
+ next: val(node, 'next'),
+ isDefault: getAttribute(node, `${w}:default`) === '1',
+ },
+ ]
+ : [];
+ });
+}
+
+/** The id of the paragraph style a name or id refers to, or null. */
+export function findStyle(
+ styles: readonly ParagraphStyleInfo[],
+ style: string
+): string | null {
+ const wanted = style.trim();
+ const lower = wanted.toLowerCase();
+ const found =
+ styles.find((s) => s.id === wanted) ??
+ styles.find((s) => s.name.toLowerCase() === lower) ??
+ styles.find((s) => s.id.toLowerCase() === lower) ??
+ styles.find(
+ (s) =>
+ s.name.replace(/\s+/g, '').toLowerCase() === lower.replace(/\s+/g, '')
+ );
+ return found?.id ?? null;
+}
diff --git a/packages/collaboration/src/docx/word-agent.test.ts b/packages/collaboration/src/docx/word-agent.test.ts
new file mode 100644
index 0000000000..4b1fc06081
--- /dev/null
+++ b/packages/collaboration/src/docx/word-agent.test.ts
@@ -0,0 +1,202 @@
+import { LoroDoc, LoroMap, LoroText } from 'loro-crdt';
+import { describe, expect, it } from 'vitest';
+import { DocxAgentError } from './agent-types';
+import {
+ describeWord,
+ editWord,
+ isWordFormat,
+ WordDocument,
+} from './word-agent';
+
+const W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const STYLES = `<w:styles xmlns:w="${W}"><w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style><w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/><w:next w:val="Normal"/></w:style><w:style w:type="paragraph" w:styleId="Quote"><w:name w:val="Quote"/></w:style></w:styles>`;
+
+type Spec = {
+ id: string;
+ k: string;
+ p?: string;
+ o: string;
+ x?: string;
+ t?: Array<{ insert: string; attributes?: Record<string, string> }>;
+};
+
+/** A document in the engine's shared format. */
+function shared(blocks: Spec[]): LoroDoc {
+ const doc = new LoroDoc();
+ doc.configDefaultTextStyle({ expand: 'none' });
+ doc.getMap('docxMeta').set('formatVersion', 2);
+ const parts = doc.getMap('wordParts');
+ parts.set(
+ '/word/document.xml',
+ `<w:document xmlns:w="${W}"><w:body>\u0000BLOCKS\u0000</w:body></w:document>`
+ );
+ parts.set('/word/styles.xml', STYLES);
+ const map = doc.getMap('wordBlocks');
+ for (const b of blocks) {
+ const m = map.setContainer(b.id, new LoroMap());
+ m.set('k', b.k);
+ m.set('p', b.p ?? '');
+ m.set('o', b.o);
+ m.set('a', '');
+ m.set('x', b.x ?? '');
+ if (b.k === 'p') {
+ const text = m.setContainer('t', new LoroText());
+ if (b.t?.length) text.applyDelta(b.t);
+ }
+ }
+ doc.commit();
+ return doc;
+}
+
+const TIMES = { 'r:w:rFonts': '<w:rFonts w:ascii="Times New Roman"/>' };
+
+function sample() {
+ return shared([
+ {
+ id: 'h1',
+ k: 'p',
+ o: 'A',
+ x: '<w:pPr><w:pStyle w:val="Heading1"/></w:pPr>',
+ t: [{ insert: '1. Term' }],
+ },
+ {
+ id: 'p1',
+ k: 'p',
+ o: 'B',
+ x: '<w:pPr><w:jc w:val="both"/><w:sectPr><w:pgSz w:w="12240"/></w:sectPr></w:pPr>',
+ t: [
+ { insert: 'The term is ', attributes: TIMES },
+ { insert: '', attributes: { mark: '<w:bookmarkStart w:id="0"/>' } },
+ {
+ insert: 'two (2) years',
+ attributes: { ...TIMES, 'r:w:b': '<w:b/>' },
+ },
+ {
+ insert: ' old',
+ attributes: { wrap: '[["<w:del w:id=\\"1\\">","</w:del>"]]' },
+ },
+ { insert: '.', attributes: TIMES },
+ ],
+ },
+ { id: 't1', k: 'tbl', o: 'C' },
+ { id: 'r1', k: 'tr', p: 't1', o: 'V' },
+ { id: 'c1', k: 'tc', p: 'r1', o: 'V' },
+ { id: 'cp', k: 'p', p: 'c1', o: 'V', t: [{ insert: 'Phase one' }] },
+ ]);
+}
+
+const texts = (doc: LoroDoc) => {
+ const word = new WordDocument(doc);
+ const out: string[] = [];
+ const walk = (parent: string) => {
+ for (const b of word.kids(parent)) {
+ if (b.kind === 'p') out.push(word.visible(b).text);
+ walk(b.id);
+ }
+ };
+ walk('');
+ return out;
+};
+
+describe('Word documents in the shared format', () => {
+ it('reads blocks with ids, styles, visible text and formatting', () => {
+ const doc = sample();
+ expect(isWordFormat(doc)).toBe(true);
+ const read = describeWord(doc);
+ expect(read).toContain('Word document with 3 blocks.');
+ expect(read).toContain('#1 paragraph h1 (Heading1)');
+ // Deleted text and markers are not part of what it says.
+ expect(read).toContain(
+ '#2 paragraph p1 (both)\n The term is two (2) years.'
+ );
+ expect(read).toContain('bold: "two (2) years"');
+ expect(read).toContain('#3 table t1, 1 rows x 1 columns');
+ expect(read).toMatch(/row 1, cell 1:\n\s+paragraph cp\n\s+Phase one/);
+ expect(read).toContain('Paragraph styles: Heading1,');
+ });
+
+ it('edits text, formatting, styles and paragraphs as CRDT operations', () => {
+ const doc = sample();
+ const peer = new LoroDoc();
+ peer.import(doc.export({ mode: 'snapshot' }));
+ const version = doc.version();
+ const result = editWord(doc, [
+ {
+ type: 'replaceText',
+ paragraph: 'p1',
+ find: 'two (2) years',
+ replace: 'three (3) years',
+ },
+ { type: 'formatText', paragraph: 'p1', find: 'term', italic: true },
+ { type: 'setStyle', paragraph: 'p1', style: 'quote' },
+ { type: 'insertParagraph', after: 'h1', text: 'First\nSecond' },
+ { type: 'setText', paragraph: 'cp', text: 'Discovery' },
+ { type: 'insertParagraph', after: 'cp', text: 'Weeks 1-2' },
+ ]);
+ expect(result).toContain('Applied 6 operations.');
+ expect(texts(doc)).toEqual([
+ '1. Term',
+ 'First',
+ 'Second',
+ 'The term is three (3) years.',
+ 'Discovery',
+ 'Weeks 1-2',
+ ]);
+ const word = new WordDocument(doc);
+ const p1 = word.blocks.get('p1')!;
+ // The replacement keeps the replaced text's formatting; the bookmark and
+ // the deleted text stay where they were.
+ const delta = word.spans(p1);
+ expect(delta.find((s) => s.insert.startsWith('three'))?.attributes).toEqual(
+ { ...TIMES, 'r:w:b': '<w:b/>' }
+ );
+ expect(word.text(p1).toString()).toContain('');
+ expect(word.text(p1).toString()).toContain(' old');
+ expect(delta.find((s) => s.insert === 'term')?.attributes?.['r:w:i']).toBe(
+ '<w:i/>'
+ );
+ expect(word.propVal(p1, 'pStyle')).toBe('Quote');
+ // A heading is followed by its next style; the section break stays put.
+ const inserted = word.kids('')[1];
+ expect(inserted.props).toBe('');
+ // Paragraphs added after a body paragraph copy its properties, without
+ // its section break.
+ const cellParas = word.kids('c1');
+ expect(cellParas.map((b) => b.parent)).toEqual(['c1', 'c1']);
+ // Another peer merges the edit as an ordinary update.
+ peer.import(doc.export({ mode: 'update', from: version }));
+ expect(texts(peer)).toEqual(texts(doc));
+ });
+
+ it('copies paragraph properties without the section break', () => {
+ const doc = sample();
+ editWord(doc, [{ type: 'insertParagraph', after: 'p1', text: 'Next' }]);
+ const word = new WordDocument(doc);
+ const next = word.kids('')[2];
+ expect(word.visible(next).text).toBe('Next');
+ expect(next.props).toBe('<w:pPr><w:jc w:val="both"/></w:pPr>');
+ // New text is formatted like the paragraph it follows.
+ expect(word.spans(next)[0].attributes).toEqual(TIMES);
+ });
+
+ it('deletes blocks and refuses what the document cannot do', () => {
+ const doc = sample();
+ editWord(doc, [{ type: 'delete', id: 't1' }]);
+ expect(texts(doc)).toEqual(['1. Term', 'The term is two (2) years.']);
+ expect(new WordDocument(doc).blocks.has('cp')).toBe(false);
+ const fails = (operations: Parameters<typeof editWord>[1]) => () =>
+ editWord(sample(), operations);
+ expect(fails([{ type: 'delete', id: 'nope' }])).toThrow(
+ /No paragraph or block has id nope/
+ );
+ expect(fails([{ type: 'delete', id: 'cp' }])).toThrow(
+ /only paragraph in its table cell/
+ );
+ expect(
+ fails([{ type: 'replaceText', paragraph: 'p1', find: 'x', replace: 'y' }])
+ ).toThrow(DocxAgentError);
+ expect(
+ fails([{ type: 'setStyle', paragraph: 'p1', style: 'Nope' }])
+ ).toThrow(/no paragraph style "Nope"/);
+ });
+});
diff --git a/packages/collaboration/src/docx/word-agent.ts b/packages/collaboration/src/docx/word-agent.ts
new file mode 100644
index 0000000000..8009194c20
--- /dev/null
+++ b/packages/collaboration/src/docx/word-agent.ts
@@ -0,0 +1,849 @@
+import { type LoroDoc, LoroMap, LoroText } from 'loro-crdt';
+import {
+ DocxAgentError,
+ type DocxAgentOperation,
+ MAX_DOCX_OPERATIONS,
+ occurrences,
+ preview,
+ READ_BUDGET,
+} from './agent-types';
+import { keysBetween } from './fractional-index';
+import {
+ findStyle,
+ type ParagraphStyleInfo,
+ paragraphStylesFromXml,
+} from './styles';
+
+/**
+ * AI tool requests on a Word document in the shared format the DOCX engine
+ * writes (format version 2): every block is a map in `wordBlocks` (`k`
+ * kind, `p` parent, `o` position key, `x` properties as XML) and every
+ * paragraph's text is rich text whose marks are its formatting (`r:w:b` →
+ * `<w:b/>`, ...). Edits land as ordinary CRDT operations, so open editors
+ * patch them in and concurrent typing elsewhere merges.
+ */
+
+/** Containers of the shared format. */
+export const WORD_CONTAINERS = {
+ meta: 'docxMeta',
+ parts: 'wordParts',
+ blocks: 'wordBlocks',
+} as const;
+
+export const WORD_FORMAT_VERSION = 2;
+
+/** Stands in for objects (pictures, fields, note references) in the text. */
+const OBJECT = '';
+const WORDML_NS =
+ 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+
+type Attributes = Record<string, string>;
+type Span = { insert: string; attributes?: Attributes };
+
+/** One block of the body as stored. */
+export type WordBlock = {
+ id: string;
+ kind: string;
+ parent: string;
+ key: string;
+ props: string;
+ map: LoroMap;
+};
+
+/** A paragraph's text as a reader sees it, with where each character is. */
+type Visible = {
+ text: string;
+ /** Index in the stored text of each visible character. */
+ at: number[];
+ /** Attributes of each visible character. */
+ attrs: Attributes[];
+};
+
+function field(map: LoroMap, key: string): string {
+ const value = map.get(key);
+ return typeof value === 'string' ? value : '';
+}
+
+/** Text that is not part of what a paragraph says: field codes, deleted
+ * text and markers between runs. */
+function hidden(attrs: Attributes): boolean {
+ if ('instr' in attrs || 'mark' in attrs || 'obj' in attrs) return true;
+ const wrap = attrs.wrap;
+ return !!wrap && /<[\w]*:?del[\s>/]|<[\w]*:?moveFrom[\s>/]/.test(wrap);
+}
+
+/** Whether a run property mark turns its toggle on (`<w:b/>`, not `w:val="0"`). */
+function on(xml: string | undefined): boolean {
+ if (!xml) return false;
+ const val = /:val="([^"]*)"/.exec(xml)?.[1];
+ return val === undefined || !['0', 'false', 'off', 'none'].includes(val);
+}
+
+/** The document's shared copy, read for an agent. */
+export class WordDocument {
+ readonly blocks = new Map<string, WordBlock>();
+ private readonly children = new Map<string, WordBlock[]>();
+ /** The prefix the document binds to WordprocessingML. */
+ readonly w: string;
+
+ constructor(readonly doc: LoroDoc) {
+ doc.configDefaultTextStyle({ expand: 'none' });
+ const map = doc.getMap(WORD_CONTAINERS.blocks);
+ for (const id of map.keys()) {
+ const value = map.get(id);
+ if (!(value instanceof LoroMap)) continue;
+ const kind = field(value, 'k');
+ if (!kind) continue;
+ this.blocks.set(id, {
+ id,
+ kind,
+ parent: field(value, 'p'),
+ key: field(value, 'o'),
+ props: field(value, 'x'),
+ map: value,
+ });
+ }
+ this.reindex();
+ this.w = this.prefix();
+ }
+
+ private reindex() {
+ this.children.clear();
+ for (const block of this.blocks.values()) {
+ // Blocks whose parent is gone (a concurrent delete) are not shown.
+ if (block.parent && !this.blocks.has(block.parent)) continue;
+ const list = this.children.get(block.parent) ?? [];
+ list.push(block);
+ this.children.set(block.parent, list);
+ }
+ for (const list of this.children.values())
+ list.sort((a, b) =>
+ a.key < b.key ? -1 : a.key > b.key ? 1 : a.id < b.id ? -1 : 1
+ );
+ }
+
+ private prefix(): string {
+ const parts = this.doc.getMap(WORD_CONTAINERS.parts);
+ for (const name of parts.keys()) {
+ if (!name.endsWith('document.xml') && !name.endsWith('document2.xml'))
+ continue;
+ const shell = parts.get(name);
+ if (typeof shell !== 'string') continue;
+ const match = new RegExp(
+ `xmlns:(\\w+)="${WORDML_NS.replace(/[./]/g, '\\$&')}"`
+ ).exec(shell);
+ if (match) return match[1];
+ }
+ return 'w';
+ }
+
+ /** Children of a block (`''` for the body), in order. */
+ kids(parent: string): WordBlock[] {
+ return this.children.get(parent) ?? [];
+ }
+
+ /** A part's text by name (with or without the leading slash). */
+ part(name: string): string | undefined {
+ const parts = this.doc.getMap(WORD_CONTAINERS.parts);
+ const value = parts.get(`/${name}`) ?? parts.get(name);
+ return typeof value === 'string' ? value : undefined;
+ }
+
+ text(block: WordBlock): LoroText {
+ const value = block.map.get('t');
+ if (value instanceof LoroText) return value;
+ return block.map.setContainer('t', new LoroText());
+ }
+
+ spans(block: WordBlock): Span[] {
+ return this.text(block).toDelta() as Span[];
+ }
+
+ visible(block: WordBlock): Visible {
+ const out: Visible = { text: '', at: [], attrs: [] };
+ let index = 0;
+ for (const span of this.spans(block)) {
+ const attrs = span.attributes ?? {};
+ const skip = hidden(attrs);
+ for (const unit of span.insert) {
+ // Code units, as the shared text counts them.
+ for (let i = 0; i < unit.length; i++) {
+ if (!skip && unit !== OBJECT) {
+ out.text += unit[i];
+ out.at.push(index);
+ out.attrs.push(attrs);
+ }
+ index++;
+ }
+ }
+ }
+ return out;
+ }
+
+ /** The value of a property child (`pStyle`, `jc`...) of a block's XML. */
+ propVal(block: WordBlock, local: string): string | null {
+ const re = new RegExp(
+ `<${this.w}:${local}\\b[^>]*\\b${this.w}:val="([^"]*)"`
+ );
+ return re.exec(block.props)?.[1] ?? null;
+ }
+
+ hasProp(block: WordBlock, local: string): boolean {
+ return new RegExp(`<${this.w}:${local}[\\s>/]`).test(block.props);
+ }
+
+ /** Removes a block and everything in it. */
+ remove(block: WordBlock) {
+ const map = this.doc.getMap(WORD_CONTAINERS.blocks);
+ const walk = (b: WordBlock) => {
+ for (const kid of this.kids(b.id)) walk(kid);
+ map.delete(b.id);
+ this.blocks.delete(b.id);
+ };
+ walk(block);
+ this.reindex();
+ }
+
+ /** Adds a paragraph next to `anchor`. */
+ addParagraph(
+ anchor: WordBlock,
+ after: boolean,
+ props: string,
+ spans: Span[]
+ ): WordBlock {
+ const siblings = this.kids(anchor.parent);
+ const index = siblings.indexOf(anchor);
+ const low = after ? anchor.key : (siblings[index - 1]?.key ?? null);
+ const high = after ? (siblings[index + 1]?.key ?? null) : anchor.key;
+ const [key] = keysBetween(low || null, high || null, 1);
+ const id = newBlockId();
+ const map = this.doc
+ .getMap(WORD_CONTAINERS.blocks)
+ .setContainer(id, new LoroMap());
+ map.set('k', 'p');
+ map.set('p', anchor.parent);
+ map.set('o', key);
+ map.set('a', '');
+ map.set('x', props);
+ const text = map.setContainer('t', new LoroText());
+ if (spans.length) text.applyDelta(spans);
+ const block: WordBlock = {
+ id,
+ kind: 'p',
+ parent: anchor.parent,
+ key,
+ props,
+ map,
+ };
+ this.blocks.set(id, block);
+ this.reindex();
+ return block;
+ }
+
+ setProps(block: WordBlock, props: string) {
+ block.map.set('x', props);
+ block.props = props;
+ }
+}
+
+/** A fresh block id in the engine's style (base 36), unlikely to collide. */
+function newBlockId(): string {
+ const bytes = new Uint8Array(8);
+ crypto.getRandomValues(bytes);
+ let n = 0n;
+ for (const b of bytes) n = (n << 8n) | BigInt(b);
+ return `g${n.toString(36)}`;
+}
+
+/** Whether the document is in the engine's shared format. */
+export function isWordFormat(doc: LoroDoc): boolean {
+ return (
+ doc.getMap(WORD_CONTAINERS.meta).get('formatVersion') ===
+ WORD_FORMAT_VERSION
+ );
+}
+
+/** The run formatting an agent can change, as mark keys and values. */
+export function formatMarks(
+ w: string,
+ format: {
+ bold?: boolean;
+ italic?: boolean;
+ underline?: boolean;
+ strikethrough?: boolean;
+ }
+): Attributes {
+ const marks: Attributes = {};
+ const flag = (local: string, value: boolean | undefined) => {
+ if (value === undefined) return;
+ marks[`r:${w}:${local}`] = value
+ ? `<${w}:${local}/>`
+ : `<${w}:${local} ${w}:val="0"/>`;
+ };
+ flag('b', format.bold);
+ flag('i', format.italic);
+ flag('strike', format.strikethrough);
+ if (format.underline !== undefined)
+ marks[`r:${w}:u`] =
+ `<${w}:u ${w}:val="${format.underline ? 'single' : 'none'}"/>`;
+ return marks;
+}
+
+/** Which of the four toggles a character's marks turn on. */
+export function formatOf(w: string, attrs: Attributes) {
+ return {
+ bold: on(attrs[`r:${w}:b`]),
+ italic: on(attrs[`r:${w}:i`]),
+ underline: on(attrs[`r:${w}:u`]),
+ strikethrough: on(attrs[`r:${w}:strike`]),
+ };
+}
+
+/** The formatting text typed in place of other text takes: its run
+ * properties and wrappers, not object or marker keys. */
+export function typingAttributes(attrs: Attributes | undefined): Attributes {
+ const out: Attributes = {};
+ for (const [key, value] of Object.entries(attrs ?? {}))
+ if (key.startsWith('r:') || key.startsWith('ra:') || key === 'wrap')
+ out[key] = value;
+ return out;
+}
+
+const quote = (text: string) => `"${preview(text, 60)}"`;
+const KINDS = ['bold', 'italic', 'underline', 'strikethrough'] as const;
+
+/** Formatted spans worth telling a reader about, e.g. `bold: "Agreement"`. */
+function formattingNotes(word: WordDocument, visible: Visible): string[] {
+ const spans: Record<(typeof KINDS)[number], string[]> = {
+ bold: [],
+ italic: [],
+ underline: [],
+ strikethrough: [],
+ };
+ const open: Partial<Record<(typeof KINDS)[number], string>> = {};
+ const n = visible.text.length;
+ for (let i = 0; i < n; i++) {
+ const format = formatOf(word.w, visible.attrs[i]);
+ for (const kind of KINDS) {
+ if (format[kind]) open[kind] = (open[kind] ?? '') + visible.text[i];
+ if ((!format[kind] || i === n - 1) && open[kind]) {
+ if (open[kind]!.trim()) spans[kind].push(open[kind]!);
+ open[kind] = undefined;
+ }
+ }
+ }
+ return KINDS.flatMap((kind) => {
+ const list = spans[kind];
+ if (list.length === 0) return [];
+ if (list.length === 1 && list[0] === visible.text) return [`${kind}: all`];
+ const shown = list.slice(0, 6).map(quote).join(', ');
+ return [`${kind}: ${shown}${list.length > 6 ? ', …' : ''}`];
+ });
+}
+
+function paragraphLines(
+ word: WordDocument,
+ block: WordBlock,
+ label: string,
+ indent: string
+): string[] {
+ const traits = [
+ word.propVal(block, 'pStyle'),
+ word.propVal(block, 'jc'),
+ word.hasProp(block, 'numPr') ? 'numbered' : null,
+ ].filter(Boolean);
+ const visible = word.visible(block);
+ const text = visible.text.replace(/\n/g, '↵');
+ const head = `${indent}${label}paragraph ${block.id}${traits.length ? ` (${traits.join(', ')})` : ''}`;
+ if (!text) return [`${head} (empty)`];
+ return [
+ head,
+ `${indent} ${text}`,
+ ...formattingNotes(word, visible).map((note) => `${indent} ${note}`),
+ ];
+}
+
+function contentLines(
+ word: WordDocument,
+ parent: string,
+ indent: string
+): string[] {
+ return word
+ .kids(parent)
+ .flatMap((block) => blockLines(word, block, '', indent));
+}
+
+function blockLines(
+ word: WordDocument,
+ block: WordBlock,
+ label: string,
+ indent: string
+): string[] {
+ switch (block.kind) {
+ case 'p':
+ return paragraphLines(word, block, label, indent);
+ case 'tbl': {
+ const rows = word.kids(block.id).filter((r) => r.kind === 'tr');
+ const columns = Math.max(
+ 0,
+ ...rows.map(
+ (r) => word.kids(r.id).filter((c) => c.kind === 'tc').length
+ )
+ );
+ const lines = [
+ `${indent}${label}table ${block.id}, ${rows.length} rows x ${columns} columns`,
+ ];
+ rows.forEach((row, r) => {
+ word
+ .kids(row.id)
+ .filter((c) => c.kind === 'tc')
+ .forEach((cell, c) => {
+ lines.push(`${indent} row ${r + 1}, cell ${c + 1}:`);
+ lines.push(...contentLines(word, cell.id, `${indent} `));
+ });
+ });
+ return lines;
+ }
+ case 'sdt': {
+ const title =
+ /:(?:alias|tag|docPartGallery)\b[^>]*:val="([^"]*)"/.exec(
+ block.props
+ )?.[1] ?? null;
+ return [
+ `${indent}${label}content control ${block.id}${title ? ` (${title})` : ''}`,
+ ...contentLines(word, block.id, `${indent} `),
+ ];
+ }
+ default:
+ // Bookmarks and other markers between paragraphs carry no content.
+ return [];
+ }
+}
+
+function styles(word: WordDocument): ParagraphStyleInfo[] {
+ return paragraphStylesFromXml(word.part('word/styles.xml'));
+}
+
+/** The document as text an agent can act on: every block with its id. */
+export function describeWord(
+ doc: LoroDoc,
+ options: { start?: number; count?: number } = {}
+): string {
+ const word = new WordDocument(doc);
+ const top = word.kids('');
+ const start = Math.max(1, Math.floor(options.start ?? 1));
+ const end = Math.min(
+ top.length,
+ options.count
+ ? start - 1 + Math.max(1, Math.floor(options.count))
+ : Infinity
+ );
+ const all = styles(word);
+ const used = new Set<string>();
+ const body: string[] = [];
+ let size = 0;
+ let next: number | null = null;
+ for (let number = start; number <= end; number++) {
+ const block = top[number - 1];
+ const lines = blockLines(word, block, `#${number} `, '');
+ const length = lines.reduce((sum, line) => sum + line.length + 1, 0);
+ if (size + length > READ_BUDGET && body.length > 0) {
+ next = number;
+ break;
+ }
+ size += length;
+ body.push(...lines);
+ for (const line of lines) {
+ const style = /^\s*(?:#\d+ )?paragraph \S+ \(([^,)]+)/.exec(line)?.[1];
+ if (style) used.add(style);
+ }
+ }
+ const styleList = [
+ ...all.filter((s) => used.has(s.id)),
+ ...all.filter((s) => !used.has(s.id)),
+ ]
+ .slice(0, 40)
+ .map((s) => s.id);
+ const header = [
+ `Word document with ${top.length} blocks${start > 1 || end < top.length ? `; showing #${start}-#${next ? next - 1 : end}` : ''}.`,
+ 'Ids are stable: pass them to EditWordDocument. Text is shown plain; lines like `bold: "..."` list formatted spans. ↵ is a line break inside a paragraph.',
+ ...(styleList.length
+ ? [
+ `Paragraph styles: ${styleList.join(', ')}${all.length > 40 ? ', …' : ''}.`,
+ ]
+ : []),
+ '',
+ ];
+ const footer = next
+ ? [
+ '',
+ `… ${top.length - next + 1} more blocks. Read again with start=${next} to continue.`,
+ ]
+ : [];
+ return [...header, ...body, ...footer].join('\n');
+}
+
+/** The top-level block holding a block. */
+function topOf(word: WordDocument, block: WordBlock): WordBlock {
+ let at = block;
+ while (at.parent) {
+ const parent = word.blocks.get(at.parent);
+ if (!parent) break;
+ at = parent;
+ }
+ return at;
+}
+
+/** Paragraph properties without what belongs to that paragraph alone: its
+ * section break and recorded changes. */
+function copiedProps(props: string): string {
+ return props
+ .replace(/<(\w+:)?sectPr\b[\s\S]*?<\/\1?sectPr>/g, '')
+ .replace(/<(\w+:)?sectPr\b[^>]*\/>/g, '')
+ .replace(/<(\w+:)?pPrChange\b[\s\S]*?<\/\1?pPrChange>/g, '')
+ .replace(/<(\w+:)?(ins|del)\b[^>]*\/>/g, '');
+}
+
+/** `w:pPr` XML naming a style, from a paragraph's properties. */
+function withStyle(w: string, props: string, style: string): string {
+ const tag = `<${w}:pStyle ${w}:val="${style}"/>`;
+ if (!props.trim()) return `<${w}:pPr>${tag}</${w}:pPr>`;
+ if (new RegExp(`<${w}:pStyle\\b`).test(props))
+ return props.replace(new RegExp(`<${w}:pStyle\\b[^>]*/>`), tag);
+ if (/\/>\s*$/.test(props) && !props.includes('</'))
+ return props.replace(/\s*\/>\s*$/, `>${tag}</${w}:pPr>`);
+ // pStyle is the first property in schema order.
+ return props.replace(/^(\s*<[^>]+>)/, `$1${tag}`);
+}
+
+class WordEditor {
+ readonly touched = new Set<string>();
+ readonly deleted: string[] = [];
+ private readonly styles: ParagraphStyleInfo[];
+
+ constructor(readonly word: WordDocument) {
+ this.styles = styles(word);
+ }
+
+ private block(id: string): WordBlock {
+ const found = this.word.blocks.get(id);
+ if (!found)
+ throw new DocxAgentError(
+ `No paragraph or block has id ${id}. Read the document again for current ids.`
+ );
+ return found;
+ }
+
+ private paragraph(id: string): WordBlock {
+ const found = this.block(id);
+ if (found.kind !== 'p')
+ throw new DocxAgentError(
+ `${id} is a ${describeKind(found.kind)}, not a paragraph. Address the paragraphs inside it.`
+ );
+ return found;
+ }
+
+ private changed(block: WordBlock) {
+ this.touched.add(topOf(this.word, block).id);
+ }
+
+ /** The visible range `[start, end)` an operation addresses. */
+ private range(
+ block: WordBlock,
+ visible: Visible,
+ find: string | undefined,
+ occurrence: number | undefined
+ ): [number, number] {
+ const text = visible.text;
+ if (find === undefined) return [0, text.length];
+ const matches = occurrences(text, find);
+ if (matches.length === 0)
+ throw new DocxAgentError(
+ `"${preview(find, 80)}" does not appear in paragraph ${block.id}, whose text is: "${preview(text)}"`
+ );
+ if (occurrence === undefined && matches.length > 1)
+ throw new DocxAgentError(
+ `"${preview(find, 80)}" appears ${matches.length} times in paragraph ${block.id}; pass occurrence (1-${matches.length}) or a longer find.`
+ );
+ const index = (occurrence ?? 1) - 1;
+ if (index < 0 || index >= matches.length)
+ throw new DocxAgentError(
+ `Paragraph ${block.id} has ${matches.length} occurrence(s) of "${preview(find, 80)}"; occurrence ${occurrence} is out of range.`
+ );
+ return [matches[index], matches[index] + find.length];
+ }
+
+ /** Stored offsets of a visible range (hidden text inside it goes too). */
+ private stored(
+ visible: Visible,
+ start: number,
+ end: number
+ ): [number, number] {
+ if (start === end) {
+ const at =
+ start < visible.at.length
+ ? visible.at[start]
+ : (visible.at[visible.at.length - 1] ?? -1) + 1;
+ return [at, at];
+ }
+ return [visible.at[start], visible.at[end - 1] + 1];
+ }
+
+ /** Replaces visible text `[start, end)` with `text`, formatted like the
+ * text it replaces (or the text before it). */
+ private replace(block: WordBlock, start: number, end: number, text: string) {
+ const visible = this.word.visible(block);
+ const [from, to] = this.stored(visible, start, end);
+ const like = visible.attrs[start] ?? visible.attrs[start - 1];
+ const delta: Array<Record<string, unknown>> = [];
+ if (from > 0) delta.push({ retain: from });
+ if (to > from) delta.push({ delete: to - from });
+ if (text) {
+ const attributes = typingAttributes(like);
+ delta.push(
+ Object.keys(attributes).length
+ ? { insert: text, attributes }
+ : { insert: text }
+ );
+ }
+ if (delta.length) this.word.text(block).applyDelta(delta as never);
+ this.changed(block);
+ }
+
+ private static singleLine(text: string, what: string) {
+ if (/[\r\n]/.test(text))
+ throw new DocxAgentError(
+ `${what} cannot contain a line break; use insertParagraph to add paragraphs.`
+ );
+ }
+
+ private resolveStyle(style: string): string {
+ const found = findStyle(this.styles, style);
+ if (!found)
+ throw new DocxAgentError(
+ `The document has no paragraph style "${style}". Its paragraph styles are: ${this.styles
+ .map((s) => s.id)
+ .join(', ')}.`
+ );
+ return found;
+ }
+
+ apply(operation: DocxAgentOperation) {
+ switch (operation.type) {
+ case 'replaceText': {
+ WordEditor.singleLine(operation.replace, 'replace');
+ if (!operation.find)
+ throw new DocxAgentError('find must not be empty.');
+ const block = this.paragraph(operation.paragraph);
+ const visible = this.word.visible(block);
+ const [start, end] = this.range(
+ block,
+ visible,
+ operation.find,
+ operation.occurrence
+ );
+ this.replace(block, start, end, operation.replace);
+ return;
+ }
+ case 'setText': {
+ WordEditor.singleLine(operation.text, 'text');
+ const block = this.paragraph(operation.paragraph);
+ const visible = this.word.visible(block);
+ this.replace(block, 0, visible.text.length, operation.text);
+ return;
+ }
+ case 'formatText': {
+ const { bold, italic, underline, strikethrough } = operation;
+ if (
+ [bold, italic, underline, strikethrough].every((v) => v === undefined)
+ )
+ throw new DocxAgentError(
+ 'formatText needs at least one of bold, italic, underline or strikethrough.'
+ );
+ const block = this.paragraph(operation.paragraph);
+ const visible = this.word.visible(block);
+ const [start, end] = this.range(
+ block,
+ visible,
+ operation.find,
+ operation.occurrence
+ );
+ if (start === end) return;
+ const [from, to] = this.stored(visible, start, end);
+ const attributes = formatMarks(this.word.w, {
+ bold,
+ italic,
+ underline,
+ strikethrough,
+ });
+ const delta: Array<Record<string, unknown>> = [];
+ if (from > 0) delta.push({ retain: from });
+ delta.push({ retain: to - from, attributes });
+ this.word.text(block).applyDelta(delta as never);
+ this.changed(block);
+ return;
+ }
+ case 'insertParagraph':
+ this.insert(operation);
+ return;
+ case 'delete':
+ this.delete(operation.id);
+ return;
+ case 'setStyle': {
+ const block = this.paragraph(operation.paragraph);
+ const style = this.resolveStyle(operation.style);
+ this.word.setProps(block, withStyle(this.word.w, block.props, style));
+ this.changed(block);
+ return;
+ }
+ }
+ }
+
+ /** Paragraph properties for a paragraph added next to `anchor`. */
+ private newProps(anchor: WordBlock, style: string | undefined): string {
+ const w = this.word.w;
+ if (style !== undefined) return withStyle(w, '', this.resolveStyle(style));
+ if (anchor.kind !== 'p') return '';
+ // As Word does on Enter: a style that names a different next style (a
+ // heading, say) is followed by that style; any other paragraph is copied.
+ const current = this.word.propVal(anchor, 'pStyle');
+ const info = current
+ ? this.styles.find((s) => s.id === current)
+ : undefined;
+ if (info?.next && info.next !== info.id) {
+ const next = this.styles.find((s) => s.id === info.next);
+ return next?.isDefault ? '' : withStyle(w, '', info.next);
+ }
+ return copiedProps(anchor.props);
+ }
+
+ private insert(
+ operation: Extract<DocxAgentOperation, { type: 'insertParagraph' }>
+ ) {
+ const anchorId = operation.after ?? operation.before;
+ if (!anchorId || (operation.after && operation.before))
+ throw new DocxAgentError(
+ 'insertParagraph needs exactly one of after or before.'
+ );
+ const anchor = this.block(anchorId);
+ if (anchor.kind === 'tr' || anchor.kind === 'tc')
+ throw new DocxAgentError(
+ `${anchorId} is a table ${anchor.kind === 'tr' ? 'row' : 'cell'}; insert next to a paragraph or the table instead.`
+ );
+ const props = this.newProps(anchor, operation.style);
+ // New text is formatted like the anchor's first character.
+ const like =
+ anchor.kind === 'p' && operation.style === undefined
+ ? typingAttributes(this.word.visible(anchor).attrs[0])
+ : {};
+ const lines = operation.text.replace(/\r\n?/g, '\n').split('\n');
+ const after = operation.after !== undefined;
+ let at = anchor;
+ const ordered = after ? lines : [...lines].reverse();
+ for (const line of ordered) {
+ const spans = line
+ ? [
+ Object.keys(like).length
+ ? { insert: line, attributes: like }
+ : { insert: line },
+ ]
+ : [];
+ at = this.word.addParagraph(at, after, props, spans);
+ this.changed(at);
+ }
+ }
+
+ private delete(id: string) {
+ const block = this.block(id);
+ if (!block.parent) {
+ if (this.word.kids('').length === 1)
+ throw new DocxAgentError(
+ 'The document must keep at least one block; use setText to clear it instead.'
+ );
+ this.word.remove(block);
+ this.touched.delete(block.id);
+ this.deleted.push(block.id);
+ return;
+ }
+ const parent = this.word.blocks.get(block.parent);
+ if (
+ parent?.kind === 'tc' &&
+ !this.word
+ .kids(parent.id)
+ .some((b) => b.id !== block.id && (b.kind === 'p' || b.kind === 'tbl'))
+ )
+ throw new DocxAgentError(
+ `Paragraph ${id} is the only paragraph in its table cell; use setText with empty text to clear it.`
+ );
+ const top = topOf(this.word, block);
+ this.word.remove(block);
+ this.touched.add(top.id);
+ }
+}
+
+function describeKind(kind: string): string {
+ switch (kind) {
+ case 'tbl':
+ return 'table';
+ case 'tr':
+ return 'table row';
+ case 'tc':
+ return 'table cell';
+ case 'sdt':
+ return 'content control';
+ default:
+ return 'block';
+ }
+}
+
+/**
+ * Applies `operations` to the shared document in one commit and describes
+ * the blocks they changed. Any failure throws before anything is committed;
+ * the caller drops the document then, so nothing reaches anyone.
+ */
+export function editWord(
+ doc: LoroDoc,
+ operations: readonly DocxAgentOperation[]
+): string {
+ if (operations.length === 0 || operations.length > MAX_DOCX_OPERATIONS)
+ throw new DocxAgentError(
+ `Send between 1 and ${MAX_DOCX_OPERATIONS} operations.`
+ );
+ const editor = new WordEditor(new WordDocument(doc));
+ operations.forEach((operation, index) => {
+ try {
+ editor.apply(operation);
+ } catch (error) {
+ if (error instanceof DocxAgentError)
+ throw new DocxAgentError(
+ `Operation ${index + 1} (${operation.type}) failed, so nothing was changed: ${error.message}`
+ );
+ throw error;
+ }
+ });
+ doc.commit({ origin: 'docx-agent' });
+ // How the changed blocks read now, for the agent to check.
+ const word = new WordDocument(doc);
+ const top = word.kids('');
+ const count = operations.length;
+ const lines = [
+ `Applied ${count} operation${count === 1 ? '' : 's'}. Everyone with the document open sees the change now.`,
+ ];
+ if (editor.deleted.length)
+ lines.push(`Deleted blocks: ${editor.deleted.join(', ')}.`);
+ const touched = top.filter((b) => editor.touched.has(b.id));
+ if (touched.length) {
+ lines.push('', 'Changed blocks as they now read:');
+ let size = 0;
+ for (const block of touched) {
+ const shown = blockLines(word, block, `#${top.indexOf(block) + 1} `, '');
+ size += shown.join('\n').length;
+ if (size > READ_BUDGET) {
+ lines.push('… (more changed blocks; read the document to see them)');
+ break;
+ }
+ lines.push(...shown);
+ }
+ }
+ return lines.join('\n');
+}