@beyondwork/docx-react-component 1.0.106 → 1.0.109

package/src/runtime/workflow/word-field-matrix-calibration.ts

@@ -0,0 +1,231 @@
+import type {
+  CommentSidebarSnapshot,
+  TrackedChangesSnapshot,
+  WorkflowMarkupSnapshot,
+} from "../../api/public-types.ts";
+
+export type WorkflowWordFieldAvailability = "available" | "partial" | "missing";
+
+export interface WorkflowWordFieldMatrixRowLike {
+  readonly group: string;
+  readonly field: string;
+  readonly primaryOwner: string;
+  readonly wordStatus: WorkflowWordFieldAvailability;
+  readonly wordEvidencePath: string;
+  readonly routingNote?: string;
+}
+
+export type WorkflowReviewWordFieldFact =
+  | "clean-vs-markup-page-counts"
+  | "revision-and-comment-counts"
+  | "bookmark-and-comment-anchors";
+
+export type WorkflowReviewWordFieldRepresentation =
+  | "durable-workflow-review-posture"
+  | "explicit-anchor-evidence"
+  | "missing-matrix-row"
+  | "word-fact-missing";
+
+export interface WorkflowReviewWordFieldCalibrationFact {
+  readonly fact: WorkflowReviewWordFieldFact;
+  readonly matrixGroup: string;
+  readonly matrixField: string;
+  readonly wordEvidencePath: string;
+  readonly wordStatus: WorkflowWordFieldAvailability | "row-missing";
+  readonly representation: WorkflowReviewWordFieldRepresentation;
+  readonly l06Surfaces: readonly string[];
+  readonly downstreamRoutes: readonly string[];
+  readonly localEvidence: Readonly<Record<string, number | string | boolean>>;
+  readonly note: string;
+}
+
+export interface WorkflowReviewWordFieldCalibration {
+  readonly schemaVersion: "l06-word-field-matrix-calibration/v0";
+  readonly facts: readonly WorkflowReviewWordFieldCalibrationFact[];
+  readonly summary: {
+    readonly representedFacts: number;
+    readonly explicitAnchorEvidenceFacts: number;
+    readonly missingMatrixRows: number;
+    readonly missingWordFacts: number;
+    readonly downstreamRouteCount: number;
+  };
+}
+
+export interface WorkflowReviewWordFieldCalibrationInput {
+  readonly rows: readonly WorkflowWordFieldMatrixRowLike[];
+  readonly workflowMarkup?: WorkflowMarkupSnapshot;
+  readonly comments?: CommentSidebarSnapshot;
+  readonly trackedChanges?: TrackedChangesSnapshot;
+}
+
+const EXPECTED_FACTS = [
+  {
+    fact: "clean-vs-markup-page-counts" as const,
+    group: "reviewMarkup",
+    field: "cleanVsMarkupPageCounts",
+    representation: "durable-workflow-review-posture" as const,
+    surfaces: [
+      "WorkflowMarkupModePolicy",
+      "WorkflowMarkupSnapshot.revisions",
+      "TrackedChangesSnapshot.revisions",
+    ],
+    downstreamRoutes: ["L04 clean-vs-markup page delta", "L11 review markup visibility"],
+    note:
+      "L06 owns the review posture and revision visibility decision; page-count deltas remain L04/L11 evidence consumers, not L06 geometry.",
+  },
+  {
+    fact: "revision-and-comment-counts" as const,
+    group: "reviewMarkup",
+    field: "revisionAndCommentCounts",
+    representation: "durable-workflow-review-posture" as const,
+    surfaces: [
+      "WorkflowMarkupSnapshot.revisions",
+      "WorkflowMarkupSnapshot.comments",
+      "TrackedChangesSnapshot.revisions",
+      "CommentSidebarSnapshot.threads",
+    ],
+    downstreamRoutes: ["L11 review/comment lane visibility"],
+    note:
+      "L06 review stores and markup snapshots carry the durable revision/comment counts before presentation paints them.",
+  },
+  {
+    fact: "bookmark-and-comment-anchors" as const,
+    group: "anchorsAndObjects",
+    field: "bookmarkAndCommentAnchors",
+    representation: "explicit-anchor-evidence" as const,
+    surfaces: [
+      "CommentSidebarSnapshot.threads[].anchor",
+      "WorkflowMarkupSnapshot.comments[].anchor",
+      "WorkflowMarkupSnapshot.revisions[].anchor",
+    ],
+    downstreamRoutes: [
+      "L04/L05 anchor geometry lookup",
+      "L11 comment/bookmark visual placement",
+      "L08 bookmark/scope semantic joins",
+    ],
+    note:
+      "Comment and revision anchors are durable L06 review evidence; bookmark placement stays an explicit routed fact rather than an L06 visual/geometry claim.",
+  },
+] as const;
+
+export function calibrateWorkflowReviewWordFieldMatrix(
+  input: WorkflowReviewWordFieldCalibrationInput,
+): WorkflowReviewWordFieldCalibration {
+  const facts = EXPECTED_FACTS.map((spec) => {
+    const row = input.rows.find(
+      (candidate) =>
+        candidate.primaryOwner === "L06" &&
+        candidate.group === spec.group &&
+        candidate.field === spec.field,
+    );
+    return buildFact(spec, row, input);
+  });
+
+  return {
+    schemaVersion: "l06-word-field-matrix-calibration/v0",
+    facts,
+    summary: {
+      representedFacts: facts.filter(
+        (fact) => fact.representation === "durable-workflow-review-posture",
+      ).length,
+      explicitAnchorEvidenceFacts: facts.filter(
+        (fact) => fact.representation === "explicit-anchor-evidence",
+      ).length,
+      missingMatrixRows: facts.filter((fact) => fact.representation === "missing-matrix-row")
+        .length,
+      missingWordFacts: facts.filter((fact) => fact.representation === "word-fact-missing")
+        .length,
+      downstreamRouteCount: new Set(facts.flatMap((fact) => fact.downstreamRoutes)).size,
+    },
+  };
+}
+
+function buildFact(
+  spec: (typeof EXPECTED_FACTS)[number],
+  row: WorkflowWordFieldMatrixRowLike | undefined,
+  input: WorkflowReviewWordFieldCalibrationInput,
+): WorkflowReviewWordFieldCalibrationFact {
+  if (!row) {
+    return {
+      fact: spec.fact,
+      matrixGroup: spec.group,
+      matrixField: spec.field,
+      wordEvidencePath: "",
+      wordStatus: "row-missing",
+      representation: "missing-matrix-row",
+      l06Surfaces: spec.surfaces,
+      downstreamRoutes: spec.downstreamRoutes,
+      localEvidence: collectLocalEvidence(spec.fact, input),
+      note: `Missing L06-owned Word field matrix row for ${spec.group}.${spec.field}.`,
+    };
+  }
+
+  const representation =
+    row.wordStatus === "missing" ? "word-fact-missing" : spec.representation;
+
+  return {
+    fact: spec.fact,
+    matrixGroup: row.group,
+    matrixField: row.field,
+    wordEvidencePath: row.wordEvidencePath,
+    wordStatus: row.wordStatus,
+    representation,
+    l06Surfaces: spec.surfaces,
+    downstreamRoutes: spec.downstreamRoutes,
+    localEvidence: collectLocalEvidence(spec.fact, input),
+    note: row.wordStatus === "missing" ? row.routingNote ?? "Word fact is missing." : spec.note,
+  };
+}
+
+function collectLocalEvidence(
+  fact: WorkflowReviewWordFieldFact,
+  input: WorkflowReviewWordFieldCalibrationInput,
+): Readonly<Record<string, number | string | boolean>> {
+  const markupRevisionCount = input.workflowMarkup?.revisions.length ?? 0;
+  const markupCommentCount = input.workflowMarkup?.comments.length ?? 0;
+  const trackedRevisionCount = input.trackedChanges?.revisions.length ?? markupRevisionCount;
+  const sidebarCommentCount = input.comments?.threads.length ?? markupCommentCount;
+
+  switch (fact) {
+    case "clean-vs-markup-page-counts":
+      return {
+        hasMarkupPostureSurface: true,
+        markupRevisionCount,
+        trackedRevisionCount,
+        ownsPageGeometry: false,
+      };
+    case "revision-and-comment-counts":
+      return {
+        markupRevisionCount,
+        markupCommentCount,
+        trackedRevisionCount,
+        sidebarCommentCount,
+        reconciledCounts:
+          markupRevisionCount === trackedRevisionCount &&
+          markupCommentCount === sidebarCommentCount,
+      };
+    case "bookmark-and-comment-anchors":
+      return {
+        commentAnchorCount: countAnchors(input.workflowMarkup?.comments, input.comments?.threads),
+        revisionAnchorCount: countAnchors(input.workflowMarkup?.revisions, input.trackedChanges?.revisions),
+        detachedAnchorCount:
+          countDetachedAnchors(input.workflowMarkup?.comments, input.comments?.threads) +
+          countDetachedAnchors(input.workflowMarkup?.revisions, input.trackedChanges?.revisions),
+        ownsBookmarkGeometry: false,
+      };
+  }
+}
+
+function countAnchors(
+  primary: readonly { readonly anchor?: { readonly kind: string } }[] | undefined,
+  fallback: readonly { readonly anchor?: { readonly kind: string } }[] | undefined,
+): number {
+  return (primary ?? fallback ?? []).filter((item) => item.anchor != null).length;
+}
+
+function countDetachedAnchors(
+  primary: readonly { readonly anchor?: { readonly kind: string } }[] | undefined,
+  fallback: readonly { readonly anchor?: { readonly kind: string } }[] | undefined,
+): number {
+  return (primary ?? fallback ?? []).filter((item) => item.anchor?.kind === "detached").length;
+}

package/src/session/_sync-legacy.ts

@@ -1,38 +1,28 @@
 /**
- * Transitional sync entry — wraps `loadDocxEditorSession` from the
- * legacy `src/io/docx-session.ts` for the two sync call sites inside
- * `src/ui/editor-runtime-boundary.ts` that cannot (yet) await.
+ * Transitional sync entry — wraps the in-layer sync loader for the
+ * shell/UI call site that still needs a synchronous first-paint
+ * decision.
  *
  * Why this module exists.
  * =======================
  * `DocxSession.open()` is async per the architecture (the loader
- * yields between parse stages so the browser can paint). Two
- * `editor-runtime-boundary` paths need a sync load:
+ * yields between parse stages so the browser can paint). A small
+ * compatibility surface still needs a sync load:
  *
  *   1. `createRuntime`'s SSR / Node fallback — runs when no
  *      `preloadedDocxSession` was produced by the async warm path but
  *      `initialDocx` bytes are present. `createRuntime` is sync, so a
  *      sync loader is the only entry that keeps the mount simple.
- *      Slice 5e-9 is expected to eliminate this fallback altogether
- *      by requiring the async warm path to run, OR by making
- *      `createRuntime` async-capable.
- *
- *   2. `resolvePackageBackedExportSession` — resolves an embedded
- *      source-package blob to decide the export barrier for
- *      snapshot-only mounts. The result drives the compatibility
- *      report that shows on first paint; deferring to first export
- *      would regress the blocked-export UX. Slice 5e-9 may thread a
- *      preloaded barrier session through the async warm path
- *      instead.
+ *      A future shell cleanup can eliminate this fallback by requiring
+ *      the async warm path to run, or by making `createRuntime`
+ *      async-capable.
  *
  * Isolation.
  * ==========
- * By routing both sync call sites through this one module, the
- * `src/ui/editor-runtime-boundary.ts` file no longer imports directly
- * from `src/io/docx-session.ts`. The transit is pinned as a
- * WARNING-level debt exception in
- * `scripts/ci-check-session-layer-purity.mjs`, so the legacy-import
- * surface shrinks to one narrow file that Slice 5e-9 deletes whole.
+ * By routing sync compatibility through this one module, callers do
+ * not import from the back-compat `src/io/docx-session.ts` shim. This
+ * module reaches only the in-session loader, so the purity checker has
+ * zero debt exceptions.
  *
  * Not exported from the session barrel.
  * =====================================
@@ -46,16 +36,16 @@
 import { loadDocxSessionSync } from "./import/loader.ts";
 
 /**
- * Sync docx load — returns the legacy-shaped handle the two
- * `editor-runtime-boundary` sync call sites currently consume.
+ * Sync docx load — returns the legacy-shaped handle the
+ * `editor-runtime-boundary` SSR/Node raw-DOCX fallback currently consumes.
  *
  * Options + result are typed via `Parameters<>` / `ReturnType<>` so
  * this module does not force its loader-types dependency to widen
  * publicly.
  *
- * Removed in Slice 5e-9 when the sync call sites either flip to
- * `await DocxSession.open(...)` or rely on a preloaded session
- * produced by the async warm path.
+ * Kept only for sync compatibility. New code should use
+ * `await new DocxSession().open(...)` or
+ * `await new DocxSession().reopenFromSnapshot(...)`.
  */
 export type SyncLegacyOpenOptions = Parameters<typeof loadDocxSessionSync>[0];
 

package/src/session/import/loader.ts

@@ -378,15 +378,17 @@ export async function loadDocxSessionAsync(
       const protectionSnapshot = buildProtectionSnapshot(documentProtection, []);
 
       // Chart previews (`previewMediaId` is host-dependent) aren't cached
-      // in the envelope. C3b: when onChartPreviewsReady is provided, defer
-      // resolution out of the critical path. Otherwise block (legacy behavior).
+      // in the envelope. Cold opens preserve the legacy blocking fallback
+      // when no callback is supplied. Warm laycache opens must not re-enter
+      // chart parsing on the critical path, so schedule async resolution even
+      // for hosts that did not provide a callback.
       let documentWithChartPreviews: CanonicalDocument;
-      if (options.onChartPreviewsReady) {
+      if (options.onChartPreviewsReady || laycacheEnvelope) {
         scheduleChartPreviewResolution(
           canonicalDocument,
           sourcePackage,
           options.hostAdapter,
-          options.onChartPreviewsReady,
+          options.onChartPreviewsReady ?? (() => {}),
         );
         documentWithChartPreviews = canonicalDocument as CanonicalDocument;
       } else {

package/src/session/import/source-package-evidence.ts

@@ -9,7 +9,8 @@ import {
 } from "../../io/ooxml/part-manifest.ts";
 import { parseXml, parseXmlWithOffsets } from "../../io/ooxml/xml-parser.ts";
 import type { XmlElementNode } from "../../io/ooxml/xml-element.ts";
-import { localName } from "../../io/ooxml/xml-attr-helpers.ts";
+import { streamWalkFieldGroups } from "../../io/ooxml/parse-fields.ts";
+import { localName, readStringAttr, textContent } from "../../io/ooxml/xml-attr-helpers.ts";
 import {
   resolveMainDocumentPartPath,
 } from "./part-discovery.ts";
@@ -26,6 +27,7 @@ export interface SourcePackageElementCounts {
   fieldMarkers: number;
   fieldInstructions: number;
   simpleFields: number;
+  hyperlinks: number;
   bookmarks: number;
   footnotes: number;
   endnotes: number;
@@ -36,6 +38,7 @@ export interface SourcePackagePartEvidence {
   storyKind: SourcePackageStoryKind;
   contentType: string | null;
   byteLength: number;
+  sha256Hex: string;
   relationshipCount: number;
   counts: SourcePackageElementCounts;
 }
@@ -60,6 +63,20 @@ export interface SourcePackageLocationEvidence {
   endOffset?: number;
 }
 
+export interface SourcePackageFieldSequenceEvidence
+  extends SourcePackageLocationEvidence {
+  fieldSequenceKind: "complex" | "simple" | "hyperlink";
+  instructionFamily: string;
+  instructionHash?: string;
+  normalizedInstructionHash?: string;
+  resultHash?: string;
+  instructionLength?: number;
+  resultLength?: number;
+  cachedDisplayAvailable: boolean;
+  relationshipId?: string;
+  anchor?: string;
+}
+
 export interface SourcePackageStoryPartDescriptor {
   sourceId: string;
   partPath: string;
@@ -131,6 +148,7 @@ export interface SourcePackageLayoutInventoryEvidence {
   sections: SourcePackageSectionDescriptorEvidence[];
   tables: SourcePackageLocationEvidence[];
   fields: SourcePackageLocationEvidence[];
+  fieldSequences: SourcePackageFieldSequenceEvidence[];
   drawings: SourcePackageLocationEvidence[];
   vmlShapes: SourcePackageLocationEvidence[];
   contentControls: SourcePackageLocationEvidence[];
@@ -203,6 +221,7 @@ const ZERO_COUNTS: SourcePackageElementCounts = {
   fieldMarkers: 0,
   fieldInstructions: 0,
   simpleFields: 0,
+  hyperlinks: 0,
   bookmarks: 0,
   footnotes: 0,
   endnotes: 0,
@@ -305,6 +324,7 @@ function summarizePart(
     storyKind,
     contentType: part.contentType,
     byteLength: part.bytes.byteLength,
+    sha256Hex: sha256Hex(part.bytes),
     relationshipCount: part.relationships.length,
     counts: countPartElements(part, storyKind, parseErrors),
   };
@@ -384,6 +404,9 @@ function countElements(root: XmlElementNode): SourcePackageElementCounts {
       case "fldSimple":
         counts.simpleFields += 1;
         break;
+      case "hyperlink":
+        counts.hyperlinks += 1;
+        break;
       case "bookmarkStart":
         counts.bookmarks += 1;
         break;
@@ -421,6 +444,7 @@ function collectLayoutInventory(
     | "sections"
     | "tables"
     | "fields"
+    | "fieldSequences"
     | "drawings"
     | "vmlShapes"
     | "contentControls"
@@ -431,6 +455,7 @@ function collectLayoutInventory(
     sections: [],
     tables: [],
     fields: [],
+    fieldSequences: [],
     drawings: [],
     vmlShapes: [],
     contentControls: [],
@@ -457,7 +482,18 @@ function collectLayoutInventory(
 
     let root: XmlElementNode;
     try {
-      root = parseXmlWithOffsets(new TextDecoder("utf-8").decode(part.bytes));
+      const sourceXml = new TextDecoder("utf-8").decode(part.bytes);
+      root = parseXmlWithOffsets(sourceXml);
+      collectFieldSequences(
+        root,
+        sourceXml,
+        {
+          partPath: part.path,
+          storyKind,
+          relationships: sourceRelationshipByPart.get(part.path) ?? [],
+        },
+        locations.fieldSequences,
+      );
     } catch (error) {
       parseErrors.push({
         partPath: part.path,
@@ -606,6 +642,7 @@ function collectPartLocations(
       case "fldSimple":
       case "fldChar":
       case "instrText":
+      case "hyperlink":
         locations.fields.push(locationFor(context, node, name, nextOrdinal(name)));
         break;
       case "drawing": {
@@ -652,6 +689,152 @@ function collectPartLocations(
   visit(root);
 }
 
+function collectFieldSequences(
+  root: XmlElementNode,
+  sourceXml: string,
+  context: {
+    partPath: string;
+    storyKind: SourcePackageStoryKind;
+    relationships: SourcePackageRelationshipEvidence[];
+  },
+  fieldSequences: SourcePackageFieldSequenceEvidence[],
+): void {
+  let sequenceOrdinal = fieldSequences.length;
+  const nextSequenceOrdinal = (): number => {
+    sequenceOrdinal += 1;
+    return sequenceOrdinal;
+  };
+
+  for (const group of streamWalkFieldGroups(sourceXml)) {
+    const ordinal = nextSequenceOrdinal();
+    const instruction = group.instruction.trim();
+    const resultText = textFromXmlFragment(group.displayContent);
+    fieldSequences.push({
+      sourceId: sequenceSourceId(context.partPath, ordinal),
+      partPath: context.partPath,
+      storyKind: context.storyKind,
+      element: "fldCharSequence",
+      ordinal,
+      startOffset: group.start,
+      endOffset: group.end,
+      fieldSequenceKind: "complex",
+      instructionFamily: instructionFamily(instruction),
+      ...hashedInstruction(instruction),
+      ...hashedResult(resultText),
+      cachedDisplayAvailable: resultText.length > 0,
+    });
+  }
+
+  const visit = (node: XmlElementNode): void => {
+    const name = localName(node.name);
+    if (name === "fldSimple") {
+      const ordinal = nextSequenceOrdinal();
+      const instruction = (readStringAttr(node, "w:instr") ?? "").trim();
+      const resultText = textContent(node);
+      fieldSequences.push({
+        ...locationFor(context, node, "fieldSequence", ordinal),
+        element: "fldSimple",
+        fieldSequenceKind: "simple",
+        instructionFamily: instructionFamily(instruction),
+        ...hashedInstruction(instruction),
+        ...hashedResult(resultText),
+        cachedDisplayAvailable: resultText.length > 0,
+      });
+    } else if (name === "hyperlink") {
+      const ordinal = nextSequenceOrdinal();
+      const relationshipId = readStringAttr(node, "r:id");
+      const anchor = readStringAttr(node, "w:anchor");
+      const target = relationshipId
+        ? context.relationships.find(
+            (relationship) => relationship.relationshipId === relationshipId,
+          )?.target
+        : undefined;
+      const instruction = [
+        "HYPERLINK",
+        anchor ? "anchor" : undefined,
+        anchor,
+        relationshipId ? "relationship" : undefined,
+        relationshipId,
+        target ? "target" : undefined,
+        target,
+      ].filter((value): value is string => Boolean(value)).join(" ");
+      const resultText = textContent(node);
+      fieldSequences.push({
+        ...locationFor(context, node, "fieldSequence", ordinal),
+        element: "hyperlink",
+        fieldSequenceKind: "hyperlink",
+        instructionFamily: "HYPERLINK",
+        ...hashedInstruction(instruction),
+        ...hashedResult(resultText),
+        cachedDisplayAvailable: resultText.length > 0,
+        ...(relationshipId !== undefined ? { relationshipId } : {}),
+        ...(anchor !== undefined ? { anchor } : {}),
+      });
+    }
+
+    for (const child of node.children) {
+      if (child.type === "element") {
+        visit(child);
+      }
+    }
+  };
+
+  visit(root);
+}
+
+function sequenceSourceId(partPath: string, ordinal: number): string {
+  return `${partSourceId(partPath)}#fieldSequence:${ordinal}`;
+}
+
+function instructionFamily(instruction: string): string {
+  const normalized = normalizeInstruction(instruction);
+  const family = normalized.match(/^[A-Z0-9_]+/u)?.[0] ?? "";
+  return family || "UNKNOWN";
+}
+
+function hashedInstruction(
+  instruction: string,
+): Pick<
+  SourcePackageFieldSequenceEvidence,
+  "instructionHash" | "normalizedInstructionHash" | "instructionLength"
+> {
+  if (instruction.length === 0) {
+    return { instructionLength: 0 };
+  }
+  const normalized = normalizeInstruction(instruction);
+  return {
+    instructionHash: hashText(instruction),
+    normalizedInstructionHash: hashText(normalized),
+    instructionLength: instruction.length,
+  };
+}
+
+function hashedResult(
+  resultText: string,
+): Pick<SourcePackageFieldSequenceEvidence, "resultHash" | "resultLength"> {
+  return {
+    resultHash: hashText(resultText),
+    resultLength: resultText.length,
+  };
+}
+
+function hashText(value: string): string {
+  return sha256Hex(new TextEncoder().encode(value));
+}
+
+function normalizeInstruction(instruction: string): string {
+  return instruction.trim().replace(/\s+/gu, " ").toUpperCase();
+}
+
+function textFromXmlFragment(xml: string): string {
+  if (xml.trim().length === 0) return "";
+  try {
+    return textContent(parseXml(`<root>${xml}</root>`));
+  } catch {
+    return xml.replace(/<[^>]*>/gu, "").replace(/\s+/gu, " ").trim();
+  }
+}
+
 function locationFor(
   context: {
     partPath: string;
@@ -847,6 +1030,7 @@ function aggregateElementCounts(
     aggregate.fieldMarkers += counts.fieldMarkers;
     aggregate.fieldInstructions += counts.fieldInstructions;
     aggregate.simpleFields += counts.simpleFields;
+    aggregate.hyperlinks += counts.hyperlinks;
     aggregate.bookmarks += counts.bookmarks;
     aggregate.footnotes += counts.footnotes;
     aggregate.endnotes += counts.endnotes;

package/src/session/index.ts

@@ -1,12 +1,11 @@
 /**
  * Public barrel for Layer 01 (package / session).
  *
- * Reserved shape — matches `docs/architecture/01-package-session.md`
+ * Public shape — matches `docs/architecture/01-package-session.md`
  * § Public entry points. Consumers should import from `src/session`
  * (or the `@beyondwork/docx-react-component/session` package subpath)
- * rather than reaching into `src/io/docx-session.ts`. The legacy entry
- * points remain exported from the root barrel for back-compat until
- * Slice 5 deletes them.
+ * rather than reaching into the back-compat `src/io/docx-session.ts`
+ * shim.
  */
 
 export {
@@ -17,7 +16,7 @@ export {
 export { isReopenBarrier } from "./types.ts";
 export type { EditorSessionState } from "./session-state.ts";
 export type {
-  // Reserved Layer-01 contract types.
+  // Layer-01 contract types.
   OpenOptions,
   OpenResult,
   ExportOptions,
@@ -28,7 +27,7 @@ export type {
   EmbeddedDocumentManifest,
   // P8 Step 7 offload surface.
   ReopenBarrier,
-  // Transitional re-exports from the legacy IO layer.
+  // Back-compat public types also exposed from the session package.
   ExportResult,
   EditorHostAdapter,
   ExportDocxOptions,