@beyondwork/docx-react-component 1.0.37 → 1.0.39

package/src/runtime/paragraph-style-resolver.ts

@@ -0,0 +1,194 @@
+/**
+ * Resolve style chains for paragraph and character styles by walking the
+ * `basedOn` reference, with cycle detection.
+ *
+ * Returned chains are leaf-first (most-specific style at index 0, root at the
+ * end). Cycles break at the first re-encounter. Dangling `basedOn` references
+ * stop the walk silently (the leaf is still returned).
+ *
+ * Tasks 9 and 10 extend this module with `resolveEffective*Formatting`
+ * helpers that cascade the chain into a flat formatting record.
+ */
+
+import type {
+  CanonicalParagraphFormatting,
+  CanonicalRunFormatting,
+  CharacterStyleDefinition,
+  ParagraphStyleDefinition,
+  StylesCatalog,
+} from "../model/canonical-document.ts";
+
+export function resolveParagraphStyleChain(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): string[] {
+  const chain: string[] = [];
+  if (!catalog) return chain;
+  const visited = new Set<string>();
+  let current: string | undefined = styleId;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const def: ParagraphStyleDefinition | undefined = catalog.paragraphs[current];
+    if (!def) break;
+    chain.push(current);
+    current = def.basedOn;
+  }
+  return chain;
+}
+
+export function resolveCharacterStyleChain(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): string[] {
+  const chain: string[] = [];
+  if (!catalog) return chain;
+  const visited = new Set<string>();
+  let current: string | undefined = styleId;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const def: CharacterStyleDefinition | undefined = catalog.characters[current];
+    if (!def) break;
+    chain.push(current);
+    current = def.basedOn;
+  }
+  return chain;
+}
+
+function mergeRun(
+  base: CanonicalRunFormatting | undefined,
+  over: CanonicalRunFormatting | undefined,
+): CanonicalRunFormatting | undefined {
+  if (!base && !over) return undefined;
+  return { ...(base ?? {}), ...(over ?? {}) };
+}
+
+function mergeParagraph(
+  base: CanonicalParagraphFormatting | undefined,
+  over: CanonicalParagraphFormatting | undefined,
+): CanonicalParagraphFormatting | undefined {
+  if (!base && !over) return undefined;
+  const merged: CanonicalParagraphFormatting = { ...(base ?? {}), ...(over ?? {}) };
+  if (base?.spacing || over?.spacing) {
+    merged.spacing = { ...(base?.spacing ?? {}), ...(over?.spacing ?? {}) };
+  }
+  if (base?.indentation || over?.indentation) {
+    merged.indentation = { ...(base?.indentation ?? {}), ...(over?.indentation ?? {}) };
+  }
+  if (base?.borders || over?.borders) {
+    merged.borders = { ...(base?.borders ?? {}), ...(over?.borders ?? {}) };
+  }
+  if (base?.shading || over?.shading) {
+    merged.shading = { ...(base?.shading ?? {}), ...(over?.shading ?? {}) };
+  }
+  if (base?.paragraphMarkRunProperties || over?.paragraphMarkRunProperties) {
+    merged.paragraphMarkRunProperties = mergeRun(
+      base?.paragraphMarkRunProperties,
+      over?.paragraphMarkRunProperties,
+    );
+  }
+  return merged;
+}
+
+export interface ParagraphResolveInput {
+  styleId: string | undefined;
+  direct: CanonicalParagraphFormatting | undefined;
+}
+
+/**
+ * Resolve paragraph formatting cascade: docDefaults.paragraph → basedOn chain
+ * (root-to-leaf) → direct. Returns `{}` when nothing is present.
+ */
+export function resolveEffectiveParagraphFormatting(
+  input: ParagraphResolveInput,
+  catalog: StylesCatalog | undefined,
+): CanonicalParagraphFormatting {
+  let acc: CanonicalParagraphFormatting | undefined = catalog?.docDefaults?.paragraph;
+  if (catalog && input.styleId) {
+    const chain = resolveParagraphStyleChain(input.styleId, catalog);
+    // Walk root-to-leaf (most-general first) so the most-specific style wins
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeParagraph(acc, catalog.paragraphs[styleId]?.paragraphProperties);
+    }
+  }
+  acc = mergeParagraph(acc, input.direct);
+  return acc ?? {};
+}
+
+export interface RunResolveInput {
+  paragraphStyleId: string | undefined;
+  characterStyleId: string | undefined;
+  direct: CanonicalRunFormatting | undefined;
+}
+
+/**
+ * Resolve run formatting cascade: docDefaults.run → paragraph-style-chain rPr
+ * (root-to-leaf) → character-style-chain (root-to-leaf) → direct. Returns
+ * `{}` when nothing is present.
+ */
+export function resolveEffectiveRunFormatting(
+  input: RunResolveInput,
+  catalog: StylesCatalog | undefined,
+): CanonicalRunFormatting {
+  let acc: CanonicalRunFormatting | undefined = catalog?.docDefaults?.run;
+  if (catalog && input.paragraphStyleId) {
+    const chain = resolveParagraphStyleChain(input.paragraphStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeRun(acc, catalog.paragraphs[styleId]?.runProperties);
+    }
+  }
+  if (catalog && input.characterStyleId) {
+    const chain = resolveCharacterStyleChain(input.characterStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeRun(acc, catalog.characters[styleId]?.runProperties);
+    }
+  }
+  acc = mergeRun(acc, input.direct);
+  return acc ?? {};
+}
+
+export interface MarkerResolveInput {
+  paragraphStyleId: string | undefined;
+  levelRunProperties: CanonicalRunFormatting | undefined;
+}
+
+/**
+ * Resolve the numbering marker's character formatting — the rPr that styles
+ * the number/bullet glyph itself (bold, color, font, size, etc.).
+ *
+ * Cascade order (lowest to highest priority):
+ *   1. `docDefaults.run` — Word's baseline run formatting.
+ *   2. Paragraph style chain's `runProperties` — walked root-to-leaf; the
+ *      numbered paragraph's styleId contributes each ancestor's rPr.
+ *   3. The leaf paragraph style's `paragraphProperties.paragraphMarkRunProperties`
+ *      — Word stores the paragraph-mark rPr separately from the body rPr,
+ *      and the mark's formatting is what the numbering marker inherits from.
+ *   4. `levelRunProperties` — `<w:lvl><w:rPr>` on the numbering level. Per
+ *      ECMA-376, this is the most specific formatting for the marker and
+ *      overrides the paragraph's run formatting entirely for the marker.
+ */
+export function resolveNumberingMarkerRunFormatting(
+  input: MarkerResolveInput,
+  catalog: StylesCatalog | undefined,
+): CanonicalRunFormatting {
+  // Start with docDefaults baseline
+  let acc: CanonicalRunFormatting | undefined = catalog?.docDefaults?.run;
+
+  // Walk the paragraph style chain's rPr (root-to-leaf, most-specific wins)
+  if (catalog && input.paragraphStyleId) {
+    const chain = resolveParagraphStyleChain(input.paragraphStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const styleId = chain[i]!;
+      acc = mergeRun(acc, catalog.paragraphs[styleId]?.runProperties);
+    }
+    // Leaf paragraph style's paragraph-mark rPr layers on top of the chain
+    const leaf = catalog.paragraphs[input.paragraphStyleId];
+    acc = mergeRun(acc, leaf?.paragraphProperties?.paragraphMarkRunProperties);
+  }
+
+  // Level rPr has the final say (per ECMA-376 17.9)
+  acc = mergeRun(acc, input.levelRunProperties);
+  return acc ?? {};
+}

package/src/runtime/render/block-fragment-projection.ts

@@ -0,0 +1,35 @@
+/**
+ * Block fragment projection (P4b).
+ *
+ * Classifies each `PublicBlockFragment` produced by the layout facet into
+ * a `RenderBlock["kind"]` so the render kernel's output is accurate across
+ * paragraph / table / opaque / synthetic blocks.  Previously the kernel's
+ * `classifyBlockKind` stub always returned `"paragraph"`.
+ *
+ * The classification is driven by the deterministic blockId prefix scheme
+ * emitted by `src/runtime/surface-projection.ts`:
+ *   - `paragraph-*`  → "paragraph"
+ *   - `table-*`      → "table"
+ *   - `opaque-*`     → "opaque"
+ *   - `section-break-*` → "opaque" (read-only boundary marker)
+ *   - `sdt-*`, `sdt-wrapper-*` → "opaque"
+ *   - `custom-xml-*` → "opaque"
+ *   - `alt-chunk-*`  → "opaque"
+ *   - `synthetic-*`  → "synthetic"
+ * Unknown prefixes fall back to `"paragraph"` so the render frame stays
+ * usable while a new surface node type is in development.
+ */
+
+import type { RenderBlock } from "./render-frame-types.ts";
+
+export function classifyBlockKind(blockId: string): RenderBlock["kind"] {
+  if (blockId.startsWith("paragraph")) return "paragraph";
+  if (blockId.startsWith("table")) return "table";
+  if (blockId.startsWith("opaque")) return "opaque";
+  if (blockId.startsWith("section-break")) return "opaque";
+  if (blockId.startsWith("sdt")) return "opaque";
+  if (blockId.startsWith("custom-xml")) return "opaque";
+  if (blockId.startsWith("alt-chunk")) return "opaque";
+  if (blockId.startsWith("synthetic")) return "synthetic";
+  return "paragraph";
+}

package/src/runtime/render/decoration-resolver.ts

@@ -0,0 +1,189 @@
+/**
+ * Decoration resolver — single pass that turns canonical decoration sources
+ * (workflow scopes, comments, revisions, search, locked zones) into the
+ * five lanes of `DecorationIndex` that chrome consumes.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §1, the kernel's MVP leaves
+ * `DecorationIndex` empty; chrome surfaces that need per-decoration anchor
+ * rects re-project from runtime offsets themselves.  The resolver fixes
+ * that by walking each source once, resolving its body rect through the
+ * kernel's anchor index, and emitting a `RenderBlockDecoration` entry with
+ * the stable rect.  Chrome reads the resolved lanes directly and never
+ * touches the DOM or re-runs anchor math.
+ *
+ * The resolver is pure: same inputs produce the same output.  The kernel
+ * invokes it once per frame build, cached against the frame's revision.
+ */
+
+import type {
+  CommentDecorationModel,
+  CommentDecorationThread,
+} from "../../ui/headless/comment-decoration-model.ts";
+import type {
+  RevisionDecorationModel,
+  RevisionDecorationEntry,
+} from "../../ui/headless/revision-decoration-model.ts";
+import type { ScopeRailSegment } from "../workflow-rail-segments.ts";
+import type {
+  DecorationIndex,
+  RenderAnchorIndex,
+  RenderBlockDecoration,
+  RenderFrameRect,
+} from "./render-frame-types.ts";
+
+// ---------------------------------------------------------------------------
+// Input shapes
+// ---------------------------------------------------------------------------
+
+export interface SearchMatchRange {
+  /** Stable identifier the search plugin emits for each match. */
+  matchId: string;
+  /** Inclusive runtime offset. */
+  from: number;
+  /** Exclusive runtime offset. */
+  to: number;
+  /** True when this match is the currently-focused "active" result. */
+  isActive?: boolean;
+}
+
+export interface LockedRangeInput {
+  /** Stable id of the lock (fragmentId for locked zones, scopeId for preserve-only scopes). */
+  lockId: string;
+  /** Inclusive runtime offset. */
+  from: number;
+  /** Exclusive runtime offset. */
+  to: number;
+  /** Optional human label. */
+  label?: string;
+}
+
+export interface ResolveDecorationIndexInput {
+  anchorIndex: RenderAnchorIndex;
+  /**
+   * Scope rail segments covering the active story.  The resolver re-uses
+   * their anchor rects when present (`bodyTintRect`) and falls back to
+   * `anchorIndex.bySelection(from, to)` otherwise.
+   */
+  workflowSegments?: readonly ScopeRailSegment[];
+  comments?: CommentDecorationModel | null | undefined;
+  revisions?: RevisionDecorationModel | null | undefined;
+  searchMatches?: readonly SearchMatchRange[];
+  lockedRanges?: readonly LockedRangeInput[];
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export function resolveDecorationIndex(
+  input: ResolveDecorationIndexInput,
+): DecorationIndex {
+  const workflow: RenderBlockDecoration[] = [];
+  const comments: RenderBlockDecoration[] = [];
+  const revisions: RenderBlockDecoration[] = [];
+  const search: RenderBlockDecoration[] = [];
+  const locked: RenderBlockDecoration[] = [];
+
+  if (input.workflowSegments) {
+    for (const segment of input.workflowSegments) {
+      const frame =
+        segment.bodyTintRect ??
+        input.anchorIndex.bySelection(segment.fromOffset, segment.toOffset);
+      if (!frame) continue;
+      workflow.push({
+        kind: "workflow",
+        refId: segment.scopeId,
+        frame,
+      });
+    }
+  }
+
+  if (input.comments) {
+    for (const thread of input.comments.threads) {
+      const frame = resolveRange(
+        input.anchorIndex,
+        thread.from,
+        thread.to,
+      );
+      if (!frame) continue;
+      comments.push({
+        kind: "comment",
+        refId: thread.commentId,
+        frame,
+      });
+      // Track active thread separately so chrome can prioritize rendering.
+      // (We don't have a per-decoration "isActive" field today; chrome
+      // reads `CommentDecorationModel.activeCommentId` alongside the
+      // decoration lane and picks out the matching refId.)
+      void asCommentThread(thread);
+    }
+  }
+
+  if (input.revisions) {
+    for (const revision of input.revisions.revisions) {
+      const frame = resolveRange(
+        input.anchorIndex,
+        revision.from,
+        revision.to,
+      );
+      if (!frame) continue;
+      revisions.push({
+        kind: "revision",
+        refId: revision.revisionId,
+        frame,
+      });
+      void asRevisionEntry(revision);
+    }
+  }
+
+  if (input.searchMatches) {
+    for (const match of input.searchMatches) {
+      const frame = resolveRange(input.anchorIndex, match.from, match.to);
+      if (!frame) continue;
+      search.push({
+        kind: "search",
+        refId: match.matchId,
+        frame,
+      });
+    }
+  }
+
+  if (input.lockedRanges) {
+    for (const lock of input.lockedRanges) {
+      const frame = resolveRange(input.anchorIndex, lock.from, lock.to);
+      if (!frame) continue;
+      locked.push({
+        kind: "locked",
+        refId: lock.lockId,
+        frame,
+      });
+    }
+  }
+
+  return { workflow, comments, revisions, search, locked };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function resolveRange(
+  anchorIndex: RenderAnchorIndex,
+  from: number,
+  to: number,
+): RenderFrameRect | null {
+  if (from >= to) {
+    return anchorIndex.byRuntimeOffset(from);
+  }
+  return anchorIndex.bySelection(from, to);
+}
+
+// Type preservation helpers so the input shapes stay referenced and
+// `tsgo --noEmit` catches shape drift if the upstream models change.
+function asCommentThread(thread: CommentDecorationThread): CommentDecorationThread {
+  return thread;
+}
+
+function asRevisionEntry(entry: RevisionDecorationEntry): RevisionDecorationEntry {
+  return entry;
+}

package/src/runtime/render/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Runtime-owned render kernel — internal API surface.
+ *
+ * The kernel consumes the layout facet and emits `RenderFrame` objects
+ * that every chrome surface reads.  Nothing in this module is part of
+ * the package's public API; consumers go through `ref.layout.getRenderFrame`
+ * (facet) rather than wiring the kernel directly.
+ */
+
+export {
+  createRenderKernel,
+  sumDeltasBefore,
+  type RenderKernel,
+  type CreateRenderKernelInput,
+  type DecorationSources,
+  type PendingOpDelta,
+} from "./render-kernel.ts";
+
+export {
+  createPendingOpDeltaReader,
+  type PendingOpDeltaReader,
+  type PendingOpDeltaSnapshot,
+  type CreatePendingOpDeltaReaderInput,
+} from "./pending-op-delta-reader.ts";
+
+export {
+  resolveDecorationIndex,
+  type ResolveDecorationIndexInput,
+  type SearchMatchRange,
+  type LockedRangeInput,
+} from "./decoration-resolver.ts";
+
+export {
+  DEFAULT_PX_PER_TWIP,
+  EMPTY_DECORATION_INDEX,
+  defaultChromeReservations,
+  resolveDefaultZoom,
+  type DecorationIndex,
+  type PageChromeReservations,
+  type RenderAnchorIndex,
+  type RenderAnchorQuery,
+  type RenderBlock,
+  type RenderBlockDecoration,
+  type RenderFrame,
+  type RenderFrameQueryOptions,
+  type RenderFrameRect,
+  type RenderHitResult,
+  type RenderKernelEvent,
+  type RenderPoint,
+  type RenderLine,
+  type RenderLineAnchor,
+  type RenderPage,
+  type RenderPageRegions,
+  type RenderStoryRegion,
+  type RenderZoom,
+  type DefaultZoomInput,
+} from "./render-frame-types.ts";

package/src/runtime/render/pending-op-delta-reader.ts

@@ -0,0 +1,129 @@
+/**
+ * Pending-op delta reader — thin accessor over `createRenderKernel`'s
+ * `getPendingOpDeltas` seam so chrome surfaces can reason about the
+ * predicted-dispatch window without reaching into the kernel's internals.
+ *
+ * Chrome must NOT mutate anchor rects during the predicted-dispatch window —
+ * per `bounded-local-first-interaction-architecture.md`, the rects settle
+ * when `TextCommandAck` reconciles.  Chrome surfaces that want to *mask*
+ * during that window (disable buttons, show a spinner) read a flag from
+ * this module instead of polling the kernel directly.
+ *
+ * The reader is decoupled from the kernel so the predicted lane can be
+ * swapped or gated without touching chrome code.
+ */
+
+import type { PendingOpDelta } from "./render-kernel.ts";
+
+// ---------------------------------------------------------------------------
+// Reader contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Snapshot of the predicted-dispatch state at the moment it was read.
+ *
+ * `deltas` is the same shape the kernel's anchor index receives; chrome
+ * uses the summary fields below instead of walking the array in hot paths.
+ */
+export interface PendingOpDeltaSnapshot {
+  /** Raw delta array, identical to what the kernel received. */
+  deltas: readonly PendingOpDelta[];
+  /** True when any pending op is outstanding. */
+  hasPending: boolean;
+  /** Count of pending ops (for perf probe sampling). */
+  pendingCount: number;
+  /** Net character delta summed across all pending ops. */
+  netCharacterDelta: number;
+  /** Lowest runtime offset touched by any pending op, or null when empty. */
+  earliestTouchedOffset: number | null;
+  /** Highest runtime offset touched by any pending op, or null when empty. */
+  latestTouchedOffset: number | null;
+}
+
+export interface PendingOpDeltaReader {
+  /** Read the current snapshot.  Safe to call every render. */
+  read(): PendingOpDeltaSnapshot;
+  /**
+   * Predicate: is a given runtime offset inside the range touched by the
+   * pending window?  Chrome uses this to decide whether a selection anchor
+   * is stable yet.
+   */
+  isOffsetPending(offset: number): boolean;
+}
+
+export interface CreatePendingOpDeltaReaderInput {
+  /**
+   * Reads the current pending-op deltas — typically
+   * `() => localEditSessionState.getPendingDeltas()` or the kernel's own
+   * `getPendingOpDeltas` accessor.  When absent, the reader returns an
+   * empty snapshot.
+   */
+  getDeltas?: () => readonly PendingOpDelta[];
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+const EMPTY_SNAPSHOT: PendingOpDeltaSnapshot = Object.freeze({
+  deltas: [],
+  hasPending: false,
+  pendingCount: 0,
+  netCharacterDelta: 0,
+  earliestTouchedOffset: null,
+  latestTouchedOffset: null,
+});
+
+export function createPendingOpDeltaReader(
+  input: CreatePendingOpDeltaReaderInput = {},
+): PendingOpDeltaReader {
+  const getDeltas = input.getDeltas;
+
+  function read(): PendingOpDeltaSnapshot {
+    if (!getDeltas) {
+      return EMPTY_SNAPSHOT;
+    }
+    const deltas = getDeltas();
+    if (deltas.length === 0) {
+      return EMPTY_SNAPSHOT;
+    }
+    return summarize(deltas);
+  }
+
+  return {
+    read,
+    isOffsetPending(offset) {
+      const snapshot = read();
+      if (!snapshot.hasPending) return false;
+      const earliest = snapshot.earliestTouchedOffset;
+      const latest = snapshot.latestTouchedOffset;
+      if (earliest === null || latest === null) return false;
+      return offset >= earliest && offset <= latest;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function summarize(
+  deltas: readonly PendingOpDelta[],
+): PendingOpDeltaSnapshot {
+  let net = 0;
+  let earliest = Number.POSITIVE_INFINITY;
+  let latest = Number.NEGATIVE_INFINITY;
+  for (const delta of deltas) {
+    net += delta.delta;
+    if (delta.fromRuntime < earliest) earliest = delta.fromRuntime;
+    if (delta.fromRuntime > latest) latest = delta.fromRuntime;
+  }
+  return {
+    deltas,
+    hasPending: true,
+    pendingCount: deltas.length,
+    netCharacterDelta: net,
+    earliestTouchedOffset: Number.isFinite(earliest) ? earliest : null,
+    latestTouchedOffset: Number.isFinite(latest) ? latest : null,
+  };
+}