@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/runtime/prerender/prerender-document.ts

@@ -2,6 +2,8 @@ import type { EditorSurfaceSnapshot } from "../../api/public-types";
 import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
 import { loadDocxEditorSessionAsync } from "../../io/docx-session.ts";
 import { createLoadScheduler } from "../../io/load-scheduler.ts";
+import { readOpcPackage } from "../../io/opc/package-reader.ts";
+import { writeOpcPackage } from "../../io/opc/package-writer.ts";
 import {
   LAYCACHE_SCHEMA_VERSION,
   LAYOUT_ENGINE_VERSION,
@@ -14,6 +16,8 @@ import {
   deriveCacheKey,
   type CacheKeyBlock,
 } from "./cache-key.ts";
+import { computeCanonicalDocumentHash } from "./canonical-document-hash.ts";
+import { writeEnvelopeToOpcPackage } from "./customxml-cache.ts";
 import { resolveFontFingerprint } from "./font-fingerprint.ts";
 import { canonicalizeGraph } from "./graph-canonicalize.ts";
 
@@ -46,11 +50,18 @@ import { canonicalizeGraph } from "./graph-canonicalize.ts";
 export interface PrerenderOptions {
   readonly fontFingerprint?: string;
   /**
-   * Plan B hook — when true, prerenderDocument will inject the cache
-   * envelope into the document's `laycache` customXml namespace and
-   * return the re-serialized bytes in `docWithCustomXml`. In Plan A
-   * (this task) the flag is accepted for API stability but ignored;
-   * `docWithCustomXml` returns the input unchanged.
+   * Plan B — when true, prerenderDocument injects the cache envelope into
+   * the document's workflow-payload customXml part under a `laycache`
+   * unknown-namespace entry, and returns the re-serialized bytes in
+   * `docWithCustomXml`. Default: `false`, in which case `docWithCustomXml`
+   * equals the input bytes.
+   *
+   * Scope caveat: requires the input docx to already have a
+   * `/customXml/item1.xml` part. If the part is absent, the flag is a
+   * no-op (documented via `counters.persistedToCustomXml`) and the caller
+   * falls back to IndexedDB-only caching. Fresh/minimal docs that lack
+   * the part are already fast-opening; Plan B targets CCEP-scale
+   * templates which reliably carry the part.
    */
   readonly persistToCustomXml?: boolean;
 }
@@ -59,6 +70,13 @@ export interface PrerenderCounters {
   readonly blockCount: number;
   readonly pageCount: number;
   readonly prerenderMs: number;
+  /**
+   * Plan B signal: `true` when `persistToCustomXml` was requested AND the
+   * docx had an existing workflow-payload part to mutate. `false` when
+   * the flag was off OR the docx had no such part (caller should fall
+   * back to IndexedDB caching).
+   */
+  readonly persistedToCustomXml: boolean;
 }
 
 export interface PrerenderResult {
@@ -70,6 +88,15 @@ export interface PrerenderResult {
 
 const PRERENDER_DOCUMENT_ID = "prerender";
 
+/**
+ * Fixed ISO8601 timestamp used to override session-birth `createdAt` /
+ * `updatedAt` on the prerendered envelope. Epoch zero — a valid ISO8601
+ * value that downstream validators accept — replacing `Date.now()`-driven
+ * values that would otherwise defeat byte-identical `docWithCustomXml`
+ * output across two prerender calls on identical bytes.
+ */
+const PRERENDER_NORMALIZED_TIMESTAMP = "1970-01-01T00:00:00.000Z";
+
 function toUint8Array(input: ArrayBuffer | Uint8Array): Uint8Array {
   if (input instanceof Uint8Array) return input;
   return new Uint8Array(input);
@@ -106,7 +133,20 @@ export async function prerenderDocument(
     );
   }
 
-  const envelope = session.initialSessionState.canonicalDocument;
+  // Normalize session-birth timestamps. `loadDocxEditorSessionAsync` sets
+  // `createdAt`/`updatedAt` from `new Date().toISOString()`; without this
+  // override, two sequential prerender calls on identical bytes would
+  // produce different envelopes → different customXml bytes → determinism
+  // failure on the B.5 byte-identical gate.  Using the epoch keeps the
+  // value a valid ISO8601 string (downstream validators accept it) while
+  // eliminating the only remaining source of non-determinism.  The live
+  // session's updatedAt is re-populated by runtime mutations anyway, so
+  // the normalized value is irrelevant at runtime.
+  const envelope: typeof session.initialSessionState.canonicalDocument = {
+    ...session.initialSessionState.canonicalDocument,
+    createdAt: PRERENDER_NORMALIZED_TIMESTAMP,
+    updatedAt: PRERENDER_NORMALIZED_TIMESTAMP,
+  };
   const surface = createEditorSurfaceSnapshot(envelope, createSelectionSnapshot(), { kind: "main" });
 
   const engine = createLayoutEngine({ autoUpgradeToCanvasBackend: false });
@@ -114,11 +154,17 @@ export async function prerenderDocument(
   const graph = canonicalizeGraph(rawGraph);
 
   const structuralHash = await computeStructuralHash(blocksToCacheKeyBlocks(surface));
+  // L7 Phase 2.5 Plan B B.2 — sha256 of stable-stringified canonical document.
+  // Enters the cache key as the 5th input so style / metadata / comments /
+  // preservation mutations correctly invalidate (structuralHash alone misses
+  // them because the block-id list is unchanged).
+  const canonicalDocumentHash = await computeCanonicalDocumentHash(envelope);
   const cacheKey = await deriveCacheKey({
     blocks: blocksToCacheKeyBlocks(surface),
     fontFingerprint,
     engineVersion: LAYOUT_ENGINE_VERSION,
     schemaVersion: LAYCACHE_SCHEMA_VERSION,
+    canonicalDocumentHash,
   });
 
   const cacheBlob: CacheEnvelope = {
@@ -126,20 +172,41 @@ export async function prerenderDocument(
     engineVersion: LAYOUT_ENGINE_VERSION,
     fontFingerprint,
     structuralHash,
+    canonicalDocumentHash,
     graph,
     surface,
+    canonicalDocument: envelope,
   };
 
+  // Plan B B.5 — persistToCustomXml: inject the envelope into the docx's
+  // workflow-payload part. Re-parses the OPC package from bytes (~17 ms on
+  // extra-large) because `LoadedDocxEditorSession` does not expose
+  // `sourcePackage` publicly. Acceptable cost on the one-shot ingest path.
+  let docWithCustomXml = bytes;
+  let persistedToCustomXml = false;
+  if (options.persistToCustomXml === true) {
+    const opcPackage = readOpcPackage(bytes);
+    const writeResult = writeEnvelopeToOpcPackage(opcPackage, cacheBlob);
+    if (writeResult.written) {
+      docWithCustomXml = writeOpcPackage(opcPackage);
+      persistedToCustomXml = true;
+    }
+    // writeResult.written === false → docx had no customXml part; silently
+    // fall through with docWithCustomXml = input bytes. Caller observes via
+    // counters.persistedToCustomXml.
+  }
+
   const prerenderMs = performance.now() - t0;
 
   return {
-    docWithCustomXml: bytes,
+    docWithCustomXml,
     cacheBlob,
     cacheKey,
     counters: {
       blockCount: surface.blocks.length,
       pageCount: graph.pages.length,
       prerenderMs,
+      persistedToCustomXml,
     },
   };
 }

package/src/runtime/scope-resolver.ts

@@ -0,0 +1,148 @@
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+} from "../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import type { EditorAnchorProjection } from "../api/public-types.ts";
+
+export interface ResolvedScopeLocation {
+  scopeId: string;
+  startPos: number;
+  endPos: number;
+}
+
+function inlineLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
+}
+
+function walkParagraphs(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): { paragraph: ParagraphNode; from: number }[] {
+  const envelope = document as CanonicalDocumentEnvelope;
+  const root =
+    "content" in envelope
+      ? (envelope.content as DocumentRootNode)
+      : (document as unknown as DocumentRootNode);
+  const out: { paragraph: ParagraphNode; from: number }[] = [];
+  let cursor = 0;
+  for (let index = 0; index < root.children.length; index += 1) {
+    const block = root.children[index];
+    if (block && block.type === "paragraph") {
+      out.push({ paragraph: block, from: cursor });
+      cursor += block.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    } else if (block && block.type === "table") {
+      cursor += 1;
+    } else {
+      cursor += 1;
+    }
+    if (index < root.children.length - 1) {
+      cursor += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk all paragraphs in the document and return the absolute positions of the
+ * start and end markers for each scope that has either side present. Used by
+ * `resolveScope` + `findScopeAt`; exported so test code can inspect the
+ * marker-to-position mapping directly.
+ */
+export function collectScopeLocations(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): Map<string, { startPos?: number; endPos?: number }> {
+  const locations = new Map<string, { startPos?: number; endPos?: number }>();
+  const paragraphs = walkParagraphs(document);
+  for (const { paragraph, from } of paragraphs) {
+    let cursor = from;
+    for (const child of paragraph.children) {
+      if (child.type === "scope_marker_start") {
+        const prior = locations.get(child.scopeId) ?? {};
+        locations.set(child.scopeId, { ...prior, startPos: cursor });
+      } else if (child.type === "scope_marker_end") {
+        const prior = locations.get(child.scopeId) ?? {};
+        locations.set(child.scopeId, { ...prior, endPos: cursor });
+      }
+      cursor += inlineLength(child as InlineNode);
+    }
+  }
+  return locations;
+}
+
+/**
+ * Resolve a scopeId to a live public range anchor derived from the marker
+ * positions currently in the document. Returns:
+ *   - A range anchor when both markers are present
+ *   - A detached anchor when one or zero markers survive
+ *   - `null` when neither marker is in the document
+ */
+export function resolveScope(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  scopeId: string,
+): EditorAnchorProjection | null {
+  const locations = collectScopeLocations(document);
+  const loc = locations.get(scopeId);
+  if (!loc) return null;
+
+  if (loc.startPos !== undefined && loc.endPos !== undefined) {
+    const from = Math.min(loc.startPos, loc.endPos);
+    const to = Math.max(loc.startPos, loc.endPos);
+    return {
+      kind: "range",
+      from,
+      to,
+      assoc: { start: -1, end: 1 },
+    };
+  }
+
+  return {
+    kind: "detached",
+    reason: "deleted",
+    lastKnownRange: {
+      from: loc.startPos ?? loc.endPos ?? 0,
+      to: loc.endPos ?? loc.startPos ?? 0,
+    },
+  };
+}
+
+/**
+ * Given a position, return the innermost enclosing scope (by document order).
+ * Used by the chrome overlay hit-test and by the edit-dispatch guard that
+ * routes delete-through-marker to `removeScope`.
+ */
+export function findScopeAt(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  position: number,
+): { scopeId: string; startPos: number; endPos: number } | null {
+  const locations = collectScopeLocations(document);
+  let best: { scopeId: string; startPos: number; endPos: number } | null = null;
+  for (const [scopeId, loc] of locations) {
+    if (loc.startPos === undefined || loc.endPos === undefined) continue;
+    if (position < loc.startPos || position > loc.endPos) continue;
+    if (!best || loc.startPos > best.startPos) {
+      best = { scopeId, startPos: loc.startPos, endPos: loc.endPos };
+    }
+  }
+  return best;
+}

package/src/runtime/scope-tag-registry.ts

@@ -53,6 +53,16 @@ export const DEFAULT_REGISTRY_ENTRIES: Readonly<Record<string, ScopeTagBehavior>
     trimOnDelete: true,
     bailIfCrossed: false,
   },
+  // S1 scope-marker anchoring. `trimOnDelete: false` is the load-bearing
+  // difference vs. `bookmark` — a delete that crosses a scope marker routes
+  // through `removeScope` instead of silently trimming the marker, so
+  // half-scope states (orphaned metadata in customXml) never appear.
+  "workflow-scope-marker": {
+    extendOnInsertLeft: true,
+    extendOnInsertRight: true,
+    trimOnDelete: false,
+    bailIfCrossed: false,
+  },
   sdt: {
     extendOnInsertLeft: false,
     extendOnInsertRight: false,

package/src/runtime/surface-projection.ts

@@ -51,6 +51,7 @@ import {
   resolveEffectiveRunFormatting,
   resolveNumberingMarkerRunFormatting,
 } from "./paragraph-style-resolver.ts";
+import { resolveHyperlinkRunFormatting } from "./hyperlink-color-resolver.ts";
 import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 
 interface ParagraphAccumulator {
@@ -97,6 +98,17 @@ export function createEditorSurfaceSnapshot(
   };
 
   for (let index = 0; index < root.children.length; index += 1) {
+    const isInViewport =
+      viewportBlockRange === null ||
+      (index >= viewportBlockRange.start && index < viewportBlockRange.end);
+    // L7 Phase 2.9 — viewport bail on the style-cascade work. When the
+    // block is outside the viewport, the surface block produced below is
+    // immediately discarded in favor of a `placeholder-culled` entry (we
+    // only consume `nextCursor`). Pass `cullBuild: true` so the paragraph
+    // + inline walkers skip `resolveEffectiveParagraphFormatting`,
+    // `resolveNumberingMarkerRunFormatting`, and per-segment
+    // `resolveEffectiveRunFormatting` — the expensive style-catalog walks
+    // that dominate surface-projection cost on large docs.
     const surfaceBlock = createSurfaceBlock(
       root.children[index],
       document,
@@ -104,10 +116,8 @@ export function createEditorSurfaceSnapshot(
       counters,
       numberingPrefixResolver,
       activeStory.kind !== "main",
+      !isInViewport,
     );
-    const isInViewport =
-      viewportBlockRange === null ||
-      (index >= viewportBlockRange.start && index < viewportBlockRange.end);
 
     if (isInViewport) {
       blocks.push(surfaceBlock.block);
@@ -165,6 +175,7 @@ function createSurfaceBlock(
   },
   numberingPrefixResolver: NumberingPrefixResolver,
   promoteSecondaryStoryTextBoxes: boolean,
+  cullBuild: boolean = false,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   if (block.type === "opaque_block") {
     const fragment = getOpaqueFragment(document.preservation as never, block.fragmentId);
@@ -205,6 +216,7 @@ function createSurfaceBlock(
       counters,
       numberingPrefixResolver,
       promoteSecondaryStoryTextBoxes,
+      cullBuild,
     );
   }
 
@@ -244,6 +256,7 @@ function createSurfaceBlock(
       counters,
       numberingPrefixResolver,
       promoteSecondaryStoryTextBoxes,
+      cullBuild,
     );
   }
 
@@ -336,6 +349,7 @@ function createSurfaceBlock(
     cursor,
     numberingPrefixResolver,
     promoteSecondaryStoryTextBoxes,
+    cullBuild,
   );
 }
 
@@ -354,6 +368,7 @@ function createTableBlock(
   },
   numberingPrefixResolver: NumberingPrefixResolver,
   promoteSecondaryStoryTextBoxes: boolean,
+  cullBuild: boolean = false,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   const lockedFragmentIds: string[] = [];
   let innerCursor = cursor;
@@ -374,6 +389,7 @@ function createTableBlock(
           counters,
           numberingPrefixResolver,
           promoteSecondaryStoryTextBoxes,
+          cullBuild,
         );
         cellContent.push(result.block);
         lockedFragmentIds.push(...result.lockedFragmentIds);
@@ -518,6 +534,7 @@ function createSdtBlock(
   },
   numberingPrefixResolver: NumberingPrefixResolver,
   promoteSecondaryStoryTextBoxes: boolean,
+  cullBuild: boolean = false,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   const children: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
@@ -531,6 +548,7 @@ function createSdtBlock(
       counters,
       numberingPrefixResolver,
       promoteSecondaryStoryTextBoxes,
+      cullBuild,
     );
     children.push(result.block);
     lockedFragmentIds.push(...result.lockedFragmentIds);
@@ -566,34 +584,52 @@ function createParagraphBlock(
   start: number,
   numberingPrefixResolver: NumberingPrefixResolver,
   promoteSecondaryStoryTextBoxes: boolean,
+  cullBuild: boolean = false,
 ): {
   block: SurfaceBlockSnapshot;
   nextCursor: number;
   lockedFragmentIds: string[];
 } {
-  const effectiveNumbering = resolveEffectiveParagraphNumbering(document, paragraph);
-  const resolvedNumbering = effectiveNumbering
-    ? numberingPrefixResolver.resolveDetailed(effectiveNumbering, paragraph)
-    : null;
-
-  // Task 11: compute cascaded paragraph formatting
+  // L7 Phase 2.9 — viewport bail. When the paragraph is outside the
+  // viewport, the returned block is discarded (the outer caller in
+  // `createEditorSurfaceSnapshot` replaces it with a placeholder-culled
+  // entry and only consumes `nextCursor`). Skip the two style-catalog
+  // walks (`resolveEffectiveParagraphFormatting`,
+  // `resolveNumberingMarkerRunFormatting`) — their results are not read
+  // by the placeholder path. Segment-level work inside
+  // `appendInlineSegments` is suppressed symmetrically via the same
+  // `cullBuild` flag, preserving cursor arithmetic.
+  const effectiveNumbering = cullBuild
+    ? undefined
+    : resolveEffectiveParagraphNumbering(document, paragraph);
+  const resolvedNumbering =
+    !cullBuild && effectiveNumbering
+      ? numberingPrefixResolver.resolveDetailed(effectiveNumbering, paragraph)
+      : null;
+
+  // Task 11: compute cascaded paragraph formatting (expensive — styles-catalog walk).
   const stylesCatalog = document.styles;
-  const directParagraphFormatting = buildDirectParagraphFormattingFromNode(paragraph);
-  const resolvedParagraphFormatting = resolveEffectiveParagraphFormatting(
-    { styleId: paragraph.styleId, direct: directParagraphFormatting },
-    stylesCatalog,
-  );
-
-  // Task 11: compute cascaded marker run formatting
-  const markerRunProperties = effectiveNumbering
-    ? resolveNumberingMarkerRunFormatting(
-        {
-          paragraphStyleId: paragraph.styleId,
-          levelRunProperties: resolvedNumbering?.markerRunProperties,
-        },
+  const directParagraphFormatting = cullBuild
+    ? undefined
+    : buildDirectParagraphFormattingFromNode(paragraph);
+  const resolvedParagraphFormatting = cullBuild
+    ? undefined
+    : resolveEffectiveParagraphFormatting(
+        { styleId: paragraph.styleId, direct: directParagraphFormatting },
         stylesCatalog,
-      )
-    : undefined;
+      );
+
+  // Task 11: compute cascaded marker run formatting (expensive).
+  const markerRunProperties =
+    !cullBuild && effectiveNumbering
+      ? resolveNumberingMarkerRunFormatting(
+          {
+            paragraphStyleId: paragraph.styleId,
+            levelRunProperties: resolvedNumbering?.markerRunProperties,
+          },
+          stylesCatalog,
+        )
+      : undefined;
 
   const accumulator: ParagraphAccumulator = {
     blockId: `paragraph-${paragraphIndex}`,
@@ -650,6 +686,8 @@ function createParagraphBlock(
       document,
       cursor,
       promoteSecondaryStoryTextBoxes,
+      undefined,
+      cullBuild,
     );
     cursor = result.nextCursor;
     lockedFragmentIds.push(...result.lockedFragmentIds);
@@ -812,22 +850,39 @@ function appendInlineSegments(
   start: number,
   promoteSecondaryStoryTextBoxes: boolean,
   hyperlinkHref?: string,
+  cullBuild: boolean = false,
 ): { nextCursor: number; lockedFragmentIds: string[] } {
   switch (node.type) {
     case "text": {
       const cloned = node.marks ? cloneMarks(node.marks) : { marks: [] as SurfaceTextMark[] };
-      const directRunFormatting = buildDirectRunFormattingFromMarks(
-        cloned.marks.length > 0 ? cloned.marks : undefined,
-        cloned.markAttrs,
-      );
-      const resolvedRunFormatting = resolveEffectiveRunFormatting(
-        {
-          paragraphStyleId: paragraph.styleId,
-          characterStyleId: undefined,
-          direct: directRunFormatting,
-        },
-        document.styles,
-      );
+      // L7 Phase 2.9 — skip the styles-catalog run-cascade walk when
+      // the block will be culled. `resolveEffectiveRunFormatting`
+      // dominates per-text-segment cost on style-heavy docs; the
+      // placeholder path does not read `resolvedRunFormatting`.
+      const directRunFormatting = cullBuild
+        ? undefined
+        : buildDirectRunFormattingFromMarks(
+            cloned.marks.length > 0 ? cloned.marks : undefined,
+            cloned.markAttrs,
+          );
+      // V7 — runs inside <w:hyperlink> go through the hyperlink color
+      // cascade (auto-applies the Hyperlink character style + resolves
+      // theme hlink slot with Word-default fallback). Non-hyperlink
+      // runs take the unchanged cascade path.
+      const runResolveInput = {
+        paragraphStyleId: paragraph.styleId,
+        characterStyleId: undefined,
+        direct: directRunFormatting,
+      };
+      const resolvedRunFormatting = cullBuild
+        ? {}
+        : hyperlinkHref
+          ? resolveHyperlinkRunFormatting(
+              runResolveInput,
+              document.styles,
+              document.subParts?.resolvedTheme,
+            )
+          : resolveEffectiveRunFormatting(runResolveInput, document.styles);
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
         kind: "text",
@@ -869,6 +924,7 @@ function appendInlineSegments(
           cursor,
           promoteSecondaryStoryTextBoxes,
           node.href,
+          cullBuild,
         );
         cursor = result.nextCursor;
       }
@@ -1003,6 +1059,8 @@ function appendInlineSegments(
             document,
             cursor,
             promoteSecondaryStoryTextBoxes,
+            undefined,
+            cullBuild,
           );
           cursor = result.nextCursor;
           lockedIds.push(...result.lockedFragmentIds);
@@ -1047,7 +1105,11 @@ function appendInlineSegments(
     }
     case "bookmark_start":
     case "bookmark_end":
-      // Zero-width markers — no visual, no cursor advancement
+    case "scope_marker_start":
+    case "scope_marker_end":
+      // Zero-width markers — no visual, no cursor advancement. Scope markers
+      // (S1) follow the bookmark precedent: structural anchors whose positions
+      // track with surrounding text but which don't occupy cursor positions.
       return { nextCursor: start, lockedFragmentIds: [] };
     default:
       return { nextCursor: start + 1, lockedFragmentIds: [] };
@@ -1466,6 +1528,9 @@ function summarizePreviewInline(node: InlineNode): string {
       return node.name ? `[Bookmark: ${node.name}]` : "[Bookmark]";
     case "bookmark_end":
       return "";
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return "";
     case "image":
       return node.altText ? `[Image: ${node.altText}]` : "[Image]";
     case "opaque_inline":