@beyondwork/docx-react-component 1.0.70 → 1.0.72

package/src/runtime/layout/resolved-formatting-state.ts

@@ -72,11 +72,11 @@ const FONT_AVG_CHAR_WIDTH: Record<string, number> = {
   "palatino linotype": 5.5,
   "cambria": 5.3,
   // Proportional sans-serif (xAvgCharWidth ≈ 0.50-0.60 em)
-  "arial": 5.8,
+  "arial": 4.9,
   "calibri": 5.0,
   "helvetica": 5.8,
   "verdana": 6.7,
-  "tahoma": 5.9,
+  "tahoma": 6.3,
   "segoe ui": 5.4,
   "trebuchet ms": 5.6,
   // Monospace (every glyph ≈ 0.60-0.67 em)
@@ -157,9 +157,21 @@ export interface ResolvedTableRowFormatting {
 // Paragraph formatting resolution
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolved theme-font lookup. When a segment's
+ * `resolvedRunFormatting.*Theme` carries a slot reference (`minorHAnsi`,
+ * `majorAscii`, …) but no literal `fontFamily*` name, the dominant-font
+ * resolver consults these fallbacks. Source: `document.subParts?.resolvedTheme`.
+ */
+export interface LayoutThemeFonts {
+  minorFont?: string;
+  majorFont?: string;
+}
+
 export function resolveBlockFormatting(
   block: SurfaceBlockSnapshot,
   defaultTabInterval = 720,
+  themeFonts?: LayoutThemeFonts,
 ): ResolvedParagraphFormatting | null {
   if (block.kind !== "paragraph") {
     return null;
@@ -167,7 +179,7 @@ export function resolveBlockFormatting(
 
   const spacing = resolveSpacing(block);
   const indent = resolveIndentation(block);
-  const fontInfo = resolveDominantFont(block);
+  const fontInfo = resolveDominantFont(block, themeFonts);
   const lineHeight = resolveLineHeight(spacing, fontInfo.fontSizeHalfPoints);
   const markerLane = block.resolvedNumbering?.geometry?.markerLane;
 
@@ -293,6 +305,7 @@ function resolveIndentation(
 
 function resolveDominantFont(
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+  themeFonts?: LayoutThemeFonts,
 ): { fontSizeHalfPoints: number; avgCharWidth: number; fontFamily: string | undefined } {
   // L03 → L04 contract: read formatting from the canonical L03 output
   // (`segment.resolvedRunFormatting`) first; fall back to the surface
@@ -304,10 +317,27 @@ function resolveDominantFont(
   // to combine layers for performance" permits layout to ride the
   // surface snapshot for locality, but the authoritative values must
   // come from L03.
+  //
+  // Theme-slot fallback (Task A4 follow-up, 2026-04-23): when the L03
+  // cascade leaves `fontFamilyAscii` absent but carries an `asciiTheme`
+  // slot reference (ECMA-376 §17.3.2.26 — `<w:rFonts w:asciiTheme="minorHAnsi"/>`),
+  // resolve through `themeFonts` — mirrors L03's own
+  // `resolveRunFontFamily` behavior so the empirical measurement
+  // backend doesn't fall to the DEFAULT factor for theme-referenced
+  // paragraphs. CCEP templates with Tahoma/Calibri theme-bound bodies
+  // (e.g. `EU & Global IT Services SOW`) land here.
   let fontFamily: string | undefined;
   let fontSizeHalfPoints: number | undefined;
+  let resolvedViaTheme = false;
   let maxTextLength = 0;
 
+  const resolveThemeSlot = (
+    slot: string | undefined,
+  ): string | undefined => {
+    if (!slot || !themeFonts) return undefined;
+    return slot.startsWith("major") ? themeFonts.majorFont : themeFonts.minorFont;
+  };
+
   for (const segment of block.segments) {
     if (segment.kind !== "text") continue;
     const resolved = segment.resolvedRunFormatting;
@@ -315,11 +345,23 @@ function resolveDominantFont(
     // already layered docDefaults → paragraph style → character style →
     // direct overrides; the markAttrs fallback only applies when the
     // block was viewport-culled (resolvedRunFormatting absent).
-    const segFontFamily =
-      resolved?.fontFamilyAscii ??
-      resolved?.fontFamily ??
-      resolved?.fontFamilyHAnsi ??
-      segment.markAttrs?.fontFamily;
+    // Script precedence: ascii → hAnsi → eastAsia → cs. Within each
+    // script, concrete family wins over theme slot.
+    let segResolvedViaTheme = false;
+    let segFontFamily: string | undefined;
+    if (resolved?.fontFamilyAscii) {
+      segFontFamily = resolved.fontFamilyAscii;
+    } else if (resolved?.asciiTheme && themeFonts) {
+      segFontFamily = resolveThemeSlot(resolved.asciiTheme);
+      if (segFontFamily) segResolvedViaTheme = true;
+    } else if (resolved?.fontFamilyHAnsi) {
+      segFontFamily = resolved.fontFamilyHAnsi;
+    } else if (resolved?.hAnsiTheme && themeFonts) {
+      segFontFamily = resolveThemeSlot(resolved.hAnsiTheme);
+      if (segFontFamily) segResolvedViaTheme = true;
+    } else {
+      segFontFamily = resolved?.fontFamily ?? segment.markAttrs?.fontFamily;
+    }
     const segFontSize =
       resolved?.fontSizeHalfPoints ?? segment.markAttrs?.fontSize;
     const textLength = segment.text.length;
@@ -328,6 +370,7 @@ function resolveDominantFont(
       maxTextLength = textLength;
       if (typeof segFontFamily === "string") {
         fontFamily = segFontFamily;
+        resolvedViaTheme = segResolvedViaTheme;
       }
       if (typeof segFontSize === "number") {
         fontSizeHalfPoints = segFontSize;
@@ -341,8 +384,32 @@ function resolveDominantFont(
     ? (FONT_AVG_CHAR_WIDTH[normalizedFamily] ?? DEFAULT_FONT_AVG_CHAR_WIDTH)
     : DEFAULT_FONT_AVG_CHAR_WIDTH;
 
+  // Theme-slot safety margin: xAvgCharWidth is derived from a fixed
+  // character-frequency sample and undercounts character-class-skewed
+  // content (legal-contract prose — heavy on capitalized defined terms
+  // and digits). When L03 left the paragraph bound to a theme slot and
+  // we resolved through `themeFonts`, the actual rendered width on these
+  // paragraphs is systematically wider than `xAvgCharWidth × chars`.
+  // Apply a safety multiplier — calibrated against 6 CCEP docs
+  // (coord-04 §1.18.2 regression finding). 2.4× is the minimum that
+  // restores `eu-global-it-services-sow` to its pre-v47 exact-parity
+  // (17/17) without regressing any of the 4 docs that won at v47.
+  // Concrete-family paragraphs keep the `xAvgCharWidth` factor untouched.
+  // The v49 safety multiplier was calibrated against a corpus where
+  // `<w:br w:type="page"/>` was being silently dropped by
+  // `src/io/normalize/normalize-text.ts::normalizeInlineChildren` (no
+  // `case "page_break"` → fell through). With the normalize fix landed
+  // alongside this change, real page-breaks now force pagination and
+  // SOW lands at 17/17 exact parity at multiplier 1.0 — i.e. theme-slot
+  // resolution is still useful for identifying the font, but the
+  // character-width factor does not need additional inflation.
+  const themeSafetyMultiplier = 1.0;
+  const effectiveFactor = resolvedViaTheme
+    ? charWidthFactor * themeSafetyMultiplier
+    : charWidthFactor;
+
   // Average char width in twips = factor * (fontSize in half-points)
-  const avgCharWidth = Math.max(96, Math.round(charWidthFactor * effectiveSize));
+  const avgCharWidth = Math.max(96, Math.round(effectiveFactor * effectiveSize));
 
   return { fontSizeHalfPoints: effectiveSize, avgCharWidth, fontFamily };
 }
@@ -403,11 +470,39 @@ function resolveTabStops(
     leader: tab.leader,
   });
 
-  if (numSurfaceTabs && numSurfaceTabs.length > 0 && surfaceTabs && surfaceTabs.length > 0) {
+  // Style-cascaded tab stops (coord-04 §1.19.a). L03's
+  // `resolveEffectiveParagraphFormatting` merges `docDefaults.paragraph.tabs`
+  // → basedOn-chain style tabs → direct `w:tabs`, with direct winning on
+  // conflicting positions. The resolved merged set is deposited on
+  // `block.resolvedParagraphFormatting.tabStops` in canonical shape
+  // (`{ position, align, leader }`). Paragraphs styled TOC1/TOC2/etc.
+  // typically have no direct `w:tabs`; the style cascade is the only
+  // source. Without this fallback, TOC entries measured under L04 behave
+  // as if no tab-stops exist — right-aligned page-number columns get no
+  // dedicated tab-stop and the paragraph measurement collapses the tab
+  // advance to the default tab interval.
+  const cascadeTabs = block.resolvedParagraphFormatting?.tabStops;
+  const normalizeCanonical = (tab: {
+    position: number;
+    align: string;
+    leader?: string;
+  }): LayoutTabStop => ({
+    position: tab.position,
+    align: tab.align,
+    leader: tab.leader,
+  });
+
+  const paraTabs: LayoutTabStop[] = surfaceTabs && surfaceTabs.length > 0
+    ? surfaceTabs.map(normalize)
+    : cascadeTabs && cascadeTabs.length > 0
+      ? cascadeTabs.map(normalizeCanonical)
+      : [];
+
+  if (numSurfaceTabs && numSurfaceTabs.length > 0 && paraTabs.length > 0) {
     const numPositions = new Set(numSurfaceTabs.map((t) => t.pos));
     const merged = [
       ...numSurfaceTabs.map(normalize),
-      ...surfaceTabs.filter((t) => !numPositions.has(t.pos)).map(normalize),
+      ...paraTabs.filter((t) => !numPositions.has(t.position)),
     ];
     return merged.sort((a, b) => a.position - b.position);
   }
@@ -416,8 +511,8 @@ function resolveTabStops(
     return numSurfaceTabs.map(normalize).sort((a, b) => a.position - b.position);
   }
 
-  if (surfaceTabs && surfaceTabs.length > 0) {
-    return surfaceTabs.map(normalize).sort((a, b) => a.position - b.position);
+  if (paraTabs.length > 0) {
+    return [...paraTabs].sort((a, b) => a.position - b.position);
   }
 
   return [];

package/src/runtime/markdown-sanitizer.ts

@@ -47,17 +47,34 @@ export function sanitizeMarkdown(raw: string): SanitizeResult {
     (_match, addr: string) => `<${addr}>`,
   );
 
+  // SEC-UI-01 (2026-04-23): strip HTML tags strictly.
+  //
+  // Prior implementation preserved any match containing `://`, `@`, or `:` as
+  // a heuristic for autolinks. That let `<img onerror="alert(1)" src="x:y">`
+  // and `<a href="javascript:alert(1)">` and SVG `<use xlink:href="..."/>`
+  // through — the colon in an attribute value triggered preservation.
+  //
+  // The autolink pre-passes above (scheme URI + email form) already leave
+  // proper autolinks as `<scheme:target>` or `<user@host>`. They are the only
+  // angle-bracketed forms that should survive this strip. Anything else —
+  // anything with attributes, anything with whitespace inside the brackets,
+  // anything with quoted attribute content — is HTML-shaped and must be
+  // removed regardless of whether its internals happen to contain `:` / `@`.
+  const AUTOLINK_SCHEME_RE =
+    /^<[a-zA-Z][a-zA-Z0-9+.-]*:[^\s<>"'`]+>$/;
+  const AUTOLINK_EMAIL_RE =
+    /^<[A-Za-z0-9][A-Za-z0-9._%+-]*@[A-Za-z0-9.-]+\.[A-Za-z]{2,}>$/;
   const strippedHtml = text.replace(
     // Require a recognisable HTML tag name so we do not strip safe
     // autolinks that survived the pass above (email autolinks, bare URIs).
     /<\/?([A-Za-z][A-Za-z0-9-]*)(\s[^>]*)?\/?>/g,
     (match, tagName: string) => {
-      // Skip angle-bracket content that looks like an autolink we just
-      // approved (email or scheme URI).
-      if (match.includes("://") || match.includes("@") || match.includes(":")) {
+      // Preserve ONLY pure autolink shape. Any attributes / whitespace /
+      // quotes → definitely HTML, strip.
+      if (AUTOLINK_SCHEME_RE.test(match) || AUTOLINK_EMAIL_RE.test(match)) {
         return match;
       }
-      // Also skip plain URIs like `<example.com>` — rare, but preserve.
+      // Preserve plain URIs like `<example.com>` — rare, but benign.
       if (/^[a-z]+\.[a-z]/.test(tagName)) {
         return match;
       }

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

@@ -353,7 +353,27 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
 // Internals
 // ---------------------------------------------------------------------------
 
-const PAGE_GAP_PX = 16;
+/**
+ * Inter-page gap in CSS pixels — the vertical gutter the kernel reserves
+ * between adjacent page frames in `RenderPage[]` Y coordinates.
+ *
+ * **Reconciled to 48 px on 2026-04-23 (refactor/10 Slice L11-3, delegated
+ * from refactor/05 closureBlockers.16/48px-gap-reconciliation +
+ * refactor/05 handover §5 deferred item 1).** Previously 16 px while the
+ * DOM page-break widget at `pm-page-break-decorations.ts:38` rendered a
+ * 48 px inter-page gap, causing a 32 px-per-page-boundary drift between
+ * kernel-reported `frame.pages[i].topPx` and the actual painted scroll
+ * position. Drift was previously compensated for by the chrome layer's
+ * DOM-measurement fallback path (overlay-rects "experimental" notice
+ * + scroll-anchor's `prepaintFallback`); reconciliation moves the
+ * geometry-direct warm path from "experimental" to "production".
+ *
+ * Consumer impact: every `topPx` value on `frame.pages[i]` for `i >= 1`
+ * shifts by +32 px per preceding page boundary. `LAYOUT_ENGINE_VERSION`
+ * bumped in the same commit so persisted laycache envelopes auto-
+ * invalidate.
+ */
+const PAGE_GAP_PX = 48;
 
 function buildPage(
   page: PublicPageNode,

package/src/runtime/scopes/audit-bundle.ts

@@ -29,6 +29,11 @@ export interface EmitScopeActionAuditInputs {
   readonly validation: ValidationResult;
   readonly emittedAtUtc: string;
   readonly bus?: TelemetryBus;
+  /**
+   * Gap A — revision IDs the runtime authored during this apply.
+   * Populated for suggest-mode dispatch; omitted for direct-edit.
+   */
+  readonly authoredRevisionIds?: readonly string[];
 }
 
 export function buildScopeActionAudit(
@@ -52,6 +57,9 @@ export function buildScopeActionAudit(
     ),
     validation: inputs.validation,
     emittedAtUtc: inputs.emittedAtUtc,
+    ...(inputs.authoredRevisionIds && inputs.authoredRevisionIds.length > 0
+      ? { authoredRevisionIds: Object.freeze([...inputs.authoredRevisionIds]) }
+      : {}),
   };
 }
 

package/src/runtime/scopes/compiler-service.ts

@@ -339,6 +339,7 @@ export function createScopeCompilerService(
             ]),
             warnings: Object.freeze([]),
           },
+          authoredRevisionIds: Object.freeze([]),
         };
       }
       // Caller-supplied proposedContent takes precedence (structured-

package/src/runtime/scopes/enumerate-scopes.ts

@@ -256,6 +256,46 @@ function buildClassificationIndex(
   return out;
 }
 
+/**
+ * Coord-08 §9 / A3 — read a caller-set `stableRefHint` off an overlay
+ * scope's metadata. Returns the requested strategy when the field is
+ * present AND feasible for the compiler to honor, `null` otherwise
+ * (falls back to the default selection).
+ *
+ * Feasibility matrix:
+ *   - `"scope-id"` / `"semantic-path"` — always feasible.
+ *   - `"bookmark"` — requires a bookmark registered at the block; no
+ *     bookmark-lookup is wired in phase 1, so falls back.
+ *   - `"runtime-handle"` — not a persistent strategy; ignored.
+ *   - Unknown string — ignored.
+ */
+function stableRefHintForScopeId(
+  scopeId: string,
+  overlay: WorkflowOverlay | null | undefined,
+): ScopeHandle["stableRef"]["kind"] | null {
+  if (!overlay) return null;
+  const scope = overlay.scopes.find(
+    (s: WorkflowScope) => s.scopeId === scopeId,
+  );
+  if (!scope || !scope.metadata) return null;
+  const hintField = scope.metadata.find(
+    (f: WorkflowScopeMetadataField) => f.key === "stableRefHint",
+  );
+  if (!hintField || typeof hintField.value !== "string") return null;
+  switch (hintField.value) {
+    case "scope-id":
+    case "semantic-path":
+      return hintField.value;
+    case "bookmark":
+    case "runtime-handle":
+      // Declared-but-not-implementable: fall back. Adding bookmark
+      // lookup is a phase-2 extension; see coord-08 §9.
+      return null;
+    default:
+      return null;
+  }
+}
+
 /**
  * Walk paragraph children and return the first scope-marker id that
  * *starts* inside the paragraph. When a paragraph carries multiple
@@ -417,6 +457,26 @@ export function enumerateScopes(
         markerScopeId !== null ? "marker-backed" : "derived";
       const rangePrecision: ScopeHandle["rangePrecision"] =
         markerScopeId !== null ? "marker-backed" : "canonical";
+      // Coord-08 §9 — honor caller-set stableRefHint when present. Only
+      // consulted on marker-backed paragraphs (derived scopes have no
+      // overlay entry to carry a hint).
+      const hint =
+        markerScopeId !== null
+          ? stableRefHintForScopeId(markerScopeId, inputs.overlay)
+          : null;
+      const defaultMarkerStable =
+        markerScopeId !== null
+          ? ({ kind: "scope-id", value: markerScopeId } as const)
+          : undefined;
+      const stableRefOverride =
+        hint === "semantic-path"
+          ? ({
+              kind: "semantic-path" as const,
+              value: semanticPath.join("/"),
+            })
+          : hint === "scope-id" && markerScopeId !== null
+            ? ({ kind: "scope-id" as const, value: markerScopeId })
+            : defaultMarkerStable;
       const handle = buildHandle(
         scopeId,
         documentId,
@@ -424,9 +484,7 @@ export function enumerateScopes(
         provenance,
         rangePrecision,
         undefined,
-        markerScopeId !== null
-          ? { kind: "scope-id", value: markerScopeId }
-          : undefined,
+        stableRefOverride,
       );
       const classifications =
         markerScopeId !== null

package/src/runtime/scopes/replacement/apply.ts

@@ -66,6 +66,17 @@ export interface ApplyScopeReplacementResult {
   readonly audit?: ScopeActionAudit;
   readonly plan?: RuntimeOperationPlan;
   readonly scope?: SemanticScope;
+  /**
+   * Gap A (coord-08 post-Slice-7 integration) — revision IDs authored
+   * by the runtime during this apply. Populated for suggest-mode
+   * dispatch (where `text-insert-tracked` / `text-delete-tracked`
+   * commands author `RevisionRecord` entries in
+   * `review.revisions`); empty array for direct-edit (no revisions
+   * authored). Agents can pass each id into `ai.acceptRevision` /
+   * `ai.rejectRevision` to land or discard the proposal without
+   * having to diff the runtime's revision map themselves.
+   */
+  readonly authoredRevisionIds: readonly string[];
 }
 
 function documentHash(doc: CanonicalDocumentEnvelope): string {
@@ -117,7 +128,12 @@ export function applyScopeReplacement(
       ]),
       warnings: Object.freeze([]),
     };
-    return { applied: false, reason: "scope-not-resolvable", validation };
+    return {
+      applied: false,
+      reason: "scope-not-resolvable",
+      validation,
+      authoredRevisionIds: Object.freeze([]),
+    };
   }
 
   const verdict = composeScopeValidation({
@@ -139,6 +155,7 @@ export function applyScopeReplacement(
       reason: "validation-blocked",
       validation: verdict,
       scope: resolvedScope,
+      authoredRevisionIds: Object.freeze([]),
     };
   }
 
@@ -190,19 +207,44 @@ export function applyScopeReplacement(
       blockedReasons: Object.freeze([blocker]),
       warnings: verdict.warnings,
     };
+    // Coord-08 U5 — `reason` mirrors `blockers[0]` for symmetry. Agents
+    // reading either channel at the top level see the same
+    // most-actionable signal (`compile-refused:<kind>[:operation-not-
+    // implemented:<op>]`). Pre-U5 (before 2026-04-23) `reason` was the
+    // bare prefix `"compile-refused"` — callers had to descend into
+    // `validation.blockedReasons[0]` to recover the suffix.
     return {
       applied: false,
-      reason: "compile-refused",
+      reason: blocker,
       validation: refused,
       scope: resolvedScope,
+      authoredRevisionIds: Object.freeze([]),
     };
   }
 
   const documentHashBefore = documentHash(docBefore);
 
+  // Gap A — capture revision-map keys before dispatch so we can diff
+  // post-apply and surface the authored ids to agents. Suggest-mode
+  // dispatch (text-insert-tracked / text-delete-tracked) authors
+  // insertion + deletion `RevisionRecord` entries in
+  // `canonicalDocument.review.revisions`; direct-edit dispatch touches
+  // no revisions. The diff approach is side-channel-free and doesn't
+  // require plumbing a new return value through the runtime's
+  // applyTextCommandInActiveStory seam.
+  const revisionsBefore = new Set(
+    Object.keys(docBefore.review.revisions ?? {}),
+  );
+
   inputs.sink.applyScopeReplacement(plan);
 
-  const documentHashAfter = documentHash(inputs.sink.getCanonicalDocument());
+  const docAfter = inputs.sink.getCanonicalDocument();
+  const documentHashAfter = documentHash(docAfter);
+
+  const authoredRevisionIds: string[] = [];
+  for (const id of Object.keys(docAfter.review.revisions ?? {})) {
+    if (!revisionsBefore.has(id)) authoredRevisionIds.push(id);
+  }
 
   const audit = emitScopeActionAudit({
     actionId: inputs.actionId ?? "replacement",
@@ -215,6 +257,9 @@ export function applyScopeReplacement(
     plan,
     validation: verdict,
     emittedAtUtc: inputs.emittedAtUtc,
+    ...(authoredRevisionIds.length > 0
+      ? { authoredRevisionIds }
+      : {}),
     ...(inputs.bus ? { bus: inputs.bus } : {}),
   });
 
@@ -224,5 +269,6 @@ export function applyScopeReplacement(
     audit,
     plan,
     scope: resolvedScope,
+    authoredRevisionIds: Object.freeze([...authoredRevisionIds]),
   };
 }

package/src/runtime/scopes/semantic-scope-types.ts

@@ -426,6 +426,14 @@ export interface ScopeActionAudit {
   }[];
   readonly validation: ValidationResult;
   readonly emittedAtUtc: string;
+  /**
+   * Gap A (coord-08 post-Slice-7 integration) — revision IDs authored
+   * by the runtime during this apply. Populated for suggest-mode
+   * dispatch (tracked insert + delete revisions); omitted for direct-
+   * edit. Agents chain into `ai.acceptRevision` / `ai.rejectRevision`
+   * to land / discard the proposal without diffing the revision map.
+   */
+  readonly authoredRevisionIds?: readonly string[];
 }
 
 /* -------------------------------------------------------------------------

package/src/runtime/surface-projection.ts

@@ -1400,6 +1400,25 @@ function appendInlineSegments(
         state: "locked-preserve-only",
       });
       return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "page_break":
+      // coord-04 §1.18.5 / coord-03 §11 — `<w:br w:type="page"/>` forces
+      // subsequent content onto a new page. Mirror `column_break`'s
+      // quiet-marker emission (label-based detection). L04 pagination
+      // reads `segment.label === "Page break"` via `hasPageBreak` and
+      // forces `pushPage(block.to)` after placing the carrying block.
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "opaque_inline",
+        from: start,
+        to: start + 1,
+        fragmentId: "",
+        warningId: "",
+        label: "Page break",
+        detail: "Word hard page break marker — pagination forces a new page here.",
+        presentation: "quiet-marker",
+        state: "locked-preserve-only",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
     case "footnote_ref":
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -2070,6 +2089,8 @@ function summarizePreviewInline(node: InlineNode): string {
       return node.char ? String.fromCodePoint(parseInt(node.char, 16)) : "\uFFFD";
     case "column_break":
       return "[Column break]";
+    case "page_break":
+      return "[Page break]";
     case "chart_preview":
       return "[Embedded chart]";
     case "smartart_preview":
@@ -2376,6 +2397,7 @@ function cloneMarks(marks: TextMark[]): {
         break;
       case "highlight":
         highlightColor = mark.color;
+        supported.push("highlight");
         break;
       case "charSpacing":
         attrs.charSpacing = mark.val;

package/src/runtime/workflow/coordinator.ts

@@ -838,6 +838,9 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
       anchor: publicAnchor,
       ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
       ...(params.label ? { label: params.label } : {}),
+      ...(params.scopeMetadataFields && params.scopeMetadataFields.length > 0
+        ? { metadata: [...params.scopeMetadataFields] }
+        : {}),
     };
 
     deps.dispatch({

package/src/runtime/workflow/scope-writer.ts

@@ -34,6 +34,7 @@ import type {
   RuntimeRenderSnapshot,
   WorkflowMetadataEntry,
   WorkflowMetadataPersistence,
+  WorkflowScopeMetadataField,
   WorkflowScopeMode,
 } from "../../api/public-types.ts";
 
@@ -68,6 +69,26 @@ export interface CreateScopeFromBlockIdInput {
    * completeness since `BoundaryAssoc` typing allows them.
    */
   readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+  /**
+   * Coord-08 §9 / coord-09 §1.13 (A3) — caller-steerable identity
+   * strategy for the enumerated scope's `ScopeHandle.stableRef`.
+   * Stored as an overlay-scope metadata field (`key: "stableRefHint"`)
+   * at creation time; the L08 compiler reads it back during
+   * enumeration and honors the requested kind when the strategy is
+   * feasible, falling back to its default selection otherwise (see
+   * `src/runtime/scopes/enumerate-scopes.ts::stableRefHintForScopeId`
+   * for the feasibility matrix).
+   *
+   * Today's honored values: `"scope-id"` / `"semantic-path"`. The
+   * `"bookmark"` + `"runtime-handle"` kinds currently fall back (no
+   * bookmark-lookup wired in phase 1; runtime-handle is a transient
+   * strategy with no durability meaning).
+   */
+  readonly stableRefHint?:
+    | "scope-id"
+    | "bookmark"
+    | "semantic-path"
+    | "runtime-handle";
 }
 
 export type CreateScopeFromBlockIdResult =
@@ -172,6 +193,16 @@ export function createScopeFromBlockId(
   if (!anchor) {
     return { status: "block-not-found", blockId: input.blockId };
   }
+  // Coord-08 §9 — encode stableRefHint as an overlay-scope metadata
+  // field so the L08 compiler can read it back at enumeration time.
+  const scopeMetadataFields: WorkflowScopeMetadataField[] = [];
+  if (input.stableRefHint !== undefined) {
+    scopeMetadataFields.push({
+      key: "stableRefHint",
+      valueType: "string",
+      value: input.stableRefHint,
+    });
+  }
   const result: AddScopeResult = runtime.addScope({
     anchor,
     mode: input.mode,
@@ -180,6 +211,9 @@ export function createScopeFromBlockId(
     metadata: input.metadata,
     storyTarget: input.storyTarget,
     label: input.label,
+    ...(scopeMetadataFields.length > 0
+      ? { scopeMetadataFields }
+      : {}),
   });
   return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
 }