@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/model/canonical-document.ts

@@ -12,6 +12,14 @@ import {
   expectUuid,
   stableStringify,
 } from "./cds-1.0.0.ts";
+import type {
+  ScopeMarkerStartNode,
+  ScopeMarkerEndNode,
+} from "./scope-markers.ts";
+import type { ChartModel } from "../io/ooxml/chart/types.ts";
+
+export type { ScopeMarkerStartNode, ScopeMarkerEndNode } from "./scope-markers.ts";
+export type { ChartModel } from "../io/ooxml/chart/types.ts";
 
 const CANONICAL_DOCUMENT_TOP_LEVEL_KEYS = [
   "schemaVersion",
@@ -97,6 +105,14 @@ export interface ParagraphStyleDefinition {
   isDefault: boolean;
   paragraphProperties?: CanonicalParagraphFormatting;
   runProperties?: CanonicalRunFormatting;
+  /**
+   * Style ID of the linked character style (from `<w:link w:val="..."/>`).
+   * Populated during parse; the second-pass resolver in `parse-styles.ts`
+   * synthesizes the reciprocal link on the partner when the source only
+   * declares the relationship on one side. Mirrors LibreOffice's
+   * `StyleSheetTable.cxx:535` second pass.
+   */
+  linkedStyleId?: string;
 }
 
 export interface ParagraphStyleNumberingReference {
@@ -111,6 +127,12 @@ export interface CharacterStyleDefinition {
   kind: "character";
   isDefault: boolean;
   runProperties?: CanonicalRunFormatting;
+  /**
+   * Style ID of the linked paragraph style (from `<w:link w:val="..."/>`).
+   * See `ParagraphStyleDefinition.linkedStyleId` for the second-pass
+   * reciprocal-resolution contract.
+   */
+  linkedStyleId?: string;
 }
 
 export interface TableStyleDefinition {
@@ -257,9 +279,63 @@ export interface ThemeDefinition {
   fontScheme?: ThemeFontScheme;
 }
 
+/**
+ * One <w:compatSetting> entry under <w:compat>. Word emits multiple of these
+ * with the same `name` across different `uri` namespaces, so the canonical
+ * shape is an ordered tuple list rather than a name→value map.
+ *
+ * `value` is preserved as the raw `w:val` string (e.g. "15", "1", "0") so the
+ * future serializer can re-emit byte-stable diffs.
+ */
+export interface CompatSetting {
+  name: string;
+  uri: string;
+  value: string;
+}
+
 export interface DocumentSettings {
   evenAndOddHeaders?: boolean;
   zoomLevel?: "pageWidth" | "onePage" | number;
+  /**
+   * Ordered list of <w:compatSetting> entries inside <w:compat>. Insertion
+   * order is preserved for serializer diff stability.
+   */
+  compatSettings?: CompatSetting[];
+  /**
+   * Boolean flag children of <w:compat> that are NOT <w:compatSetting>
+   * (e.g. <w:spaceForUL/>, <w:doNotExpandShiftReturn/>). Keyed by local
+   * element name. The value reflects ST_OnOff semantics: missing `w:val` is
+   * true; explicit `w:val="0"`/`"false"` is false.
+   */
+  compatFlags?: Record<string, boolean>;
+  /**
+   * Settings-level (NOT inside <w:compat>) compat-adjacent boolean flags
+   * such as <w:doNotEmbedSmartTags/>. Kept in a separate field from
+   * compatFlags because the OOXML location differs and the future
+   * serializer must re-emit them at root, not inside <w:compat>.
+   */
+  rootCompatFlags?: Record<string, boolean>;
+  /**
+   * <w:themeFontLang> attribute bag, captured verbatim so the future
+   * serializer can re-emit unknown attributes Word may add.
+   *
+   * Distinguishes three states:
+   *   - undefined: the element was absent.
+   *   - {}: the element existed with no attributes.
+   *   - { "w:val": "en-US", … }: attributes preserved with their qualified
+   *     names so the serializer round-trips namespace prefixes intact.
+   */
+  themeFontLang?: Record<string, string>;
+  /**
+   * Local names of every direct child of <w:settings> that this parser does
+   * not model individually. Insertion order preserved; duplicates retained.
+   *
+   * Diagnostic only — round-trip is served by whole-part preservation while
+   * settings.xml stays out of `ownedOutputPaths`. The future serializer will
+   * use this list as a validator assertion that every preserved child still
+   * appears in the re-emitted output.
+   */
+  unmodelledSettingsChildren?: string[];
 }
 
 export interface SubPartsCatalog {
@@ -305,6 +381,8 @@ export type DocumentNode =
   | FieldNode
   | BookmarkStartNode
   | BookmarkEndNode
+  | ScopeMarkerStartNode
+  | ScopeMarkerEndNode
   | SectionBreakNode
   | OpaqueInlineNode
   | OpaqueBlockNode
@@ -394,10 +472,34 @@ export interface CanonicalRunFormatting {
    */
   colorHex?: string;
   colorThemeSlot?: string;
+  /**
+   * `w:themeTint` hex byte (0x00–0xFF) read from `<w:color>`. ECMA-376
+   * §17.18.85. Applied at render/cascade time against `colorThemeSlot`:
+   * luminance mod = (1 - tint/255) * L + tint/255 (shifts hue toward
+   * white; 0xFF means no modulation). Preserved as the raw hex string
+   * for byte-stable round-trip; resolution math lives in the runtime
+   * theme-color resolver.
+   */
+  colorThemeTint?: string;
+  /**
+   * `w:themeShade` hex byte (0x00–0xFF) from `<w:color>`. ECMA-376
+   * §17.18.83. Applied at render/cascade time: luminance mod =
+   * shade/255 * L (darkens toward black; 0xFF means no modulation).
+   */
+  colorThemeShade?: string;
   highlight?: string;
   characterSpacingTwips?: number;
   characterStyleId?: string;
   languageCode?: string;
+  /**
+   * Unmodelled direct children of `<w:rPr>` captured verbatim for round-trip.
+   * See `src/io/ooxml/property-grab-bag.ts` and
+   * `CanonicalParagraphFormatting.unknownPropertyChildren` for the full
+   * pattern. Preserves extension-namespace properties like `<w14:textOutline>`,
+   * `<w:em>`, `<w:kern>` through parse→serialize round-trip even though the
+   * runtime does not model them.
+   */
+  unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
 /** Body of an OOXML `<w:pPr>` (paragraph properties). All fields optional; absence = "not specified at this level". */
@@ -418,6 +520,32 @@ export interface CanonicalParagraphFormatting {
   suppressLineNumbers?: boolean;
   suppressAutoHyphens?: boolean;
   paragraphMarkRunProperties?: CanonicalRunFormatting;
+  /**
+   * Unmodelled direct children of `<w:pPr>` captured verbatim for round-trip.
+   * See `src/io/ooxml/property-grab-bag.ts` for the mechanism and Lane 3 O2
+   * plan for the LibreOffice `PropertyMap.hxx:82` precedent.
+   *
+   * Each entry carries the source XML for an unmodelled child element plus
+   * its qualified name. On export, entries are re-emitted after the
+   * modelled children so Word-extension properties like `<w15:collapsed>`
+   * or `<w:kinsoku>` survive a parse→serialize round-trip even though the
+   * runtime doesn't understand them.
+   */
+  unknownPropertyChildren?: UnknownPropertyChild[];
+}
+
+/**
+ * A single unmodelled direct child of an OOXML property container (pPr,
+ * rPr, tcPr, trPr, tblPr, sectPr). Captured verbatim so the serializer
+ * re-emits source bytes without loss. See `src/io/ooxml/property-grab-bag.ts`
+ * for the helper that computes the diff against a per-container modelled-
+ * child allow-list.
+ */
+export interface UnknownPropertyChild {
+  /** Qualified element name as it appeared in source, e.g. "w15:collapsed". */
+  elementName: string;
+  /** Verbatim source XML for the child element, including closing/self-closing form. */
+  rawXml: string;
 }
 
 /** Body of an OOXML `<w:docDefaults>` — baseline formatting applied before style chain. */
@@ -818,6 +946,15 @@ export interface SectionProperties {
   footerReferences?: HeaderFooterReference[];
   sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
   titlePage?: boolean;
+  /**
+   * Unmodelled direct children of `<w:sectPr>` captured verbatim for
+   * round-trip. Mirrors `CanonicalParagraphFormatting.unknownPropertyChildren`
+   * and `CanonicalRunFormatting.unknownPropertyChildren` (Lane 3 O2 Slices
+   * 1+2). Preserves extension-namespace properties like
+   * `<w15:footnoteColumns>` and Word-internal section knobs through a
+   * parse→serialize round-trip when the runtime mutates section properties.
+   */
+  unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
 export interface PageSize {
@@ -890,6 +1027,8 @@ export type InlineNode =
   | FieldNode
   | BookmarkStartNode
   | BookmarkEndNode
+  | ScopeMarkerStartNode
+  | ScopeMarkerEndNode
   | OpaqueInlineNode
   | FootnoteRefNode
   | ChartPreviewNode
@@ -992,6 +1131,23 @@ export interface OpaqueInlineNode {
 export interface ChartPreviewNode {
   type: "chart_preview";
   previewMediaId?: string;
+  /**
+   * Typed chart data model parsed from the `c:chartSpace` part, when
+   * available. Populated at import time by the Stage 1 chart parser
+   * (`src/io/ooxml/chart/parse-chart-space.ts`). Undefined when the chart
+   * part cannot be located, fails to parse, or has no chart-family match
+   * — consumers fall back to the fallback bitmap (`previewMediaId`) or the
+   * typed badge in that case.
+   *
+   * **`rawXml` is the authoritative round-trip source** regardless of
+   * whether `parsedData` is populated. `parsedData` is a read-only
+   * projection of that rawXml; mutating it would diverge the two fields
+   * and silently degrade export fidelity. The `readonly` modifier
+   * enforces this at the type level — any future collab-replay that
+   * needs to edit a chart must round-trip through `rawXml`, not patch
+   * `parsedData` in place.
+   */
+  readonly parsedData?: ChartModel;
   rawXml: string;
 }
 
@@ -1658,6 +1814,10 @@ function validateDocumentNode(
     case "bookmark_end":
       expectString(record.bookmarkId, `${path}.bookmarkId`, issues);
       return;
+    case "scope_marker_start":
+    case "scope_marker_end":
+      expectString(record.scopeId, `${path}.scopeId`, issues);
+      return;
     case "section_break":
       return;
     case "text":

package/src/model/scope-markers.ts

@@ -0,0 +1,144 @@
+import type {
+  CanonicalDocument,
+  DocumentNode,
+  DocumentRootNode,
+} from "./canonical-document.ts";
+
+/**
+ * Inline zero-width marker that opens a workflow scope. Modeled on
+ * `BookmarkStartNode` — the marker lives IN the document so PM handles
+ * position bookkeeping for free. `scopeId` is the key; metadata persistence
+ * is orthogonal and owned by `WorkflowOverlay` + customXml payloads.
+ */
+export interface ScopeMarkerStartNode {
+  type: "scope_marker_start";
+  scopeId: string;
+}
+
+/**
+ * Inline zero-width marker that closes a workflow scope opened by a matching
+ * `ScopeMarkerStartNode` with the same `scopeId`.
+ */
+export interface ScopeMarkerEndNode {
+  type: "scope_marker_end";
+  scopeId: string;
+}
+
+export type ScopeMarkerNode = ScopeMarkerStartNode | ScopeMarkerEndNode;
+
+export function isScopeMarkerNode(node: unknown): node is ScopeMarkerNode {
+  if (typeof node !== "object" || node === null) return false;
+  const t = (node as { type?: unknown }).type;
+  return t === "scope_marker_start" || t === "scope_marker_end";
+}
+
+export interface ScopeMarkerWalkEntry {
+  scopeId: string;
+  source: "canonical";
+  status: "paired" | "start-only" | "end-only";
+  startIndex?: number;
+  endIndex?: number;
+}
+
+interface OpenScopeMarker {
+  scopeId: string;
+  startIndex: number;
+}
+
+/**
+ * Walk the canonical document in pre-order and return one entry per scope
+ * detected. A paired entry carries both `startIndex` + `endIndex`; an
+ * unpaired entry has only the surviving side filled.
+ */
+export function collectScopeMarkers(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): ScopeMarkerWalkEntry[] {
+  const root = ("content" in document
+    ? document.content
+    : document) as DocumentNode | DocumentRootNode;
+  const sequence: ScopeMarkerNode[] = [];
+
+  walkDocument(root, (node) => {
+    if (isScopeMarkerNode(node)) {
+      sequence.push(node);
+    }
+  });
+
+  const open = new Map<string, OpenScopeMarker[]>();
+  const results: ScopeMarkerWalkEntry[] = [];
+
+  for (let index = 0; index < sequence.length; index += 1) {
+    const marker = sequence[index]!;
+    if (marker.type === "scope_marker_start") {
+      const stack = open.get(marker.scopeId) ?? [];
+      stack.push({ scopeId: marker.scopeId, startIndex: index });
+      open.set(marker.scopeId, stack);
+      continue;
+    }
+
+    const stack = open.get(marker.scopeId);
+    const opener = stack?.pop();
+    if (stack && stack.length === 0) {
+      open.delete(marker.scopeId);
+    }
+
+    if (opener) {
+      results.push({
+        scopeId: marker.scopeId,
+        source: "canonical",
+        status: "paired",
+        startIndex: opener.startIndex,
+        endIndex: index,
+      });
+      continue;
+    }
+
+    results.push({
+      scopeId: marker.scopeId,
+      source: "canonical",
+      status: "end-only",
+      endIndex: index,
+    });
+  }
+
+  for (const stack of open.values()) {
+    for (const opener of stack) {
+      results.push({
+        scopeId: opener.scopeId,
+        source: "canonical",
+        status: "start-only",
+        startIndex: opener.startIndex,
+      });
+    }
+  }
+
+  return results.sort(
+    (left, right) =>
+      (left.startIndex ?? left.endIndex ?? Number.MAX_SAFE_INTEGER) -
+        (right.startIndex ?? right.endIndex ?? Number.MAX_SAFE_INTEGER) ||
+      left.scopeId.localeCompare(right.scopeId),
+  );
+}
+
+function walkDocument(
+  node: DocumentNode | DocumentRootNode,
+  visit: (node: DocumentNode) => void,
+): void {
+  visit(node as DocumentNode);
+
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      walkDocument(child as DocumentNode, visit);
+    }
+  }
+
+  if (node.type === "table") {
+    for (const row of node.rows) {
+      walkDocument(row, visit);
+    }
+  } else if (node.type === "table_row") {
+    for (const cell of node.cells) {
+      walkDocument(cell, visit);
+    }
+  }
+}

package/src/runtime/collab/base-doc-fingerprint.ts

@@ -0,0 +1,99 @@
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import { sha256Hex } from "../../io/source-package-provenance.ts";
+
+/**
+ * Computes a deterministic fingerprint of the base-doc portion of a
+ * {@link CanonicalDocumentEnvelope}. The fingerprint is used by
+ * `createRuntimeCollabSync` to verify that every peer attaching to a
+ * shared `Y.Doc` started from the same canonical content.
+ *
+ * The fingerprint intentionally **excludes** session-local identity
+ * fields so two peers loading the same source `.docx` under different
+ * local session IDs still converge on the same hash:
+ *
+ * | Field | Included | Rationale |
+ * |---|---|---|
+ * | `schemaVersion` | yes | CDS contract version; mismatch is a different base |
+ * | `metadata` | yes | customProperties are part of the document |
+ * | `styles` | yes | style cascade is base content |
+ * | `numbering` | yes | numbering definitions are base content |
+ * | `media` | yes | embedded media are base content |
+ * | `content` | yes | the editable body tree |
+ * | `preservation` | yes | opaque fragments round-trip identically from the source |
+ * | `docId` | **no** | session-local |
+ * | `createdAt` / `updatedAt` | **no** | session-local timestamps |
+ * | `review` | **no** | tracked changes are session state |
+ * | `diagnostics` | **no** | validator output is session state |
+ * | `subParts` / `fieldRegistry` | **no** | may be partially session-computed |
+ *
+ * Hash pipeline: the subset is serialized via {@link stableStringify}
+ * (sorts object keys recursively, preserves array order, follows
+ * `JSON.stringify` semantics for `undefined`), encoded UTF-8, and fed
+ * to `sha256Hex` from `src/io/source-package-provenance.ts`. Returns a
+ * 64-char lowercase hex string.
+ *
+ * This function is pure and synchronous — safe to call at attach time
+ * without breaking the `createRuntimeCollabSync` disposer contract.
+ */
+export function computeBaseDocFingerprint(envelope: CanonicalDocumentEnvelope): string {
+  const subset = {
+    schemaVersion: envelope.schemaVersion,
+    metadata: envelope.metadata,
+    styles: envelope.styles,
+    numbering: envelope.numbering,
+    media: envelope.media,
+    content: envelope.content,
+    preservation: envelope.preservation,
+  };
+  const serialized = stableStringify(subset);
+  const bytes = new TextEncoder().encode(serialized);
+  return sha256Hex(bytes);
+}
+
+/**
+ * Deterministic JSON-like serializer. Object keys are sorted
+ * alphabetically at every depth; arrays preserve order; `undefined`
+ * values in objects are skipped, `undefined` values in arrays become
+ * `null` — matching `JSON.stringify` semantics. Primitives emit
+ * identically to `JSON.stringify`.
+ *
+ * Exported for unit testing and for callers that want to hash a
+ * narrower slice of the envelope.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "null";
+
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    const parts: string[] = [];
+    for (const item of value) {
+      parts.push(item === undefined ? "null" : stableStringify(item));
+    }
+    return "[" + parts.join(",") + "]";
+  }
+
+  if (t === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys: string[] = [];
+    for (const key of Object.keys(obj)) {
+      if (obj[key] !== undefined) {
+        keys.push(key);
+      }
+    }
+    keys.sort();
+    const parts: string[] = [];
+    for (const key of keys) {
+      parts.push(JSON.stringify(key) + ":" + stableStringify(obj[key]));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+
+  // Functions, symbols, bigints — should not appear in a canonical
+  // envelope. Fall back to `null` to keep the output valid JSON-ish.
+  return "null";
+}

package/src/runtime/collab/checkpoint-election.ts

@@ -0,0 +1,75 @@
+import type { Awareness } from "y-protocols/awareness";
+
+/**
+ * Election policy for "which peer should write the next checkpoint":
+ * the peer with the lowest `clientID` currently visible in
+ * `awareness.getStates()` wins. Deterministic, zero-coordination, and
+ * stable across the network (every peer independently computes the
+ * same winner).
+ *
+ * Properties:
+ * - `clientID` is stable per Y.Doc lifetime, so a peer does not drift
+ *   between elected / not-elected while connected.
+ * - If the elected peer disconnects, `awareness` emits `change` with
+ *   `removed`, and the next-lowest peer observes the change + becomes
+ *   elected. No consensus handshake needed.
+ * - If awareness is empty (no peers have published state yet), no peer
+ *   is elected — wait for `setLocalStateField` / `setLocalState` calls
+ *   to land.
+ *
+ * NOT a leader-election primitive with fencing / lease semantics. Two
+ * peers racing at exactly the same split-second could both believe
+ * they're elected and both write a checkpoint. That is benign — both
+ * writes flow into the same `Y.Array<Checkpoint>`; joiners simply see
+ * two consecutive checkpoints and apply the last one. Bandwidth cost
+ * is one extra snapshot per race, no correctness impact.
+ */
+export function isElectedCheckpointAuthor(
+  awareness: Awareness,
+  localClientId: number,
+): boolean {
+  const states = awareness.getStates();
+  if (states.size === 0) return false;
+  let minClientId: number | null = null;
+  for (const [clientId] of states) {
+    if (minClientId === null || clientId < minClientId) {
+      minClientId = clientId;
+    }
+  }
+  return minClientId === localClientId;
+}
+
+/**
+ * Subscribes to election-status changes for the local client. Fires
+ * immediately on subscribe with the current status, then on every
+ * awareness `change` where the elected status flips. Never fires
+ * consecutively with the same value.
+ *
+ * Returns an unsubscribe function.
+ */
+export function subscribeElectedCheckpointAuthor(
+  awareness: Awareness,
+  localClientId: number,
+  listener: (isElected: boolean) => void,
+): () => void {
+  let lastValue: boolean | null = null;
+
+  function check(): void {
+    const elected = isElectedCheckpointAuthor(awareness, localClientId);
+    if (elected !== lastValue) {
+      lastValue = elected;
+      try {
+        listener(elected);
+      } catch {
+        // Listener errors are isolated.
+      }
+    }
+  }
+
+  awareness.on("change", check);
+  check();
+
+  return () => {
+    awareness.off("change", check);
+  };
+}