@beyondwork/docx-react-component 1.0.128 → 1.0.130

package/dist/{chunk-YHZHPXDB.js → chunk-THVM6EP5.js}

@@ -2,11 +2,12 @@ import {
   buildRunFormattingMap,
   calculateParagraphHeight,
   createEmpiricalBackend,
+  createLayoutReadyFormattingSnapshot,
   resolveBlockFormatting,
   resolveCharsPerLine,
   resolveNumberingPrefixLength,
   resolveTextWidth
-} from "./chunk-KFCQYZXR.js";
+} from "./chunk-OVLZQ6FZ.js";
 import {
   parseTextStory
 } from "./chunk-QIO6V46H.js";
@@ -18,13 +19,13 @@ import {
   resolveSectionVariants,
   sectionSupportsStoryTarget,
   storyTargetKey
-} from "./chunk-CXSYRB37.js";
+} from "./chunk-A3GSNB4G.js";
 import {
   createSelectionSnapshot
 } from "./chunk-OYGMRRR7.js";
 import {
   collectCanonicalLayoutInputs
-} from "./chunk-5DGKFNQT.js";
+} from "./chunk-A66ZVUAT.js";
 import {
   MAIN_STORY_TARGET,
   createDetachedAnchor,
@@ -3692,6 +3693,14 @@ function paginateSectionBlocksWithSplits(section, blocks, layout, footnotes, mea
         pushPage(block.from);
         continue;
       }
+      if (isStandalonePageBreakParagraph(block)) {
+        if (columnHeight > 0) {
+          pushPage(nextBoundary);
+        } else {
+          pageStart = Math.max(pageStart, Math.min(nextBoundary, section.end));
+        }
+        break;
+      }
       const effectiveNoteHeight = estimateFootnoteReservation(
         block,
         footnotes,
@@ -3866,6 +3875,21 @@ function hasPageBreak(block) {
   }
   return nestedBlocks(block).some(hasPageBreak);
 }
+function isStandalonePageBreakParagraph(block) {
+  if (block.kind !== "paragraph") return false;
+  let sawPageBreak = false;
+  for (const segment of block.segments) {
+    if (segment.kind === "opaque_inline" && segment.label === "Page break") {
+      sawPageBreak = true;
+      continue;
+    }
+    if (segment.kind === "text" && segment.text.trim().length === 0) {
+      continue;
+    }
+    return false;
+  }
+  return sawPageBreak;
+}
 function nestedBlocks(block) {
   if (block.kind === "sdt_block") {
     return block.children;
@@ -5350,6 +5374,9 @@ function projectSurfaceBlocksToPageFragments(surface, pages, splits, columnByBlo
   for (let blockIndex = 0; blockIndex < surface.blocks.length; blockIndex += 1) {
     const block = surface.blocks[blockIndex];
     const blockPath = `main/block[${blockIndex}]`;
+    if (isStandalonePageBreakParagraph2(block)) {
+      continue;
+    }
     if (block.kind === "table") {
       const tableSliceList = splits?.tablesByBlockId.get(block.blockId);
       if (tableSliceList && tableSliceList.length > 1) {
@@ -5435,6 +5462,23 @@ function projectSurfaceBlocksToPageFragments(surface, pages, splits, columnByBlo
   }
   return byPage;
 }
+function isStandalonePageBreakParagraph2(block) {
+  if (block.kind !== "paragraph") {
+    return false;
+  }
+  let sawPageBreak = false;
+  for (const segment of block.segments) {
+    if (segment.kind === "opaque_inline" && segment.label === "Page break") {
+      sawPageBreak = true;
+      continue;
+    }
+    if (segment.kind === "text" && segment.text.trim().length === 0) {
+      continue;
+    }
+    return false;
+  }
+  return sawPageBreak;
+}
 function projectLineBoxesForPageFragments(pages, fragmentsByPageIndex, fragmentMeasurementsByPageIndex, surface) {
   const byPage = /* @__PURE__ */ new Map();
   const blocksById = surface ? new Map(surface.blocks.map((block) => [block.blockId, block])) : /* @__PURE__ */ new Map();
@@ -5947,13 +5991,11 @@ function buildBookmarkRanges(targets) {
 }
 var EMPTY_NUMBERING_INPUT_INDEX = {
   byNumberingKey: /* @__PURE__ */ new Map(),
-  byBlockPath: /* @__PURE__ */ new Map(),
-  byParagraphIndex: /* @__PURE__ */ new Map()
+  byBlockPath: /* @__PURE__ */ new Map()
 };
 function buildNumberingInputIndex(numberingInputs) {
   const byNumberingKey = /* @__PURE__ */ new Map();
   const byBlockPath = /* @__PURE__ */ new Map();
-  const byParagraph = /* @__PURE__ */ new Map();
   for (const input of numberingInputs) {
     if (!byNumberingKey.has(input.numberingKey)) {
       byNumberingKey.set(input.numberingKey, input);
@@ -5961,11 +6003,8 @@ function buildNumberingInputIndex(numberingInputs) {
     if (!byBlockPath.has(input.blockPath)) {
       byBlockPath.set(input.blockPath, input);
     }
-    if (!byParagraph.has(input.paragraphIndex)) {
-      byParagraph.set(input.paragraphIndex, input);
-    }
   }
-  return { byNumberingKey, byBlockPath, byParagraphIndex: byParagraph };
+  return { byNumberingKey, byBlockPath };
 }
 function collectBookmarkRangeLayoutFacts(fragmentId, blockPath, bookmarkRanges) {
   if (!blockPath || !bookmarkRanges || bookmarkRanges.length === 0) return [];
@@ -6085,8 +6124,7 @@ function collectNumberingLayoutFactsForBlock(block, blockPath, numberingIndex, n
     const canonical = lookupNumberingInput(
       numberingIndex,
       numberingKey,
-      context.path,
-      paragraphIndex
+      context.path
     );
     const target = findNumberingTarget(numberingTargets, context.path);
     const numberingLayoutId = numberingKey ?? [
@@ -6126,7 +6164,7 @@ function findNumberingTarget(numberingTargets, blockPath) {
   if (blockPath === void 0) return void 0;
   return numberingTargets.find((target) => target.blockPath === blockPath);
 }
-function lookupNumberingInput(numberingIndex, numberingKey, blockPath, paragraphIndex) {
+function lookupNumberingInput(numberingIndex, numberingKey, blockPath) {
   if (!numberingIndex) return void 0;
   if (numberingKey !== void 0) {
     const byKey = numberingIndex.byNumberingKey.get(numberingKey);
@@ -6136,7 +6174,7 @@ function lookupNumberingInput(numberingIndex, numberingKey, blockPath, paragraph
     const byPath = numberingIndex.byBlockPath.get(blockPath);
     if (byPath !== void 0) return byPath;
   }
-  return paragraphIndex !== void 0 ? numberingIndex.byParagraphIndex.get(paragraphIndex) : void 0;
+  return void 0;
 }
 function collectNumberingUnavailableReasons(numbering, canonical) {
   const reasons = [];
@@ -6545,20 +6583,337 @@ function createEmpiricalProvider() {
 }
 async function createCanvasProvider(fontLoader) {
   try {
-    const mod = await import("./measurement-backend-canvas-Q3MJMEYX.js");
+    const mod = await import("./measurement-backend-canvas-F7ZYDACK.js");
     return mod.createCanvasBackend(fontLoader);
   } catch {
     return createEmpiricalProvider();
   }
 }
 
+// src/runtime/layout/persistent-layout-measurement-cache.ts
+var DEFAULT_MAX_ENTRIES = 1e4;
+var DEFAULT_MAX_ESTIMATED_BYTES = 50 * 1024 * 1024;
+function createPersistentLayoutMeasurementCache(options = {}) {
+  const maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+  const maxEstimatedBytes = Math.max(
+    1024,
+    options.maxEstimatedBytes ?? DEFAULT_MAX_ESTIMATED_BYTES
+  );
+  const entries = /* @__PURE__ */ new Map();
+  const counters = {
+    hits: 0,
+    misses: 0,
+    sets: 0,
+    evictions: 0,
+    clears: 0,
+    estimatedBytes: 0,
+    invalidatedByReason: {}
+  };
+  function evictOldest() {
+    const oldest = entries.keys().next();
+    if (oldest.done) return;
+    const entry = entries.get(oldest.value);
+    if (entry) {
+      counters.estimatedBytes -= entry.estimatedBytes;
+    }
+    entries.delete(oldest.value);
+    counters.evictions += 1;
+  }
+  return {
+    get(key) {
+      const cacheKey = serializeCacheKey(key);
+      const entry = entries.get(cacheKey);
+      if (!entry) {
+        counters.misses += 1;
+        return void 0;
+      }
+      entries.delete(cacheKey);
+      entries.set(cacheKey, entry);
+      counters.hits += 1;
+      return entry.value;
+    },
+    set(key, value) {
+      const cacheKey = serializeCacheKey(key);
+      const previous = entries.get(cacheKey);
+      if (previous) {
+        counters.estimatedBytes -= previous.estimatedBytes;
+        entries.delete(cacheKey);
+      }
+      const estimatedBytes = estimateBytes(key, value);
+      entries.set(cacheKey, { key, value, estimatedBytes });
+      counters.estimatedBytes += estimatedBytes;
+      counters.sets += 1;
+      while (entries.size > maxEntries || counters.estimatedBytes > maxEstimatedBytes) {
+        evictOldest();
+      }
+    },
+    invalidate(reason, predicate) {
+      if (!predicate) {
+        const removed2 = entries.size;
+        counters.estimatedBytes = 0;
+        entries.clear();
+        counters.invalidatedByReason[reason] = (counters.invalidatedByReason[reason] ?? 0) + removed2;
+        return;
+      }
+      let removed = 0;
+      for (const [cacheKey, entry] of entries) {
+        if (!predicate(entry.key)) continue;
+        counters.estimatedBytes -= entry.estimatedBytes;
+        entries.delete(cacheKey);
+        removed += 1;
+      }
+      counters.invalidatedByReason[reason] = (counters.invalidatedByReason[reason] ?? 0) + removed;
+    },
+    clear(reason) {
+      const removed = entries.size;
+      counters.estimatedBytes = 0;
+      entries.clear();
+      counters.clears += 1;
+      counters.invalidatedByReason[reason] = (counters.invalidatedByReason[reason] ?? 0) + removed;
+    },
+    stats() {
+      return {
+        hits: counters.hits,
+        misses: counters.misses,
+        sets: counters.sets,
+        evictions: counters.evictions,
+        clears: counters.clears,
+        size: entries.size,
+        estimatedBytes: Math.max(0, counters.estimatedBytes),
+        invalidatedByReason: { ...counters.invalidatedByReason }
+      };
+    }
+  };
+}
+function createCachedLayoutMeasurementProvider(delegate, options = {}) {
+  const cache = options.cache ?? createPersistentLayoutMeasurementCache(options);
+  function emitCounter(type, key) {
+    const telemetryBus = options.telemetryBus;
+    if (!telemetryBus?.isEnabled("layout")) return;
+    telemetryBus.emitLazy("layout", () => ({
+      type,
+      payload: key ? {
+        measurementKind: key.measurementKind,
+        blockId: key.blockId,
+        backendVersion: key.backendVersion
+      } : void 0
+    }));
+  }
+  return {
+    get fidelity() {
+      return delegate.fidelity;
+    },
+    measurementCache: cache,
+    measurementCacheStats() {
+      return cache.stats();
+    },
+    whenReady() {
+      return delegate.whenReady();
+    },
+    measureLineFragments(input) {
+      const key = buildLineFragmentsKey(input, delegate, options);
+      const cached = cache.get(key);
+      if (cached) {
+        emitCounter("pageRender.measurement.hit", key);
+        return cloneMeasuredLineFragments(cached);
+      }
+      emitCounter("pageRender.measurement.miss", key);
+      const measured = delegate.measureLineFragments(input);
+      cache.set(key, cloneMeasuredLineFragments(measured));
+      return measured;
+    },
+    measureInlineObject(input) {
+      const key = buildInlineObjectKey(input, delegate, options);
+      const cached = cache.get(key);
+      if (cached) {
+        emitCounter("pageRender.measurement.hit", key);
+        return { ...cached };
+      }
+      emitCounter("pageRender.measurement.miss", key);
+      const measured = delegate.measureInlineObject(input);
+      cache.set(key, { ...measured });
+      return measured;
+    },
+    measureTableBlock(input) {
+      const key = buildTableBlockKey(input, delegate, options);
+      const cached = cache.get(key);
+      if (cached) {
+        emitCounter("pageRender.measurement.hit", key);
+        return cloneMeasuredTableBlock(cached);
+      }
+      emitCounter("pageRender.measurement.miss", key);
+      const measured = delegate.measureTableBlock(input);
+      cache.set(key, cloneMeasuredTableBlock(measured));
+      return measured;
+    },
+    invalidateCache() {
+      delegate.invalidateCache();
+      cache.clear("provider.invalidateCache");
+      emitCounter("pageRender.measurement.invalidated.provider.invalidateCache");
+    }
+  };
+}
+function isCachedLayoutMeasurementProvider(provider) {
+  return typeof provider.measurementCacheStats === "function";
+}
+function buildLineFragmentsKey(input, delegate, options) {
+  const block = input.block;
+  const identity = measurementIdentityForBlock(block);
+  return {
+    measurementKind: "line-fragments",
+    blockId: identity.blockId,
+    blockPath: identity.blockPath,
+    contentHash: hashStable({
+      kind: block.kind,
+      identity: identity.identityHash,
+      segments: block.segments,
+      numbering: block.numbering,
+      numberingPrefix: block.numberingPrefix,
+      numberingSuffix: block.numberingSuffix,
+      resolvedNumbering: block.resolvedNumbering
+    }),
+    formattingHash: createLayoutReadyFormattingSnapshot(
+      input.formatting,
+      input.runs
+    ).hash,
+    constraintsHash: hashStable({ columnWidth: input.columnWidth }),
+    sectionHash: resolveOptionValue(options.sectionHash, "section:provider-input"),
+    fontEpoch: resolveOptionValue(options.fontEpoch, "font:default"),
+    backendVersion: resolveOptionValue(options.backendVersion, delegate.fidelity),
+    displayModeHash: resolveOptionValue(options.displayModeHash, "display:default")
+  };
+}
+function buildInlineObjectKey(input, delegate, options) {
+  return {
+    measurementKind: "inline-object",
+    blockId: "inline-object",
+    blockPath: "inline-object",
+    contentHash: hashStable({ display: input.display }),
+    formattingHash: "format:none",
+    constraintsHash: hashStable({
+      widthTwips: input.widthTwips,
+      heightTwips: input.heightTwips
+    }),
+    sectionHash: resolveOptionValue(options.sectionHash, "section:provider-input"),
+    fontEpoch: resolveOptionValue(options.fontEpoch, "font:default"),
+    backendVersion: resolveOptionValue(options.backendVersion, delegate.fidelity),
+    displayModeHash: resolveOptionValue(options.displayModeHash, "display:default")
+  };
+}
+function buildTableBlockKey(input, delegate, options) {
+  const block = input.block;
+  const identity = measurementIdentityForBlock(block);
+  return {
+    measurementKind: "table-block",
+    blockId: identity.blockId,
+    blockPath: identity.blockPath,
+    contentHash: hashStable({
+      kind: block.kind,
+      identity: identity.identityHash,
+      rows: block.rows,
+      gridColumns: block.gridColumns,
+      gridColumnsRelative: block.gridColumnsRelative,
+      tableResolved: block.tableResolved,
+      tblLook: block.tblLook
+    }),
+    formattingHash: hashStable({
+      styleId: block.styleId,
+      alignment: block.alignment
+    }),
+    constraintsHash: hashStable({ columnWidth: input.columnWidth }),
+    sectionHash: resolveOptionValue(options.sectionHash, "section:provider-input"),
+    fontEpoch: resolveOptionValue(options.fontEpoch, "font:default"),
+    backendVersion: resolveOptionValue(options.backendVersion, delegate.fidelity),
+    displayModeHash: resolveOptionValue(options.displayModeHash, "display:default")
+  };
+}
+function measurementIdentityForBlock(block) {
+  const identity = block.layoutIdentity;
+  if (!identity) {
+    return {
+      blockId: block.blockId,
+      blockPath: blockPathForBlock(block),
+      identityHash: "identity:legacy"
+    };
+  }
+  return {
+    blockId: identity.blockId,
+    blockPath: identity.blockPath,
+    identityHash: hashStable({
+      storyKey: identity.storyKey,
+      blockId: identity.blockId,
+      blockPath: identity.blockPath,
+      sourceRef: identity.sourceRef,
+      table: identity.table,
+      list: identity.list,
+      field: identity.field,
+      object: identity.object
+    })
+  };
+}
+function blockPathForBlock(block) {
+  return `${block.from}:${block.to}`;
+}
+function resolveOptionValue(option, fallback) {
+  if (typeof option === "function") return option();
+  return option ?? fallback;
+}
+function serializeCacheKey(key) {
+  return stableStringify(key);
+}
+function estimateBytes(key, value) {
+  return stableStringify(key).length + stableStringify(value).length;
+}
+function cloneMeasuredLineFragments(value) {
+  return {
+    lineCount: value.lineCount,
+    maxLineWidth: value.maxLineWidth,
+    lineHeights: [...value.lineHeights]
+  };
+}
+function cloneMeasuredTableBlock(value) {
+  return {
+    totalHeightTwips: value.totalHeightTwips,
+    rowHeights: [...value.rowHeights]
+  };
+}
+function hashStable(value) {
+  return fnv1a(stableStringify(value)).toString(36);
+}
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  if (value instanceof Map) {
+    return stableStringify(Array.from(value.entries()));
+  }
+  const object = value;
+  const keys = Object.keys(object).filter((key) => object[key] !== void 0 && typeof object[key] !== "function").sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+}
+function fnv1a(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
 // src/runtime/layout/layout-engine-version.ts
-var LAYOUT_ENGINE_VERSION = 88;
+var LAYOUT_ENGINE_VERSION = 93;
 var LAYCACHE_SCHEMA_VERSION = 12;
 
 // src/runtime/layout/layout-engine-instance.ts
 var FULL_VIEWPORT_WINDOW_KEY = "full";
 var DEFAULT_VIEWPORT_PAGE_WINDOW_BUFFER = 1;
+function indexLayoutIdentitiesByBlockPath(identities) {
+  return new Map(identities.map((identity) => [identity.blockPath, identity]));
+}
+function indexEditableTargetsByBlockPath(targets) {
+  return new Map(targets.map((target) => [target.blockPath, target]));
+}
 function normalizeViewportPageWindow(window2) {
   if (!window2) return void 0;
   const buffer = Number.isFinite(window2.bufferPages) ? Math.max(0, Math.floor(window2.bufferPages ?? 0)) : DEFAULT_VIEWPORT_PAGE_WINDOW_BUFFER;
@@ -6754,8 +7109,22 @@ function recordFullRebuildReason(reasonKind) {
   probe.invalidationCounts[totalKey] = (probe.invalidationCounts[totalKey] ?? 0) + 1;
   probe.invalidationCounts[byReasonKey] = (probe.invalidationCounts[byReasonKey] ?? 0) + 1;
 }
+function wrapMeasurementProvider(provider, measurementCache, telemetryBus) {
+  if (!measurementCache || isCachedLayoutMeasurementProvider(provider)) {
+    return provider;
+  }
+  const cacheOptions = measurementCache === true ? {} : measurementCache;
+  return createCachedLayoutMeasurementProvider(provider, {
+    ...cacheOptions,
+    ...telemetryBus ? { telemetryBus } : {}
+  });
+}
 function createLayoutEngine(options = {}) {
-  let measurementProvider = options.measurementProvider ?? createEmpiricalMeasurementProvider();
+  let measurementProvider = wrapMeasurementProvider(
+    options.measurementProvider ?? createEmpiricalMeasurementProvider(),
+    options.measurementCache,
+    options.telemetryBus
+  );
   const autoUpgradeToCanvas = options.autoUpgradeToCanvasBackend !== false;
   const telemetryBus = options.telemetryBus;
   const dirtyFieldFamilies = /* @__PURE__ */ new Set();
@@ -6855,13 +7224,20 @@ function createLayoutEngine(options = {}) {
     const pageCountBeforeRecompute = previousPageCount;
     const document2 = input.document;
     const viewportWindow = normalizeViewportPageWindow(input.viewportPageWindow);
+    const layoutInputs = collectCanonicalLayoutInputs(document2);
+    const layoutIdentitiesByBlockPath = indexLayoutIdentitiesByBlockPath(
+      layoutInputs.layoutIdentities
+    );
+    const editableTargetsByBlockPath = indexEditableTargetsByBlockPath(
+      layoutInputs.editableTargets
+    );
     const mainSurface = createEditorSurfaceSnapshot(
       document2,
       createSelectionSnapshot(0, 0),
-      MAIN_STORY_TARGET
+      MAIN_STORY_TARGET,
+      { editableTargetsByBlockPath, layoutIdentitiesByBlockPath }
     );
     const sections = buildResolvedSections(document2);
-    const layoutInputs = collectCanonicalLayoutInputs(document2);
     const fieldRegions = layoutInputs.fieldRegions;
     const pageStack = buildPageStackWithSplits(
       document2,
@@ -6973,10 +7349,18 @@ function createLayoutEngine(options = {}) {
     const firstDirty = range.firstPageIndex;
     if (firstDirty < 0 || firstDirty >= priorGraph.pages.length) return null;
     const document2 = input.document;
+    const layoutInputs = collectCanonicalLayoutInputs(document2);
+    const layoutIdentitiesByBlockPath = indexLayoutIdentitiesByBlockPath(
+      layoutInputs.layoutIdentities
+    );
+    const editableTargetsByBlockPath = indexEditableTargetsByBlockPath(
+      layoutInputs.editableTargets
+    );
     const mainSurface = createEditorSurfaceSnapshot(
       document2,
       createSelectionSnapshot(0, 0),
-      MAIN_STORY_TARGET
+      MAIN_STORY_TARGET,
+      { editableTargetsByBlockPath, layoutIdentitiesByBlockPath }
     );
     const sections = buildResolvedSections(document2);
     const dirtyPage = priorGraph.pages[firstDirty];
@@ -7005,7 +7389,6 @@ function createLayoutEngine(options = {}) {
     const freshSnapshotsToRebuild = freshSnapshots.slice(0, convergenceIndex);
     const convergedTailStart = convergenceIndex < freshSnapshots.length ? firstDirty + convergenceIndex : void 0;
     const freshStories = resolvePageStories(freshSnapshotsToRebuild);
-    const layoutInputs = collectCanonicalLayoutInputs(document2);
     const fieldRegions = layoutInputs.fieldRegions;
     const freshBodyFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
       mainSurface,
@@ -7135,9 +7518,13 @@ function createLayoutEngine(options = {}) {
     const readCachedRevision = () => cachedGraph?.revision ?? 0;
     void (async () => {
       try {
-        const mod = await import("./measurement-backend-canvas-Q3MJMEYX.js");
+        const mod = await import("./measurement-backend-canvas-F7ZYDACK.js");
         const canvasProvider = mod.createCanvasBackend();
-        measurementProvider = canvasProvider;
+        measurementProvider = wrapMeasurementProvider(
+          canvasProvider,
+          options.measurementCache,
+          telemetryBus
+        );
         cachedKey = null;
         cachedGraph = null;
         cachedFormatting = null;
@@ -7222,7 +7609,11 @@ function createLayoutEngine(options = {}) {
     },
     swapMeasurementProvider(provider) {
       const previousFidelity = measurementProvider.fidelity;
-      measurementProvider = provider;
+      measurementProvider = wrapMeasurementProvider(
+        provider,
+        options.measurementCache,
+        telemetryBus
+      );
       if (previousFidelity !== provider.fidelity) {
         cachedKey = null;
         cachedGraph = null;
@@ -7251,6 +7642,10 @@ function createLayoutEngine(options = {}) {
       cachedFormatting = null;
       cachedMapper = null;
     },
+    getMeasurementCacheStats() {
+      if (!isCachedLayoutMeasurementProvider(measurementProvider)) return null;
+      return measurementProvider.measurementCacheStats();
+    },
     /**
      * L7 Phase 2.5 — seed the cached graph from a prerender envelope.
      * Populates both `cachedGraph` and `cachedKey` (keyed on the provided