@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/io/ooxml/parse-object.ts

@@ -67,17 +67,21 @@ export function parseObject(
 
   // hotfix/ole-digestibility-guard — classify the embedding before
   // constructing a canonical node. When the classifier returns
-  // "store-only" (nested Word docs, PDF OLE, Excel/PowerPoint
-  // embeddings, unknown ProgIDs), return undefined so the caller's
-  // existing opaque-fragment fallback preserves both <w:object> XML
-  // and its r:id verbatim. Binary preservation is unaffected —
-  // collectPreservedPackageParts indexes embedding parts by path, not
-  // by canonical-tree reference.
+  // `store-only` OR `offloadable` (nested Word docs, PDF OLE, Excel/
+  // PowerPoint embeddings, unknown ProgIDs), return undefined so
+  // the caller's existing opaque-fragment fallback preserves both
+  // `<w:object>` XML and its r:id verbatim. Binary preservation is
+  // unaffected — `collectPreservedPackageParts` indexes embedding
+  // parts by path, not by canonical-tree reference.
   //
-  // TODO(refactor/01 Step 6-7): replace this skip-construction with
-  // extraction + offload via hostAdapter.storeEmbeddedDocument?. See
-  // docs/architecture/01-package-session.md §P8 + docs/plans/refactor/
-  // 01-package-session.md Steps 6-7.
+  // Offload handling: the session layer runs `processEmbeddedOffload`
+  // (`src/session/import/embedded-offload.ts`) AFTER this parse step
+  // and AFTER the preservation index is built. For `offloadable`
+  // manifests with an opted-in host adapter, the session removes the
+  // corresponding part path from preservation (via the offload
+  // `ownedPartPaths` list fed into `buildImportPreservation`) and
+  // reconstitutes at export time. This parser stays agnostic.
+  // Shipped in refactor/01 Step 7 (Slice 5e-10).
   const kind = classifyEmbedding({
     progId,
     relationshipType: resolved.relationshipType,

package/src/io/ooxml/parse-run-formatting.ts

@@ -1,4 +1,7 @@
-import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
+import type {
+  CanonicalRunFormatting,
+  ThemeFontSlot,
+} from "../../model/canonical-document.ts";
 import { findChildOptional, readIntVal, readOnOff, readStringAttr } from "./xml-attr-helpers.ts";
 import type { XmlElementNode } from "./xml-element.ts";
 import {
@@ -124,6 +127,33 @@ export function readRunProperties(
     if (cs) rPr.fontFamilyCs = cs;
     const primary = ascii ?? hAnsi ?? eastAsia ?? cs;
     if (primary) rPr.fontFamily = primary;
+
+    // ECMA-376 §17.3.2.26 theme-slot attrs. Unknown slot values are
+    // dropped (enumeration is closed); parsers that see an ECMA-376-
+    // valid slot we don't model land in the grab bag and round-trip
+    // through a different path.
+    const asciiTheme = toThemeFontSlot(
+      rFonts.attributes["w:asciiTheme"] ?? rFonts.attributes.asciiTheme,
+    );
+    const hAnsiTheme = toThemeFontSlot(
+      rFonts.attributes["w:hAnsiTheme"] ?? rFonts.attributes.hAnsiTheme,
+    );
+    const eastAsiaTheme = toThemeFontSlot(
+      rFonts.attributes["w:eastAsiaTheme"] ?? rFonts.attributes.eastAsiaTheme,
+    );
+    // ECMA-376: the complex-script theme attr is "cstheme" (all lower)
+    // — not "csTheme" — and Word emits that form. Both casings are
+    // handled defensively.
+    const csTheme = toThemeFontSlot(
+      rFonts.attributes["w:cstheme"] ??
+        rFonts.attributes.cstheme ??
+        rFonts.attributes["w:csTheme"] ??
+        rFonts.attributes.csTheme,
+    );
+    if (asciiTheme) rPr.asciiTheme = asciiTheme;
+    if (hAnsiTheme) rPr.hAnsiTheme = hAnsiTheme;
+    if (eastAsiaTheme) rPr.eastAsiaTheme = eastAsiaTheme;
+    if (csTheme) rPr.csTheme = csTheme;
   }
 
   const sz = readIntVal(findChildOptional(node, "sz"));
@@ -176,3 +206,19 @@ export function readRunProperties(
 
   return Object.keys(rPr).length > 0 ? rPr : undefined;
 }
+
+const THEME_FONT_SLOTS = new Set<string>([
+  "majorAscii",
+  "minorAscii",
+  "majorHAnsi",
+  "minorHAnsi",
+  "majorEastAsia",
+  "minorEastAsia",
+  "majorBidi",
+  "minorBidi",
+]);
+
+function toThemeFontSlot(value: string | undefined): ThemeFontSlot | undefined {
+  if (value === undefined) return undefined;
+  return THEME_FONT_SLOTS.has(value) ? (value as ThemeFontSlot) : undefined;
+}

package/src/io/ooxml/property-grab-bag.ts

@@ -5,7 +5,7 @@
  * property container (`<w:pPr>`, `<w:rPr>`, `<w:tcPr>`, `<w:trPr>`,
  * `<w:tblPr>`, `<w:sectPr>`) via per-container "grab bags" keyed by
  * element name — see `PropertyMap.hxx:82` and
- * `libreoffice-analysis.md` §2 for the mechanism. On export, every grab
+ * `docs/reference/libreoffice-analysis.md` §2 for the mechanism. On export, every grab
  * bag re-emits verbatim inside its container so the round-trip pipeline
  * does not silently drop extension-namespace properties (`w15:collapsed`,
  * `w16cex:...`, etc.) or attributes Word adds after we parsed its schema.
@@ -95,7 +95,7 @@ export interface PropertyGrabBagDescriptor {
    * `TableCellNode.propertiesXml`. That path cannot participate in the
    * attribute-level grab-bag slice until it is retrofit to emit
    * `UnknownPropertyChild[]` through this descriptor. Tracked as a Lane 3
-   * Tier-2 backlog entry — see `docs/plans/lane-3-layout-engine-ooxml-fidelity.md`.
+   * Tier-2 backlog entry — see `CLAUDE.md (lane status table)`.
    */
   modelledChildAttributes: ReadonlyMap<string, ReadonlySet<string>>;
 }

package/src/io/ooxml/units.ts

@@ -0,0 +1,11 @@
+/**
+ * OOXML unit constants used by the IO layer's parsers.
+ *
+ * Slice 3 of refactor/01 package-session. Migrated from
+ * src/runtime/units.ts (drift fix #5 — IO-layer constants must not
+ * live under src/runtime/**). The runtime module keeps a re-export
+ * alias for one-release back-compat.
+ */
+
+/** OOXML gradient-stop and crop-offset unit (100 000 = 100%). */
+export const GRADIENT_STOP_UNITS = 100_000;

package/src/io/ooxml/workflow-payload.ts

@@ -5,6 +5,12 @@ import type {
 } from "./part-manifest.ts";
 import type {
   EditorAnchorProjection,
+  OverlayKind,
+  OverlayVisibilityEnforcement,
+  OverlayVisibilityPolicy,
+  WorkflowMarkupMode,
+  WorkflowMarkupModeEnforcement,
+  WorkflowMarkupModePolicy,
   WorkflowOverlay,
   WorkflowMetadataDefinition,
   WorkflowMetadataEntry,
@@ -92,6 +98,17 @@ export interface WorkflowPayloadEnvelope {
   workflowOverlay?: WorkflowOverlay;
   /** Present only when the payload was version 1.2+ and carried a non-empty <bw:editorState> block. */
   editorState?: EditorStatePayload;
+  /**
+   * W10 — class-A overlay-visibility policies, one per `OverlayKind` at
+   * most. Empty array when the payload carried no `<bw:overlayVisibility>`
+   * block (documents predating the schema read as "no policy").
+   */
+  visibilityPolicies?: readonly OverlayVisibilityPolicy[];
+  /**
+   * X5 — class-A markup-mode policy (single record). `null` when the
+   * payload carried no `<bw:markupModePolicy>` block.
+   */
+  markupModePolicy?: WorkflowMarkupModePolicy | null;
   validatorIssues?: readonly ValidatorIssue[];
 }
 
@@ -119,6 +136,19 @@ export function buildWorkflowPayloadParts(input: {
   workflowOverlay?: WorkflowOverlay;
   /** Optional schema 1.2 editor-state block. Omitted when empty. */
   editorState?: EditorStatePayload;
+  /**
+   * W10 — class-A overlay-visibility policies. When non-empty, emitted
+   * as a `<bw:overlayVisibility>` block inside the workflow payload and
+   * forces the customXml part to be written (even when no overlay /
+   * metadata / editorState content would otherwise require it).
+   */
+  visibilityPolicies?: readonly OverlayVisibilityPolicy[];
+  /**
+   * X5 — class-A markup-mode policy. When non-null, emitted as a
+   * `<bw:markupModePolicy>` block and forces customXml rewrite (same
+   * pattern as visibility policies).
+   */
+  markupModePolicy?: WorkflowMarkupModePolicy | null;
   documentId: string;
   createdAt: string;
   updatedAt: string;
@@ -139,13 +169,29 @@ export function buildWorkflowPayloadParts(input: {
     : undefined;
   const sourceHasRuntimeOwnedPayloadContent = Boolean(
     existingPayloadEnvelope?.workflowOverlay ||
-      (existingPayloadEnvelope?.workflowMetadata.definitions.length ?? 0) > 0,
+      (existingPayloadEnvelope?.workflowMetadata.definitions.length ?? 0) > 0 ||
+      (existingPayloadEnvelope?.visibilityPolicies?.length ?? 0) > 0 ||
+      existingPayloadEnvelope?.markupModePolicy != null,
   );
+  // Schema 1.2: the editorState block carries the runtime's full workflow
+  // state (definitions + entries including `metadataPersistence: "internal"`
+  // that do NOT pass the document-backed filter). When the runtime has any
+  // such state, the customXml part MUST be emitted — otherwise a caller who
+  // only uses `setWorkflowMetadataEntries` / `addScope({ persistence: ...})`
+  // ships docs with silently-dropped entries.
+  const hasEditorStateContent = hasNonEmptyEditorState(input.editorState);
+  const visibilityPolicies = input.visibilityPolicies ?? [];
+  const hasVisibilityPolicies = visibilityPolicies.length > 0;
+  const markupModePolicy = input.markupModePolicy ?? null;
+  const hasMarkupModePolicy = markupModePolicy !== null;
   if (
     workflowMetadata.definitions.length === 0 &&
     workflowMetadata.entries.length === 0 &&
     !input.workflowOverlay &&
-    !sourceHasRuntimeOwnedPayloadContent
+    !sourceHasRuntimeOwnedPayloadContent &&
+    !hasEditorStateContent &&
+    !hasVisibilityPolicies &&
+    !hasMarkupModePolicy
   ) {
     return null;
   }
@@ -159,6 +205,8 @@ export function buildWorkflowPayloadParts(input: {
     workflowMetadata,
     workflowOverlay: input.workflowOverlay,
     editorState: input.editorState,
+    visibilityPolicies,
+    markupModePolicy,
     preservedExtensionsXml: getPreservedExtensionsXml(input.sourcePackage, descriptor.payloadPartPath),
   });
   const itemPropsXml = buildItemPropsXml(descriptor.itemId);
@@ -272,17 +320,80 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
 
   const validatorIssues = validateWorkflowPayloadEnvelope(xml);
   const editorState = parseEditorStateXml(xml);
+  // Schema 1.2: the `<bw:editorState>` `workflowMetadata` namespace carries
+  // the full runtime snapshot (including entries whose effective persistence
+  // is `"internal"`, which do NOT survive the `<bw:entry>` / document-backed
+  // filter). Fold its entries + definitions in here so the reload path sees
+  // the authoritative state. Existing `<bw:entry>`-extracted data wins on
+  // metadataId collision — it represents the external/document-backed view.
+  const merged = mergeEditorStateWorkflowMetadata(
+    { definitions, entries },
+    editorState,
+  );
+  const visibilityPolicies = parseOverlayVisibilityBlock(xml);
+  const markupModePolicy = parseMarkupModePolicyBlock(xml);
   return {
-    workflowMetadata: {
-      definitions,
-      entries,
-    },
+    workflowMetadata: merged,
     workflowOverlay: parseWorkflowOverlay(xml),
     ...(editorState !== undefined ? { editorState } : {}),
+    ...(visibilityPolicies.length > 0 ? { visibilityPolicies } : {}),
+    ...(markupModePolicy !== null ? { markupModePolicy } : {}),
     ...(validatorIssues.length > 0 ? { validatorIssues } : {}),
   };
 }
 
+function mergeEditorStateWorkflowMetadata(
+  base: WorkflowMetadataSnapshot,
+  editorState: EditorStatePayload | undefined,
+): WorkflowMetadataSnapshot {
+  if (!editorState) {
+    return base;
+  }
+  const inlineEntry = editorState.entries.find(
+    (candidate) => candidate.namespace === "workflowMetadata" && candidate.inline !== undefined,
+  );
+  if (!inlineEntry || typeof inlineEntry.inline !== "object" || inlineEntry.inline === null) {
+    return base;
+  }
+  const inlinePayload = inlineEntry.inline as {
+    definitions?: WorkflowMetadataDefinition[];
+    entries?: WorkflowMetadataEntry[];
+  };
+  const inlineDefinitions = Array.isArray(inlinePayload.definitions) ? inlinePayload.definitions : [];
+  const inlineEntries = Array.isArray(inlinePayload.entries) ? inlinePayload.entries : [];
+
+  const baseDefinitionIds = new Set(base.definitions.map((definition) => definition.metadataId));
+  const baseEntryKeys = new Set(
+    base.entries.map((entry) => `${entry.entryId}${entry.metadataId}`),
+  );
+
+  const mergedDefinitions = [
+    ...base.definitions,
+    ...inlineDefinitions.filter(
+      (definition) =>
+        definition !== null &&
+        typeof definition === "object" &&
+        typeof definition.metadataId === "string" &&
+        !baseDefinitionIds.has(definition.metadataId),
+    ),
+  ];
+  const mergedEntries = [
+    ...base.entries,
+    ...inlineEntries.filter(
+      (entry) =>
+        entry !== null &&
+        typeof entry === "object" &&
+        typeof entry.entryId === "string" &&
+        typeof entry.metadataId === "string" &&
+        !baseEntryKeys.has(`${entry.entryId}${entry.metadataId}`),
+    ),
+  ];
+  return {
+    definitions: mergedDefinitions,
+    entries: mergedEntries,
+  };
+}
+
 function needsSchemaV11(input: {
   workflowMetadata: WorkflowMetadataSnapshot;
   workflowOverlay?: WorkflowOverlay;
@@ -460,10 +571,16 @@ function buildPayloadXml(input: {
   workflowMetadata: WorkflowMetadataSnapshot;
   workflowOverlay?: WorkflowOverlay;
   editorState?: EditorStatePayload;
+  /** W10 — class-A overlay-visibility policies. Empty = block omitted. */
+  visibilityPolicies: readonly OverlayVisibilityPolicy[];
+  /** X5 — class-A markup-mode policy. `null` = block omitted. */
+  markupModePolicy: WorkflowMarkupModePolicy | null;
   preservedExtensionsXml: string;
 }): string {
   const hasEditorState = hasNonEmptyEditorState(input.editorState);
-  const schemaVersion = hasEditorState
+  const hasVisibilityPolicies = input.visibilityPolicies.length > 0;
+  const hasMarkupModePolicy = input.markupModePolicy !== null;
+  const schemaVersion = hasEditorState || hasVisibilityPolicies || hasMarkupModePolicy
     ? "1.2"
     : needsSchemaV11(input)
       ? "1.1"
@@ -523,6 +640,12 @@ function buildPayloadXml(input: {
     .join("\n");
 
   const editorStateXml = hasEditorState ? buildEditorStateXml(input.editorState!) : "";
+  const overlayVisibilityXml = hasVisibilityPolicies
+    ? buildOverlayVisibilityXml(input.visibilityPolicies)
+    : "";
+  const markupModePolicyXml = input.markupModePolicy
+    ? buildMarkupModePolicyXml(input.markupModePolicy)
+    : "";
 
   return [
     `<?xml version="1.0" encoding="UTF-8"?>`,
@@ -535,6 +658,8 @@ function buildPayloadXml(input: {
     definitionEntriesXml ? indentLines(definitionEntriesXml, 4) : "",
     metadataEntriesXml ? indentLines(metadataEntriesXml, 4) : "",
     `  </bw:metadata>`,
+    overlayVisibilityXml,
+    markupModePolicyXml,
     editorStateXml,
     extensionsXml
       ? `  <bw:extensions>\n${indentLines(extensionsXml, 4)}\n  </bw:extensions>`
@@ -543,6 +668,156 @@ function buildPayloadXml(input: {
   ].filter((line) => line.length > 0).join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// W10 · <bw:overlayVisibility> block
+//
+// Fixed OverlayKind order for byte-identical round-trip. See
+// `src/runtime/workflow/visibility-policy.ts` for the canonical order.
+// ---------------------------------------------------------------------------
+
+const OVERLAY_KIND_ORDER: readonly OverlayKind[] = [
+  "scope-rail",
+  "comments",
+  "tracked-changes",
+  "suggestions",
+  "debug-panel",
+  "presence",
+];
+
+function buildOverlayVisibilityXml(
+  policies: readonly OverlayVisibilityPolicy[],
+): string {
+  if (policies.length === 0) return "";
+  const index = (kind: OverlayKind): number => OVERLAY_KIND_ORDER.indexOf(kind);
+  const ordered = [...policies].sort((a, b) => index(a.kind) - index(b.kind));
+  const body = ordered.map(formatOverlayVisibilityPolicy).join("\n");
+  return `  <bw:overlayVisibility>\n${body}\n  </bw:overlayVisibility>`;
+}
+
+function formatOverlayVisibilityPolicy(policy: OverlayVisibilityPolicy): string {
+  const attrs = [
+    ` kind="${escapeXml(policy.kind)}"`,
+    ` enforcement="${escapeXml(policy.enforcement)}"`,
+    ` defaultOn="${policy.defaultOn ? "true" : "false"}"`,
+  ].join("");
+  if (!policy.authoredBy) {
+    return `    <bw:policy${attrs}/>`;
+  }
+  return [
+    `    <bw:policy${attrs}>`,
+    `      <bw:authoredBy actorId="${escapeXml(policy.authoredBy.actorId)}" at="${escapeXml(policy.authoredBy.at)}"/>`,
+    `    </bw:policy>`,
+  ].join("\n");
+}
+
+const VALID_OVERLAY_KINDS: ReadonlySet<OverlayKind> = new Set(OVERLAY_KIND_ORDER);
+const VALID_ENFORCEMENT: ReadonlySet<OverlayVisibilityEnforcement> = new Set([
+  "authored-default",
+  "always",
+  "never",
+]);
+
+// ---------------------------------------------------------------------------
+// X5 · <bw:markupModePolicy> block
+//
+// Single-record policy; no ordering concerns. Byte-identical round-trip
+// when unchanged: same attribute ordering (mode, enforcement, optional
+// authoredBy child) every emit.
+// ---------------------------------------------------------------------------
+
+const VALID_MARKUP_MODES: ReadonlySet<WorkflowMarkupMode> = new Set([
+  "clean",
+  "simple",
+  "all",
+]);
+const VALID_MARKUP_ENFORCEMENT: ReadonlySet<WorkflowMarkupModeEnforcement> = new Set([
+  "authored-default",
+  "always",
+]);
+
+function buildMarkupModePolicyXml(policy: WorkflowMarkupModePolicy): string {
+  const attrs = [
+    ` mode="${escapeXml(policy.mode)}"`,
+    ` enforcement="${escapeXml(policy.enforcement)}"`,
+  ].join("");
+  if (!policy.authoredBy) {
+    return `  <bw:markupModePolicy${attrs}/>`;
+  }
+  return [
+    `  <bw:markupModePolicy${attrs}>`,
+    `    <bw:authoredBy actorId="${escapeXml(policy.authoredBy.actorId)}" at="${escapeXml(policy.authoredBy.at)}"/>`,
+    `  </bw:markupModePolicy>`,
+  ].join("\n");
+}
+
+function parseMarkupModePolicyBlock(xml: string): WorkflowMarkupModePolicy | null {
+  const match = xml.match(
+    /<bw:markupModePolicy\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bw:markupModePolicy>)/u,
+  );
+  if (!match) return null;
+  const attrs = parseAttributes(match[1] ?? "");
+  const mode = attrs.mode;
+  const enforcement = attrs.enforcement;
+  if (!mode || !VALID_MARKUP_MODES.has(mode as WorkflowMarkupMode)) return null;
+  if (!enforcement || !VALID_MARKUP_ENFORCEMENT.has(enforcement as WorkflowMarkupModeEnforcement)) {
+    return null;
+  }
+  const childXml = match[2] ?? "";
+  const authoredMatch = childXml.match(/<bw:authoredBy\b([^>]*)\/>/u);
+  const authoredAttrs = authoredMatch
+    ? parseAttributes(authoredMatch[1] ?? "")
+    : undefined;
+  const authoredBy =
+    authoredAttrs?.actorId && authoredAttrs?.at
+      ? { actorId: authoredAttrs.actorId, at: authoredAttrs.at }
+      : undefined;
+  return {
+    mode: mode as WorkflowMarkupMode,
+    enforcement: enforcement as WorkflowMarkupModeEnforcement,
+    ...(authoredBy ? { authoredBy } : {}),
+  };
+}
+
+function parseOverlayVisibilityBlock(
+  xml: string,
+): readonly OverlayVisibilityPolicy[] {
+  const block = xml.match(
+    /<bw:overlayVisibility\b[^>]*>([\s\S]*?)<\/bw:overlayVisibility>/u,
+  );
+  if (!block) return [];
+  const body = block[1] ?? "";
+  const policies: OverlayVisibilityPolicy[] = [];
+  const pattern =
+    /<bw:policy\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bw:policy>)/gu;
+  for (const match of body.matchAll(pattern)) {
+    const attrs = parseAttributes(match[1] ?? "");
+    const kind = attrs.kind;
+    const enforcement = attrs.enforcement;
+    const defaultOnRaw = attrs.defaultOn;
+    if (!kind || !VALID_OVERLAY_KINDS.has(kind as OverlayKind)) continue;
+    if (!enforcement || !VALID_ENFORCEMENT.has(enforcement as OverlayVisibilityEnforcement)) continue;
+    if (defaultOnRaw !== "true" && defaultOnRaw !== "false") continue;
+
+    const childXml = match[2] ?? "";
+    const authoredMatch = childXml.match(/<bw:authoredBy\b([^>]*)\/>/u);
+    const authoredAttrs = authoredMatch
+      ? parseAttributes(authoredMatch[1] ?? "")
+      : undefined;
+    const authoredBy =
+      authoredAttrs?.actorId && authoredAttrs?.at
+        ? { actorId: authoredAttrs.actorId, at: authoredAttrs.at }
+        : undefined;
+
+    policies.push({
+      kind: kind as OverlayKind,
+      enforcement: enforcement as OverlayVisibilityEnforcement,
+      defaultOn: defaultOnRaw === "true",
+      ...(authoredBy ? { authoredBy } : {}),
+    });
+  }
+  return policies;
+}
+
 function buildItemPropsXml(itemId: string): string {
   return [
     `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,

package/src/model/anchor.ts

@@ -0,0 +1,85 @@
+/**
+ * Pure-data anchor shapes shared by the review-record types in
+ * `src/model/review/**` and the mapping mechanism in
+ * `src/core/selection/mapping.ts`. Anchors are model-level concerns — they
+ * describe where on a `CanonicalDocument` a revision or comment is
+ * attached — while the mapping / remap engine that evolves anchors across
+ * transactions remains in core.
+ *
+ * Moved here from `src/core/selection/mapping.ts` so the model layer can
+ * define `RevisionRecord` + `CommentThread` without importing up into core.
+ * The old mapping module re-exports every symbol in this file for
+ * back-compat; existing call-sites continue to work unchanged.
+ */
+
+export type Position = number;
+export type Assoc = -1 | 1;
+
+export interface DocRange {
+  from: Position;
+  to: Position;
+}
+
+export interface BoundaryAssoc {
+  start: Assoc;
+  end: Assoc;
+}
+
+export interface RangeAnchor {
+  kind: "range";
+  range: DocRange;
+  assoc: BoundaryAssoc;
+}
+
+export interface NodeAnchor {
+  kind: "node";
+  at: Position;
+  assoc: Assoc;
+}
+
+export interface DetachedAnchor {
+  kind: "detached";
+  lastKnownRange: DocRange;
+  reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
+}
+
+/**
+ * Internal representation of an anchor projection — uses `DocRange` so
+ * mapping helpers compose ranges independently of assoc semantics. The
+ * public-facing shape lives at `src/api/public-types.ts` (same simple name
+ * `EditorAnchorProjection`) and is flat (`{ kind: "range", from, to, assoc }`).
+ * Conversion between the two goes through `src/core/selection/anchor-conversion.ts`.
+ */
+export type InternalEditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+
+/**
+ * @deprecated X3 Phase 5 — prefer `InternalEditorAnchorProjection` to avoid
+ * name-collision with the public `EditorAnchorProjection` from
+ * `src/api/public-types.ts`. Internal call-sites have migrated (via
+ * `import type { EditorAnchorProjection as InternalEditorAnchorProjection }`
+ * aliasing in `document-runtime.ts`). This alias stays for one release cycle
+ * so third-party internal consumers don't break. Remove in v2.1+.
+ */
+export type EditorAnchorProjection = InternalEditorAnchorProjection;
+
+export const DEFAULT_BOUNDARY_ASSOC: BoundaryAssoc = {
+  start: 1,
+  end: -1,
+};
+
+export function normalizeRange(range: DocRange): DocRange {
+  return range.from <= range.to
+    ? { from: range.from, to: range.to }
+    : { from: range.to, to: range.from };
+}
+
+export function createDetachedAnchor(
+  lastKnownRange: DocRange,
+  reason: DetachedAnchor["reason"],
+): DetachedAnchor {
+  return {
+    kind: "detached",
+    lastKnownRange: normalizeRange(lastKnownRange),
+    reason,
+  };
+}