@beyondwork/docx-react-component 1.0.74 → 1.0.75

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.74",
+  "version": "1.0.75",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -5625,6 +5625,13 @@ export interface ShortcutDelegationContext {
   selectionRange: SelectionSnapshot;
 }
 
+/**
+ * Resolver contract (`resolveChromeVisibilityForPreset`): every field on
+ * this interface is REQUIRED — no `| undefined`, no optional sugar. Each
+ * preset's default-visibility block (`src/api/v3/ui/chrome-preset-model.ts`)
+ * MUST set every field. If you add a new surface visibility flag, add it
+ * here AND to all preset default blocks in the same commit.
+ */
 export interface WordReviewEditorChromeVisibility {
   toolbar: boolean;
   alerts: boolean;

package/src/api/v3/runtime/workflow.ts

@@ -11,12 +11,16 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
+  EditorStoryTarget,
   OverlayKind,
   OverlayVisibilityPolicy,
   WorkflowMarkupModePolicy,
 } from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
-import { createScopeFromBlockId } from "../../../runtime/workflow/scope-writer.ts";
+import {
+  createScopeFromAnchor,
+  createScopeFromBlockId,
+} from "../../../runtime/workflow/scope-writer.ts";
 import { attachScopeMetadata } from "../../../runtime/workflow/metadata-writer.ts";
 import {
   DEFAULT_REGISTRY_ENTRIES,
@@ -113,6 +117,59 @@ export interface CreateScopeResult {
   readonly status: "created" | "block-not-found";
 }
 
+/**
+ * Input for `createScopeFromAnchor` — sub-block marker-backed scope.
+ *
+ * Use this variant when the scope must bracket a range *within* a block
+ * (a phrase inside a paragraph) or across blocks (a selection that
+ * spans paragraph boundaries). For whole-block scopes, prefer
+ * `createScope({blockId})` — it stays block-aligned after edits at the
+ * block boundary.
+ *
+ * The `from`/`to` positions are consumed **once** at creation. After
+ * this call returns, use the returned `scopeId` as the reference. Do
+ * not cache, store, or reuse the positions — they are positional
+ * queries (KI-P9), valid only in the document state they were captured
+ * in. The scope itself is marker-backed and travels with its bracketed
+ * content through any number of subsequent edits.
+ */
+export interface CreateScopeFromAnchorInput {
+  readonly anchor: {
+    /** Zero-based surface offset, inclusive. Must be `>= 0`. */
+    readonly from: number;
+    /** Zero-based surface offset, exclusive of the marker slot. Must be `>= from` and `<= storyLength`. */
+    readonly to: number;
+    /** Non-main-body story (footnote / header / endnote). Defaults to `{kind:"main"}`. */
+    readonly storyTarget?: EditorStoryTarget;
+  };
+  readonly mode?: "edit" | "suggest" | "comment" | "view";
+  readonly label?: string;
+  readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+  readonly stableRefHint?:
+    | "scope-id"
+    | "bookmark"
+    | "semantic-path"
+    | "runtime-handle";
+}
+
+export type CreateScopeFromAnchorResult =
+  | { readonly scopeId: string; readonly status: "created" }
+  | {
+      readonly scopeId: "";
+      readonly status: "range-invalid";
+      readonly reason:
+        | "from-negative"
+        | "to-less-than-from"
+        | "range-exceeds-story-length";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      /** Agent-actionable single-sentence explanation. Safe to surface to LLM tool replies as-is. */
+      readonly message: string;
+      /** Machine-routable next-step hint (`"clamp-from-to-zero"` / `"swap-from-and-to"` / `"clamp-to-to-storyLength-or-pick-a-different-range"`). */
+      readonly nextStep: string;
+    };
+
 export const createScopeMetadata: ApiV3FnMetadata = {
   name: "runtime.workflow.createScope",
   status: "live-with-adapter",
@@ -129,6 +186,32 @@ export const createScopeMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.workflow.createScope",
 };
 
+export const createScopeFromAnchorMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.createScopeFromAnchor",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-from-anchor-live.test.ts",
+    commit: "pending",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "scope-created",
+    expectedDelta:
+      "rail shows new scope chip for the sub-block range; editor surface refreshes with inline markers planted at from/to",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "scope-creation",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.workflow.createScopeFromAnchor. Companion to createScope({blockId}) for sub-block ranges. Consumes from/to once to plant inline scope_marker_start/end; the returned scopeId is the durable reference (KI-P9).",
+};
+
 export interface AttachMetadataInput {
   readonly scopeId: string;
   readonly metadataId: string;
@@ -411,6 +494,52 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
       return { scopeId: adapterResult.scopeId, status: "created" };
     },
 
+    createScopeFromAnchor(
+      input: CreateScopeFromAnchorInput,
+    ): CreateScopeFromAnchorResult {
+      // @endStateApi — live-with-adapter. Delegates to the layer-06
+      // scope-writer with the anchor range passed through directly.
+      // Bounds are validated against the story length; out-of-bounds
+      // ranges return a typed `range-invalid` discriminator rather than
+      // inventing a scopeId.
+      const adapterResult = createScopeFromAnchor(runtime, {
+        anchor: input.anchor,
+        mode: input.mode,
+        label: input.label,
+        ...(input.assoc ? { assoc: input.assoc } : {}),
+        ...(input.stableRefHint
+          ? { stableRefHint: input.stableRefHint }
+          : {}),
+      });
+      emitUxResponse(runtime, {
+        apiFn: createScopeFromAnchorMetadata.name,
+        intent: createScopeFromAnchorMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: createScopeFromAnchorMetadata.uxIntent.expectedDelta,
+        actualDelta:
+          adapterResult.status === "created"
+            ? {
+                kind: "inline-change",
+                payload: { scopeId: adapterResult.scopeId },
+              }
+            : undefined,
+      });
+      if (adapterResult.status !== "created") {
+        return {
+          scopeId: "",
+          status: "range-invalid",
+          reason: adapterResult.reason,
+          from: adapterResult.from,
+          to: adapterResult.to,
+          storyLength: adapterResult.storyLength,
+          message: adapterResult.message,
+          nextStep: adapterResult.nextStep,
+        };
+      }
+      return { scopeId: adapterResult.scopeId, status: "created" };
+    },
+
     getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null {
       // @endStateApi — live. Class-A policy read; composition with
       // class-C local preference lives in L10 (`ui.overlays.getVisibility`).

package/src/io/ooxml/parse-headers-footers.ts

@@ -17,6 +17,7 @@ import { resolveHighlightColor } from "./highlight-colors.ts";
 import type { ParseDrawingOpts } from "./parse-drawing.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
+import { isSafeTableFieldInstruction } from "./table-opaque-preservation.ts";
 import { parseXmlWithOffsets as parseXml } from "./xml-parser.ts";
 import { localName, readStringAttr } from "./xml-attr-helpers.ts";
 import {
@@ -1018,8 +1019,12 @@ function containsRiskyElement(element: XmlElementNode): boolean {
       const instruction =
         readStringAttr(child, "w:instr") ??
         extractTextContent(child);
-      const classification = classifyFieldInstruction(instruction);
-      if (!isSafeSecondaryStoryFieldFamily(classification.family)) {
+      // Coord-01 §11 unification (2026-04-24): the field-safety check
+      // is delegated to the shared `isSafeTableFieldInstruction` helper
+      // so body-direct + secondary-story tables apply the same
+      // allowlist. Legacy form fields (FORMTEXT/FORMCHECKBOX/
+      // FORMDROPDOWN) now pass here just like in main-story tables.
+      if (!isSafeTableFieldInstruction(instruction)) {
         return true;
       }
       continue;
@@ -1041,17 +1046,6 @@ function containsRiskyElement(element: XmlElementNode): boolean {
   return false;
 }
 
-function isSafeSecondaryStoryFieldFamily(family: string): boolean {
-  return (
-    family === "REF" ||
-    family === "PAGEREF" ||
-    family === "NOTEREF" ||
-    family === "TOC" ||
-    family === "PAGE" ||
-    family === "NUMPAGES"
-  );
-}
-
 function parseSimpleTableElement(
   tblElement: XmlElementNode,
   sourceXml: string,

package/src/io/ooxml/parse-main-document.ts

@@ -41,6 +41,7 @@ import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 import { parseObject } from "./parse-object.ts";
 import { parseDrawingFrame } from "./parse-drawing.ts";
 import { readFrameProperties } from "./parse-paragraph-formatting.ts";
+import { tableRequiresOpaquePreservation } from "./table-opaque-preservation.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
@@ -2020,37 +2021,12 @@ function readCellCnfStyle(node: XmlElementNode): string | undefined {
  * Tables matching this check stay opaque until the respective features
  * are implemented in the table editing path.
  */
-function tableRequiresOpaquePreservation(rawXml: string): boolean {
-  // Safe table-local content now includes hyperlinks, bookmarks, comments,
-  // nested tables, floating images, VML preview atoms, and bounded field
-  // families already owned by the current field slice. Risky table-local
-  // semantics still fail closed to preserve-only.
-  if (/<w:(ins|del|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag)\b/.test(rawXml)) {
-    return true;
-  }
-
-  const simpleInstructions = [...rawXml.matchAll(/\bw:instr="([^"]*)"/g)].map((match) => match[1] ?? "");
-  const complexInstructions = extractComplexFieldInstructions(rawXml);
-  for (const instruction of [...simpleInstructions, ...complexInstructions]) {
-    const classification = classifyFieldInstruction(instruction);
-    if (!isSafeMainStoryTableFieldFamily(classification.family)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-function isSafeMainStoryTableFieldFamily(family: string): boolean {
-  return (
-    family === "REF" ||
-    family === "PAGEREF" ||
-    family === "NOTEREF" ||
-    family === "TOC" ||
-    family === "PAGE" ||
-    family === "NUMPAGES"
-  );
-}
+// `tableRequiresOpaquePreservation` now lives in
+// `src/io/ooxml/table-opaque-preservation.ts` as a shared helper used by
+// `parse-main-document.ts`, `parse-headers-footers.ts`, and
+// `parse-footnotes.ts`. Unified 2026-04-24 per coord-01 §11 to stop the
+// three parsers from drifting out of alignment. The top-of-file import
+// `tableRequiresOpaquePreservation` points at that module.
 
 function extractComplexFieldInstructions(rawXml: string): string[] {
   const tokenPattern =

package/src/io/ooxml/table-opaque-preservation.ts

@@ -0,0 +1,171 @@
+/**
+ * Unified table-opaque-preservation predicate — shared across
+ * `parse-main-document.ts`, `parse-headers-footers.ts`, and
+ * `parse-footnotes.ts` so the three parsers agree on which tables can
+ * be promoted to the typed `TableNode` shape and which must fall back
+ * to `opaque_block` for lossless rawXml round-trip.
+ *
+ * ## History
+ *
+ * Before this module existed, each of the three parsers maintained its
+ * own divergent allowlist. That divergence drove the coord-01 §11
+ * finding (2026-04-24): legacy form fields (`FORMTEXT`,
+ * `FORMCHECKBOX`, `FORMDROPDOWN`) classify as `UNKNOWN` under
+ * `FIELD_FAMILY_PATTERN` (which targets data-field families), so both
+ * the main-story and secondary-story table predicates rejected them
+ * even though the body-direct paragraph parser path (via
+ * `parseFFDataFromFldChar`) handles them correctly. The result was
+ * 58 cell paragraphs lost on APS Short Form because 2 body-direct
+ * tables flattened to opaque_block; 5 additional footer tables on
+ * the same doc also flatten (those carry `DOCPROPERTY` — a real data
+ * field, distinct from the legacy form-field case).
+ *
+ * ## Contract
+ *
+ * A `<w:tbl>` is "safe to parse as structured" iff NONE of the
+ * following are true:
+ *
+ * 1. **Revision markup.** `<w:ins>`, `<w:del>`, `<w:moveFrom>`,
+ *    `<w:moveTo>`, `<w:rPrChange>`, `<w:pPrChange>`,
+ *    `<w:tblPrChange>`, `<w:trPrChange>`, `<w:tcPrChange>`,
+ *    `<w:sectPrChange>`, `<w:cellIns>`, `<w:cellDel>`,
+ *    `<w:cellMerge>`, `<w:smartTag>`.
+ *    Rationale: tracked-change-aware table editing isn't implemented;
+ *    flattening preserves fidelity until it is.
+ *
+ * 2. **Field instruction outside the safe set.** Scan every
+ *    `w:instr` simple-field attribute + every `<w:instrText>` inside
+ *    a complex field (`<w:fldChar>begin</w:fldChar>...end`) and
+ *    classify via `classifyFieldInstruction`. If the classified
+ *    family isn't in `SAFE_TABLE_FIELD_FAMILIES` AND the instruction
+ *    isn't a legacy form field (`isLegacyFormFieldInstruction`), the
+ *    table flattens. The legacy-form-field short-circuit is the
+ *    coord-01 §11 fix — those tokens are fully supported by the cell
+ *    paragraph parser but classify as `UNKNOWN`.
+ *
+ * Extending this contract is a cross-layer architectural decision:
+ * widening `SAFE_TABLE_FIELD_FAMILIES` lets more tables parse as
+ * structured but commits the edit-command layer (L06/L08) to handle
+ * each field family's cell-level edit semantics. Keep this list
+ * aligned with the field families supported by the runtime
+ * formatting + scope-command pipeline.
+ */
+
+import { classifyFieldInstruction } from "./parse-fields.ts";
+
+/**
+ * Field families safe enough to leave a `<w:tbl>` in structured
+ * canonical form. Widening this set commits L06 / L08 to cell-level
+ * edit semantics for that family — don't expand opportunistically.
+ */
+export const SAFE_TABLE_FIELD_FAMILIES: ReadonlySet<string> = new Set([
+  "REF",
+  "PAGEREF",
+  "NOTEREF",
+  "TOC",
+  "PAGE",
+  "NUMPAGES",
+]);
+
+/**
+ * Revision + structural markup that forces table flattening.
+ */
+const RISKY_TABLE_MARKUP_RE =
+  /<w:(ins|del|moveFrom|moveTo|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag)\b/;
+
+const SIMPLE_FIELD_INSTR_RE = /\bw:instr="([^"]*)"/g;
+
+const COMPLEX_FIELD_TOKEN_RE =
+  /<(?:\w+:)?fldChar\b[^>]*?(?:\w+:)?fldCharType="(begin|separate|end)"[^>]*?(?:\/>|>[\s\S]*?<\/(?:\w+:)?fldChar>)|<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu;
+
+/**
+ * Decode the minimal set of XML entities that can appear inside an
+ * `instrText` payload. `classifyFieldInstruction` consumes the raw
+ * instruction text, so we normalize `&amp;` / `&quot;` / `&lt;` /
+ * `&gt;` / `&apos;` before handing it off. Matches the pre-existing
+ * behavior in `parse-main-document.ts::extractComplexFieldInstructions`.
+ */
+function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+/**
+ * Extract every complex-field instruction (`<w:fldChar
+ * fldCharType="begin">...<w:instrText>...</w:instrText>...</w:fldChar
+ * fldCharType="end">`) as a single concatenated instruction string.
+ * Mirrors `parse-main-document.ts::extractComplexFieldInstructions`.
+ */
+export function extractComplexFieldInstructionsFromRaw(rawXml: string): string[] {
+  const instructions: string[] = [];
+  let active = "";
+  let capturing = false;
+  for (const match of rawXml.matchAll(COMPLEX_FIELD_TOKEN_RE)) {
+    const [, fldCharType, instrText] = match;
+    if (fldCharType === "begin") {
+      active = "";
+      capturing = true;
+      continue;
+    }
+    if (fldCharType === "separate" || fldCharType === "end") {
+      if (capturing && active.trim().length > 0) instructions.push(active);
+      active = "";
+      capturing = false;
+      continue;
+    }
+    if (capturing && instrText !== undefined) active += decodeXmlEntities(instrText);
+  }
+  return instructions;
+}
+
+/**
+ * Legacy form fields (ECMA-376 §17.16.21) — `FORMTEXT`, `FORMCHECKBOX`,
+ * `FORMDROPDOWN`. These are fully supported by the body-direct
+ * paragraph parser via `parseFFDataFromFldChar` but classify as
+ * `UNKNOWN` under `FIELD_FAMILY_PATTERN` (which targets data-field
+ * families like REF / TOC / MERGEFIELD). Short-circuiting them lets
+ * form-field cells stay in structured canonical tables instead of
+ * flattening the entire table to `opaque_block`. Coord-01 §11, 2026-04-24.
+ */
+export function isLegacyFormFieldInstruction(instruction: string): boolean {
+  return /^\s*(FORMTEXT|FORMCHECKBOX|FORMDROPDOWN)\b/i.test(instruction);
+}
+
+/**
+ * Decides whether a single field instruction (either `w:instr`
+ * attribute value or concatenated `instrText` run) is safe for
+ * structured-table parsing. Used by the shared predicate below;
+ * exposed for direct callers (the debug diagnostics script runs
+ * this to classify source instructions alongside the canonical).
+ */
+export function isSafeTableFieldInstruction(instruction: string): boolean {
+  if (isLegacyFormFieldInstruction(instruction)) return true;
+  const family = classifyFieldInstruction(instruction).family;
+  return SAFE_TABLE_FIELD_FAMILIES.has(family);
+}
+
+/**
+ * Shared `<w:tbl>` opaque-preservation predicate. Returns `true`
+ * when the table must fall back to `opaque_block` for lossless
+ * round-trip, `false` when `parseTable` / `parseSimpleTableElement`
+ * can promote it to a structured `TableNode`.
+ *
+ * Callers (`parse-main-document.ts`, `parse-headers-footers.ts`,
+ * `parse-footnotes.ts`) pass the raw XML of the `<w:tbl>` element.
+ */
+export function tableRequiresOpaquePreservation(rawXml: string): boolean {
+  if (RISKY_TABLE_MARKUP_RE.test(rawXml)) return true;
+
+  const simpleInstructions = [...rawXml.matchAll(SIMPLE_FIELD_INSTR_RE)].map(
+    (match) => match[1] ?? "",
+  );
+  const complexInstructions = extractComplexFieldInstructionsFromRaw(rawXml);
+  for (const instruction of [...simpleInstructions, ...complexInstructions]) {
+    if (!isSafeTableFieldInstruction(instruction)) return true;
+  }
+  return false;
+}

package/src/runtime/document-runtime.ts

@@ -1036,6 +1036,9 @@ function normalizeViewportRanges(
   for (let i = 1; i < cleaned.length; i += 1) {
     const next = cleaned[i]!;
     const last = merged[merged.length - 1]!;
+    // Mutation is safe: `last` is a fresh object from the `.map` step above,
+    // not aliased with any caller-provided input. The `Object.freeze` at the
+    // return site only runs after the merge loop finishes.
     if (next.start <= last.end) {
       if (next.end > last.end) last.end = next.end;
     } else {
@@ -1372,6 +1375,17 @@ export function createDocumentRuntime(
     | {
         revisionToken: string;
         activeStoryKey: string;
+        /**
+         * Serialized viewport ranges at build time. A surface snapshot is
+         * only reusable for a subsequent `getCachedSurface` call if the
+         * runtime's current `viewportRangesKey` matches — otherwise the
+         * cached snapshot realizes a different set of blocks as real vs
+         * placeholder-culled than the current runtime state demands.
+         * Pre-refactor/11b this was a (revisionToken, activeStoryKey) key
+         * only, which was silently stale-prone when callers applied new
+         * viewport ranges without also calling `requestViewportRefresh()`.
+         */
+        viewportRangesKey: string;
         snapshot: RuntimeRenderSnapshot["surface"];
       }
     | undefined;
@@ -1533,7 +1547,8 @@ export function createDocumentRuntime(
     if (
       cachedSurface &&
       cachedSurface.revisionToken === state.revisionToken &&
-      cachedSurface.activeStoryKey === activeStoryKey
+      cachedSurface.activeStoryKey === activeStoryKey &&
+      cachedSurface.viewportRangesKey === viewportRangesKey
     ) {
       return cachedSurface.snapshot;
     }
@@ -1549,8 +1564,13 @@ export function createDocumentRuntime(
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey,
+      viewportRangesKey,
       snapshot,
     };
+    // Keep the scroll-path fingerprint in lockstep so a subsequent
+    // `maybeRefreshSurfaceForViewport` sees the freshly-built snapshot
+    // and short-circuits instead of paying a redundant projection.
+    cachedSurfaceFingerprint = `${state.revisionToken}|${activeStoryKey}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     return snapshot;
   }
 
@@ -2394,6 +2414,7 @@ export function createDocumentRuntime(
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey: storyTargetKey(activeStory),
+      viewportRangesKey,
       snapshot: newSurface,
     };
     cachedRenderSnapshot = {
@@ -2427,6 +2448,12 @@ export function createDocumentRuntime(
 
   function invalidateDerivedRuntimeCaches(): void {
     cachedSurface = undefined;
+    // Keep the scroll-path fingerprint in lockstep with `cachedSurface`.
+    // Otherwise a post-commit `requestViewportRefresh` would compute a new
+    // fingerprint, see it differs from the stale pre-commit value, and
+    // rebuild + broadcast even when the freshly-hydrated `cachedSurface`
+    // already matches — wasted projection + listener fan-out.
+    cachedSurfaceFingerprint = null;
     cachedCompatibility = undefined;
     cachedComments = undefined;
     cachedTrackedChanges = undefined;

package/src/runtime/surface-projection.ts

@@ -106,6 +106,15 @@ export interface SurfaceProjectionOptions {
    * block stays real without realizing the document-scale gap between the
    * two). Callers still supplying the legacy scalar `viewportBlockRange` get
    * wrapped into a single-element array internally.
+   *
+   * **Invariant (caller responsibility):** intervals must be sorted ascending
+   * by `start` and non-overlapping. The projection function itself only
+   * checks membership — it does not sort or merge — so an unsorted input
+   * produces a correct `isInViewport` answer but the snapshot's
+   * `viewportBlockRanges` field carries the unnormalized shape to downstream
+   * consumers (e.g. the surface-build-key serializer). Runtime callers
+   * route through `DocumentRuntime.applyViewportRanges` which normalizes;
+   * if you call `createEditorSurfaceSnapshot` directly, normalize first.
    */
   viewportBlockRanges?: readonly { start: number; end: number }[] | null;
   /** @deprecated use `viewportBlockRanges`. Kept for back-compat; wrapped into a 1-element array when supplied alone. */

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

@@ -1,21 +1,26 @@
 /**
- * Layer-06 Slice 3 — `createScopeFromBlockId` adapter.
+ * Layer-06 — marker-backed workflow-scope creators.
  *
- * Resolves a `blockId` (paragraph/table/sdt-index identifier minted by
- * `src/runtime/surface-projection.ts`) into the `EditorAnchorProjection`
- * that `runtime.addScope` expects, then delegates to the existing
- * marker-backed scope creator.
+ * Two adapters share `runtime.addScope` as the underlying creator:
+ *
+ * 1. `createScopeFromBlockId` — resolves a block identifier
+ *    (`paragraph-N`, `table-N`, `sdt-N`) minted by
+ *    `src/runtime/surface-projection.ts` into the whole-block range.
+ *    Use when the scope should cover an entire paragraph / table / SDT.
+ *
+ * 2. `createScopeFromAnchor` — takes a sub-block `{from, to}` range
+ *    directly. Use when the scope should bracket a sub-span — a phrase
+ *    inside a paragraph, a cross-paragraph selection, a span from a
+ *    click + drag. Resolves the KI-P9 "positions-as-references" trap:
+ *    positions are consumed **once** at creation to plant the markers;
+ *    the returned `scopeId` is durable and survives subsequent editing.
+ *    Callers must stop carrying the positions after the call returns.
  *
  * Resolution walks the canonical document directly, not the surface
  * snapshot. Going through `runtime.getRenderSnapshot().surface.blocks`
  * would miss blocks the surface replaces with `placeholder-culled-*`
  * entries under viewport culling — a real reproducibility failure on
  * CCEP-size documents.
- *
- * This adapter unblocks `v3 runtime.workflow.createScope` graduation
- * from `mock` → `live-with-adapter`. Consumers that already carry a
- * full `EditorAnchorProjection` should continue calling
- * `runtime.addScope` directly.
  */
 
 import type {
@@ -220,3 +225,200 @@ export function createScopeFromBlockId(
 
 // Exported for tests that need to verify the resolver independently.
 export { resolveBlockAnchorFromCanonical };
+
+/**
+ * Input for `createScopeFromAnchor`. The `anchor` fields are a one-shot
+ * position query — the runtime plants inline `scope_marker_start` /
+ * `scope_marker_end` at these offsets and returns a marker-backed
+ * `scopeId`. From that moment the markers travel with their bracketed
+ * content through any number of edits; callers must re-resolve by
+ * `scopeId` afterward and MUST NOT store or reuse `from`/`to`.
+ */
+export interface CreateScopeFromAnchorInput {
+  /**
+   * Range in the current document state. `from` and `to` are measured
+   * in the editor's surface-projection offset space (the same space
+   * `findText`, `replaceText`, and `addScope` ranges use). Must satisfy
+   * `0 <= from <= to <= storyLength`.
+   */
+  readonly anchor: {
+    readonly from: number;
+    readonly to: number;
+    readonly storyTarget?: EditorStoryTarget;
+  };
+  readonly mode?: WorkflowScopeMode;
+  readonly label?: string;
+  readonly scopeId?: string;
+  readonly persistence?: WorkflowMetadataPersistence;
+  readonly metadata?: Partial<WorkflowMetadataEntry>;
+  /**
+   * Per-scope edge stickiness for the range anchor. Defaults to
+   * `{ start: 1, end: -1 }` (greedy — absorbs boundary inserts). See
+   * `CreateScopeFromBlockIdInput.assoc` for the full matrix.
+   */
+  readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+  /** Caller-steerable identity strategy; same semantics as on `CreateScopeFromBlockIdInput`. */
+  readonly stableRefHint?:
+    | "scope-id"
+    | "bookmark"
+    | "semantic-path"
+    | "runtime-handle";
+}
+
+export type CreateScopeFromAnchorResult =
+  | {
+      readonly status: "created";
+      readonly scopeId: string;
+      readonly anchor: EditorAnchorProjection;
+    }
+  | {
+      readonly status: "range-invalid";
+      readonly reason:
+        | "from-negative"
+        | "to-less-than-from"
+        | "range-exceeds-story-length";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      /**
+       * Single-sentence, agent-actionable explanation. Tells the caller
+       * what the failure was and the concrete next step — no guesswork
+       * required. Safe to surface directly to an LLM tool-use loop as
+       * the `error` content of the tool reply.
+       */
+      readonly message: string;
+      /**
+       * Short machine-routable next-step hint for thin consumers that
+       * don't want to pattern-match on `reason`. Examples:
+       *   "clamp-from-to-zero", "swap-from-and-to",
+       *   "clamp-to-to-storyLength-or-pick-a-different-range".
+       */
+      readonly nextStep: string;
+    };
+
+/**
+ * Sum the total length of the main story by walking blocks with
+ * inter-block gap semantics matched to `resolveBlockAnchorFromCanonical`.
+ * Used as the bounds check for `createScopeFromAnchor`.
+ */
+function computeMainStoryLength(document: CanonicalDocumentEnvelope): number {
+  const root = document.content as DocumentRootNode;
+  const blocks = root.children;
+  let total = 0;
+  for (let i = 0; i < blocks.length; i += 1) {
+    const block: BlockNode = blocks[i]!;
+    if (block.type === "paragraph") {
+      total += paragraphLength(block);
+    } else {
+      total += 1;
+    }
+    if (i < blocks.length - 1) total += 1;
+  }
+  return total;
+}
+
+/**
+ * Create a marker-backed workflow scope over a sub-block anchor range.
+ *
+ * The returned `scopeId` is the durable reference — after this call
+ * returns, `from`/`to` are not part of the scope's identity and must
+ * not be stored or reused. All later lookups use
+ * `resolveReference({kind:"scope-id", value: scopeId})` or `get_scope`,
+ * which walk to the markers' current positions regardless of
+ * intervening edits.
+ *
+ * Bounds: `0 <= from <= to <= storyLength`. Out-of-bounds or inverted
+ * ranges return `{status: "range-invalid", reason}` without mutating
+ * the document. `storyTarget` defaults to main; footnote / header /
+ * endnote stories are supported by passing the target through.
+ */
+export function createScopeFromAnchor(
+  runtime: ScopeWriterRuntime,
+  input: CreateScopeFromAnchorInput,
+): CreateScopeFromAnchorResult {
+  const doc = runtime.getCanonicalDocument();
+  const storyTarget: EditorStoryTarget =
+    input.anchor.storyTarget ?? { kind: "main" };
+  // Bounds check only covers the main story today. Non-main stories
+  // (footnote / header / endnote) skip the numeric bound check —
+  // `runtime.addScope` is the authoritative bound enforcer for those
+  // secondary stories and returns an error anchor when the range is
+  // invalid. This matches the pre-existing `createScopeFromBlockId`
+  // contract where block resolution handles story-aware bounds.
+  const storyLength =
+    storyTarget.kind === "main" ? computeMainStoryLength(doc) : Number.MAX_SAFE_INTEGER;
+
+  const { from, to } = input.anchor;
+  if (from < 0) {
+    return {
+      status: "range-invalid",
+      reason: "from-negative",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor requires from >= 0 (received from=${from}). ` +
+        `Offsets are zero-based absolute positions in the current document; ` +
+        `clamp negative values to 0 before calling.`,
+      nextStep: "clamp-from-to-zero",
+    };
+  }
+  if (to < from) {
+    return {
+      status: "range-invalid",
+      reason: "to-less-than-from",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor requires to >= from (received from=${from}, to=${to}). ` +
+        `The range is inverted — swap the two values before calling.`,
+      nextStep: "swap-from-and-to",
+    };
+  }
+  if (to > storyLength) {
+    return {
+      status: "range-invalid",
+      reason: "range-exceeds-story-length",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor requires to <= storyLength (received to=${to}, ` +
+        `storyLength=${storyLength}). This typically means the offset was ` +
+        `captured from a stale document state (see KI-P9) — do not carry ` +
+        `offsets across mutations. Re-derive from the current document, or ` +
+        `clamp to <= storyLength and verify the result targets the intended content.`,
+      nextStep: "clamp-to-to-storyLength-or-pick-a-different-range",
+    };
+  }
+
+  const anchor: EditorAnchorProjection = {
+    kind: "range",
+    from,
+    to,
+    assoc: input.assoc ?? { start: 1, end: -1 },
+  };
+
+  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,
+    scopeId: input.scopeId,
+    persistence: input.persistence,
+    metadata: input.metadata,
+    storyTarget,
+    label: input.label,
+    ...(scopeMetadataFields.length > 0 ? { scopeMetadataFields } : {}),
+  });
+
+  return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
+}

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -289,7 +289,15 @@ export const editorSchema = new Schema({
         if (pageBreak) styles.push("border-top: 2px dashed rgba(0,0,0,0.1); padding-top: 8px; margin-top: 16px");
         // `<w:framePr>` out-of-flow frame — mirror the static-path branch in
         // tw-page-block-view.helpers.ts so PM-rendered page 1 absolutely
-        // positions the frame identically to pages 2+.
+        // positions the frame identically to pages 2+. Gating rules
+        // match the static path: drop-cap stays in-flow; a framePr with
+        // zero positional fields stays in-flow (no out-of-flow without
+        // a declared position — M3 review finding).
+        //
+        // N1: `position: absolute` is pushed BEFORE `hiddenTextOnly`'s
+        // `display: none` by code order; `display: none` wins visually
+        // regardless of source order, so a hidden framed paragraph
+        // collapses as expected. Do not "fix" the order — it's correct.
         const framePr = node.attrs.frameProperties as
           | {
               xTwips?: number;
@@ -298,9 +306,21 @@ export const editorSchema = new Schema({
               heightTwips?: number;
               hRule?: "auto" | "atLeast" | "exact";
               dropCap?: "none" | "drop" | "margin";
+              xAlign?: string;
+              yAlign?: string;
             }
           | null;
-        if (framePr && framePr.dropCap !== "drop" && framePr.dropCap !== "margin") {
+        const hasPosition =
+          typeof framePr?.xTwips === "number" ||
+          typeof framePr?.yTwips === "number" ||
+          typeof framePr?.xAlign === "string" ||
+          typeof framePr?.yAlign === "string";
+        if (
+          framePr &&
+          framePr.dropCap !== "drop" &&
+          framePr.dropCap !== "margin" &&
+          hasPosition
+        ) {
           styles.push("position: absolute");
           if (typeof framePr.xTwips === "number") styles.push(`left: ${framePr.xTwips / 20}pt`);
           if (typeof framePr.yTwips === "number") styles.push(`top: ${framePr.yTwips / 20}pt`);

package/src/ui-tailwind/editor-surface/tw-page-block-view.helpers.ts

@@ -124,6 +124,9 @@ export function computeTabWidthsInPoints(
     if (stop) {
       const prevPos = tabIndex > 0 ? readPos(rawStops[tabIndex - 1]) : 0;
       const widthTwips = readPos(stop) - prevPos;
+      // `> 0` (not `>= 0`) is intentional — a zero-width zone between
+      // two identical stops is meaningless; skip so the caller falls
+      // back to the 32 px default.
       if (widthTwips > 0) {
         widths.set(seg.segmentId, widthTwips / 20);
       }
@@ -254,10 +257,26 @@ export function buildParagraphStyle(
   // `<w:framePr>` out-of-flow frame (ECMA-376 §17.3.1.11). L04 returns 0
   // from measureBlockHeight for these paragraphs (a298391e) so the inline
   // flow doesn't double-count; L11 renders them absolutely positioned.
-  // Drop-cap (dropCap="drop"|"margin") is in-flow — only the initial
-  // letter is framed — so skip the absolute switch there.
+  //
+  // Gating rules (M3 review finding):
+  //   - Drop-cap (`dropCap` "drop" | "margin") is in-flow — only the
+  //     initial letter is framed; paragraph body stays with its text.
+  //   - A `<w:framePr/>` with ZERO positional fields (no xTwips / yTwips
+  //     / xAlign / yAlign) is ambiguous; Word treats it as in-flow. If
+  //     we emitted `position: absolute` we'd pin the paragraph at (0,0)
+  //     of the nearest positioned ancestor — dramatically wrong.
   const framePr = block.frameProperties;
-  if (framePr && framePr.dropCap !== "drop" && framePr.dropCap !== "margin") {
+  const hasPosition =
+    typeof framePr?.xTwips === "number" ||
+    typeof framePr?.yTwips === "number" ||
+    typeof framePr?.xAlign === "string" ||
+    typeof framePr?.yAlign === "string";
+  if (
+    framePr &&
+    framePr.dropCap !== "drop" &&
+    framePr.dropCap !== "margin" &&
+    hasPosition
+  ) {
     style.position = "absolute";
     if (typeof framePr.xTwips === "number") {
       style.left = `${framePr.xTwips / 20}pt`;

package/src/ui-tailwind/page-stack/floating-image-overlay-model.ts

@@ -145,11 +145,15 @@ export function collectFloatingImageOverlayItems(input: {
   };
 
   // coord-01 §9 / §5.1 — CCEP logos live in header stories; collect from
-  // the main story for the active-story case AND from every secondary
-  // story so header/footer images reach the overlay regardless of which
-  // story is active in the editor.
+  // the active story's surface.blocks (always) + every secondary story
+  // EXCEPT the one whose target matches activeStory (runtime fills
+  // surface.blocks with that same story's blocks, so walking secondary
+  // stories unconditionally would double-emit header/footer segments
+  // the moment the user enters a header for editing — M1).
   collectFromStory(surface.blocks, activeStory);
+  const activeKey = storyTargetKey(activeStory);
   for (const secondary of surface.secondaryStories ?? []) {
+    if (storyTargetKey(secondary.target) === activeKey) continue;
     collectFromStory(secondary.blocks, secondary.target);
   }
 

package/src/ui-tailwind/page-stack/tw-endnote-area.tsx

@@ -52,7 +52,11 @@ export const TwEndnoteArea: React.FC<TwEndnoteAreaProps> = ({
           marginBottom: "8pt",
         }}
       />
-      <TwRegionBlockRenderer blocks={blocks} mediaPreviews={mediaPreviews} />
+      <TwRegionBlockRenderer
+        blocks={blocks}
+        mediaPreviews={mediaPreviews}
+        fallbackDisplay="hidden"
+      />
     </div>
   );
 };

package/src/ui-tailwind/page-stack/tw-footnote-area.tsx

@@ -66,7 +66,11 @@ export const TwFootnoteArea: React.FC<TwFootnoteAreaProps> = React.memo(({
           marginBottom: "4pt",
         }}
       />
-      <TwRegionBlockRenderer blocks={blocks} mediaPreviews={mediaPreviews} />
+      <TwRegionBlockRenderer
+        blocks={blocks}
+        mediaPreviews={mediaPreviews}
+        fallbackDisplay="hidden"
+      />
     </div>
   );
 });

package/src/ui-tailwind/page-stack/tw-region-block-renderer.tsx

@@ -14,6 +14,7 @@ import {
   headingClassList,
   resolveHeadingLevel,
 } from "../editor-surface/tw-page-block-view.helpers.ts";
+import { shouldRenderAbsoluteFloatingImageInPageOverlay } from "./floating-image-overlay-model.ts";
 
 const EMU_PER_PX = 9525;
 
@@ -94,11 +95,12 @@ function renderSegment(
     case "hard_break":
       return <br key={seg.segmentId} />;
     case "image": {
-      // §5.1 gap 3 — floating-anchor images are owned by the absolute
-      // floating-image overlay (`TwFloatingImageLayer`). Emitting them
-      // inline here would double-paint the CCEP header logo on every
-      // page. Skip entirely so only the overlay renders them.
-      if (seg.anchor?.display === "floating") {
+      // §5.1 gap 3 — floating-anchor images the overlay can render
+      // (`TwFloatingImageLayer`) are owned by the overlay. Skip inline
+      // emission ONLY for anchors the overlay predicate accepts —
+      // otherwise wrap-mode=square / column-relative / tight-wrapped
+      // floats get dropped from inline AND from the overlay (M2).
+      if (shouldRenderAbsoluteFloatingImageInPageOverlay(seg.anchor)) {
         return null;
       }
       // Mirror body-renderer behavior (`pm-state-from-snapshot.ts` :500+):

package/src/ui-tailwind/review-workspace/use-workspace-side-effects.ts

@@ -2,7 +2,6 @@ import { useCallback, useEffect } from "react";
 import type { Dispatch, SetStateAction } from "react";
 
 import { createCanvasBackend } from "../../api/public-types.ts";
-import type { RuntimeRenderSnapshot } from "../../api/public-types.ts";
 import {
   incrementInvalidationCounter,
   recordPerfSample,
@@ -17,8 +16,6 @@ export interface UseWorkspaceSideEffectsOptions {
   activeParagraphLayout: ActiveParagraphLayout | null;
   pageChromeModel: PageChromeModel;
   pageShellMetrics: PageShellMetrics;
-  isPageWorkspace: boolean;
-  activeStoryKind: RuntimeRenderSnapshot["activeStory"]["kind"];
   showDrawerReviewRail: boolean;
   setReviewRailOpen: Dispatch<SetStateAction<boolean>>;
   onOpenHeaderStory?: () => void;
@@ -58,8 +55,6 @@ export function useWorkspaceSideEffects(
     activeParagraphLayout,
     pageChromeModel,
     pageShellMetrics,
-    isPageWorkspace,
-    activeStoryKind,
     showDrawerReviewRail,
     setReviewRailOpen,
     onOpenHeaderStory,
@@ -67,14 +62,6 @@ export function useWorkspaceSideEffects(
     onDismissSelectionToolbar,
   } = options;
 
-  // Slice A (designsystem §6.20 reshape, 2026-04-24): isPageWorkspace +
-  // activeStoryKind referenced here so the prop sweep stays a no-op
-  // type-checker pass even though the auto-open-layout-tools effect
-  // they fed retired with the strip. Slice B mounts an active-band
-  // ribbon that observes activeStoryKind directly.
-  void isPageWorkspace;
-  void activeStoryKind;
-
   useEffect(() => {
     recordPerfSample("workspace.chrome");
     incrementInvalidationCounter("workspace.chrome.recomputes");

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -10,10 +10,6 @@ import React, {
 import * as Tooltip from "@radix-ui/react-tooltip";
 import { ChevronRight } from "lucide-react";
 
-import {
-  useVisibleBlockRange,
-  useVisiblePageIndexRange,
-} from "./page-stack/use-visible-block-range.ts";
 import { sliceBlocksForPage } from "./editor-surface/page-slice-util.ts";
 import {
   findScrollAnchor,
@@ -330,8 +326,6 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
       activeParagraphLayout,
       pageChromeModel,
       pageShellMetrics,
-      isPageWorkspace,
-      activeStoryKind: snapshot.activeStory.kind,
       showDrawerReviewRail: responsiveChrome.showDrawerReviewRail,
       setReviewRailOpen,
       onOpenHeaderStory: props.onOpenHeaderStory,