@beyondwork/docx-react-component 1.0.47 → 1.0.49

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

@@ -0,0 +1,188 @@
+/**
+ * Resolve a (`<w:color>`-shaped) theme-color reference to a concrete hex
+ * string, applying the `w:themeTint` / `w:themeShade` HSL-luminance
+ * modulation per ECMA-376 §17.18.85 / §17.18.83.
+ *
+ * Usage:
+ *   - The IO layer (`parse-run-formatting.ts`) captures
+ *     `colorThemeSlot` / `colorThemeTint` / `colorThemeShade` on
+ *     `CanonicalRunFormatting` as raw strings (preserved for
+ *     byte-stable round-trip).
+ *   - The render/cascade layer calls `resolveThemeColorHex(rPr, theme)`
+ *     to collapse the reference to the actual hex colour the browser
+ *     should paint. The original fields stay intact so export still
+ *     round-trips the theme reference (not the computed hex).
+ *
+ * Lane 3 L2.c. Mirrors LibreOffice's `Color::ApplyTintOrShade` at
+ * `vendor/libreoffice/include/tools/color.hxx:200-240` (shape only; no
+ * code copied — our implementation is pure TypeScript against the
+ * ECMA-376 formulae).
+ *
+ * **Scope boundary:** this resolver handles the standard tint/shade
+ * pair. Theme-color-mapping (clrSchemeMapping — how "accent1" maps to a
+ * different `<w:clrScheme>` slot in older Word versions) is NOT applied
+ * here — `resolveThemeColor` from `src/io/ooxml/parse-theme.ts` is the
+ * authoritative slot→hex lookup and future work will layer scheme
+ * mapping into it.
+ */
+
+import type { CanonicalRunFormatting, ResolvedTheme } from "../model/canonical-document.ts";
+import { resolveThemeColor } from "../io/ooxml/parse-theme.ts";
+
+/**
+ * Collapse `<w:color>`-style theme-slot + tint + shade references into a
+ * single resolved hex colour. Returns:
+ *   - the raw `colorHex` as-is when it's a direct hex (the theme fields
+ *     are ignored because direct colour wins per ECMA-376 cascade).
+ *   - `"auto"` when the source declared `w:color w:val="auto"` (sentinel
+ *     kept verbatim per our long-standing A.9 round-trip rule).
+ *   - the theme slot's hex — tint/shade applied — when the source
+ *     declared `w:themeColor="accent1"` etc. and the theme is available.
+ *   - `undefined` otherwise (no colour declared, or theme slot absent).
+ */
+export function resolveThemeColorHex(
+  rPr: Pick<
+    CanonicalRunFormatting,
+    "colorHex" | "colorThemeSlot" | "colorThemeTint" | "colorThemeShade"
+  >,
+  theme: ResolvedTheme | undefined,
+): string | undefined {
+  if (rPr.colorHex === "auto") return "auto";
+  if (rPr.colorHex) return rPr.colorHex;
+  if (!rPr.colorThemeSlot) return undefined;
+
+  const baseHex = resolveThemeColor(theme, rPr.colorThemeSlot);
+  if (!baseHex) return undefined;
+
+  return applyThemeTintShade(baseHex, rPr.colorThemeTint, rPr.colorThemeShade);
+}
+
+/**
+ * Apply `w:themeTint` (shift toward white) and/or `w:themeShade` (shift
+ * toward black) to a base hex colour. Pure function.
+ *
+ * Tint/shade are each a 0x00–0xFF hex byte representing a fraction of
+ * 255 (ECMA-376 §17.18.85 / §17.18.83). Only one may be present per
+ * `<w:color>`; when both are omitted, the base hex is returned.
+ *
+ * Formulae (per Microsoft's Word/OOXML guidance mirrored in LibreOffice):
+ *   - tint byte T → frac = T / 255; newL = frac * L + (1 - frac) * 1.0
+ *     (at T=0 the colour becomes pure white; at T=255 it stays unchanged)
+ *   - shade byte S → frac = S / 255; newL = frac * L
+ *     (at S=0 the colour becomes pure black; at S=255 it stays unchanged)
+ *
+ * These are LUMINANCE modulations in the HSL colour space (hue + saturation
+ * preserved). The conversion hex → HSL → hex is the standard 0–1 / 0–360
+ * form.
+ */
+export function applyThemeTintShade(
+  baseHex: string,
+  tint: string | undefined,
+  shade: string | undefined,
+): string {
+  const tintByte = parseHexByte(tint);
+  const shadeByte = parseHexByte(shade);
+  if (tintByte === undefined && shadeByte === undefined) {
+    return baseHex;
+  }
+
+  const rgb = parseHexColor(baseHex);
+  if (!rgb) return baseHex;
+
+  const hsl = rgbToHsl(rgb);
+  let newL = hsl.l;
+  if (tintByte !== undefined) {
+    const frac = tintByte / 255;
+    newL = frac * hsl.l + (1 - frac);
+  } else if (shadeByte !== undefined) {
+    const frac = shadeByte / 255;
+    newL = frac * hsl.l;
+  }
+  newL = Math.max(0, Math.min(1, newL));
+
+  const out = hslToRgb({ h: hsl.h, s: hsl.s, l: newL });
+  return formatHexColor(out);
+}
+
+function parseHexByte(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = Number.parseInt(value, 16);
+  if (!Number.isFinite(n)) return undefined;
+  return Math.max(0, Math.min(255, n));
+}
+
+function parseHexColor(hex: string): { r: number; g: number; b: number } | undefined {
+  const normalized = hex.replace(/^#/u, "").trim();
+  if (normalized.length !== 6) return undefined;
+  const n = Number.parseInt(normalized, 16);
+  if (!Number.isFinite(n)) return undefined;
+  return {
+    r: (n >> 16) & 0xff,
+    g: (n >> 8) & 0xff,
+    b: n & 0xff,
+  };
+}
+
+function formatHexColor(rgb: { r: number; g: number; b: number }): string {
+  const to2 = (n: number): string => Math.round(n).toString(16).padStart(2, "0").toUpperCase();
+  return `${to2(rgb.r)}${to2(rgb.g)}${to2(rgb.b)}`;
+}
+
+function rgbToHsl(rgb: { r: number; g: number; b: number }): {
+  h: number;
+  s: number;
+  l: number;
+} {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r:
+        h = ((g - b) / d + (g < b ? 6 : 0)) * 60;
+        break;
+      case g:
+        h = ((b - r) / d + 2) * 60;
+        break;
+      default:
+        h = ((r - g) / d + 4) * 60;
+    }
+  }
+  return { h, s, l };
+}
+
+function hslToRgb(hsl: { h: number; s: number; l: number }): {
+  r: number;
+  g: number;
+  b: number;
+} {
+  const { h, s, l } = hsl;
+  if (s === 0) {
+    const gray = l * 255;
+    return { r: gray, g: gray, b: gray };
+  }
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const hueToRgb = (t: number): number => {
+    let tt = t;
+    if (tt < 0) tt += 1;
+    if (tt > 1) tt -= 1;
+    if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+    if (tt < 1 / 2) return q;
+    if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
+    return p;
+  };
+  const hFrac = h / 360;
+  return {
+    r: hueToRgb(hFrac + 1 / 3) * 255,
+    g: hueToRgb(hFrac) * 255,
+    b: hueToRgb(hFrac - 1 / 3) * 255,
+  };
+}

package/src/runtime/workflow-markup.ts

@@ -22,6 +22,7 @@ import type {
   WorkflowCommentMarkup,
 } from "../api/public-types";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { createPublicRangeAnchor } from "../core/selection/anchor-conversion.ts";
 import {
   projectSurfaceText,
   searchProjectedSurfaceText,
@@ -145,7 +146,7 @@ export function collectWorkflowMarkupSnapshot(input: {
         markupId: `protected-range:${range.rangeId}`,
         kind: "protected_range",
         rangeId: range.rangeId,
-        anchor: createRangeAnchor(range.start, range.end),
+        anchor: createPublicRangeAnchor(range.start, range.end),
         storyTarget: MAIN_STORY_TARGET,
         label: `Protected range ${range.rangeId}`,
         excerpt: range.enforcementReason,
@@ -283,7 +284,7 @@ function collectSurfaceMarkup(
       kind: "opaque_fragment",
       fragmentId: block.fragmentId,
       warningId: block.warningId,
-      anchor: createRangeAnchor(block.from, block.to),
+      anchor: createPublicRangeAnchor(block.from, block.to),
       storyTarget,
       label: block.label,
       excerpt: block.detail,
@@ -308,7 +309,7 @@ function collectSegmentMarkup(
     highlights.push({
       markupId: `highlight:${storyTargetKey(storyTarget)}:${segment.from}:${segment.to}:${segment.markAttrs.backgroundColor}`,
       kind: "highlight",
-      anchor: createRangeAnchor(segment.from, segment.to),
+      anchor: createPublicRangeAnchor(segment.from, segment.to),
       storyTarget,
       label: `Highlight ${segment.markAttrs.backgroundColor}`,
       excerpt: segment.text,
@@ -326,7 +327,7 @@ function collectSegmentMarkup(
       kind: "opaque_fragment",
       fragmentId: segment.fragmentId,
       warningId: segment.warningId,
-      anchor: createRangeAnchor(segment.from, segment.to),
+      anchor: createPublicRangeAnchor(segment.from, segment.to),
       storyTarget,
       label: segment.label,
       excerpt: segment.detail,
@@ -380,7 +381,7 @@ function collectFieldMarkup(
           {
             markupId: `field:${field.index}`,
             kind: "field",
-            anchor: createRangeAnchor(match.from, match.to),
+            anchor: createPublicRangeAnchor(match.from, match.to),
             storyTarget: story.storyTarget,
             label: displayText,
             excerpt: field.instruction,
@@ -417,7 +418,7 @@ function collectOpaqueFragmentMarkup(
         kind: "opaque_fragment",
         fragmentId: fragment.fragmentId,
         warningId: fragment.warningId,
-        anchor: createRangeAnchor(fragment.lastKnownRange.from, fragment.lastKnownRange.to),
+        anchor: createPublicRangeAnchor(fragment.lastKnownRange.from, fragment.lastKnownRange.to),
         storyTarget: MAIN_STORY_TARGET,
         label: descriptor.label,
         excerpt: descriptor.detail,
@@ -427,18 +428,6 @@ function collectOpaqueFragmentMarkup(
     });
 }
 
-function createRangeAnchor(from: number, to: number): EditorAnchorProjection {
-  return {
-    kind: "range",
-    from,
-    to,
-    assoc: {
-      start: -1,
-      end: 1,
-    },
-  };
-}
-
 function storyTargetKey(storyTarget: EditorStoryTarget): string {
   switch (storyTarget.kind) {
     case "main":

package/src/ui/WordReviewEditor.tsx

@@ -75,6 +75,7 @@ import type {
   ZoomLevel,
 } from "../api/public-types";
 import { MetadataResolverMissingError } from "../api/public-types";
+import { readHarnessDebugPortsFlag } from "../internal/harness-debug-ports.ts";
 import type { ScopeMetadataResolver } from "../api/scope-metadata-resolver-types.ts";
 import {
   editorSessionStateFromPersistedSnapshot,
@@ -178,6 +179,7 @@ import {
   useRuntimeSnapshotSlice,
   useRuntimeValue,
 } from "./runtime-snapshot-selectors.ts";
+import { computeEffectiveShowUnsupportedPreviews } from "./unsupported-previews-policy.ts";
 import type { MarkupDisplay } from "./headless/comment-decoration-model";
 import { resolveScopedChromePolicy } from "./headless/scoped-chrome-policy";
 import type {
@@ -494,6 +496,9 @@ export function __createWordReviewEditorRefBridge(
     deleteComment: (commentId) => {
       applyRuntimeDeleteComment(runtime, commentId);
     },
+    addScope: (params) => runtime.addScope(params),
+    getScope: (scopeId) => runtime.getScope(scopeId),
+    removeScope: (scopeId) => runtime.removeScope(scopeId),
     acceptChange: (changeId) => runtime.acceptChange(changeId),
     rejectChange: (changeId) => runtime.rejectChange(changeId),
     acceptAllChanges: () => runtime.acceptAllChanges(),
@@ -776,6 +781,9 @@ export function __createWordReviewEditorRefBridge(
     clearWorkflowOverlay: () => {
       runtime.clearWorkflowOverlay();
     },
+    setSharedWorkflowState: (state) => {
+      runtime.setSharedWorkflowState(state === null ? null : clonePublicValue(state));
+    },
     getWorkflowScopeSnapshot: () => {
       return clonePublicValue(runtime.getWorkflowScopeSnapshot());
     },
@@ -1033,7 +1041,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       chromePreset,
       chromeOptions,
       markupDisplay,
-      showUnsupportedObjectPreviews = false,
+      __harnessDebugPorts,
+      unsupportedPreviewsPolicy = "never",
       onError,
       onEvent,
       onWarning,
@@ -1042,6 +1051,12 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onFindRequested,
       onPrintRequested,
       onZoomRequested,
+      onReplaceRequested,
+      onGoToRequested,
+      onSpellRequested,
+      onThesaurusRequested,
+      onExtendSelectionRequested,
+      onLastEditRequested,
       readOnly = false,
       reviewMode = "review",
       suggestionsEnabled = false,
@@ -1477,6 +1492,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         deleteComment: (commentId) => {
           applyRuntimeDeleteComment(activeRuntime, commentId);
         },
+        addScope: (params) => activeRuntime.addScope(params),
+        getScope: (scopeId) => activeRuntime.getScope(scopeId),
+        removeScope: (scopeId) => activeRuntime.removeScope(scopeId),
         acceptChange: (changeId) => activeRuntime.acceptChange(changeId),
         rejectChange: (changeId) => activeRuntime.rejectChange(changeId),
         acceptAllChanges: () => activeRuntime.acceptAllChanges(),
@@ -1813,6 +1831,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         clearWorkflowOverlay: () => {
           activeRuntime.clearWorkflowOverlay();
         },
+        setSharedWorkflowState: (state) => {
+          activeRuntime.setSharedWorkflowState(state === null ? null : clonePublicValue(state));
+        },
         getWorkflowScopeSnapshot: () => {
           return clonePublicValue(activeRuntime.getWorkflowScopeSnapshot());
         },
@@ -2608,6 +2629,24 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
             shortcut.shortcut === "zoom-out" ? "out" : "reset";
           onZoomRequested(direction);
           handled = true;
+        } else if (shortcut.shortcut === "replace" && onReplaceRequested) {
+          onReplaceRequested({ selectionText: "", selectionRange: snapshot.selection });
+          handled = true;
+        } else if (shortcut.shortcut === "go-to" && onGoToRequested) {
+          onGoToRequested({ selectionText: "", selectionRange: snapshot.selection });
+          handled = true;
+        } else if (shortcut.shortcut === "spell" && onSpellRequested) {
+          onSpellRequested({ selectionText: "", selectionRange: snapshot.selection });
+          handled = true;
+        } else if (shortcut.shortcut === "thesaurus" && onThesaurusRequested) {
+          onThesaurusRequested({ selectionText: "", selectionRange: snapshot.selection });
+          handled = true;
+        } else if (shortcut.shortcut === "extend-selection" && onExtendSelectionRequested) {
+          onExtendSelectionRequested({ selectionText: "", selectionRange: snapshot.selection });
+          handled = true;
+        } else if (shortcut.shortcut === "last-edit" && onLastEditRequested) {
+          onLastEditRequested({ selectionText: "", selectionRange: snapshot.selection });
+          handled = true;
         }
         if (handled) {
           event.preventDefault();
@@ -2908,6 +2947,13 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       },
     });
 
+    const harnessShowUnsupportedPreviews = readHarnessDebugPortsFlag(__harnessDebugPorts, "unsupportedObjectPreviews");
+    const effectiveShowUnsupportedPreviews = computeEffectiveShowUnsupportedPreviews({
+      harnessShowUnsupportedPreviews,
+      unsupportedPreviewsPolicy,
+      reviewMode,
+    });
+
     const documentElement = (
       <EditorSurfaceController
         ref={surfaceRef}
@@ -2918,7 +2964,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         documentNavigation={documentNavigation}
         reviewMode={reviewMode}
         markupDisplay={liveMarkupDisplay}
-        showUnsupportedObjectPreviews={showUnsupportedObjectPreviews}
+        showUnsupportedObjectPreviews={effectiveShowUnsupportedPreviews}
         activeRevisionId={activeRevisionId}
         activeSelectionToolKind={activeSelectionTool?.kind ?? null}
         showTrackedChanges={showTrackedChanges}

package/src/ui/editor-runtime-boundary.ts

@@ -44,6 +44,7 @@ import {
   loadDocxEditorSession,
   loadDocxEditorSessionAsync,
 } from "../io/docx-session.ts";
+import { tryReadLaycacheEnvelope } from "../runtime/prerender/customxml-probe.ts";
 import {
   createLoadScheduler,
   type LoadScheduler,
@@ -79,6 +80,14 @@ export interface ResolvedSource {
    * does the classic synchronous load.
    */
   preloadedDocxSession?: ReturnType<typeof loadDocxEditorSession>;
+  /**
+   * L7 Phase 2.7 — when the editor-runtime-boundary probe finds a
+   * laycache envelope in `/customXml/item1.xml`, its `graph` is stashed
+   * here and forwarded to `createDocumentRuntime` as `seedLayoutCache`.
+   * This is the Plan A (graph-seed) win layered on top of the Plan B
+   * (loader short-circuit) win. Undefined when no envelope is available.
+   */
+  preloadedLaycacheGraph?: import("../runtime/layout/page-graph.ts").RuntimePageGraph;
 }
 
 export interface CreateRuntimeArgs {
@@ -404,6 +413,18 @@ export function useEditorRuntimeBoundary(
         // can paint the skeleton while the rest of the parse finishes.
         // SSR / Node tests fall through to the synchronous load inside
         // `createRuntime`.
+        //
+        // L7 Phase 2.7 — Plan B read-path wiring. Before invoking the
+        // async loader, probe the docx for a laycache envelope stashed
+        // in `/customXml/item1.xml` (shipped by Plan B Slice 2). When the
+        // probe returns a validated envelope, pass it to the loader so
+        // the five expensive parse stages short-circuit against the
+        // cached `canonicalDocument`. Measured win on 138-pp extra-large
+        // CCEP: ~947 ms cold → ~590 ms warm (Δ 376 ms), same delta the
+        // Node-side `prerender-cache.bench.ts` records. Probe is ~20–50 ms;
+        // `tryReadLaycacheEnvelope` returns null on any rejection path
+        // (missing part, stale structural hash, schema mismatch) and the
+        // loader falls through to the full parse.
         if (
           source.initialDocx !== undefined &&
           source.preloadedDocxSession === undefined &&
@@ -411,12 +432,20 @@ export function useEditorRuntimeBoundary(
         ) {
           const scheduler = createLoadScheduler();
           loadSchedulerRef.current = scheduler;
+          const probeResult = await tryReadLaycacheEnvelope(source.initialDocx);
+          if (cancelled) {
+            scheduler.dispose();
+            loadSchedulerRef.current = null;
+            return;
+          }
+          recordPerfSample("loadSession.laycacheProbe");
           const preloaded = await loadDocxEditorSessionAsync({
             documentId,
             sourceLabel: source.sourceLabel,
             bytes: source.initialDocx,
             editorBuild: "dev",
             scheduler,
+            ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {}),
           });
           if (cancelled) {
             scheduler.dispose();
@@ -424,6 +453,9 @@ export function useEditorRuntimeBoundary(
             return;
           }
           source.preloadedDocxSession = preloaded;
+          if (probeResult) {
+            source.preloadedLaycacheGraph = probeResult.envelope.graph;
+          }
         }
 
         const nextRuntime = createRuntime(
@@ -662,6 +694,9 @@ function createRuntime(
     editorBuild: runtimeSessionState.editorBuild,
     fatalError: docxSession?.fatalError,
     protectionSnapshot: docxSession?.protectionSnapshot,
+    ...(args.source.preloadedLaycacheGraph
+      ? { seedLayoutCache: args.source.preloadedLaycacheGraph }
+      : {}),
     exportDocx: async (sessionState, options) => {
       if (docxSession) {
         return docxSession.exportDocx(sessionState, options);
@@ -900,6 +935,11 @@ function createLoadingRuntimeBridge(input: {
       throw createLoadingBoundaryError(input.snapshot.documentId, "comment");
     },
     editCommentBody: () => undefined,
+    addScope: () => {
+      throw createLoadingBoundaryError(input.snapshot.documentId, "scope");
+    },
+    getScope: () => null,
+    removeScope: () => undefined,
     acceptChange: () => undefined,
     rejectChange: () => undefined,
     acceptAllChanges: () => undefined,
@@ -960,6 +1000,7 @@ function createLoadingRuntimeBridge(input: {
       Promise.reject(createLoadingBoundaryError(input.snapshot.documentId, "export")),
     setWorkflowOverlay: () => undefined,
     clearWorkflowOverlay: () => undefined,
+    setSharedWorkflowState: () => undefined,
     getWorkflowOverlay: () => null,
     getWorkflowScopeSnapshot: () => null,
     getInteractionGuardSnapshot: () => ({ effectiveMode: "edit", blockedReasons: [] }),
@@ -1016,7 +1057,7 @@ function createLoadingRuntimeBridge(input: {
 
 function createLoadingBoundaryError(
   documentId: string,
-  target: "comment" | "session" | "snapshot" | "export",
+  target: "comment" | "session" | "snapshot" | "export" | "scope",
 ): EditorError {
   return {
     errorId: `${documentId}-loading-${target}`,

package/src/ui/headless/selection-helpers.ts

@@ -1,31 +1,22 @@
 import type { SelectionSnapshot } from "../../api/public-types";
+import {
+  createPublicNodeAnchor,
+  createPublicRangeAnchor,
+} from "../../core/selection/anchor-conversion.ts";
 
 /**
  * Headless-UI-side `createSelectionSnapshot` that produces the **public**
- * `EditorAnchorProjection` shape (top-level `from`/`to`). The runtime-facing
- * twin at `src/core/state/editor-state.ts` produces the internal
- * `RangeAnchor` shape (`range: { from, to }`). The two are *not*
- * interchangeable — they serve different type contracts. See the
- * `EditorAnchorProjection` definitions in `src/api/public-types.ts` vs
- * `src/core/selection/mapping.ts`. Do not merge without first unifying
- * those two definitions.
+ * `EditorAnchorProjection` shape via the canonical
+ * `createPublicRangeAnchor` constructor. The runtime-facing twin at
+ * `src/core/state/editor-state.ts` produces the internal `RangeAnchor`
+ * shape (`range: { from, to }`) — the two are not interchangeable.
  */
 export function createSelectionSnapshot(anchor: number, head = anchor): SelectionSnapshot {
-  const from = Math.min(anchor, head);
-  const to = Math.max(anchor, head);
   return {
     anchor,
     head,
     isCollapsed: anchor === head,
-    activeRange: {
-      kind: "range",
-      from,
-      to,
-      assoc: {
-        start: -1,
-        end: 1,
-      },
-    },
+    activeRange: createPublicRangeAnchor(anchor, head),
   };
 }
 
@@ -34,11 +25,7 @@ export function createNodeSelectionSnapshot(at: number, assoc: -1 | 1 = 1): Sele
     anchor: at,
     head: at,
     isCollapsed: true,
-    activeRange: {
-      kind: "node",
-      at,
-      assoc,
-    },
+    activeRange: createPublicNodeAnchor(at, assoc),
   };
 }
 

package/src/ui/runtime-shortcut-dispatch.ts

@@ -23,7 +23,12 @@ export interface SurfaceShortcutContext {
 
 export type ShellShortcutResolution =
   | { kind: "none" }
-  | { kind: "delegate"; shortcut: "find" | "print" | "zoom-in" | "zoom-out" | "zoom-reset" }
+  | { kind: "delegate"; shortcut:
+        | "find" | "print"
+        | "zoom-in" | "zoom-out" | "zoom-reset"
+        | "replace" | "go-to"
+        | "spell" | "thesaurus"
+        | "extend-selection" | "last-edit" }
   | { kind: "block"; command: string; reason: WorkflowBlockedCommandReason }
   | { kind: "history"; history: "undo" | "redo" }
   | { kind: "focus-region"; direction: 1 | -1 }
@@ -115,14 +120,14 @@ export function resolveShellShortcut(
   }
 
   if (isReplaceShortcut(input, key)) {
-    return resolveBlockedCapability("replaceText");
+    return { kind: "delegate", shortcut: "replace" };
   }
 
   if (
     isGoToShortcut(input, key) ||
     (key === "f5" && !input.shiftKey)
   ) {
-    return resolveBlockedCapability("goTo");
+    return { kind: "delegate", shortcut: "go-to" };
   }
 
   if (isModShiftShortcut(input, key, "e")) {
@@ -130,19 +135,19 @@ export function resolveShellShortcut(
   }
 
   if (key === "f7" && !input.shiftKey) {
-    return resolveBlockedCapability("checkSpelling");
+    return { kind: "delegate", shortcut: "spell" };
   }
 
   if (key === "f7" && input.shiftKey) {
-    return resolveBlockedCapability("openThesaurus");
+    return { kind: "delegate", shortcut: "thesaurus" };
   }
 
   if (key === "f8") {
-    return resolveBlockedCapability("extendSelection");
+    return { kind: "delegate", shortcut: "extend-selection" };
   }
 
   if (key === "f5" && input.shiftKey) {
-    return resolveBlockedCapability("lastEdit");
+    return { kind: "delegate", shortcut: "last-edit" };
   }
 
   return { kind: "none" };

package/src/ui/unsupported-previews-policy.ts

@@ -0,0 +1,23 @@
+/**
+ * I4 — Effective-visibility rule for preserve-only previews.
+ *
+ * Combines the harness-only opaque-token flag (from
+ * `__harnessDebugPorts`, read via `readHarnessDebugPortsFlag(..., "unsupportedObjectPreviews")`)
+ * with the public sibling `unsupportedPreviewsPolicy` prop (default
+ * `"never"`). The harness token remains unreachable from consumer
+ * apps (see `test/ui/unsupported-previews-invariant.test.ts`).
+ */
+export interface EffectiveShowUnsupportedPreviewsInput {
+  harnessShowUnsupportedPreviews: boolean;
+  unsupportedPreviewsPolicy: "never" | "review-only" | "always";
+  reviewMode: "editing" | "review";
+}
+
+export function computeEffectiveShowUnsupportedPreviews(
+  input: EffectiveShowUnsupportedPreviewsInput,
+): boolean {
+  if (input.harnessShowUnsupportedPreviews === true) return true;
+  if (input.unsupportedPreviewsPolicy === "always") return true;
+  if (input.unsupportedPreviewsPolicy === "review-only" && input.reviewMode === "review") return true;
+  return false;
+}

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -152,6 +152,14 @@ export interface TwChromeOverlayProps {
    * handle leaves focus-restore as a no-op — DOM reparent still runs.
    */
   pmView?: PmPortalView | null;
+  /**
+   * L7 Phase 2.8 — viewport cull for `TwPageStackChromeLayer`. Sequential
+   * page-index range (plus overscan) that should render full chrome
+   * bands; pages outside the range render empty frame wrappers only.
+   * When omitted, every page's chrome mounts (pre-Phase-2.8 behavior).
+   * See `useVisiblePageIndexRange` in `src/ui-tailwind/page-stack/use-visible-block-range.ts`.
+   */
+  visiblePageIndexRange?: { start: number; end: number } | null;
 }
 
 /**
@@ -188,6 +196,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   onOpenStory,
   pmSurfaceElement,
   pmView,
+  visiblePageIndexRange,
 }) => {
   return (
     <div
@@ -211,6 +220,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
           onOpenStory={onOpenStory}
           pmSurfaceElement={pmSurfaceElement}
           pmView={pmView}
+          visiblePageIndexRange={visiblePageIndexRange ?? null}
         />
       ) : null}
       <TwScopeRailLayer

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -5,6 +5,7 @@ export type PerfProbeKind =
   | "typing.divergence"
   | "selection"
   | "runtime.create"
+  | "loadSession.laycacheProbe"
   | "snapshot.surface"
   | "snapshot.compatibility"
   | "snapshot.navigation"