@beyondwork/docx-react-component 1.0.0

package/test/core/mapping.test.ts

@@ -0,0 +1,186 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createDetachedAnchor,
+  createRangeAnchor,
+  mapAnchor,
+  mapPosition,
+  type TransactionMapping,
+} from "../../src/core/selection/mapping.ts";
+import {
+  createDefaultCanonicalDocument,
+  type CanonicalDocumentEnvelope,
+} from "../../src/core/state/editor-state.ts";
+import { createDocumentRuntime } from "../../src/runtime/document-runtime.ts";
+
+test("mapPosition shifts positions after an insertion", () => {
+  const mapping: TransactionMapping = {
+    steps: [
+      {
+        from: 5,
+        to: 5,
+        insertSize: 3,
+      },
+    ],
+  };
+
+  assert.deepEqual(mapPosition(9, 1, mapping), {
+    position: 12,
+    deleted: false,
+  });
+});
+
+test("mapAnchor detaches a fully deleted range", () => {
+  const mapping: TransactionMapping = {
+    steps: [
+      {
+        from: 2,
+        to: 6,
+        insertSize: 0,
+      },
+    ],
+  };
+
+  const anchor = createRangeAnchor(3, 5);
+  const mapped = mapAnchor(anchor, mapping);
+
+  assert.deepEqual(mapped, createDetachedAnchor({ from: 3, to: 5 }, "deleted"));
+});
+
+test("mapAnchor preserves structural invalidation reason when flagged", () => {
+  const mapping: TransactionMapping = {
+    steps: [
+      {
+        from: 2,
+        to: 4,
+        insertSize: 0,
+      },
+    ],
+    metadata: {
+      invalidatesStructures: true,
+    },
+  };
+
+  const mapped = mapAnchor(createRangeAnchor(3, 3), mapping);
+
+  assert.deepEqual(
+    mapped,
+    createDetachedAnchor({ from: 3, to: 3 }, "invalidatedByStructureChange"),
+  );
+});
+
+test("document runtime routes mutations through dispatch and tracks undo redo", () => {
+  const eventTypes: string[] = [];
+  const runtime = createDocumentRuntime({
+    documentId: "doc-1",
+    initialCanonicalDocument: createDefaultCanonicalDocument(
+      "doc-1",
+      "2026-03-26T00:00:00.000Z",
+    ),
+    clock: () => "2026-03-26T00:00:00.000Z",
+    onEvent(event) {
+      eventTypes.push(event.type);
+    },
+  });
+
+  runtime.dispatch({
+    type: "selection.set",
+    selection: {
+      anchor: 1,
+      head: 4,
+      isCollapsed: false,
+      activeRange: createRangeAnchor(1, 4),
+    },
+  });
+
+  const commentId = runtime.addComment({
+    body: "Needs review",
+  });
+
+  assert.equal(runtime.getRenderSnapshot().selection.anchor, 1);
+  assert.equal(runtime.getRenderSnapshot().comments.openCommentIds.length, 1);
+  assert.ok(commentId.startsWith("comment-"));
+
+  runtime.undo();
+  assert.equal(runtime.getRenderSnapshot().comments.openCommentIds.length, 0);
+
+  runtime.redo();
+  assert.equal(runtime.getRenderSnapshot().comments.openCommentIds.length, 1);
+  assert.ok(eventTypes.includes("selection_changed"));
+  assert.ok(eventTypes.includes("comment_added"));
+});
+
+test("persisted snapshots remain separate from render snapshots", () => {
+  const runtime = createDocumentRuntime({
+    documentId: "doc-2",
+    initialCanonicalDocument: createDefaultCanonicalDocument(
+      "doc-2",
+      "2026-03-26T00:00:00.000Z",
+    ),
+    clock: () => "2026-03-26T00:00:00.000Z",
+    editorBuild: "test-build",
+  });
+
+  const persisted = runtime.getPersistedSnapshot();
+  const renderSnapshot = runtime.getRenderSnapshot();
+
+  assert.equal(persisted.snapshotVersion, "persisted-editor-snapshot/1");
+  assert.equal(persisted.editorBuild, "test-build");
+  assert.equal(typeof persisted.canonicalDocument.docId, "string");
+  assert.ok(persisted.canonicalDocument.docId.length > 0);
+  assert.ok("documentStats" in renderSnapshot);
+  assert.ok(!("documentStats" in persisted));
+});
+
+test("document replacement remaps stored comment anchors", () => {
+  const runtime = createDocumentRuntime({
+    documentId: "doc-3",
+    initialCanonicalDocument: createDefaultCanonicalDocument(
+      "doc-3",
+      "2026-03-26T00:00:00.000Z",
+    ),
+    clock: () => "2026-03-26T00:00:00.000Z",
+  });
+
+  runtime.dispatch({
+    type: "selection.set",
+    selection: {
+      anchor: 2,
+      head: 4,
+      isCollapsed: false,
+      activeRange: createRangeAnchor(2, 4),
+    },
+  });
+
+  const commentId = runtime.addComment({ body: "Shift me" });
+  const nextDocument =
+    runtime.getPersistedSnapshot().canonicalDocument as unknown as CanonicalDocumentEnvelope;
+
+  runtime.dispatch({
+    type: "document.replace",
+    document: nextDocument,
+    mapping: {
+      steps: [
+        {
+          from: 0,
+          to: 0,
+          insertSize: 3,
+        },
+      ],
+      metadata: {
+        affectsComments: true,
+      },
+    },
+  });
+
+  const comment = (
+    runtime.getPersistedSnapshot().canonicalDocument as unknown as CanonicalDocumentEnvelope
+  ).review.comments[commentId];
+
+  assert.equal(comment.anchor.kind, "range");
+  if (comment.anchor.kind === "range") {
+    assert.equal(comment.anchor.range.from, 5);
+    assert.equal(comment.anchor.range.to, 7);
+  }
+});

package/test/core/text-commands.test.ts

@@ -0,0 +1,176 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  deleteSelectionOrBackward,
+  insertHardBreak,
+  insertTab,
+  insertText,
+  splitParagraph,
+} from "../../src/core/commands/text-commands.ts";
+import { createRangeAnchor, mapAnchor } from "../../src/core/selection/mapping.ts";
+import {
+  createSelectionSnapshot,
+  type CanonicalDocumentEnvelope,
+} from "../../src/core/state/editor-state.ts";
+import { TextTransactionError } from "../../src/core/state/text-transaction.ts";
+import { createPlainText, parseTextStory } from "../../src/core/schema/text-schema.ts";
+
+const TIMESTAMP = "2026-03-26T09:00:00.000Z";
+
+function createDocument(
+  blocks: Array<
+    | { type: "paragraph"; children: Array<Record<string, unknown>> }
+    | { type: "opaque_block"; fragmentId: string; warningId: string }
+  >,
+): CanonicalDocumentEnvelope {
+  return {
+    schemaVersion: "cds/1.0.0",
+    docId: "doc-1",
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+    metadata: {},
+    styles: {},
+    numbering: {},
+    media: {},
+    content: {
+      type: "doc",
+      children: blocks,
+    },
+    review: {
+      comments: {},
+      revisions: {},
+    },
+    preservation: {},
+    diagnostics: {},
+  };
+}
+
+test("insertText retains consecutive whitespace and emits a stable mapping step", () => {
+  const document = createDocument([{ type: "paragraph", children: [{ type: "text", text: "AlphaBeta" }] }]);
+  const selection = createSelectionSnapshot(5, 5);
+
+  const result = insertText(document, selection, "  ", {
+    timestamp: TIMESTAMP,
+  });
+
+  assert.equal(result.storyText, "Alpha  Beta");
+  assert.deepEqual(result.mapping.steps, [{ from: 5, to: 5, insertSize: 2 }]);
+  assert.equal(result.selection.anchor, 7);
+  assert.equal(createPlainText(parseTextStory(result.document.content)), "Alpha  Beta");
+});
+
+test("insertTab and insertHardBreak create the expected inline units", () => {
+  const document = createDocument([{ type: "paragraph", children: [{ type: "text", text: "Hello" }] }]);
+
+  const withTab = insertTab(document, createSelectionSnapshot(5, 5), {
+    timestamp: TIMESTAMP,
+  });
+  assert.equal(withTab.storyText, "Hello\t");
+
+  const withBreak = insertHardBreak(withTab.document, createSelectionSnapshot(6, 6), {
+    timestamp: TIMESTAMP,
+  });
+
+  assert.equal(withBreak.storyText, "Hello\t\n");
+
+  const story = parseTextStory(withBreak.document.content);
+  assert.equal(story.units[5]?.kind, "tab");
+  assert.equal(story.units[6]?.kind, "hard_break");
+});
+
+test("splitParagraph preserves story order and marks structure invalidation in mapping metadata", () => {
+  const document = createDocument([{ type: "paragraph", children: [{ type: "text", text: "AlphaBeta" }] }]);
+
+  const result = splitParagraph(document, createSelectionSnapshot(5, 5), {
+    timestamp: TIMESTAMP,
+  });
+
+  assert.equal(result.storyText, "Alpha\nBeta");
+  assert.equal(result.mapping.metadata?.invalidatesStructures, true);
+  assert.deepEqual(result.mapping.steps, [{ from: 5, to: 5, insertSize: 1 }]);
+
+  const story = parseTextStory(result.document.content);
+  assert.equal(story.units[5]?.kind, "paragraph_break");
+});
+
+test("backward delete across a paragraph boundary merges paragraphs and remaps anchors deterministically", () => {
+  const document = createDocument([
+    { type: "paragraph", children: [{ type: "text", text: "Alpha" }] },
+    { type: "paragraph", children: [{ type: "text", text: "Beta" }] },
+  ]);
+
+  const result = deleteSelectionOrBackward(document, createSelectionSnapshot(6, 6), {
+    timestamp: TIMESTAMP,
+  });
+
+  assert.equal(result.storyText, "AlphaBeta");
+  assert.equal(result.mapping.metadata?.invalidatesStructures, true);
+
+  const mappedAnchor = mapAnchor(createRangeAnchor(6, 10), result.mapping);
+  assert.equal(mappedAnchor.kind, "range");
+  if (mappedAnchor.kind === "range") {
+    assert.equal(mappedAnchor.range.from, 5);
+    assert.equal(mappedAnchor.range.to, 9);
+  }
+});
+
+test("range deletion removes selected content and collapses the resulting selection", () => {
+  const document = createDocument([{ type: "paragraph", children: [{ type: "text", text: "AlphaBeta" }] }]);
+
+  const result = deleteSelectionOrBackward(document, createSelectionSnapshot(2, 7), {
+    timestamp: TIMESTAMP,
+  });
+
+  assert.equal(result.storyText, "Alta");
+  assert.equal(result.selection.anchor, 2);
+  assert.deepEqual(result.mapping.steps, [{ from: 2, to: 7, insertSize: 0 }]);
+});
+
+test("transactions reject deletions that would silently discard protected opaque content", () => {
+  const document = createDocument([
+    {
+      type: "paragraph",
+      children: [
+        { type: "text", text: "A" },
+        { type: "opaque_inline", fragmentId: "fragment-1", warningId: "warning-1" },
+        { type: "text", text: "B" },
+      ],
+    },
+  ]);
+
+  assert.throws(
+    () =>
+      deleteSelectionOrBackward(document, createSelectionSnapshot(1, 2), {
+        timestamp: TIMESTAMP,
+      }),
+    (error: unknown) =>
+      error instanceof TextTransactionError && error.code === "unsupported_content",
+  );
+});
+
+test("insertText preserves top-level opaque blocks and trailing paragraph structure", () => {
+  const document = createDocument([
+    { type: "paragraph", children: [{ type: "text", text: "Alpha" }] },
+    { type: "opaque_block", fragmentId: "fragment:block-1", warningId: "warning:block-1" },
+    {
+      type: "paragraph",
+      children: [{ type: "text", text: "Beta" }],
+    },
+  ]);
+
+  const result = insertText(document, createSelectionSnapshot(6, 6), "!", {
+    timestamp: TIMESTAMP,
+  });
+
+  assert.equal(result.storyText, "Alpha\uFFFA!Beta");
+  assert.deepEqual(result.mapping.steps, [{ from: 6, to: 6, insertSize: 1 }]);
+  assert.deepEqual(result.document.content, {
+    type: "doc",
+    children: [
+      { type: "paragraph", children: [{ type: "text", text: "Alpha" }] },
+      { type: "opaque_block", fragmentId: "fragment:block-1", warningId: "warning:block-1" },
+      { type: "paragraph", children: [{ type: "text", text: "!Beta" }] },
+    ],
+  });
+});

package/test/fixtures/docx/F01-basic-contract.md

@@ -0,0 +1,33 @@
+# F01 Basic contract skeleton
+
+## Source shape
+
+- file: `F01-basic-contract.docx`
+- source package findings: `0`
+- source SDK findings: `0`
+- observed focus: baseline paragraphs, runs, whitespace, tabs, hard breaks, and paragraph split or merge behavior
+
+## Import expectation
+
+- the session should load into editable canonical paragraphs and runs
+- whitespace, tabs, and hard breaks should normalize into runtime-owned text content without flattening semantic boundaries
+
+## Edit expectation
+
+- normal text edits, paragraph splits, and paragraph merges remain supported
+- no preserve-only fallback should be required for the main text story in this fixture
+
+## Export expectation
+
+- export should regenerate the owned main-document story content from canonical state
+- roundtripped paragraph and run boundaries should remain stable enough for reload and Word reopen
+
+## Validation expectation
+
+- package integrity should remain valid after supported edits
+- the source and supported edited exports should remain at `0` package findings and `0` SDK findings
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- baseline paragraph structure and whitespace behavior should remain intact after export

package/test/fixtures/docx/F02-headings-styles.md

@@ -0,0 +1,33 @@
+# F02 Headings and styles contract
+
+## Source shape
+
+- file: `F02-headings-styles.docx`
+- source package findings: `0`
+- source SDK findings: `0`
+- observed focus: heading paragraphs, paragraph style references, and outline-level preservation through the main story
+
+## Import expectation
+
+- heading paragraphs should import into canonical paragraph content with style bindings intact
+- style-backed outline semantics should remain attached to the relevant paragraphs instead of being flattened to plain text
+
+## Edit expectation
+
+- normal text edits inside styled paragraphs remain supported
+- heading paragraphs should keep their style identity through supported edits unless the runtime explicitly changes that style binding
+
+## Export expectation
+
+- export should preserve paragraph style references and heading ordering
+- reimported output should still identify the same heading paragraphs through their style-backed metadata
+
+## Validation expectation
+
+- package integrity should remain valid after supported edits
+- the source and supported edited exports should remain at `0` package findings and `0` SDK findings
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- heading styling and outline behavior should remain intact after export

package/test/fixtures/docx/F03-legal-outline-numbering.md

@@ -0,0 +1,34 @@
+# F03 Legal outline numbering
+
+## Source shape
+
+- file: `F03-legal-outline-numbering.docx`
+- source package findings: `0`
+- source SDK findings: `0`
+- observed focus: nested numbered and bulleted legal-outline content with numbering bindings carried through `word/numbering.xml`
+
+## Import expectation
+
+- numbered and bulleted paragraphs should import into canonical list-aware paragraph content
+- numbering bindings should remain runtime-owned metadata rather than being flattened into plain paragraph text
+
+## Edit expectation
+
+- normal text edits inside list items remain supported
+- supported list edits should preserve nesting and numbering bindings instead of dropping the list structure
+
+## Export expectation
+
+- export should preserve numbering definitions and paragraph numbering bindings
+- reimported output should continue to identify the same nested list structure
+
+## Validation expectation
+
+- package integrity should remain valid after supported edits
+- the source and supported edited exports should remain at `0` package findings and `0` SDK findings
+- this fixture is part of the supported-roundtrip numbering slice for Wave 5 and Wave 10
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- numbering, indentation, and nested legal-outline structure should remain intact after export

package/test/fixtures/docx/F04-restart-numbering-schedules.md

@@ -0,0 +1,33 @@
+# F04 Restart numbering schedules
+
+## Source shape
+
+- `word/document.xml` contains one primary numbered sequence and one restarted sequence.
+- `word/numbering.xml` defines one abstract numbering definition plus two numbering instances.
+- `numId=2` carries a level-0 `<w:startOverride w:val="1"/>` restart override.
+
+## Import expectation
+
+- the session should load as editable canonical paragraphs with numbering bindings intact
+- canonical numbering state should include both numbering instances and the restart override on `num:2`
+
+## Edit expectation
+
+- normal text edits inside numbered paragraphs remain supported
+- restart semantics remain owned by numbering state, not flattened into plain paragraphs
+
+## Export expectation
+
+- export should preserve paragraph numbering bindings for both sequences
+- `word/numbering.xml` should retain the restart override for the restarted schedule
+- reimported output should still report the restart override on `num:2`
+
+## Validation expectation
+
+- package integrity should remain valid after supported text edits
+- the fixture is part of the `supported-roundtrip` numbering slice for Wave 5 and Wave 10
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- the restarted schedule should still begin at `1` after export

package/test/fixtures/docx/F05-table-heavy-agreement.md

@@ -0,0 +1,34 @@
+# F05 Table-heavy agreement
+
+## Source shape
+
+- file: `F05-table-heavy-agreement.docx`
+- source package findings: `0`
+- source SDK findings: `0`
+- observed focus: body-level table markup, `w:tblGrid`, and package-backed cell-content survival
+
+## Import expectation
+
+- surrounding non-table story content may import into canonical editable text
+- body-level table content should import as locked preserve-only package-backed content rather than first-class canonical table state
+
+## Edit expectation
+
+- supported edits may occur around the preserved table region
+- the table surface itself must remain atomic and non-editable on the current live path
+
+## Export expectation
+
+- export should preserve the original table subtree and package-backed table content without semantic rewriting
+- `w:tbl`, `w:tblGrid`, and related table structure should survive roundtrip intact
+
+## Validation expectation
+
+- package integrity should remain valid after supported surrounding edits
+- the source and preserve-only roundtrip exports should remain at `0` package findings and `0` SDK findings
+- this fixture proves preserve-only table survival, not first-class table editing
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- the table layout and cell content should remain intact after export

package/test/fixtures/docx/F06-merged-cells-signature-table.md

@@ -0,0 +1,34 @@
+# F06 Merged-cells signature table
+
+## Source shape
+
+- file: `F06-merged-cells-signature-table.docx`
+- source package findings: `0`
+- source SDK findings: `0`
+- observed focus: body-level table markup with horizontal and vertical merged-cell behavior
+
+## Import expectation
+
+- surrounding non-table story content may import into canonical editable text
+- merged-cell table markup should import as locked preserve-only package-backed content rather than canonical table state
+
+## Edit expectation
+
+- supported edits may occur around the preserved table region
+- merged-cell structure must remain atomic and non-editable on the current live path
+
+## Export expectation
+
+- export should preserve the original merged-cell table subtree without semantic rewriting
+- `w:gridSpan`, `w:vMerge`, and related table structure should survive roundtrip intact
+
+## Validation expectation
+
+- package integrity should remain valid after supported surrounding edits
+- the source and preserve-only roundtrip exports should remain at `0` package findings and `0` SDK findings
+- this fixture proves preserve-only merged-cell survival, not first-class table editing
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- merged-cell layout and signature-table structure should remain intact after export

package/test/fixtures/docx/F07-inline-images-exhibit.md

@@ -0,0 +1,34 @@
+# F07 Inline images exhibit
+
+## Source shape
+
+- file: `F07-inline-images-exhibit.docx`
+- source package findings: `0`
+- source SDK findings: `0`
+- observed focus: inline drawing markup, image part retention, and document-to-media relationship integrity
+
+## Import expectation
+
+- inline images should import into the supported story surface without dropping their media backing
+- media parts and image relationships should remain tracked as package-backed assets through the runtime session
+
+## Edit expectation
+
+- normal text edits around existing inline images remain supported
+- this fixture does not claim arbitrary image replacement or resizing; the requirement is non-destructive inline-image survival on the owned path
+
+## Export expectation
+
+- export should preserve image parts, content types, and document relationship targets required for inline rendering
+- reimported output should still surface the inline images in the same story locations
+
+## Validation expectation
+
+- package integrity should remain valid after supported edits
+- the source and supported edited exports should remain at `0` package findings and `0` SDK findings
+- relationship integrity is part of the supported-roundtrip proof for this fixture
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- inline images should still render in place after export

package/test/fixtures/docx/F08-hyperlinks.md

@@ -0,0 +1,33 @@
+# F08 Hyperlinks exhibit list
+
+## Source shape
+
+- file: `F08-hyperlinks.docx`
+- source package findings: `0`
+- source SDK findings: `0`
+- observed focus: external hyperlink relationships in body content and hyperlink-bearing content inside preserved table regions
+
+## Import expectation
+
+- body-level hyperlinks should import into canonical text content with their targets preserved
+- hyperlinks that live inside preserve-only regions should stay attached to those opaque preserved regions
+
+## Edit expectation
+
+- normal text edits around supported body hyperlinks remain supported
+- preserve-only regions containing hyperlinks must remain atomic and non-editable on the live path
+
+## Export expectation
+
+- export should preserve external hyperlink relationships required by supported body hyperlinks
+- hyperlink targets and relationship integrity should survive roundtrip for both canonical and preserved surfaces
+
+## Validation expectation
+
+- package integrity should remain valid after supported edits
+- the source and supported edited exports should remain at `0` package findings and `0` SDK findings
+
+## Word expectation
+
+- Word should reopen the edited package without repair prompts
+- hyperlink text and target behavior should remain intact after export