@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/scopes/scope-kinds/field.ts

@@ -0,0 +1,65 @@
+/**
+ * Field scope kind — Slice 3.
+ *
+ * A field is an inline `FieldNode` living inside a paragraph. Content is
+ * the concatenated inline text (the field's result tree). Instruction,
+ * refresh status, and family live on the formatting + audit projections
+ * so AI consumers can branch on family (`PAGE`, `REF`, `STYLEREF`, …)
+ * without re-parsing the instruction string.
+ */
+
+import type { InlineNode } from "../../../model/canonical-document.ts";
+import type { FieldEnumeratedScope } from "../enumerate-scopes.ts";
+import { deriveReplaceability } from "../replaceability.ts";
+import type {
+  SemanticScope,
+  SemanticScopeFormatting,
+} from "../semantic-scope-types.ts";
+import { buildExcerpt } from "./_paragraph-text.ts";
+
+function flattenFieldText(children: readonly InlineNode[]): string {
+  const parts: string[] = [];
+  for (const child of children) {
+    if (child.type === "text") parts.push(child.text);
+    else if (child.type === "tab") parts.push("\t");
+    else if (child.type === "hard_break" || child.type === "column_break") parts.push("\n");
+    else if (child.type === "symbol") parts.push(child.char ?? "");
+    else if (child.type === "hyperlink" || child.type === "field") {
+      parts.push(flattenFieldText(child.children as readonly InlineNode[]));
+    }
+  }
+  return parts.join("");
+}
+
+export function compileFieldScope(entry: FieldEnumeratedScope): SemanticScope {
+  const { handle, field } = entry;
+  const text = flattenFieldText(field.children as readonly InlineNode[]);
+  const formatting: SemanticScopeFormatting = {};
+  return {
+    handle,
+    kind: "field",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting,
+    layout: {},
+    geometry: {},
+    // Fields are computed — agents must not edit the result tree
+    // directly; authoring goes through the instruction. Workflow mode
+    // `view` matches replaceability `preserve-only`.
+    workflow: { scopeIds: [], effectiveMode: "view" },
+    replaceability: deriveReplaceability(entry.kind, handle.provenance),
+    audit: {
+      source: "runtime",
+      derivedFrom: [
+        "canonical",
+        `field-family:${field.fieldFamily ?? "unknown"}`,
+        `field-instruction:${field.instruction}`,
+      ],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}

package/src/runtime/scopes/scope-kinds/heading.ts

@@ -0,0 +1,84 @@
+/**
+ * Heading scope kind — Slice 1 + 2 + 2026-04-22 closure.
+ *
+ * A heading is a paragraph carrying either `outlineLevel` or a `Heading{N}`
+ * style id. Formatting flows through the scope-local seam, which delegates
+ * to Layer 03's `resolveEffectiveFormatting` when the full canonical
+ * document is threaded.
+ *
+ * When we cannot determine the outline level (neither `outlineLevel` nor a
+ * `Heading\d` style id is present on the paragraph), we OMIT `outlineLevel`
+ * from the formatting projection — silently defaulting to 0 would be a
+ * correctness surprise (consumers would see H1 when the author's intent
+ * was unknown).
+ */
+
+import type { CanonicalDocument } from "../../../model/canonical-document.ts";
+import { resolveEffectiveFormattingForScope } from "../_formatting-seam.ts";
+import type { ParagraphLikeEnumeratedScope } from "../enumerate-scopes.ts";
+import { deriveReplaceability } from "../replaceability.ts";
+import type {
+  SemanticScope,
+  SemanticScopeFormatting,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+
+import {
+  buildExcerpt,
+  extractParagraphText,
+} from "./_paragraph-text.ts";
+
+export interface CompileHeadingOptions {
+  readonly document?: CanonicalDocument;
+  readonly paragraphIndex?: number;
+  readonly workflow?: SemanticScopeWorkflow;
+  /** See `CompileParagraphOptions.sectionIndex` — coord-08 §12. */
+  readonly sectionIndex?: number;
+}
+
+export function compileHeadingScope(
+  entry: ParagraphLikeEnumeratedScope,
+  options: CompileHeadingOptions = {},
+): SemanticScope {
+  const { handle, paragraph } = entry;
+  const text = extractParagraphText(paragraph);
+  const effective = resolveEffectiveFormattingForScope({
+    paragraph,
+    ...(options.document ? { document: options.document } : {}),
+    ...(typeof options.paragraphIndex === "number"
+      ? { paragraphIndex: options.paragraphIndex }
+      : {}),
+  });
+  const formatting: SemanticScopeFormatting = {
+    ...(typeof effective.outlineLevel === "number"
+      ? { outlineLevel: effective.outlineLevel }
+      : {}),
+    ...(effective.paragraphStyleId
+      ? { paragraphStyleId: effective.paragraphStyleId }
+      : {}),
+    ...(effective.emphasis.length > 0 ? { emphasis: effective.emphasis } : {}),
+  };
+  return {
+    handle,
+    kind: "heading",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting,
+    layout:
+      typeof options.sectionIndex === "number"
+        ? { sectionIndex: options.sectionIndex }
+        : {},
+    geometry: {},
+    workflow: options.workflow ?? { scopeIds: [], effectiveMode: "edit" },
+    replaceability: deriveReplaceability(entry.kind, handle.provenance),
+    audit: {
+      source: "runtime",
+      derivedFrom: ["canonical"],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}

package/src/runtime/scopes/scope-kinds/list-item.ts

@@ -0,0 +1,77 @@
+/**
+ * List-item scope kind — Slice 1 + 2 + 2026-04-22 closure.
+ *
+ * Carries the numbering binding on the formatting projection. When the
+ * seam has access to Layer 03 (full canonical document threaded), the
+ * resolved marker glyph ("1.", "a)", "•") lands in
+ * `formatting.numbering.label`; without it, only the instance + level are
+ * populated.
+ */
+
+import type { CanonicalDocument } from "../../../model/canonical-document.ts";
+import { resolveEffectiveFormattingForScope } from "../_formatting-seam.ts";
+import type { ParagraphLikeEnumeratedScope } from "../enumerate-scopes.ts";
+import { deriveReplaceability } from "../replaceability.ts";
+import type {
+  SemanticScope,
+  SemanticScopeFormatting,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+
+import {
+  buildExcerpt,
+  extractParagraphText,
+} from "./_paragraph-text.ts";
+
+export interface CompileListItemOptions {
+  readonly document?: CanonicalDocument;
+  readonly paragraphIndex?: number;
+  readonly workflow?: SemanticScopeWorkflow;
+  /** See `CompileParagraphOptions.sectionIndex` — coord-08 §12. */
+  readonly sectionIndex?: number;
+}
+
+export function compileListItemScope(
+  entry: ParagraphLikeEnumeratedScope,
+  options: CompileListItemOptions = {},
+): SemanticScope {
+  const { handle, paragraph } = entry;
+  const text = extractParagraphText(paragraph);
+  const effective = resolveEffectiveFormattingForScope({
+    paragraph,
+    ...(options.document ? { document: options.document } : {}),
+    ...(typeof options.paragraphIndex === "number"
+      ? { paragraphIndex: options.paragraphIndex }
+      : {}),
+  });
+  const formatting: SemanticScopeFormatting = {
+    ...(effective.numbering ? { numbering: effective.numbering } : {}),
+    ...(effective.paragraphStyleId
+      ? { paragraphStyleId: effective.paragraphStyleId }
+      : {}),
+    ...(effective.emphasis.length > 0 ? { emphasis: effective.emphasis } : {}),
+  };
+  return {
+    handle,
+    kind: "list-item",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting,
+    layout:
+      typeof options.sectionIndex === "number"
+        ? { sectionIndex: options.sectionIndex }
+        : {},
+    geometry: {},
+    workflow: options.workflow ?? { scopeIds: [], effectiveMode: "edit" },
+    replaceability: deriveReplaceability(entry.kind, handle.provenance),
+    audit: {
+      source: "runtime",
+      derivedFrom: ["canonical"],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}

package/src/runtime/scopes/scope-kinds/paragraph.ts

@@ -0,0 +1,182 @@
+/**
+ * Paragraph scope kind — Slice 1 + 2 + 2026-04-22 closure.
+ *
+ * Routes formatting through the scope-local seam, which itself delegates
+ * to Layer 03's `resolveEffectiveFormatting` when `doc` + `paragraphIndex`
+ * are threaded. Without them, the seam degrades to a narrow paragraph-
+ * only projection (still honest, just narrower).
+ *
+ * `layout` / `geometry` / `workflow` are intentionally bounded — see
+ * module `layout-geometry-bounded.md` in the architecture doc. Paragraph
+ * scopes stay `partial: true` because those projections are not yet
+ * compiler-backed.
+ */
+
+import type { CanonicalDocument } from "../../../model/canonical-document.ts";
+import { resolveEffectiveFormattingForScope } from "../_formatting-seam.ts";
+import type { ParagraphLikeEnumeratedScope } from "../enumerate-scopes.ts";
+import { computeBlockPositions } from "../position-map.ts";
+import { deriveReplaceability } from "../replaceability.ts";
+import {
+  isStructuredReplacementContent,
+  type ReplacementScope,
+  type RuntimeOperationPlan,
+  type SemanticScope,
+  type SemanticScopeFormatting,
+  type SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+import type { CanonicalDocumentEnvelope } from "../../../core/state/editor-state.ts";
+
+import {
+  buildExcerpt,
+  extractParagraphText,
+} from "./_paragraph-text.ts";
+
+export interface CompileParagraphOptions {
+  readonly document?: CanonicalDocument;
+  readonly paragraphIndex?: number;
+  readonly workflow?: SemanticScopeWorkflow;
+  /**
+   * 0-based section index derived by counting `section_break` blocks
+   * that appear before this paragraph's block (see
+   * `buildSectionIndexByBlockIndex` in `../compile-scope.ts`). When
+   * present, projects into `SemanticScopeLayout.sectionIndex`. Closes
+   * coord-08 §12 / harness finding E5a.
+   */
+  readonly sectionIndex?: number;
+}
+
+export function compileParagraphScope(
+  entry: ParagraphLikeEnumeratedScope,
+  options: CompileParagraphOptions = {},
+): SemanticScope {
+  const { handle, paragraph } = entry;
+  const text = extractParagraphText(paragraph);
+  const effective = resolveEffectiveFormattingForScope({
+    paragraph,
+    ...(options.document ? { document: options.document } : {}),
+    ...(typeof options.paragraphIndex === "number"
+      ? { paragraphIndex: options.paragraphIndex }
+      : {}),
+  });
+  const formatting: SemanticScopeFormatting = {
+    ...(effective.paragraphStyleId
+      ? { paragraphStyleId: effective.paragraphStyleId }
+      : {}),
+    ...(effective.emphasis.length > 0 ? { emphasis: effective.emphasis } : {}),
+  };
+  return {
+    handle,
+    kind: "paragraph",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting,
+    layout:
+      typeof options.sectionIndex === "number"
+        ? { sectionIndex: options.sectionIndex }
+        : {},
+    geometry: {},
+    workflow: options.workflow ?? { scopeIds: [], effectiveMode: "edit" },
+    replaceability: deriveReplaceability(entry.kind, handle.provenance),
+    audit: {
+      source: "runtime",
+      derivedFrom:
+        entry.classifications.length > 0
+          ? ["canonical", "workflow-overlay"]
+          : ["canonical"],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}
+
+export interface CompileParagraphReplacementOptions {
+  readonly document: CanonicalDocumentEnvelope;
+  readonly posture: "direct-edit" | "suggest-mode";
+}
+
+/**
+ * Slice 5 — lower a paragraph-scope replacement proposal into a
+ * `RuntimeOperationPlan`. Handles two content kinds:
+ *
+ *   - `kind: "text"` → single `text-replace` step spanning the
+ *     paragraph's canonical block range; passes a flat string through
+ *     the existing `text.insert` runtime command.
+ *   - `kind: "structured"` → single `fragment-replace` step carrying
+ *     a `CanonicalDocumentFragment` payload; dispatches via the
+ *     runtime's `insertFragment` pipeline with the block range as
+ *     selection. Unblocked 2026-04-22 once L02 shipped
+ *     `CanonicalDocumentFragment` (`src/model/canonical-document.ts`).
+ *
+ * Determinism (S3): the plan is a pure projection of (blockIndex,
+ * content, posture). No timestamps, no random ids.
+ */
+export function compileParagraphReplacement(
+  entry: ParagraphLikeEnumeratedScope,
+  proposed: ReplacementScope,
+  options: CompileParagraphReplacementOptions,
+): RuntimeOperationPlan | null {
+  if (proposed.operation !== "replace") return null;
+
+  const blocks = computeBlockPositions(options.document);
+  const blockRange = blocks.find((b) => b.blockIndex === entry.blockIndex);
+  if (!blockRange) return null;
+
+  if (proposed.proposedContent.kind === "text") {
+    const text = proposed.proposedContent.text ?? "";
+    const stepKind =
+      options.posture === "suggest-mode" ? "text-insert-tracked" : "text-replace";
+    return {
+      scopeId: entry.handle.scopeId,
+      targetKind: "paragraph",
+      operation: proposed.operation,
+      steps: Object.freeze([
+        {
+          kind: stepKind,
+          summary:
+            stepKind === "text-replace"
+              ? `replace paragraph #${entry.blockIndex} text (len ${text.length})`
+              : `suggest-mode paragraph #${entry.blockIndex} text replace (len ${text.length})`,
+          range: { from: blockRange.from, to: blockRange.to },
+          text,
+        },
+      ]),
+      ...(proposed.preserve ? { preserve: proposed.preserve } : {}),
+      posture: options.posture,
+    };
+  }
+
+  if (proposed.proposedContent.kind === "structured") {
+    // Structured-fragment path (L02-shipped CanonicalDocumentFragment).
+    // Suggest-mode fragment replacement is NOT wired today — it would
+    // require per-block tracked-insert/delete dispatch which depends
+    // on the same runtime-core suggest-mode primitive that blocks
+    // coord item 2. Refuse cleanly until both are ready.
+    if (options.posture === "suggest-mode") {
+      return null;
+    }
+    const fragment = proposed.proposedContent.structured;
+    if (!isStructuredReplacementContent(fragment)) return null;
+    const blockCount = fragment.blocks.length;
+    return {
+      scopeId: entry.handle.scopeId,
+      targetKind: "paragraph",
+      operation: proposed.operation,
+      steps: Object.freeze([
+        {
+          kind: "fragment-replace",
+          summary: `replace paragraph #${entry.blockIndex} with structured fragment (${blockCount} block(s))`,
+          range: { from: blockRange.from, to: blockRange.to },
+          fragment,
+        },
+      ]),
+      ...(proposed.preserve ? { preserve: proposed.preserve } : {}),
+      posture: options.posture,
+    };
+  }
+
+  return null;
+}

package/src/runtime/scopes/scope-kinds/revision.ts

@@ -0,0 +1,62 @@
+/**
+ * Revision scope kind — Slice 3.
+ *
+ * Projects a canonical `RevisionRecord` into a scope. Content is a terse
+ * one-line summary (`<kind> by <authorId>`); richer narrative (before /
+ * after payloads, semanticKind, linkedRevisionIds) rides on the `audit`
+ * projection for agent inspection without inflating `content.text`.
+ */
+
+import type { RevisionEnumeratedScope } from "../enumerate-scopes.ts";
+import { deriveReplaceability } from "../replaceability.ts";
+import type {
+  SemanticScope,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+
+function revisionSummary(
+  revision: RevisionEnumeratedScope["revision"],
+): string {
+  const author = revision.authorId ?? "unknown-author";
+  return `${revision.kind} by ${author}`;
+}
+
+export function compileRevisionScope(
+  entry: RevisionEnumeratedScope,
+): SemanticScope {
+  const { handle, revision } = entry;
+  const text = revisionSummary(revision);
+  const workflow: SemanticScopeWorkflow = {
+    scopeIds: [revision.changeId],
+    effectiveMode: revision.status === "open" ? "suggest" : "view",
+    ...(revision.status === "detached"
+      ? { blockedReasons: ["revision-detached"] }
+      : {}),
+  };
+  const derivedFrom: string[] = [
+    "canonical.review.revisions",
+    `kind:${revision.kind}`,
+    `status:${revision.status}`,
+  ];
+  if (revision.metadata?.semanticKind) {
+    derivedFrom.push(`semantic-kind:${revision.metadata.semanticKind}`);
+  }
+  return {
+    handle,
+    kind: "revision",
+    classifications: entry.classifications,
+    content: { text },
+    formatting: {},
+    layout: {},
+    geometry: {},
+    workflow,
+    replaceability: deriveReplaceability(entry.kind, handle.provenance),
+    audit: {
+      source: revision.metadata?.source === "import" ? "import" : "runtime",
+      derivedFrom,
+      confidence: revision.status === "detached" ? "low" : "high",
+    },
+    // layout / geometry projections unpopulated until refactor/05 Slice 5.
+    partial: true,
+  };
+}

package/src/runtime/scopes/scope-kinds/table-cell.ts

@@ -0,0 +1,57 @@
+/**
+ * Table-cell scope kind — Slice 2.
+ *
+ * Content is the joined text of the cell's paragraphs. Formatting carries
+ * the cell's structural role (header / body / footer) derived from the
+ * enclosing row. A cell's replaceability is `text-only` because editing
+ * structure (grid span, merge) belongs to a higher-level operation than
+ * scope-scoped replacement.
+ */
+
+import type { TableCellEnumeratedScope } from "../enumerate-scopes.ts";
+import type {
+  SemanticScope,
+  SemanticScopeFormatting,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+
+import { deriveTableCellRole } from "../_formatting-seam.ts";
+import { buildExcerpt } from "./_paragraph-text.ts";
+import { extractCellText } from "./_table-text.ts";
+
+export interface CompileTableCellOptions {
+  readonly workflow?: SemanticScopeWorkflow;
+}
+
+export function compileTableCellScope(
+  entry: TableCellEnumeratedScope,
+  options: CompileTableCellOptions = {},
+): SemanticScope {
+  const { handle, cell, row, table, rowIndex } = entry;
+  const text = extractCellText(cell);
+  const role = deriveTableCellRole({ row, rowIndex, table }, cell);
+  const formatting: SemanticScopeFormatting = { tableRole: role };
+  return {
+    handle,
+    kind: "table-cell",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting,
+    layout: {},
+    geometry: {},
+    workflow: options.workflow ?? { scopeIds: [], effectiveMode: "edit" },
+    replaceability: {
+      level: "text-only",
+      reason: "table-cell-preserves-structure",
+    },
+    audit: {
+      source: "runtime",
+      derivedFrom: ["canonical"],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}

package/src/runtime/scopes/scope-kinds/table-row.ts

@@ -0,0 +1,61 @@
+/**
+ * Table-row scope kind — Slice 2.
+ *
+ * Content is the joined text of the row's cells (pipe-separated). The row
+ * carries the structural role (header / body / footer) on the formatting
+ * projection so consumers can branch without walking structure.
+ */
+
+import type { TableRowEnumeratedScope } from "../enumerate-scopes.ts";
+import type {
+  SemanticScope,
+  SemanticScopeFormatting,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+
+import { deriveTableCellRole } from "../_formatting-seam.ts";
+import { buildExcerpt } from "./_paragraph-text.ts";
+import { extractRowText } from "./_table-text.ts";
+
+export interface CompileTableRowOptions {
+  readonly workflow?: SemanticScopeWorkflow;
+}
+
+export function compileTableRowScope(
+  entry: TableRowEnumeratedScope,
+  options: CompileTableRowOptions = {},
+): SemanticScope {
+  const { handle, row, table, rowIndex } = entry;
+  const text = extractRowText(row);
+  // Role is a row-level concept; borrow the cell-role derivation since it
+  // reads `row.isHeader` + row position. A header row's cells are all
+  // "header"; a body row's cells are "body"; terminal row is "footer".
+  const firstCell = row.cells[0];
+  const role = firstCell
+    ? deriveTableCellRole({ row, rowIndex, table }, firstCell)
+    : "body";
+  const formatting: SemanticScopeFormatting = { tableRole: role };
+  return {
+    handle,
+    kind: "table-row",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting,
+    layout: {},
+    geometry: {},
+    workflow: options.workflow ?? { scopeIds: [], effectiveMode: "edit" },
+    replaceability: {
+      level: "blocked",
+      reason: "table-row-replacement-not-yet-implemented",
+    },
+    audit: {
+      source: "runtime",
+      derivedFrom: ["canonical"],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}

package/src/runtime/scopes/scope-kinds/table.ts

@@ -0,0 +1,55 @@
+/**
+ * Table scope kind — Slice 2.
+ *
+ * A table scope is the whole `TableNode`. Formatting projects `styleId`;
+ * content is a joined plain-text preview of the first two rows so AI
+ * bundles can disambiguate tables by opening content.
+ */
+
+import type { TableEnumeratedScope } from "../enumerate-scopes.ts";
+import type {
+  SemanticScope,
+  SemanticScopeFormatting,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+
+import { buildExcerpt } from "./_paragraph-text.ts";
+import { extractTablePreview } from "./_table-text.ts";
+
+export interface CompileTableOptions {
+  readonly workflow?: SemanticScopeWorkflow;
+}
+
+export function compileTableScope(
+  entry: TableEnumeratedScope,
+  options: CompileTableOptions = {},
+): SemanticScope {
+  const { handle, table } = entry;
+  const previewText = extractTablePreview(table);
+  const formatting: SemanticScopeFormatting = {
+    ...(table.styleId ? { paragraphStyleId: table.styleId } : {}),
+  };
+  return {
+    handle,
+    kind: "table",
+    classifications: entry.classifications,
+    content: {
+      text: previewText,
+      excerpt: buildExcerpt(previewText),
+    },
+    formatting,
+    layout: {},
+    geometry: {},
+    workflow: options.workflow ?? { scopeIds: [], effectiveMode: "edit" },
+    replaceability: {
+      level: "blocked",
+      reason: "table-replacement-not-yet-implemented",
+    },
+    audit: {
+      source: "runtime",
+      derivedFrom: ["canonical"],
+      confidence: "medium",
+    },
+    partial: true,
+  };
+}