@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/runtime/hyperlink-color-resolver.ts

@@ -0,0 +1,119 @@
+/**
+ * Lane 3 V7 — hyperlink color cascade.
+ *
+ * OOXML convention: runs inside `<w:hyperlink>` inherit the `Hyperlink`
+ * character style implicitly, EVEN WHEN source XML does not declare an
+ * explicit `<w:rStyle w:val="Hyperlink"/>` on each run. Word applies the
+ * style based on the containing hyperlink element's context alone.
+ *
+ * Our existing cascade (`resolveEffectiveRunFormatting`) only applies the
+ * character-style chain when `input.characterStyleId` is populated — so
+ * runs inside hyperlinks that lacked explicit rStyle were inheriting
+ * whatever the paragraph style said (usually black body text).
+ *
+ * This module closes that gap by resolving hyperlink color via a
+ * four-tier fallback chain:
+ *
+ *   1. Direct color on the run (`colorHex !== "auto"`) — wins outright.
+ *   2. Character-style cascade — forces Hyperlink style participation.
+ *   3. Theme hlink slot (`ResolvedTheme.colors.hlink`).
+ *   4. Hardcoded Word default `#0563C1`.
+ *
+ * The resolver also honors `colorThemeSlot` + `colorThemeTint`/`colorThemeShade`
+ * from L2.c by delegating to `resolveThemeColorHex`.
+ *
+ * Contract: the returned `CanonicalRunFormatting` is the effective cascade
+ * result with `colorHex` concretized to a non-theme hex (or `"auto"`). The
+ * original `colorThemeSlot` / `colorThemeTint` / `colorThemeShade` fields
+ * are preserved on the returned object so downstream code (or re-export
+ * via the canonical document) still sees the theme reference.
+ */
+
+import type {
+  CanonicalRunFormatting,
+  ResolvedTheme,
+  StylesCatalog,
+} from "../model/canonical-document.ts";
+import { resolveThemeColor } from "../io/ooxml/parse-theme.ts";
+import { resolveThemeColorHex } from "./theme-color-resolver.ts";
+import {
+  resolveEffectiveRunFormatting,
+  type RunResolveInput,
+} from "./paragraph-style-resolver.ts";
+
+export const HYPERLINK_CHARACTER_STYLE_ID = "Hyperlink";
+
+/**
+ * Microsoft Word's default hyperlink color (applied when neither the
+ * Hyperlink character style nor the theme's `hlink` slot supplies one).
+ * Matches Word 2013+ fresh-document rendering.
+ */
+export const DEFAULT_HYPERLINK_COLOR_HEX = "0563C1";
+
+/**
+ * Resolve effective run formatting for a hyperlink-inner run. Honors the
+ * Hyperlink character style implicitly, resolves any theme-slot color
+ * references, and applies the Word-default fallback when upstream data
+ * is absent.
+ *
+ * `input.characterStyleId` is respected when the caller already passed
+ * one (e.g., source XML had an explicit `<w:rStyle>` overriding the
+ * implicit Hyperlink). Only when it is absent does the resolver inject
+ * `"Hyperlink"` itself.
+ */
+export function resolveHyperlinkRunFormatting(
+  input: RunResolveInput,
+  catalog: StylesCatalog | undefined,
+  theme: ResolvedTheme | undefined,
+): CanonicalRunFormatting {
+  // V7a — auto-apply the Hyperlink character style when the caller did
+  // not supply one (runs inside <w:hyperlink> typically lack explicit
+  // rStyle; Word applies the style by context).
+  const augmentedInput: RunResolveInput =
+    input.characterStyleId === undefined
+      ? { ...input, characterStyleId: HYPERLINK_CHARACTER_STYLE_ID }
+      : input;
+
+  const cascade = resolveEffectiveRunFormatting(augmentedInput, catalog);
+
+  // V7b — concretize the color through the theme resolver + Word default.
+  const resolvedColor = resolveHyperlinkColorHex(cascade, theme);
+  if (resolvedColor && resolvedColor !== cascade.colorHex) {
+    return { ...cascade, colorHex: resolvedColor };
+  }
+  return cascade;
+}
+
+/**
+ * Four-tier hyperlink color fallback. Exported for targeted testing; use
+ * `resolveHyperlinkRunFormatting` as the primary entry point.
+ */
+export function resolveHyperlinkColorHex(
+  cascade: Pick<
+    CanonicalRunFormatting,
+    "colorHex" | "colorThemeSlot" | "colorThemeTint" | "colorThemeShade"
+  >,
+  theme: ResolvedTheme | undefined,
+): string | undefined {
+  // Tier 1 — direct non-auto hex wins.
+  if (cascade.colorHex && cascade.colorHex !== "auto") {
+    return cascade.colorHex;
+  }
+  // Tier 2 — theme-slot reference from the cascade (which now includes the
+  // Hyperlink style's rPr — typically `<w:color w:themeColor="hlink"/>`).
+  if (cascade.colorThemeSlot) {
+    const viaTheme = resolveThemeColorHex(cascade, theme);
+    if (viaTheme && viaTheme !== "auto") {
+      return viaTheme;
+    }
+  }
+  // Tier 3 — theme hlink slot even when the cascade never wrote a slot
+  // reference. This catches docs whose Hyperlink style lacks a color
+  // declaration entirely but whose theme defines hlink.
+  const themeHlink = resolveThemeColor(theme, "hlink");
+  if (themeHlink) {
+    return themeHlink;
+  }
+  // Tier 4 — Word's hardcoded default.
+  return DEFAULT_HYPERLINK_COLOR_HEX;
+}

package/src/runtime/layout/layout-engine-version.ts

@@ -55,5 +55,12 @@ export const LAYOUT_ENGINE_VERSION = 5 as const;
  *   1 — initial envelope shape: { schemaVersion, engineVersion,
  *       fontFingerprint, structuralHash, graph, surface }. Ships with
  *       L7 Phase 2.5 Plan A.
+ *   2 — L7 Phase 2.5 Plan B: adds `canonicalDocument` + `canonicalDocumentHash`
+ *       fields so the receiving client can skip the DOCX parse entirely on
+ *       cache hit. `canonicalDocumentHash` is also a 5th input to the cache
+ *       key so any state mutation (styles, metadata, comments, preservation)
+ *       correctly invalidates. v1 envelopes are rejected on load under v2 —
+ *       no corruption path exists because schemaVersion is the top-level
+ *       discriminator.
  */
-export const LAYCACHE_SCHEMA_VERSION = 1 as const;
+export const LAYCACHE_SCHEMA_VERSION = 2 as const;

package/src/runtime/prerender/cache-envelope.ts

@@ -1,13 +1,14 @@
 import type { EditorSurfaceSnapshot } from "../../api/public-types";
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
 import type { RuntimePageGraph } from "../layout/page-graph.ts";
 
 /**
- * L7 Phase 2.5 Task 2.5.3 — prerender cache envelope shape.
+ * L7 Phase 2.5 — prerender cache envelope shape.
  *
- * The envelope is the unit written to IndexedDB (Plan A) and — after Plan B
- * ships — to the `laycache` customXml editor-state namespace. Two consumers
- * must agree on this shape: the prerender pipeline that populates it, and
- * the warm-path loader that rehydrates it.
+ * The envelope is the unit written to IndexedDB (Plan A) and — under Plan B
+ * (schema v2) — to the `laycache` customXml editor-state namespace. Two
+ * consumers must agree on this shape: the prerender pipeline that populates
+ * it, and the warm-path loader that rehydrates it.
  *
  * Load-time invariants checked by consumers before trusting the envelope:
  *   - `schemaVersion === LAYCACHE_SCHEMA_VERSION`  — bump invalidates
@@ -15,15 +16,26 @@ import type { RuntimePageGraph } from "../layout/page-graph.ts";
  *   - `graph.revision === 0`                       — canonical marker
  *
  * The envelope MUST be structured-clone-safe because IndexedDB and Plan B's
- * customXml path both rely on structured-clone semantics. Keep fields as
- * JSON-serializable primitives, plain objects, or arrays — no class
+ * customXml path both rely on structured-clone / JSON semantics. Keep fields
+ * as JSON-serializable primitives, plain objects, or arrays — no class
  * instances, functions, or symbols.
+ *
+ * Plan B additions (schema v2):
+ *   - `canonicalDocument` — the full parsed model, so the warm-path loader
+ *     can skip `parseMainDocumentXml` + `createImportedCanonicalDocument` +
+ *     `buildCompatibilityReport` + `createImportedSnapshot` on cache hit.
+ *     Saves ~584 ms of the 976 ms cold-upload on `extra-large` CCEP.
+ *   - `canonicalDocumentHash` — sha256 of sorted-keys JSON. Also the 5th
+ *     input to `deriveCacheKey`, so style/metadata/comment/preservation
+ *     mutations correctly invalidate the cache.
  */
 export interface CacheEnvelope {
   readonly schemaVersion: number;
   readonly engineVersion: number;
   readonly fontFingerprint: string;
   readonly structuralHash: string;
+  readonly canonicalDocumentHash: string;
   readonly graph: RuntimePageGraph;
   readonly surface: EditorSurfaceSnapshot;
+  readonly canonicalDocument: CanonicalDocument;
 }

package/src/runtime/prerender/cache-key.ts

@@ -1,22 +1,31 @@
 /**
- * L7 Phase 2.5 Task 2.5.1 — prerender cache-key derivation.
+ * L7 Phase 2.5 — prerender cache-key derivation.
  *
  * The cache key is the composite identity the IndexedDB (Plan A) and
  * customXml (Plan B) backends index on. It has five inputs:
  *
- *   1. structuralHash(blocks)  — sha256 of the ordered kind:blockId list.
- *                                Stable across text-only edits; changes on
- *                                insert/delete/reorder because blockIds are
- *                                kind-counter pairs (paragraph-5 stays 5
- *                                under typing, shifts to paragraph-6 after
- *                                an insert).
- *   2. fontFingerprint         — identifies the measurement-backend + font-
- *                                metric source. "empirical-backend" in Plan A;
- *                                a real font-derived string after Phase 8.
- *   3. engineVersion           — LAYOUT_ENGINE_VERSION from src/runtime/
- *                                layout/layout-engine-version.ts. Bumped by
- *                                CI gate on any layout/render shape change.
- *   4. schemaVersion           — LAYCACHE_SCHEMA_VERSION for envelope format.
+ *   1. structuralHash(blocks)    — sha256 of the ordered kind:blockId list.
+ *                                  Stable across text-only edits; changes on
+ *                                  insert/delete/reorder because blockIds are
+ *                                  kind-counter pairs (paragraph-5 stays 5
+ *                                  under typing, shifts to paragraph-6 after
+ *                                  an insert).
+ *   2. fontFingerprint           — identifies the measurement-backend + font-
+ *                                  metric source. "empirical-backend" in
+ *                                  Plan A; a real font-derived string after
+ *                                  Phase 8.
+ *   3. engineVersion             — LAYOUT_ENGINE_VERSION from src/runtime/
+ *                                  layout/layout-engine-version.ts. Bumped by
+ *                                  CI gate on any layout/render shape change.
+ *   4. schemaVersion             — LAYCACHE_SCHEMA_VERSION for envelope
+ *                                  format.
+ *   5. canonicalDocumentHash     — (Plan B, schema v2) sha256 of sorted-keys
+ *                                  JSON of the CanonicalDocument. Catches
+ *                                  non-structural mutations (styles,
+ *                                  metadata, comments, preservation) that
+ *                                  `structuralHash` alone misses. Computed
+ *                                  via `computeCanonicalDocumentHash()` from
+ *                                  `./canonical-document-hash.ts`.
  *
  * Returns a 64-char lower-case hex digest. Uses the Web Crypto API
  * (globalThis.crypto.subtle), available in Node 18+ and all target browsers —
@@ -33,6 +42,7 @@ export interface CacheKeyInputs {
   readonly fontFingerprint: string;
   readonly engineVersion: string | number;
   readonly schemaVersion: number;
+  readonly canonicalDocumentHash: string;
 }
 
 const BLOCK_SEPARATOR = "\u0000";
@@ -61,6 +71,7 @@ export async function deriveCacheKey(inputs: CacheKeyInputs): Promise<string> {
     inputs.fontFingerprint,
     String(inputs.engineVersion),
     String(inputs.schemaVersion),
+    inputs.canonicalDocumentHash,
   ].join(FIELD_SEPARATOR);
   return sha256Hex(composite);
 }

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

@@ -0,0 +1,63 @@
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import { stableStringify } from "../../model/cds-1.0.0.ts";
+
+/**
+ * L7 Phase 2.5 Plan B — deterministic hash of a CanonicalDocument.
+ *
+ * Used as the fifth input to `deriveCacheKey` so non-structural mutations
+ * (style edits, metadata changes, comment/revision edits, preservation
+ * fragment updates) correctly invalidate the cache. `structuralHash`
+ * alone — which keys on the block-id list — misses these because the
+ * block structure is unchanged by such mutations.
+ *
+ * Determinism: uses `stableStringify` from `cds-1.0.0.ts` (the same
+ * ordering the canonical-document model already uses for equality
+ * comparison), so two runs on structurally-identical documents produce
+ * byte-identical JSON → byte-identical SHA-256. Cross-process / cross-
+ * machine agreement holds as long as the CanonicalDocument shape matches.
+ *
+ * **Session-birth metadata is excluded from the hash** — `createdAt` and
+ * `updatedAt` are set to `new Date().toISOString()` at session load (see
+ * `docx-session.ts`), and `docId` derives from a runtime-allocated UUID
+ * when the host does not pin one. These fields are not document identity
+ * for cache-validity purposes: a save-and-reload should hit the cache if
+ * the document content is unchanged, even though `updatedAt` shifted.
+ *
+ * Cost budget: <50 ms on `extra-large` CCEP (~250 KB canonical). Dominated
+ * by `JSON.stringify` + Web Crypto SHA-256; the key-sort pass inside
+ * `stableStringify` is a single depth-first walk.
+ */
+
+const textEncoder = new TextEncoder();
+const NORMALIZED_SENTINEL = "__hash_normalized__";
+
+async function sha256Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", textEncoder.encode(input));
+  const bytes = new Uint8Array(digest);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i]!.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+/**
+ * Produces a copy of `doc` with session-birth metadata replaced by fixed
+ * sentinel values. Keeps the hash stable across two sequential
+ * `prerenderDocument` calls on identical bytes (both calls set
+ * `createdAt`/`updatedAt` from `Date.now()` so would otherwise diverge).
+ */
+function normalizeForHashing(doc: CanonicalDocument): CanonicalDocument {
+  return {
+    ...doc,
+    docId: NORMALIZED_SENTINEL as CanonicalDocument["docId"],
+    createdAt: NORMALIZED_SENTINEL as CanonicalDocument["createdAt"],
+    updatedAt: NORMALIZED_SENTINEL as CanonicalDocument["updatedAt"],
+  };
+}
+
+export async function computeCanonicalDocumentHash(
+  doc: CanonicalDocument,
+): Promise<string> {
+  return sha256Hex(stableStringify(normalizeForHashing(doc)));
+}

package/src/runtime/prerender/customxml-cache.ts

@@ -0,0 +1,211 @@
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import type { OpcPackagePart } from "../../io/ooxml/part-manifest.ts";
+import {
+  WORKFLOW_PAYLOAD_PART_PATH,
+  buildEditorStateXml,
+  parseEditorStateXml,
+  parseWorkflowPayloadEnvelopeFromPackage,
+  type EditorStatePayload,
+} from "../../io/ooxml/workflow-payload.ts";
+import {
+  LAYCACHE_SCHEMA_VERSION,
+  LAYOUT_ENGINE_VERSION,
+} from "../layout/layout-engine-version.ts";
+import type { CacheEnvelope } from "./cache-envelope.ts";
+
+/**
+ * L7 Phase 2.5 Plan B B.4 — customXml read/write for the prerender cache.
+ *
+ * Persists the cache envelope inside the docx's workflow-payload part
+ * (`/customXml/item1.xml`) under the "laycache" namespace, so the cache
+ * travels with the file and hands a warm-start experience to any client
+ * that opens the same bytes.
+ *
+ * **Routing decision:** laycache does NOT extend `EditorStateNamespace`.
+ * The entry round-trips through the existing `unknownNamespaces`
+ * preservation path, which already provides:
+ *   - Automatic Word round-trip (Word doesn't touch customXml parts).
+ *   - Automatic runtime save-path preservation (the save path appends
+ *     `channel.getUnknownEntries()` verbatim).
+ *   - Separation of cache concerns from runtime subsystem state (laycache
+ *     is not conflated with hostAnnotations/workflowOverlay/etc.).
+ *
+ * Tradeoff: the write path hand-builds a `<bw:namespace name="laycache">`
+ * XML fragment rather than leveraging `buildEditorStateXml`'s entry
+ * serializer. Six lines of escaped string concatenation in exchange for
+ * the above.
+ *
+ * **Scope (MVP):** Write-side requires the docx to already have a
+ * workflow-payload part (`/customXml/item1.xml`). Docs without it return
+ * `{ written: false, reason: "no-customxml-part" }` so the caller can
+ * fall back to IndexedDB-only caching. Fresh/minimal docs that lack a
+ * payload part are already fast-opening; Plan B is targeted at CCEP-scale
+ * templates which reliably carry the part.
+ */
+
+export const LAYCACHE_NAMESPACE_NAME = "laycache" as const;
+const LAYCACHE_ENTRY_SCHEMA_VERSION = `laycache/${LAYCACHE_SCHEMA_VERSION}`;
+
+export type WriteEnvelopeResult =
+  | { written: true }
+  | { written: false; reason: "no-customxml-part" };
+
+/**
+ * Writes (or replaces) the laycache envelope inside the OPC package's
+ * workflow-payload part. Mutates `opcPackage.parts` in place.
+ *
+ * Preserves all other namespaces (`hostAnnotations`, `workflowOverlay`,
+ * etc.) verbatim. Returns `{ written: false, reason: "no-customxml-part" }`
+ * when the package has no workflow-payload part — caller falls back to
+ * IndexedDB caching in that case.
+ */
+export function writeEnvelopeToOpcPackage(
+  opcPackage: OpcPackage,
+  envelope: CacheEnvelope,
+): WriteEnvelopeResult {
+  const existingPart = opcPackage.parts.get(WORKFLOW_PAYLOAD_PART_PATH);
+  if (!existingPart) {
+    return { written: false, reason: "no-customxml-part" };
+  }
+
+  const existingXml = new TextDecoder().decode(existingPart.bytes);
+  const existingEditorState: EditorStatePayload = parseEditorStateXml(existingXml) ?? {
+    entries: [],
+  };
+
+  // Remove any previous laycache entry; keep every other unknown namespace.
+  const preservedUnknowns = (existingEditorState.unknownNamespaces ?? []).filter(
+    (ns) => ns.name !== LAYCACHE_NAMESPACE_NAME,
+  );
+
+  const laycacheRawXml = buildLaycacheNamespaceXml(envelope);
+
+  const nextEditorState: EditorStatePayload = {
+    entries: existingEditorState.entries,
+    unknownNamespaces: [
+      ...preservedUnknowns,
+      { name: LAYCACHE_NAMESPACE_NAME, rawXml: laycacheRawXml },
+    ],
+  };
+
+  const newEditorStateBlock = buildEditorStateXml(nextEditorState);
+  const newXml = spliceEditorStateIntoPayloadXml(existingXml, newEditorStateBlock);
+  const newBytes = new TextEncoder().encode(newXml);
+
+  // Note: crc32 is left at the previous value. `writeOpcPackage` recomputes
+  // the CRC from uncompressedBytes at zip time (`package-writer.ts:156`), so
+  // the field is effectively documentation from the reader — not consumed by
+  // the writer.
+  const nextPart: OpcPackagePart = {
+    ...existingPart,
+    bytes: newBytes,
+  };
+  opcPackage.parts.set(WORKFLOW_PAYLOAD_PART_PATH, nextPart);
+  return { written: true };
+}
+
+/**
+ * Reads and validates the laycache envelope from an already-parsed OPC
+ * package. Returns `null` on any validation failure:
+ *   - customXml part missing
+ *   - no laycache entry in `unknownNamespaces`
+ *   - JSON parse failure
+ *   - envelope.schemaVersion mismatch (LAYCACHE_SCHEMA_VERSION)
+ *   - envelope.engineVersion mismatch (LAYOUT_ENGINE_VERSION)
+ *   - required fields missing
+ */
+export function readEnvelopeFromOpcPackage(opcPackage: OpcPackage): CacheEnvelope | null {
+  const envelope = parseWorkflowPayloadEnvelopeFromPackage(opcPackage);
+  if (!envelope?.editorState) return null;
+
+  const laycacheUnknown = (envelope.editorState.unknownNamespaces ?? []).find(
+    (ns) => ns.name === LAYCACHE_NAMESPACE_NAME,
+  );
+  if (!laycacheUnknown) return null;
+
+  const inlineJson = extractInlineCdata(laycacheUnknown.rawXml);
+  if (inlineJson === null) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(inlineJson);
+  } catch {
+    return null;
+  }
+
+  if (!isValidCacheEnvelope(parsed)) return null;
+  return parsed;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildLaycacheNamespaceXml(envelope: CacheEnvelope): string {
+  const json = JSON.stringify(envelope).replace(/\]\]>/g, "]]]]><![CDATA[>");
+  return (
+    `<bw:namespace name="${LAYCACHE_NAMESPACE_NAME}" schemaVersion="${LAYCACHE_ENTRY_SCHEMA_VERSION}">` +
+    `<bw:inline><![CDATA[${json}]]></bw:inline>` +
+    `</bw:namespace>`
+  );
+}
+
+/**
+ * Replaces (or inserts) the `<bw:editorState>` block inside an existing
+ * workflow-payload XML. Handles three cases:
+ *   1. Block already present — regex-replace in-place.
+ *   2. Block absent, `<bw:workflowPayload>…</bw:workflowPayload>` present —
+ *      insert before `</bw:workflowPayload>` and upgrade the `version`
+ *      attribute on the opening tag to "1.2".
+ *   3. Neither — leave input unchanged (defensive; parseEditorStateXml
+ *      returned undefined, and if the outer structure is also absent we
+ *      cannot safely synthesize one).
+ *
+ * Note: the outer element is `<bw:workflowPayload version="...">` (per
+ * `buildPayloadXml` at workflow-payload.ts:526), not `<bw:root>`. The
+ * `version` attribute drives the schema-version gate (1.0 / 1.1 / 1.2).
+ */
+function spliceEditorStateIntoPayloadXml(xml: string, editorStateBlock: string): string {
+  const existingBlockRe = /<bw:editorState\b[^>]*>[\s\S]*?<\/bw:editorState>/u;
+  if (existingBlockRe.test(xml)) {
+    return xml.replace(existingBlockRe, editorStateBlock);
+  }
+
+  const rootCloseRe = /<\/bw:workflowPayload>/u;
+  if (rootCloseRe.test(xml)) {
+    const upgraded = xml.replace(
+      /(<bw:workflowPayload\b[^>]*?\bversion=")([^"]*)(")/u,
+      (_m, prefix: string, _v: string, suffix: string) => `${prefix}1.2${suffix}`,
+    );
+    return upgraded.replace(rootCloseRe, `${editorStateBlock}\n</bw:workflowPayload>`);
+  }
+
+  return xml;
+}
+
+function extractInlineCdata(rawXml: string): string | null {
+  const m = rawXml.match(/<bw:inline\b[^>]*>([\s\S]*?)<\/bw:inline>/u);
+  if (!m) return null;
+  const inner = m[1] ?? "";
+  const cdata = inner.replace(/<!\[CDATA\[|\]\]>/g, "").trim();
+  return cdata.length > 0 ? cdata : null;
+}
+
+function isValidCacheEnvelope(value: unknown): value is CacheEnvelope {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.schemaVersion === LAYCACHE_SCHEMA_VERSION &&
+    v.engineVersion === LAYOUT_ENGINE_VERSION &&
+    typeof v.fontFingerprint === "string" &&
+    typeof v.structuralHash === "string" &&
+    typeof v.canonicalDocumentHash === "string" &&
+    typeof v.graph === "object" &&
+    v.graph !== null &&
+    typeof v.surface === "object" &&
+    v.surface !== null &&
+    typeof v.canonicalDocument === "object" &&
+    v.canonicalDocument !== null
+  );
+}
+

package/src/runtime/prerender/customxml-probe.ts

@@ -0,0 +1,78 @@
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import { readOpcPackage } from "../../io/opc/package-reader.ts";
+import { parseBlockStructure } from "../../io/ooxml/parse-block-structure.ts";
+import type { CacheEnvelope } from "./cache-envelope.ts";
+import { computeStructuralHash } from "./cache-key.ts";
+import { readEnvelopeFromOpcPackage } from "./customxml-cache.ts";
+
+/**
+ * L7 Phase 2.5 Plan B B.6 — customXml probe (read-side pre-parse).
+ *
+ * Opens a docx's OPC package just enough to extract the laycache envelope
+ * from `/customXml/item1.xml` without parsing `word/document.xml` or
+ * running the canonical-document builder. Consumers use the returned
+ * envelope to decide whether to take the fast seeding path or fall
+ * through to `loadDocxEditorSessionAsync`'s full pipeline.
+ *
+ * Cost budget: ~20-50 ms on extra-large (OPC unzip 17 ms + XML regex
+ * extract + JSON parse + schema validation). Well below the ~584 ms of
+ * parse + skeleton-ready work that a successful probe skips.
+ *
+ * Null is returned for every rejection path:
+ *   - OPC parse failure (malformed zip, missing Content_Types)
+ *   - no workflow-payload part (`/customXml/item1.xml`)
+ *   - no laycache entry inside the editor-state payload
+ *   - corrupted inline JSON
+ *   - envelope.schemaVersion or engineVersion mismatch
+ *   - missing/mis-typed required envelope fields
+ *
+ * The returned `opcPackage` is included so callers can hand it to
+ * downstream code that would otherwise re-parse the ZIP from bytes
+ * (saving the ~17 ms OPC unzip on the cache-hit path).
+ *
+ * **B.7 structural verification.** When the probe accepts an envelope,
+ * it additionally runs `parseBlockStructure` against the package's
+ * `word/document.xml` and compares the resulting `structuralHash`
+ * against `envelope.structuralHash`. A mismatch means the docx has
+ * been edited since the envelope was written — e.g. Word added a
+ * paragraph and saved — and the probe returns null to force the full
+ * parse path. See `src/io/ooxml/parse-block-structure.ts` for the
+ * probe's known limitations (opaque-promoting OOXML features cannot
+ * be detected shallow-parse; those docs safely fall through).
+ */
+export interface LaycacheProbeResult {
+  readonly envelope: CacheEnvelope;
+  readonly opcPackage: OpcPackage;
+}
+
+export async function tryReadLaycacheEnvelope(
+  input: ArrayBuffer | Uint8Array,
+): Promise<LaycacheProbeResult | null> {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+
+  let opcPackage: OpcPackage;
+  try {
+    opcPackage = readOpcPackage(bytes);
+  } catch {
+    return null;
+  }
+
+  const envelope = readEnvelopeFromOpcPackage(opcPackage);
+  if (!envelope) return null;
+
+  // B.7 — shallow structural probe. Reject envelopes whose cached
+  // structuralHash does not match a fresh shallow-parse of the current
+  // document.xml. Catches the "user edited the docx in Word between
+  // prerender and reopen" path. The probe is conservative: it cannot
+  // detect opaque-promoting OOXML features (content controls, floating
+  // drawings, AlternateContent), so some clean-looking structural
+  // identity docs may still be rejected — a safe false negative.
+  const documentXmlPart = opcPackage.parts.get("/word/document.xml");
+  if (!documentXmlPart) return null;
+  const documentXml = new TextDecoder().decode(documentXmlPart.bytes);
+  const probedBlocks = parseBlockStructure(documentXml);
+  const probedHash = await computeStructuralHash(probedBlocks);
+  if (probedHash !== envelope.structuralHash) return null;
+
+  return { envelope, opcPackage };
+}