@beyondwork/docx-react-component 1.0.48 → 1.0.50

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

@@ -42,8 +42,18 @@
  *       file under `src/runtime/layout/**` changed. Safe to treat
  *       versions 3, 4, and 5 as cache-compatible if a migration ever
  *       needs to collapse them.
+ *   6 — Lane 3a P9 Phase A. `RenderAnchorIndex` gains three chrome-kind
+ *       resolvers (`byScopeId`, `byCommentId`, `byRevisionId`) sourced
+ *       from the resolved `DecorationIndex`, and `buildAnchorIndex`
+ *       runs in two phases inside the render kernel so the final index
+ *       carries decoration-aware lookups. No cached-geometry change;
+ *       consumers (Lane 1 R.1 SelectionLayer, Lane 6 P11 chrome rails)
+ *       can now query one unified API instead of reaching into
+ *       `frame.decorationIndex`. Cache envelopes from version 5 are
+ *       invalidated on load because the anchor-index public shape
+ *       changed even though pixel geometry did not.
  */
-export const LAYOUT_ENGINE_VERSION = 5 as const;
+export const LAYOUT_ENGINE_VERSION = 6 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/layout/public-facet.ts

@@ -1824,22 +1824,15 @@ function resolveAnchorRects(
       return rect ? [rect] : [];
     }
     case "scope-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.workflow
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      return frame.anchorIndex.byScopeId(String(query.value));
     }
     case "comment-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.comments
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      const rect = frame.anchorIndex.byCommentId(String(query.value));
+      return rect ? [rect] : [];
     }
     case "revision-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.revisions
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      const rect = frame.anchorIndex.byRevisionId(String(query.value));
+      return rect ? [rect] : [];
     }
     default: {
       const exhaustive: never = query.kind;

package/src/runtime/render/render-frame-types.ts

@@ -230,6 +230,20 @@ export interface RenderAnchorIndex {
     tableBlockId: string,
     rowIndex: number,
   ): RenderFrameRect | null;
+  /**
+   * Chrome-kind resolvers (P9 Phase A). Read against the frame's
+   * `decorationIndex` so chrome surfaces (scope rails, comment balloons,
+   * revision margin bars, Lane 1 R.1 SelectionLayer) query one unified
+   * API instead of reaching into `frame.decorationIndex` directly.
+   *
+   * `byScopeId` returns every rect because a single workflow scope may
+   * cover multiple pages (one `RenderBlockDecoration` per page); chrome
+   * rails read the list. `byCommentId` and `byRevisionId` return a single
+   * rect — `resolveDecorationIndex` emits one entry per thread/revision.
+   */
+  byScopeId(scopeId: string): readonly RenderFrameRect[];
+  byCommentId(commentId: string): RenderFrameRect | null;
+  byRevisionId(revisionId: string): RenderFrameRect | null;
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/render/render-kernel.ts

@@ -192,7 +192,16 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
     }
 
     const pendingDeltas = input.getPendingOpDeltas?.() ?? [];
-    const anchorIndex = buildAnchorIndex(renderPages, pendingDeltas, zoom.pxPerTwip);
+    // P9 Phase A — two-phase anchor-index build. The decoration resolver
+    // reads the anchor index to map runtime ranges to frame rects; the
+    // final anchor index then exposes chrome-kind resolvers that read
+    // back from the resolved decoration index. Rebuilding the index with
+    // the resolved decoration data avoids a post-hoc mutation seam.
+    const baseAnchorIndex = buildAnchorIndex(
+      renderPages,
+      pendingDeltas,
+      zoom.pxPerTwip,
+    );
     const includeDecorations = options?.includeDecorations ?? true;
     const sources = input.getDecorationSources?.();
     const hasSources =
@@ -205,8 +214,14 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
     const decorationIndex: DecorationIndex = !includeDecorations
       ? EMPTY_DECORATION_INDEX
       : hasSources
-        ? resolveDecorationIndex({ anchorIndex, ...sources })
+        ? resolveDecorationIndex({ anchorIndex: baseAnchorIndex, ...sources })
         : buildDecorationIndex(renderPages);
+    const anchorIndex = buildAnchorIndex(
+      renderPages,
+      pendingDeltas,
+      zoom.pxPerTwip,
+      decorationIndex,
+    );
 
     // Revision: keyed off the engine's current page graph so repeated reads
     // at the same revision return the same cached frame.  We derive it
@@ -634,6 +649,7 @@ function buildAnchorIndex(
   pages: readonly RenderPage[],
   pendingDeltas: readonly PendingOpDelta[] = [],
   pxPerTwip = 1,
+  decorationIndex: DecorationIndex = EMPTY_DECORATION_INDEX,
 ): RenderAnchorIndex {
   const byRuntimeOffset = new Map<number, RenderFrameRect>();
   const byFragmentId = new Map<string, RenderFrameRect>();
@@ -739,6 +755,28 @@ function buildAnchorIndex(
     byTableRowEdge(tableBlockId, rowIndex) {
       return tableRowEdges.get(`${tableBlockId}:${rowIndex}`) ?? null;
     },
+    // P9 Phase A — chrome-kind resolvers sourced from the resolved
+    // decoration index. Empty by default (the initial frame build passes
+    // `EMPTY_DECORATION_INDEX` until decoration resolution runs); the
+    // kernel re-invokes `buildAnchorIndex` with the resolved index so the
+    // final anchor index carries chrome-aware lookups.
+    byScopeId(scopeId) {
+      return decorationIndex.workflow
+        .filter((decoration) => decoration.refId === scopeId)
+        .map((decoration) => decoration.frame);
+    },
+    byCommentId(commentId) {
+      const match = decorationIndex.comments.find(
+        (decoration) => decoration.refId === commentId,
+      );
+      return match?.frame ?? null;
+    },
+    byRevisionId(revisionId) {
+      const match = decorationIndex.revisions.find(
+        (decoration) => decoration.refId === revisionId,
+      );
+      return match?.frame ?? null;
+    },
   };
 }
 

package/src/runtime/structure-ops/fragment-insert.ts

@@ -0,0 +1,134 @@
+/**
+ * Slice 1 of the I2 Tier B rich-paste sub-plan (`docs/plans/lane-1-i2-tier-b-rich-paste.md`).
+ *
+ * `applyFragmentInsert` is the canonical splicer for `CanonicalDocumentFragment` —
+ * the block-level payload that the HTML and Word-clipboard paste parsers (Slices 2+3)
+ * will produce. Slice 1 ships the shape and a baseline "split-and-splice" semantic
+ * without any parser in front of it, so the public `insertFragment` method can be
+ * driven directly from tests + future hosts.
+ *
+ * Baseline semantics:
+ *   1. Empty fragment → no-op (no revisionToken bump).
+ *   2. Range selection → the range is deleted first via `applyTextTransaction`, then
+ *      the caret is the range start.
+ *   3. Caret paragraph is split via `splitParagraph`; fragment blocks are spliced
+ *      between the two halves. Empty halves at document boundaries are preserved —
+ *      callers can trim them if desired.
+ *
+ * What Slice 1 deliberately does NOT do:
+ *   - Merge-intent (pre-Slice-1 drafts had `firstParagraphMergeIntent` on the type).
+ *     Merge semantics will land in a follow-up slice once we have a paste fixture
+ *     that demonstrates the need.
+ *   - Fragment insertion inside table cells beyond the trivial case. Table-cell
+ *     splicing is currently best-effort: the target paragraph within the cell is
+ *     split, but cross-cell fragments are rejected as a no-op.
+ *   - Comment/revision remapping across the fragment boundary — the splicer returns
+ *     an empty mapping; follow-up slices will produce richer mappings.
+ */
+
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import {
+  type CanonicalDocumentEnvelope,
+  type SelectionSnapshot,
+  createSelectionSnapshot,
+} from "../../core/state/editor-state.ts";
+import { applyTextTransaction } from "../../core/state/text-transaction.ts";
+import { splitParagraph, type TextCommandContext } from "../../core/commands/text-commands.ts";
+import { resolveParagraphScope, type StructuralMutationResult } from "../../core/commands/structural-helpers.ts";
+import type { BlockNode, DocumentRootNode, ParagraphNode } from "../../model/canonical-document.ts";
+import { createEmptyMapping } from "../../core/selection/mapping.ts";
+
+export function applyFragmentInsert(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  fragment: CanonicalDocumentFragment,
+  context: TextCommandContext,
+): StructuralMutationResult {
+  if (fragment.blocks.length === 0) {
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  // Collapse any range selection by first deleting the selected content. The
+  // resulting caret is at `min(anchor, head)`.
+  let workingDocument = document;
+  let workingSelection = selection;
+  if (selection.anchor !== selection.head) {
+    const collapseResult = applyTextTransaction(
+      workingDocument,
+      workingSelection,
+      { type: "replace", insertion: [] },
+      context,
+    );
+    workingDocument = collapseResult.document;
+    workingSelection = collapseResult.selection;
+  }
+
+  // Split the caret paragraph; the fragment blocks go between the two halves.
+  const splitResult = splitParagraph(workingDocument, workingSelection, context);
+  const splitRoot = splitResult.document.content;
+  if (!splitRoot || splitRoot.type !== "doc") {
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  // Locate the split boundary by re-resolving the paragraph scope against the
+  // pre-split snapshot. The right-half index = scope.blockIndex + 1.
+  const scope = resolveParagraphScope(workingDocument, workingSelection);
+  if (!scope || scope.kind !== "top-level") {
+    // Table-cell fragment insert is out of scope for Slice 1.
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  const rightHalfIndex = scope.blockIndex + 1;
+  const splicedChildren: BlockNode[] = [
+    ...splitRoot.children.slice(0, rightHalfIndex),
+    ...fragment.blocks.map((block) => cloneBlock(block)),
+    ...splitRoot.children.slice(rightHalfIndex),
+  ];
+
+  const nextRoot: DocumentRootNode = {
+    ...splitRoot,
+    children: splicedChildren,
+  };
+
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...splitResult.document,
+    updatedAt: context.timestamp,
+    content: nextRoot,
+  };
+
+  // Caret lands at the end of the last fragment block. For Slice 1 we approximate
+  // this with a collapsed selection at position 0 of the new document — richer
+  // caret placement follows once parsers drive this.
+  const nextSelection = createSelectionSnapshot(0, 0);
+
+  return {
+    changed: true,
+    document: nextDocument,
+    selection: nextSelection,
+    mapping: createEmptyMapping(),
+  };
+}
+
+function cloneBlock(block: BlockNode): BlockNode {
+  // Slice 1 uses a structural clone; no need to deep-clone formatting attrs since
+  // fragment blocks are presumed freshly minted by the caller.
+  if (block.type === "paragraph") {
+    return {
+      ...block,
+      children: block.children.map((child) => ({ ...child })),
+    } as ParagraphNode;
+  }
+  return JSON.parse(JSON.stringify(block)) as BlockNode;
+}

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);