@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/src/runtime/prerender/customxml-cache.ts

@@ -0,0 +1,211 @@
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import type { OpcPackagePart } from "../../io/ooxml/part-manifest.ts";
+import {
+  WORKFLOW_PAYLOAD_PART_PATH,
+  buildEditorStateXml,
+  parseEditorStateXml,
+  parseWorkflowPayloadEnvelopeFromPackage,
+  type EditorStatePayload,
+} from "../../io/ooxml/workflow-payload.ts";
+import {
+  LAYCACHE_SCHEMA_VERSION,
+  LAYOUT_ENGINE_VERSION,
+} from "../layout/layout-engine-version.ts";
+import type { CacheEnvelope } from "./cache-envelope.ts";
+
+/**
+ * L7 Phase 2.5 Plan B B.4 — customXml read/write for the prerender cache.
+ *
+ * Persists the cache envelope inside the docx's workflow-payload part
+ * (`/customXml/item1.xml`) under the "laycache" namespace, so the cache
+ * travels with the file and hands a warm-start experience to any client
+ * that opens the same bytes.
+ *
+ * **Routing decision:** laycache does NOT extend `EditorStateNamespace`.
+ * The entry round-trips through the existing `unknownNamespaces`
+ * preservation path, which already provides:
+ *   - Automatic Word round-trip (Word doesn't touch customXml parts).
+ *   - Automatic runtime save-path preservation (the save path appends
+ *     `channel.getUnknownEntries()` verbatim).
+ *   - Separation of cache concerns from runtime subsystem state (laycache
+ *     is not conflated with hostAnnotations/workflowOverlay/etc.).
+ *
+ * Tradeoff: the write path hand-builds a `<bw:namespace name="laycache">`
+ * XML fragment rather than leveraging `buildEditorStateXml`'s entry
+ * serializer. Six lines of escaped string concatenation in exchange for
+ * the above.
+ *
+ * **Scope (MVP):** Write-side requires the docx to already have a
+ * workflow-payload part (`/customXml/item1.xml`). Docs without it return
+ * `{ written: false, reason: "no-customxml-part" }` so the caller can
+ * fall back to IndexedDB-only caching. Fresh/minimal docs that lack a
+ * payload part are already fast-opening; Plan B is targeted at CCEP-scale
+ * templates which reliably carry the part.
+ */
+
+export const LAYCACHE_NAMESPACE_NAME = "laycache" as const;
+const LAYCACHE_ENTRY_SCHEMA_VERSION = `laycache/${LAYCACHE_SCHEMA_VERSION}`;
+
+export type WriteEnvelopeResult =
+  | { written: true }
+  | { written: false; reason: "no-customxml-part" };
+
+/**
+ * Writes (or replaces) the laycache envelope inside the OPC package's
+ * workflow-payload part. Mutates `opcPackage.parts` in place.
+ *
+ * Preserves all other namespaces (`hostAnnotations`, `workflowOverlay`,
+ * etc.) verbatim. Returns `{ written: false, reason: "no-customxml-part" }`
+ * when the package has no workflow-payload part — caller falls back to
+ * IndexedDB caching in that case.
+ */
+export function writeEnvelopeToOpcPackage(
+  opcPackage: OpcPackage,
+  envelope: CacheEnvelope,
+): WriteEnvelopeResult {
+  const existingPart = opcPackage.parts.get(WORKFLOW_PAYLOAD_PART_PATH);
+  if (!existingPart) {
+    return { written: false, reason: "no-customxml-part" };
+  }
+
+  const existingXml = new TextDecoder().decode(existingPart.bytes);
+  const existingEditorState: EditorStatePayload = parseEditorStateXml(existingXml) ?? {
+    entries: [],
+  };
+
+  // Remove any previous laycache entry; keep every other unknown namespace.
+  const preservedUnknowns = (existingEditorState.unknownNamespaces ?? []).filter(
+    (ns) => ns.name !== LAYCACHE_NAMESPACE_NAME,
+  );
+
+  const laycacheRawXml = buildLaycacheNamespaceXml(envelope);
+
+  const nextEditorState: EditorStatePayload = {
+    entries: existingEditorState.entries,
+    unknownNamespaces: [
+      ...preservedUnknowns,
+      { name: LAYCACHE_NAMESPACE_NAME, rawXml: laycacheRawXml },
+    ],
+  };
+
+  const newEditorStateBlock = buildEditorStateXml(nextEditorState);
+  const newXml = spliceEditorStateIntoPayloadXml(existingXml, newEditorStateBlock);
+  const newBytes = new TextEncoder().encode(newXml);
+
+  // Note: crc32 is left at the previous value. `writeOpcPackage` recomputes
+  // the CRC from uncompressedBytes at zip time (`package-writer.ts:156`), so
+  // the field is effectively documentation from the reader — not consumed by
+  // the writer.
+  const nextPart: OpcPackagePart = {
+    ...existingPart,
+    bytes: newBytes,
+  };
+  opcPackage.parts.set(WORKFLOW_PAYLOAD_PART_PATH, nextPart);
+  return { written: true };
+}
+
+/**
+ * Reads and validates the laycache envelope from an already-parsed OPC
+ * package. Returns `null` on any validation failure:
+ *   - customXml part missing
+ *   - no laycache entry in `unknownNamespaces`
+ *   - JSON parse failure
+ *   - envelope.schemaVersion mismatch (LAYCACHE_SCHEMA_VERSION)
+ *   - envelope.engineVersion mismatch (LAYOUT_ENGINE_VERSION)
+ *   - required fields missing
+ */
+export function readEnvelopeFromOpcPackage(opcPackage: OpcPackage): CacheEnvelope | null {
+  const envelope = parseWorkflowPayloadEnvelopeFromPackage(opcPackage);
+  if (!envelope?.editorState) return null;
+
+  const laycacheUnknown = (envelope.editorState.unknownNamespaces ?? []).find(
+    (ns) => ns.name === LAYCACHE_NAMESPACE_NAME,
+  );
+  if (!laycacheUnknown) return null;
+
+  const inlineJson = extractInlineCdata(laycacheUnknown.rawXml);
+  if (inlineJson === null) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(inlineJson);
+  } catch {
+    return null;
+  }
+
+  if (!isValidCacheEnvelope(parsed)) return null;
+  return parsed;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildLaycacheNamespaceXml(envelope: CacheEnvelope): string {
+  const json = JSON.stringify(envelope).replace(/\]\]>/g, "]]]]><![CDATA[>");
+  return (
+    `<bw:namespace name="${LAYCACHE_NAMESPACE_NAME}" schemaVersion="${LAYCACHE_ENTRY_SCHEMA_VERSION}">` +
+    `<bw:inline><![CDATA[${json}]]></bw:inline>` +
+    `</bw:namespace>`
+  );
+}
+
+/**
+ * Replaces (or inserts) the `<bw:editorState>` block inside an existing
+ * workflow-payload XML. Handles three cases:
+ *   1. Block already present — regex-replace in-place.
+ *   2. Block absent, `<bw:workflowPayload>…</bw:workflowPayload>` present —
+ *      insert before `</bw:workflowPayload>` and upgrade the `version`
+ *      attribute on the opening tag to "1.2".
+ *   3. Neither — leave input unchanged (defensive; parseEditorStateXml
+ *      returned undefined, and if the outer structure is also absent we
+ *      cannot safely synthesize one).
+ *
+ * Note: the outer element is `<bw:workflowPayload version="...">` (per
+ * `buildPayloadXml` at workflow-payload.ts:526), not `<bw:root>`. The
+ * `version` attribute drives the schema-version gate (1.0 / 1.1 / 1.2).
+ */
+function spliceEditorStateIntoPayloadXml(xml: string, editorStateBlock: string): string {
+  const existingBlockRe = /<bw:editorState\b[^>]*>[\s\S]*?<\/bw:editorState>/u;
+  if (existingBlockRe.test(xml)) {
+    return xml.replace(existingBlockRe, editorStateBlock);
+  }
+
+  const rootCloseRe = /<\/bw:workflowPayload>/u;
+  if (rootCloseRe.test(xml)) {
+    const upgraded = xml.replace(
+      /(<bw:workflowPayload\b[^>]*?\bversion=")([^"]*)(")/u,
+      (_m, prefix: string, _v: string, suffix: string) => `${prefix}1.2${suffix}`,
+    );
+    return upgraded.replace(rootCloseRe, `${editorStateBlock}\n</bw:workflowPayload>`);
+  }
+
+  return xml;
+}
+
+function extractInlineCdata(rawXml: string): string | null {
+  const m = rawXml.match(/<bw:inline\b[^>]*>([\s\S]*?)<\/bw:inline>/u);
+  if (!m) return null;
+  const inner = m[1] ?? "";
+  const cdata = inner.replace(/<!\[CDATA\[|\]\]>/g, "").trim();
+  return cdata.length > 0 ? cdata : null;
+}
+
+function isValidCacheEnvelope(value: unknown): value is CacheEnvelope {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.schemaVersion === LAYCACHE_SCHEMA_VERSION &&
+    v.engineVersion === LAYOUT_ENGINE_VERSION &&
+    typeof v.fontFingerprint === "string" &&
+    typeof v.structuralHash === "string" &&
+    typeof v.canonicalDocumentHash === "string" &&
+    typeof v.graph === "object" &&
+    v.graph !== null &&
+    typeof v.surface === "object" &&
+    v.surface !== null &&
+    typeof v.canonicalDocument === "object" &&
+    v.canonicalDocument !== null
+  );
+}
+

package/src/runtime/prerender/customxml-probe.ts

@@ -0,0 +1,78 @@
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import { readOpcPackage } from "../../io/opc/package-reader.ts";
+import { parseBlockStructure } from "../../io/ooxml/parse-block-structure.ts";
+import type { CacheEnvelope } from "./cache-envelope.ts";
+import { computeStructuralHash } from "./cache-key.ts";
+import { readEnvelopeFromOpcPackage } from "./customxml-cache.ts";
+
+/**
+ * L7 Phase 2.5 Plan B B.6 — customXml probe (read-side pre-parse).
+ *
+ * Opens a docx's OPC package just enough to extract the laycache envelope
+ * from `/customXml/item1.xml` without parsing `word/document.xml` or
+ * running the canonical-document builder. Consumers use the returned
+ * envelope to decide whether to take the fast seeding path or fall
+ * through to `loadDocxEditorSessionAsync`'s full pipeline.
+ *
+ * Cost budget: ~20-50 ms on extra-large (OPC unzip 17 ms + XML regex
+ * extract + JSON parse + schema validation). Well below the ~584 ms of
+ * parse + skeleton-ready work that a successful probe skips.
+ *
+ * Null is returned for every rejection path:
+ *   - OPC parse failure (malformed zip, missing Content_Types)
+ *   - no workflow-payload part (`/customXml/item1.xml`)
+ *   - no laycache entry inside the editor-state payload
+ *   - corrupted inline JSON
+ *   - envelope.schemaVersion or engineVersion mismatch
+ *   - missing/mis-typed required envelope fields
+ *
+ * The returned `opcPackage` is included so callers can hand it to
+ * downstream code that would otherwise re-parse the ZIP from bytes
+ * (saving the ~17 ms OPC unzip on the cache-hit path).
+ *
+ * **B.7 structural verification.** When the probe accepts an envelope,
+ * it additionally runs `parseBlockStructure` against the package's
+ * `word/document.xml` and compares the resulting `structuralHash`
+ * against `envelope.structuralHash`. A mismatch means the docx has
+ * been edited since the envelope was written — e.g. Word added a
+ * paragraph and saved — and the probe returns null to force the full
+ * parse path. See `src/io/ooxml/parse-block-structure.ts` for the
+ * probe's known limitations (opaque-promoting OOXML features cannot
+ * be detected shallow-parse; those docs safely fall through).
+ */
+export interface LaycacheProbeResult {
+  readonly envelope: CacheEnvelope;
+  readonly opcPackage: OpcPackage;
+}
+
+export async function tryReadLaycacheEnvelope(
+  input: ArrayBuffer | Uint8Array,
+): Promise<LaycacheProbeResult | null> {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+
+  let opcPackage: OpcPackage;
+  try {
+    opcPackage = readOpcPackage(bytes);
+  } catch {
+    return null;
+  }
+
+  const envelope = readEnvelopeFromOpcPackage(opcPackage);
+  if (!envelope) return null;
+
+  // B.7 — shallow structural probe. Reject envelopes whose cached
+  // structuralHash does not match a fresh shallow-parse of the current
+  // document.xml. Catches the "user edited the docx in Word between
+  // prerender and reopen" path. The probe is conservative: it cannot
+  // detect opaque-promoting OOXML features (content controls, floating
+  // drawings, AlternateContent), so some clean-looking structural
+  // identity docs may still be rejected — a safe false negative.
+  const documentXmlPart = opcPackage.parts.get("/word/document.xml");
+  if (!documentXmlPart) return null;
+  const documentXml = new TextDecoder().decode(documentXmlPart.bytes);
+  const probedBlocks = parseBlockStructure(documentXml);
+  const probedHash = await computeStructuralHash(probedBlocks);
+  if (probedHash !== envelope.structuralHash) return null;
+
+  return { envelope, opcPackage };
+}

package/src/runtime/prerender/prerender-document.ts

@@ -2,6 +2,8 @@ import type { EditorSurfaceSnapshot } from "../../api/public-types";
 import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
 import { loadDocxEditorSessionAsync } from "../../io/docx-session.ts";
 import { createLoadScheduler } from "../../io/load-scheduler.ts";
+import { readOpcPackage } from "../../io/opc/package-reader.ts";
+import { writeOpcPackage } from "../../io/opc/package-writer.ts";
 import {
   LAYCACHE_SCHEMA_VERSION,
   LAYOUT_ENGINE_VERSION,
@@ -14,6 +16,8 @@ import {
   deriveCacheKey,
   type CacheKeyBlock,
 } from "./cache-key.ts";
+import { computeCanonicalDocumentHash } from "./canonical-document-hash.ts";
+import { writeEnvelopeToOpcPackage } from "./customxml-cache.ts";
 import { resolveFontFingerprint } from "./font-fingerprint.ts";
 import { canonicalizeGraph } from "./graph-canonicalize.ts";
 
@@ -46,11 +50,18 @@ import { canonicalizeGraph } from "./graph-canonicalize.ts";
 export interface PrerenderOptions {
   readonly fontFingerprint?: string;
   /**
-   * Plan B hook — when true, prerenderDocument will inject the cache
-   * envelope into the document's `laycache` customXml namespace and
-   * return the re-serialized bytes in `docWithCustomXml`. In Plan A
-   * (this task) the flag is accepted for API stability but ignored;
-   * `docWithCustomXml` returns the input unchanged.
+   * Plan B — when true, prerenderDocument injects the cache envelope into
+   * the document's workflow-payload customXml part under a `laycache`
+   * unknown-namespace entry, and returns the re-serialized bytes in
+   * `docWithCustomXml`. Default: `false`, in which case `docWithCustomXml`
+   * equals the input bytes.
+   *
+   * Scope caveat: requires the input docx to already have a
+   * `/customXml/item1.xml` part. If the part is absent, the flag is a
+   * no-op (documented via `counters.persistedToCustomXml`) and the caller
+   * falls back to IndexedDB-only caching. Fresh/minimal docs that lack
+   * the part are already fast-opening; Plan B targets CCEP-scale
+   * templates which reliably carry the part.
    */
   readonly persistToCustomXml?: boolean;
 }
@@ -59,6 +70,13 @@ export interface PrerenderCounters {
   readonly blockCount: number;
   readonly pageCount: number;
   readonly prerenderMs: number;
+  /**
+   * Plan B signal: `true` when `persistToCustomXml` was requested AND the
+   * docx had an existing workflow-payload part to mutate. `false` when
+   * the flag was off OR the docx had no such part (caller should fall
+   * back to IndexedDB caching).
+   */
+  readonly persistedToCustomXml: boolean;
 }
 
 export interface PrerenderResult {
@@ -70,6 +88,15 @@ export interface PrerenderResult {
 
 const PRERENDER_DOCUMENT_ID = "prerender";
 
+/**
+ * Fixed ISO8601 timestamp used to override session-birth `createdAt` /
+ * `updatedAt` on the prerendered envelope. Epoch zero — a valid ISO8601
+ * value that downstream validators accept — replacing `Date.now()`-driven
+ * values that would otherwise defeat byte-identical `docWithCustomXml`
+ * output across two prerender calls on identical bytes.
+ */
+const PRERENDER_NORMALIZED_TIMESTAMP = "1970-01-01T00:00:00.000Z";
+
 function toUint8Array(input: ArrayBuffer | Uint8Array): Uint8Array {
   if (input instanceof Uint8Array) return input;
   return new Uint8Array(input);
@@ -106,7 +133,20 @@ export async function prerenderDocument(
     );
   }
 
-  const envelope = session.initialSessionState.canonicalDocument;
+  // Normalize session-birth timestamps. `loadDocxEditorSessionAsync` sets
+  // `createdAt`/`updatedAt` from `new Date().toISOString()`; without this
+  // override, two sequential prerender calls on identical bytes would
+  // produce different envelopes → different customXml bytes → determinism
+  // failure on the B.5 byte-identical gate.  Using the epoch keeps the
+  // value a valid ISO8601 string (downstream validators accept it) while
+  // eliminating the only remaining source of non-determinism.  The live
+  // session's updatedAt is re-populated by runtime mutations anyway, so
+  // the normalized value is irrelevant at runtime.
+  const envelope: typeof session.initialSessionState.canonicalDocument = {
+    ...session.initialSessionState.canonicalDocument,
+    createdAt: PRERENDER_NORMALIZED_TIMESTAMP,
+    updatedAt: PRERENDER_NORMALIZED_TIMESTAMP,
+  };
   const surface = createEditorSurfaceSnapshot(envelope, createSelectionSnapshot(), { kind: "main" });
 
   const engine = createLayoutEngine({ autoUpgradeToCanvasBackend: false });
@@ -114,11 +154,17 @@ export async function prerenderDocument(
   const graph = canonicalizeGraph(rawGraph);
 
   const structuralHash = await computeStructuralHash(blocksToCacheKeyBlocks(surface));
+  // L7 Phase 2.5 Plan B B.2 — sha256 of stable-stringified canonical document.
+  // Enters the cache key as the 5th input so style / metadata / comments /
+  // preservation mutations correctly invalidate (structuralHash alone misses
+  // them because the block-id list is unchanged).
+  const canonicalDocumentHash = await computeCanonicalDocumentHash(envelope);
   const cacheKey = await deriveCacheKey({
     blocks: blocksToCacheKeyBlocks(surface),
     fontFingerprint,
     engineVersion: LAYOUT_ENGINE_VERSION,
     schemaVersion: LAYCACHE_SCHEMA_VERSION,
+    canonicalDocumentHash,
   });
 
   const cacheBlob: CacheEnvelope = {
@@ -126,20 +172,41 @@ export async function prerenderDocument(
     engineVersion: LAYOUT_ENGINE_VERSION,
     fontFingerprint,
     structuralHash,
+    canonicalDocumentHash,
     graph,
     surface,
+    canonicalDocument: envelope,
   };
 
+  // Plan B B.5 — persistToCustomXml: inject the envelope into the docx's
+  // workflow-payload part. Re-parses the OPC package from bytes (~17 ms on
+  // extra-large) because `LoadedDocxEditorSession` does not expose
+  // `sourcePackage` publicly. Acceptable cost on the one-shot ingest path.
+  let docWithCustomXml = bytes;
+  let persistedToCustomXml = false;
+  if (options.persistToCustomXml === true) {
+    const opcPackage = readOpcPackage(bytes);
+    const writeResult = writeEnvelopeToOpcPackage(opcPackage, cacheBlob);
+    if (writeResult.written) {
+      docWithCustomXml = writeOpcPackage(opcPackage);
+      persistedToCustomXml = true;
+    }
+    // writeResult.written === false → docx had no customXml part; silently
+    // fall through with docWithCustomXml = input bytes. Caller observes via
+    // counters.persistedToCustomXml.
+  }
+
   const prerenderMs = performance.now() - t0;
 
   return {
-    docWithCustomXml: bytes,
+    docWithCustomXml,
     cacheBlob,
     cacheKey,
     counters: {
       blockCount: surface.blocks.length,
       pageCount: graph.pages.length,
       prerenderMs,
+      persistedToCustomXml,
     },
   };
 }

package/src/runtime/scope-resolver.ts

@@ -0,0 +1,148 @@
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+} from "../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import type { EditorAnchorProjection } from "../api/public-types.ts";
+
+export interface ResolvedScopeLocation {
+  scopeId: string;
+  startPos: number;
+  endPos: number;
+}
+
+function inlineLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
+}
+
+function walkParagraphs(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): { paragraph: ParagraphNode; from: number }[] {
+  const envelope = document as CanonicalDocumentEnvelope;
+  const root =
+    "content" in envelope
+      ? (envelope.content as DocumentRootNode)
+      : (document as unknown as DocumentRootNode);
+  const out: { paragraph: ParagraphNode; from: number }[] = [];
+  let cursor = 0;
+  for (let index = 0; index < root.children.length; index += 1) {
+    const block = root.children[index];
+    if (block && block.type === "paragraph") {
+      out.push({ paragraph: block, from: cursor });
+      cursor += block.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    } else if (block && block.type === "table") {
+      cursor += 1;
+    } else {
+      cursor += 1;
+    }
+    if (index < root.children.length - 1) {
+      cursor += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk all paragraphs in the document and return the absolute positions of the
+ * start and end markers for each scope that has either side present. Used by
+ * `resolveScope` + `findScopeAt`; exported so test code can inspect the
+ * marker-to-position mapping directly.
+ */
+export function collectScopeLocations(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): Map<string, { startPos?: number; endPos?: number }> {
+  const locations = new Map<string, { startPos?: number; endPos?: number }>();
+  const paragraphs = walkParagraphs(document);
+  for (const { paragraph, from } of paragraphs) {
+    let cursor = from;
+    for (const child of paragraph.children) {
+      if (child.type === "scope_marker_start") {
+        const prior = locations.get(child.scopeId) ?? {};
+        locations.set(child.scopeId, { ...prior, startPos: cursor });
+      } else if (child.type === "scope_marker_end") {
+        const prior = locations.get(child.scopeId) ?? {};
+        locations.set(child.scopeId, { ...prior, endPos: cursor });
+      }
+      cursor += inlineLength(child as InlineNode);
+    }
+  }
+  return locations;
+}
+
+/**
+ * Resolve a scopeId to a live public range anchor derived from the marker
+ * positions currently in the document. Returns:
+ *   - A range anchor when both markers are present
+ *   - A detached anchor when one or zero markers survive
+ *   - `null` when neither marker is in the document
+ */
+export function resolveScope(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  scopeId: string,
+): EditorAnchorProjection | null {
+  const locations = collectScopeLocations(document);
+  const loc = locations.get(scopeId);
+  if (!loc) return null;
+
+  if (loc.startPos !== undefined && loc.endPos !== undefined) {
+    const from = Math.min(loc.startPos, loc.endPos);
+    const to = Math.max(loc.startPos, loc.endPos);
+    return {
+      kind: "range",
+      from,
+      to,
+      assoc: { start: -1, end: 1 },
+    };
+  }
+
+  return {
+    kind: "detached",
+    reason: "deleted",
+    lastKnownRange: {
+      from: loc.startPos ?? loc.endPos ?? 0,
+      to: loc.endPos ?? loc.startPos ?? 0,
+    },
+  };
+}
+
+/**
+ * Given a position, return the innermost enclosing scope (by document order).
+ * Used by the chrome overlay hit-test and by the edit-dispatch guard that
+ * routes delete-through-marker to `removeScope`.
+ */
+export function findScopeAt(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  position: number,
+): { scopeId: string; startPos: number; endPos: number } | null {
+  const locations = collectScopeLocations(document);
+  let best: { scopeId: string; startPos: number; endPos: number } | null = null;
+  for (const [scopeId, loc] of locations) {
+    if (loc.startPos === undefined || loc.endPos === undefined) continue;
+    if (position < loc.startPos || position > loc.endPos) continue;
+    if (!best || loc.startPos > best.startPos) {
+      best = { scopeId, startPos: loc.startPos, endPos: loc.endPos };
+    }
+  }
+  return best;
+}

package/src/runtime/scope-tag-registry.ts

@@ -53,6 +53,16 @@ export const DEFAULT_REGISTRY_ENTRIES: Readonly<Record<string, ScopeTagBehavior>
     trimOnDelete: true,
     bailIfCrossed: false,
   },
+  // S1 scope-marker anchoring. `trimOnDelete: false` is the load-bearing
+  // difference vs. `bookmark` — a delete that crosses a scope marker routes
+  // through `removeScope` instead of silently trimming the marker, so
+  // half-scope states (orphaned metadata in customXml) never appear.
+  "workflow-scope-marker": {
+    extendOnInsertLeft: true,
+    extendOnInsertRight: true,
+    trimOnDelete: false,
+    bailIfCrossed: false,
+  },
   sdt: {
     extendOnInsertLeft: false,
     extendOnInsertRight: false,

package/src/runtime/surface-projection.ts

@@ -1047,7 +1047,11 @@ function appendInlineSegments(
     }
     case "bookmark_start":
     case "bookmark_end":
-      // Zero-width markers — no visual, no cursor advancement
+    case "scope_marker_start":
+    case "scope_marker_end":
+      // Zero-width markers — no visual, no cursor advancement. Scope markers
+      // (S1) follow the bookmark precedent: structural anchors whose positions
+      // track with surrounding text but which don't occupy cursor positions.
       return { nextCursor: start, lockedFragmentIds: [] };
     default:
       return { nextCursor: start + 1, lockedFragmentIds: [] };
@@ -1466,6 +1470,9 @@ function summarizePreviewInline(node: InlineNode): string {
       return node.name ? `[Bookmark: ${node.name}]` : "[Bookmark]";
     case "bookmark_end":
       return "";
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return "";
     case "image":
       return node.altText ? `[Image: ${node.altText}]` : "[Image]";
     case "opaque_inline":