@beyondwork/docx-react-component 1.0.48 → 1.0.49

package/src/io/ooxml/parse-complex-content.ts

@@ -108,8 +108,11 @@ export function parseComplexContentXml(
   const uri = graphicData.attributes.uri ?? graphicData.attributes["uri"] ?? "";
   if (isChartUri(uri)) {
     const parsedData = maybeParseChart(root, chartPartLookup);
-    const node: ParsedChartContent = { type: "chart_preview", rawXml: drawingXml };
-    if (parsedData) node.parsedData = parsedData;
+    const node: ParsedChartContent = {
+      type: "chart_preview",
+      ...(parsedData ? { parsedData } : {}),
+      rawXml: drawingXml,
+    };
     return node;
   }
   if (isSmartArtUri(uri)) {
@@ -229,9 +232,9 @@ function parseAlternateContent(
       ...(previewMediaId ? { previewMediaId } : {}),
       ...(previewPackagePartName ? { previewPackagePartName } : {}),
       ...(previewContentType ? { previewContentType } : {}),
+      ...(parsedData ? { parsedData } : {}),
       rawXml: fullDrawingXml,
     };
-    if (parsedData) node.parsedData = parsedData;
     return node;
   }
 

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

@@ -67,6 +67,37 @@ import {
   readTableStyleId as readSharedTableStyleId,
   readTableWidth as readSharedTableWidth,
 } from "./parse-tables.ts";
+import {
+  buildGrabBagSourceChildFromParsed,
+  capturePropertyGrabBag,
+  type PropertyGrabBagDescriptor,
+} from "./property-grab-bag.ts";
+
+/**
+ * Modelled direct children of `<w:sectPr>` that `parseSectionPropertiesFromElement`
+ * below dispatches into typed fields on `SectionProperties`. Anything else
+ * becomes a grab-bag entry so a parse→serialize round-trip preserves
+ * extension-namespace section properties and Word-internal knobs the
+ * canonical model doesn't understand. Mirrors Slice 1/2 pPr/rPr coverage.
+ */
+const SECT_PR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "cols",
+  "docGrid",
+  "footerReference",
+  "headerReference",
+  "lnNumType",
+  "pgBorders",
+  "pgMar",
+  "pgNumType",
+  "pgSz",
+  "titlePg",
+  "type",
+]);
+
+const SECT_PR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: SECT_PR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
 
 export interface ParsedMainDocument {
   blocks: ParsedBlockNode[];
@@ -3170,6 +3201,16 @@ export function parseSectionPropertiesFromElement(
     }
   }
 
+  // Grab-bag capture for unmodelled <w:sectPr> children (O2 Slice 4).
+  const sourceChildren = node.children
+    .filter((child): child is XmlElementNode => child.type === "element")
+    .map((child) => buildGrabBagSourceChildFromParsed(child));
+  const unknown = capturePropertyGrabBag(
+    sourceChildren,
+    SECT_PR_GRAB_BAG_DESCRIPTOR,
+  );
+  if (unknown) props.unknownPropertyChildren = unknown;
+
   return props;
 }
 

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

@@ -17,6 +17,42 @@ import type {
 import { readRunProperties } from "./parse-run-formatting.ts";
 import { findChildOptional, localName, readIntAttr, readIntVal, readOnOff } from "./xml-attr-helpers.ts";
 import type { XmlElementNode } from "./xml-element.ts";
+import {
+  buildGrabBagSourceChildFromParsed,
+  capturePropertyGrabBag,
+  type PropertyGrabBagDescriptor,
+} from "./property-grab-bag.ts";
+
+/**
+ * Modelled direct children of `<w:pPr>` that `readParagraphProperties` below
+ * dispatches into typed fields on `CanonicalParagraphFormatting`. Anything
+ * else becomes a grab-bag entry so a parse→serialize round-trip preserves
+ * extension-namespace properties like `<w15:collapsed>` or Word-internal
+ * knobs like `<w:kinsoku>` that our canonical model doesn't understand.
+ */
+const PPR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "spacing",
+  "ind",
+  "jc",
+  "pBdr",
+  "shd",
+  "tabs",
+  "keepNext",
+  "keepLines",
+  "widowControl",
+  "pageBreakBefore",
+  "contextualSpacing",
+  "bidi",
+  "suppressLineNumbers",
+  "suppressAutoHyphens",
+  "outlineLvl",
+  "rPr",
+]);
+
+const PPR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: PPR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
 
 function readSpacing(node: XmlElementNode): ParagraphSpacing | undefined {
   const out: ParagraphSpacing = {};
@@ -184,5 +220,15 @@ export function readParagraphProperties(
   const markRpr = readRunProperties(rPrNode);
   if (markRpr) out.paragraphMarkRunProperties = markRpr;
 
+  // Capture any unmodelled direct children of <w:pPr> so a parse→serialize
+  // round-trip does not silently drop extension-namespace properties
+  // (w15:collapsed, w16cex:..., w:kinsoku, etc.). See Lane 3 O2 plan +
+  // src/io/ooxml/property-grab-bag.ts for the pattern.
+  const sourceChildren = node.children
+    .filter((child): child is XmlElementNode => child.type === "element")
+    .map((child) => buildGrabBagSourceChildFromParsed(child));
+  const unknown = capturePropertyGrabBag(sourceChildren, PPR_GRAB_BAG_DESCRIPTOR);
+  if (unknown) out.unknownPropertyChildren = unknown;
+
   return Object.keys(out).length > 0 ? out : undefined;
 }

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

@@ -1,6 +1,42 @@
 import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
 import { findChildOptional, readIntVal, readOnOff, readStringAttr } from "./xml-attr-helpers.ts";
 import type { XmlElementNode } from "./xml-element.ts";
+import {
+  buildGrabBagSourceChildFromParsed,
+  capturePropertyGrabBag,
+  type PropertyGrabBagDescriptor,
+} from "./property-grab-bag.ts";
+
+/**
+ * Modelled direct children of `<w:rPr>` that `readRunProperties` dispatches
+ * into typed fields on `CanonicalRunFormatting`. Anything else goes through
+ * the grab-bag helper so a parse→serialize round-trip preserves extension-
+ * namespace properties (e.g. `<w14:textOutline>`, `<w:em>`, `<w:kern>`).
+ */
+const RPR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "b",
+  "i",
+  "strike",
+  "dstrike",
+  "vanish",
+  "caps",
+  "smallCaps",
+  "u",
+  "vertAlign",
+  "rFonts",
+  "sz",
+  "szCs",
+  "color",
+  "highlight",
+  "spacing",
+  "rStyle",
+  "lang",
+]);
+
+const RPR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: RPR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
 
 /**
  * Read `<w:rPr>` (run properties) into a `CanonicalRunFormatting` value.
@@ -101,8 +137,14 @@ export function readRunProperties(
     const val = color.attributes["w:val"] ?? color.attributes["val"];
     const theme =
       color.attributes["w:themeColor"] ?? color.attributes["themeColor"];
+    const tint =
+      color.attributes["w:themeTint"] ?? color.attributes["themeTint"];
+    const shade =
+      color.attributes["w:themeShade"] ?? color.attributes["themeShade"];
     if (val) rPr.colorHex = val;
     if (theme) rPr.colorThemeSlot = theme;
+    if (tint) rPr.colorThemeTint = tint;
+    if (shade) rPr.colorThemeShade = shade;
   }
 
   const highlight = findChildOptional(node, "highlight");
@@ -125,5 +167,12 @@ export function readRunProperties(
     if (val) rPr.languageCode = val;
   }
 
+  // Grab-bag capture: unmodelled <w:rPr> children survive round-trip.
+  const sourceChildren = node.children
+    .filter((child): child is XmlElementNode => child.type === "element")
+    .map((child) => buildGrabBagSourceChildFromParsed(child));
+  const unknown = capturePropertyGrabBag(sourceChildren, RPR_GRAB_BAG_DESCRIPTOR);
+  if (unknown) rPr.unknownPropertyChildren = unknown;
+
   return Object.keys(rPr).length > 0 ? rPr : undefined;
 }

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

@@ -0,0 +1,211 @@
+/**
+ * Property-level grab-bag primitive for Lane 3 O2.
+ *
+ * LibreOffice captures unmodelled children / attributes on every OOXML
+ * 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
+ * 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.
+ *
+ * This module is a small, framework-free adapter: per-container parsers
+ * supply a descriptor listing modelled child names (and later, modelled
+ * attributes on modelled children); the helper returns everything else as
+ * raw XML in insertion order. The matching emitter is a one-liner that
+ * just joins `rawXml` strings.
+ *
+ * Scope (O2 Slice 1): per-container child diff only — the unknown-attribute
+ * diff on modelled children is a follow-up slice. Today the descriptor's
+ * `modelledChildAttributes` is declared but ignored; the helper emits a
+ * whole-child entry only when the element's localName is NOT in
+ * `modelledChildNames`.
+ */
+
+/**
+ * Input node shape accepted by `capturePropertyGrabBag`. Intentionally
+ * minimal so every caller can adapt their own scanner output — per-file
+ * parsers in `src/io/ooxml/` each carry a slightly different node shape.
+ */
+export interface GrabBagSourceChild {
+  /**
+   * Local element name (no namespace prefix). E.g. `"kinsoku"` for
+   * `<w:kinsoku>`, `"collapsed"` for `<w15:collapsed>`.
+   */
+  localName: string;
+  /**
+   * The source XML for the entire child element, including its opening
+   * tag, all attributes, any children, and its closing tag (or the
+   * self-closing form). Preserved verbatim for re-emission.
+   */
+  rawXml: string;
+}
+
+/**
+ * Interop helper for callers that only carry the parsed `XmlElementNode`
+ * shape used by `src/io/ooxml/xml-element.ts`. Reconstructs a best-effort
+ * `rawXml` string from the parsed tree so parsers that don't track source
+ * offsets can still feed the grab-bag helper.
+ *
+ * The reconstruction preserves element/attribute semantic content and
+ * attribute insertion order (since `Record<string, string>` iteration in
+ * V8 is insertion-ordered for string keys) but does NOT guarantee
+ * byte-identical source preservation: whitespace between elements and
+ * attribute quoting style are normalized. For the Slice 1 scope this is
+ * the correct trade-off — unmodelled children's semantic content
+ * survives, which closes the silent-drop gap.
+ */
+export function buildGrabBagSourceChildFromParsed(node: {
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+}): GrabBagSourceChild {
+  return {
+    localName: localNameOf(node.name),
+    rawXml: serializeElementToString(node),
+  };
+}
+
+function localNameOf(qualified: string): string {
+  const colon = qualified.indexOf(":");
+  return colon < 0 ? qualified : qualified.slice(colon + 1);
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}
+
+function escapeText(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;");
+}
+
+function serializeElementToString(node: {
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+}): string {
+  const attrs = Object.entries(node.attributes)
+    .map(([name, value]) => ` ${name}="${escapeAttr(value)}"`)
+    .join("");
+  if (node.children.length === 0) {
+    return `<${node.name}${attrs}/>`;
+  }
+  const body = node.children
+    .map((child) => {
+      if (child.type === "text") return escapeText(child.text);
+      return serializeElementToString(
+        child as {
+          name: string;
+          attributes: Record<string, string>;
+          children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+        },
+      );
+    })
+    .join("");
+  return `<${node.name}${attrs}>${body}</${node.name}>`;
+}
+
+/**
+ * Descriptor a per-container parser supplies to the helper to declare
+ * which child element names it dispatches into its modelled fields.
+ * Children not listed here become grab-bag entries.
+ */
+export interface PropertyGrabBagDescriptor {
+  /**
+   * Set of local names the container parser handles natively. Children
+   * whose `localName` matches one of these are NOT captured.
+   */
+  modelledChildNames: ReadonlySet<string>;
+  /**
+   * Reserved for the follow-up slice: per-modelled-child the set of
+   * attributes the parser consumes. The Slice 1 helper ignores this
+   * field; Slice 2 will use it to emit attribute-level grab entries on
+   * modelled children.
+   *
+   * Note: table containers (tblPr/trPr/tcPr — O2 Slice 3) currently use
+   * a parallel raw-XML mechanism in `src/io/export/table-properties-xml.ts`
+   * (`mergePropertiesXml`) that stores the full container XML as a string
+   * on `TableNode.propertiesXml`/`TableRowNode.propertiesXml`/
+   * `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`.
+   */
+  modelledChildAttributes: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+/**
+ * Single grab-bag entry: an unmodelled top-level child captured verbatim
+ * so the serializer can re-emit it inside its container without any
+ * round-trip loss.
+ */
+export interface UnknownPropertyChild {
+  /**
+   * Qualified element name as it appeared in the source (e.g.
+   * `"w:kinsoku"`, `"w15:collapsed"`). Used for diagnostics and for the
+   * future attribute-level diff so the emitter can re-open the matching
+   * element when needed.
+   */
+  elementName: string;
+  /**
+   * Verbatim XML for the child element.
+   */
+  rawXml: string;
+}
+
+/**
+ * Walk the container's direct children. Return every child whose
+ * `localName` is NOT in `descriptor.modelledChildNames` as a grab-bag
+ * entry in source order. Returns `undefined` when no unmodelled children
+ * were found — callers should prefer `undefined` over an empty array so
+ * the canonical model stays sparse.
+ *
+ * The helper does NOT inspect attributes or grandchildren. That
+ * refinement is reserved for the follow-up slice.
+ */
+export function capturePropertyGrabBag(
+  children: readonly GrabBagSourceChild[],
+  descriptor: PropertyGrabBagDescriptor,
+): UnknownPropertyChild[] | undefined {
+  const bag: UnknownPropertyChild[] = [];
+  for (const child of children) {
+    if (descriptor.modelledChildNames.has(child.localName)) continue;
+    bag.push({
+      elementName: extractQualifiedNameFromRawXml(child.rawXml) ?? child.localName,
+      rawXml: child.rawXml,
+    });
+  }
+  return bag.length > 0 ? bag : undefined;
+}
+
+/**
+ * Emit a grab-bag list back into a property container. Just concatenates
+ * each entry's `rawXml` in insertion order — the source bytes survive
+ * verbatim including attribute order, whitespace inside the element, and
+ * namespace prefixes.
+ */
+export function emitPropertyGrabBag(
+  entries: readonly UnknownPropertyChild[] | undefined,
+): string {
+  if (!entries || entries.length === 0) return "";
+  return entries.map((entry) => entry.rawXml).join("");
+}
+
+/**
+ * Best-effort extraction of the qualified element name from an opening
+ * tag — e.g. `<w15:collapsed w:val="1"/>` → `"w15:collapsed"`. Falls back
+ * to the caller-supplied `localName` when the raw XML doesn't look like
+ * a valid element.
+ */
+function extractQualifiedNameFromRawXml(rawXml: string): string | undefined {
+  const match = rawXml.match(/^<([^\s/>]+)/u);
+  return match?.[1];
+}

package/src/model/canonical-document.ts

@@ -472,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". */
@@ -496,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. */
@@ -896,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 {
@@ -1078,10 +1137,17 @@ export interface ChartPreviewNode {
    * (`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.
+   * 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.
    */
-  parsedData?: ChartModel;
+  readonly parsedData?: ChartModel;
   rawXml: string;
 }
 

package/src/runtime/collab/index.ts

@@ -42,3 +42,10 @@ export {
   type RemoteCursorTrackerHandle,
   type RemoteCursorTrackerOptions,
 } from "./remote-cursor-awareness.ts";
+export {
+  createWorkflowShared,
+  type CreateWorkflowSharedOptions,
+  type SharedWorkflowState,
+  type WorkflowSharedHandle,
+  type WorkflowSharedResult,
+} from "./workflow-shared.ts";

package/src/runtime/collab/runtime-collab-sync.ts

@@ -22,6 +22,7 @@ import {
 } from "./event-types.ts";
 import { computeBaseDocFingerprint } from "./base-doc-fingerprint.ts";
 import type { Checkpoint } from "./checkpoint-store.ts";
+import { createWorkflowShared, type WorkflowSharedHandle } from "./workflow-shared.ts";
 
 /** Shared Y.Map key — {@link SHARED_META_MAP_KEY}. */
 const SHARED_META_MAP_KEY = "meta";
@@ -188,6 +189,17 @@ export interface RuntimeCollabSyncOptions {
   runtime: DocumentRuntime;
   authorId: string;
   commandAppliedBridge: RuntimeCommandAppliedBridge;
+  /**
+   * Role of the local peer for workflow-shared gating. Defaults to `"author"`
+   * for backward compatibility with pre-P13 callers — ⚠ OMITTING THIS FIELD
+   * GRANTS AUTHOR-LEVEL WRITE ACCESS to the shared `workflow` Y.Map. Hosts
+   * that derive role from Awareness or an external auth layer should pass
+   * it explicitly to avoid silently promoting reviewers/observers to authors.
+   * - `"author"`: all workflow writes allowed.
+   * - `"reviewer"`: only `setAssignedReviewers` allowed; other writes refused.
+   * - `"observer"`: all writes refused with `collab_observer_readonly`.
+   */
+  role?: "author" | "reviewer" | "observer";
 }
 
 export interface RuntimeCollabSyncHandle {
@@ -217,6 +229,14 @@ export interface RuntimeCollabSyncHandle {
    * checkpoint covers previously-seen events).
    */
   getAppliedEventCount(): number;
+  /**
+   * Returns the shared workflow handle backing the `workflow` Y.Map.
+   * Hosts can call `.setLockedMode()`, `.setRoundDeadline()`,
+   * `.setAssignedReviewers()`, and `.setWorkItemId()` to propagate
+   * state changes to other peers. Role gating (passed in `options.role`)
+   * enforces write permissions per §7 of the lane plan.
+   */
+  getWorkflowShared(): WorkflowSharedHandle;
 }
 
 export function createRuntimeCommandAppliedBridge(): RuntimeCommandAppliedBridge {
@@ -332,6 +352,31 @@ export function createRuntimeCollabSync(
     emit({ type: "collab_sync_attached", baseDocFingerprint });
   }
 
+  // ---------------------------------------------------------------------------
+  // Workflow shared state — P13 Slice C
+  // ---------------------------------------------------------------------------
+  // Construct a WorkflowSharedHandle over `ydoc.getMap("workflow")`. The
+  // handle subscribes to Y.Map changes and propagates them to the runtime
+  // via `setSharedWorkflowState`. Role gating is enforced by the handle
+  // itself; the `role` option defaults to `"author"` for historical compat.
+  const effectiveRole = options.role ?? "author";
+  const workflowShared = createWorkflowShared({
+    ydoc,
+    role: effectiveRole,
+    localAuthorId: authorId,
+  });
+
+  // Seed initial state synchronously. For a fresh Y.Doc this is `{}`.
+  // For a late joiner it may already be populated — the seed ensures the
+  // runtime reflects pre-existing shared state at attach time (i.e. if a
+  // peer already set `lockedMode`, the new peer starts out locked).
+  runtime.setSharedWorkflowState(workflowShared.get());
+
+  const workflowUnsub = workflowShared.subscribe((state) => {
+    if (readOnly) return; // don't propagate while in read-only (post-mismatch)
+    runtime.setSharedWorkflowState(state);
+  });
+
   const unsubscribeCommandApplied = commandAppliedBridge.subscribe((command, _transaction, context, meta) => {
     if (readOnly) {
       return;
@@ -453,6 +498,9 @@ export function createRuntimeCollabSync(
       yEvents.unobserve(onYEventsChange);
       yMeta.unobserve(checkFingerprintAgainstMeta);
       yCheckpoints.unobserve(onCheckpointsChange);
+      workflowUnsub();
+      workflowShared.destroy();
+      runtime.setSharedWorkflowState(null);
       listeners.clear();
     },
     subscribe(listener) {
@@ -481,6 +529,9 @@ export function createRuntimeCollabSync(
     getAppliedEventCount() {
       return appliedEventIds.size;
     },
+    getWorkflowShared() {
+      return workflowShared;
+    },
   };
 
   function onYEventsChange(event: Y.YArrayEvent<CommandEvent>): void {