@beyondwork/docx-react-component 1.0.41 → 1.0.43

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

@@ -12,6 +12,54 @@ import type {
   WorkflowScope,
   WorkflowWorkItem,
 } from "../../api/public-types.ts";
+import type { EditorStateNamespace, EditorStateLocation } from "../../api/editor-state-types.ts";
+import {
+  validateWorkflowPayloadEnvelope,
+  type ValidatorIssue,
+} from "./workflow-payload-validator.ts";
+
+// ---------------------------------------------------------------------------
+// Schema 1.2 editor-state types (edge-of-module shape, channel-free)
+// ---------------------------------------------------------------------------
+
+export interface EditorStatePayloadNamespaceEntry {
+  namespace: EditorStateNamespace;
+  schemaVersion: string;
+  /** JSON-serializable blob (CDATA-wrapped on serialize). Exactly one of inline/storageRef. */
+  inline?: unknown;
+  storageRef?: { location: Exclude<EditorStateLocation, "in-document">; entryKey: string };
+  /**
+   * Parser-internal flag: set when the `<bw:inline>` CDATA block contained
+   * malformed JSON.  Hydration surfaces this as `editor_state_part_load_failed`
+   * rather than silently dropping the entry.
+   */
+  malformedInline?: boolean;
+}
+
+export interface EditorStatePayload {
+  entries: EditorStatePayloadNamespaceEntry[];
+  /** Unknown namespaces preserved for round-trip — raw XML fragment per entry, keyed by name. */
+  unknownNamespaces?: Array<{ name: string; rawXml: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Schema 1.1 parser helpers (fail-closed per spec §8.2)
+// ---------------------------------------------------------------------------
+
+function parseClosedEnum<T extends string>(
+  raw: string | undefined,
+  allowed: readonly T[],
+): T | undefined {
+  if (raw === undefined) return undefined;
+  return (allowed as readonly string[]).includes(raw) ? (raw as T) : undefined;
+}
+
+function parseNonNegativeInt(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) return undefined;
+  return n;
+}
 
 export const WORKFLOW_PAYLOAD_PART_PATH = "/customXml/item1.xml";
 export const WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH = "/customXml/itemProps1.xml";
@@ -39,6 +87,9 @@ type EmbeddedWorkflowPayloadDescriptor = {
 export interface WorkflowPayloadEnvelope {
   workflowMetadata: WorkflowMetadataSnapshot;
   workflowOverlay?: WorkflowOverlay;
+  /** Present only when the payload was version 1.2+ and carried a non-empty <bw:editorState> block. */
+  editorState?: EditorStatePayload;
+  validatorIssues?: readonly ValidatorIssue[];
 }
 
 export function getDocumentBackedWorkflowMetadata(
@@ -63,6 +114,8 @@ export function buildWorkflowPayloadParts(input: {
   sourcePackage: OpcPackage;
   workflowMetadata: WorkflowMetadataSnapshot | undefined;
   workflowOverlay?: WorkflowOverlay;
+  /** Optional schema 1.2 editor-state block. Omitted when empty. */
+  editorState?: EditorStatePayload;
   documentId: string;
   createdAt: string;
   updatedAt: string;
@@ -102,6 +155,7 @@ export function buildWorkflowPayloadParts(input: {
     producerVersion: input.producerVersion,
     workflowMetadata,
     workflowOverlay: input.workflowOverlay,
+    editorState: input.editorState,
     preservedExtensionsXml: getPreservedExtensionsXml(input.sourcePackage, descriptor.payloadPartPath),
   });
   const itemPropsXml = buildItemPropsXml(descriptor.itemId);
@@ -144,7 +198,8 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
   }
 
   const xml = decodeUtf8(payloadPart.bytes);
-  const entryMatches = [...xml.matchAll(/<bw:entry\b([^>]*)>([\s\S]*?)<\/bw:entry>/g)];
+  // Match both self-closing (<bw:entry .../>) and body-bearing (<bw:entry ...>body</bw:entry>)
+  const entryMatches = [...xml.matchAll(/<bw:entry\b([^>]*)(?:\/>|>([\s\S]*?)<\/bw:entry>)/g)];
   const definitions: WorkflowMetadataDefinition[] = [];
   const entries: WorkflowMetadataEntry[] = [];
 
@@ -183,6 +238,14 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
     if (!entryId || !metadataId) {
       continue;
     }
+
+    const entryMetadataPersistence = parseClosedEnum(
+      attributes.metadataPersistence,
+      ["internal", "external", "inherit"] as const,
+    );
+    const entryStorageRef = attributes.storageRef;
+    const entryMetadataVersion = parseNonNegativeInt(attributes.metadataVersion);
+
     entries.push({
       entryId,
       metadataId,
@@ -198,15 +261,191 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
       ...(attributes.scope?.startsWith("workItem:")
         ? { workItemId: attributes.scope.slice("workItem:".length) }
         : {}),
+      ...(entryMetadataPersistence !== undefined ? { metadataPersistence: entryMetadataPersistence } : {}),
+      ...(entryStorageRef !== undefined ? { storageRef: entryStorageRef } : {}),
+      ...(entryMetadataVersion !== undefined ? { metadataVersion: entryMetadataVersion } : {}),
     });
   }
 
+  const validatorIssues = validateWorkflowPayloadEnvelope(xml);
+  const editorState = parseEditorStateXml(xml);
   return {
     workflowMetadata: {
       definitions,
       entries,
     },
     workflowOverlay: parseWorkflowOverlay(xml),
+    ...(editorState !== undefined ? { editorState } : {}),
+    ...(validatorIssues.length > 0 ? { validatorIssues } : {}),
+  };
+}
+
+function needsSchemaV11(input: {
+  workflowMetadata: WorkflowMetadataSnapshot;
+  workflowOverlay?: WorkflowOverlay;
+}): boolean {
+  if (input.workflowOverlay?.metadataPersistence !== undefined) {
+    return true;
+  }
+  if (
+    input.workflowOverlay?.scopes?.some(
+      (s) => s.metadataPersistence !== undefined,
+    )
+  ) {
+    return true;
+  }
+  if (
+    input.workflowOverlay?.scopes?.some((s) =>
+      s.metadata?.some(
+        (f) =>
+          f.metadataPersistence !== undefined ||
+          f.storageRef !== undefined ||
+          f.metadataVersion !== undefined,
+      ),
+    )
+  ) {
+    return true;
+  }
+  if (
+    input.workflowMetadata.entries.some(
+      (e) =>
+        e.metadataPersistence !== undefined ||
+        e.storageRef !== undefined ||
+        e.metadataVersion !== undefined,
+    )
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/** Returns true when the payload has at least one namespace entry or unknown namespace to emit. */
+function hasNonEmptyEditorState(es: EditorStatePayload | undefined): boolean {
+  if (!es) return false;
+  return (es.entries.length > 0) || ((es.unknownNamespaces?.length ?? 0) > 0);
+}
+
+// ---------------------------------------------------------------------------
+// Known namespace names (closed set for round-trip; unknown names are opaque)
+// ---------------------------------------------------------------------------
+
+const KNOWN_EDITOR_STATE_NAMESPACES: readonly EditorStateNamespace[] = [
+  "hostAnnotations",
+  "workflowOverlay",
+  "workflowMetadata",
+  "workItems",
+];
+
+const KNOWN_STORAGE_LOCATIONS: ReadonlyArray<Exclude<EditorStateLocation, "in-document">> = [
+  "rowstore",
+  "key-only",
+];
+
+/**
+ * Escapes `]]>` inside CDATA content using the standard XML split:
+ * `]]>` → `]]]]><![CDATA[>`
+ */
+function escapeCdata(text: string): string {
+  return text.replace(/\]\]>/g, "]]]]><![CDATA[>");
+}
+
+/**
+ * Builds the `<bw:editorState>…</bw:editorState>` block.
+ * Returns an empty string when both entries and unknownNamespaces are empty.
+ */
+export function buildEditorStateXml(payload: EditorStatePayload): string {
+  if (!hasNonEmptyEditorState(payload)) {
+    return "";
+  }
+
+  const knownLines = payload.entries.map((entry) => {
+    const nsOpen = `<bw:namespace name="${escapeXml(entry.namespace)}" schemaVersion="${escapeXml(entry.schemaVersion)}">`;
+    let content: string;
+    if (entry.storageRef !== undefined) {
+      content = `<bw:storageRef location="${escapeXml(entry.storageRef.location)}" entryKey="${escapeXml(entry.storageRef.entryKey)}" />`;
+    } else {
+      const json = escapeCdata(JSON.stringify(entry.inline));
+      content = `<bw:inline><![CDATA[${json}]]></bw:inline>`;
+    }
+    return `${nsOpen}${content}</bw:namespace>`;
+  });
+
+  const unknownLines = (payload.unknownNamespaces ?? []).map((u) => u.rawXml);
+
+  const innerXml = [...knownLines, ...unknownLines].join("\n");
+  return `<bw:editorState>\n${indentLines(innerXml, 2)}\n</bw:editorState>`;
+}
+
+/**
+ * Parses the `<bw:editorState>` block from a full workflow payload XML string.
+ * Returns `undefined` when no block is present.
+ * Malformed JSON is silently skipped (validator flags it separately).
+ */
+export function parseEditorStateXml(xml: string): EditorStatePayload | undefined {
+  const blockMatch = xml.match(/<bw:editorState\b[^>]*>([\s\S]*?)<\/bw:editorState>/u);
+  if (!blockMatch) {
+    return undefined;
+  }
+  const blockBody = blockMatch[1] ?? "";
+
+  const entries: EditorStatePayloadNamespaceEntry[] = [];
+  const unknownNamespaces: Array<{ name: string; rawXml: string }> = [];
+
+  // Match each <bw:namespace ... > ... </bw:namespace>
+  const nsRe = /<bw:namespace\b([^>]*)>([\s\S]*?)<\/bw:namespace>/gu;
+  for (const nsMatch of blockBody.matchAll(nsRe)) {
+    const attrsStr = nsMatch[1] ?? "";
+    const nsBody = nsMatch[2] ?? "";
+    const rawXml = nsMatch[0] ?? "";
+    const attrs = parseAttributes(attrsStr);
+    const name = attrs.name ?? "";
+    const schemaVersion = attrs.schemaVersion ?? "";
+
+    if (!(KNOWN_EDITOR_STATE_NAMESPACES as readonly string[]).includes(name)) {
+      unknownNamespaces.push({ name, rawXml });
+      continue;
+    }
+
+    const namespace = name as EditorStateNamespace;
+
+    // Parse <bw:storageRef ... />
+    const storageRefMatch = nsBody.match(/<bw:storageRef\b([^>]*)\/>/u);
+    if (storageRefMatch) {
+      const refAttrs = parseAttributes(storageRefMatch[1] ?? "");
+      const location = refAttrs.location as Exclude<EditorStateLocation, "in-document"> | undefined;
+      const entryKey = refAttrs.entryKey ?? "";
+      entries.push({
+        namespace,
+        schemaVersion,
+        storageRef: { location: location ?? "rowstore", entryKey },
+      });
+      continue;
+    }
+
+    // Parse <bw:inline>...</bw:inline> — extract CDATA content
+    const inlineMatch = nsBody.match(/<bw:inline\b[^>]*>([\s\S]*?)<\/bw:inline>/u);
+    if (inlineMatch) {
+      const raw = inlineMatch[1] ?? "";
+      // Extract CDATA content — handles split CDATA sections from ]]> escaping
+      const cdataText = raw.replace(/<!\[CDATA\[|\]\]>/g, "").trim();
+      try {
+        const parsed = JSON.parse(cdataText) as unknown;
+        entries.push({ namespace, schemaVersion, inline: parsed });
+      } catch {
+        // Malformed JSON: surface to the runtime so the host sees a
+        // load-failure event rather than silently losing the entry.
+        entries.push({ namespace, schemaVersion, malformedInline: true });
+      }
+    }
+  }
+
+  if (entries.length === 0 && unknownNamespaces.length === 0) {
+    return undefined;
+  }
+
+  return {
+    entries,
+    ...(unknownNamespaces.length > 0 ? { unknownNamespaces } : {}),
   };
 }
 
@@ -217,8 +456,16 @@ function buildPayloadXml(input: {
   producerVersion: string;
   workflowMetadata: WorkflowMetadataSnapshot;
   workflowOverlay?: WorkflowOverlay;
+  editorState?: EditorStatePayload;
   preservedExtensionsXml: string;
 }): string {
+  const hasEditorState = hasNonEmptyEditorState(input.editorState);
+  const schemaVersion = hasEditorState
+    ? "1.2"
+    : needsSchemaV11(input)
+      ? "1.1"
+      : "1.0";
+
   const definitionEntriesXml = input.workflowMetadata.definitions
     .map((definition) => [
       `<bw:entry`,
@@ -237,7 +484,7 @@ function buildPayloadXml(input: {
       const serializedValue = serializeWorkflowMetadataValue(entry.value);
       const storyTargetAttributes = serializeWorkflowStoryTarget(entry.storyTarget);
 
-      return [
+      const baseAttrs = [
         `<bw:entry`,
         ` key="${escapeXml(entry.entryId)}"`,
         ` metadataId="${escapeXml(entry.metadataId)}"`,
@@ -245,8 +492,24 @@ function buildPayloadXml(input: {
         ` valueType="${escapeXml(serializedValue.type)}"`,
         ` scope="${escapeXml(entry.scopeId ? `scope:${entry.scopeId}` : entry.workItemId ? `workItem:${entry.workItemId}` : "document")}"`,
         storyTargetAttributes,
-        `>${escapeXml(serializedValue.text)}</bw:entry>`,
+        entry.metadataPersistence && entry.metadataPersistence !== "inherit"
+          ? ` metadataPersistence="${escapeXml(entry.metadataPersistence)}"`
+          : "",
+        entry.metadataPersistence === "external" && entry.storageRef
+          ? ` storageRef="${escapeXml(entry.storageRef)}"`
+          : "",
+        typeof entry.metadataVersion === "number" &&
+        Number.isInteger(entry.metadataVersion) &&
+        entry.metadataVersion >= 0
+          ? ` metadataVersion="${entry.metadataVersion.toString()}"`
+          : "",
       ].join("");
+
+      if (entry.metadataPersistence === "external") {
+        return `${baseAttrs}/>`;
+      }
+
+      return `${baseAttrs}>${escapeXml(serializedValue.text)}</bw:entry>`;
     })
     .filter((value) => value.length > 0)
     .join("\n");
@@ -256,9 +519,11 @@ function buildPayloadXml(input: {
     .filter((value) => value.trim().length > 0)
     .join("\n");
 
+  const editorStateXml = hasEditorState ? buildEditorStateXml(input.editorState!) : "";
+
   return [
     `<?xml version="1.0" encoding="UTF-8"?>`,
-    `<bw:workflowPayload xmlns:bw="urn:beyondwork:workflow-payload:1" version="1.0" payloadId="${escapeXml(input.descriptor.payloadId)}" itemId="${escapeXml(input.descriptor.itemId)}" documentId="${escapeXml(input.descriptor.documentId)}" createdAt="${escapeXml(input.createdAt)}" updatedAt="${escapeXml(input.updatedAt)}">`,
+    `<bw:workflowPayload xmlns:bw="urn:beyondwork:workflow-payload:1" version="${schemaVersion}" payloadId="${escapeXml(input.descriptor.payloadId)}" itemId="${escapeXml(input.descriptor.itemId)}" documentId="${escapeXml(input.descriptor.documentId)}" createdAt="${escapeXml(input.createdAt)}" updatedAt="${escapeXml(input.updatedAt)}">`,
     `  <bw:manifest>`,
     `    <bw:producer name="@beyondwork/docx-react-component" version="${escapeXml(input.producerVersion)}" />`,
     `    <bw:compatibility rebindMode="best-effort" preserveUnknownExtensions="true" />`,
@@ -267,6 +532,7 @@ function buildPayloadXml(input: {
     definitionEntriesXml ? indentLines(definitionEntriesXml, 4) : "",
     metadataEntriesXml ? indentLines(metadataEntriesXml, 4) : "",
     `  </bw:metadata>`,
+    editorStateXml,
     extensionsXml
       ? `  <bw:extensions>\n${indentLines(extensionsXml, 4)}\n  </bw:extensions>`
       : `  <bw:extensions />`,
@@ -357,6 +623,9 @@ function buildWorkblockExtensionXml(workflowOverlay: WorkflowOverlay | undefined
       workflowOverlay.activeWorkItemId
         ? ` activeWorkItemId="${escapeXml(workflowOverlay.activeWorkItemId)}"`
         : "",
+      workflowOverlay.metadataPersistence
+        ? ` metadataPersistence="${escapeXml(workflowOverlay.metadataPersistence)}"`
+        : "",
       `>`,
     ].join(""),
     `  <bw:workItems>`,
@@ -380,6 +649,9 @@ function buildWorkflowScopeXml(scope: WorkflowScope): string {
     scope.workItemId ? ` workItemRef="${escapeXml(scope.workItemId)}"` : "",
     scope.label ? ` label="${escapeXml(scope.label)}"` : "",
     scope.domain ? ` domain="${escapeXml(scope.domain)}"` : "",
+    scope.metadataPersistence && scope.metadataPersistence !== "inherit"
+      ? ` metadataPersistence="${escapeXml(scope.metadataPersistence)}"`
+      : "",
     `>`,
     indentLines(buildWorkflowAnchorXml(scope.anchor, scope.storyTarget), 2),
     scopeMetadataXml ? indentLines(scopeMetadataXml, 2) : "",
@@ -397,12 +669,28 @@ function buildWorkflowScopeMetadataXml(scopeMetadata: WorkflowScope["metadata"])
       scopeMetadata
         .map((field) => {
           const serialized = serializeWorkflowScopeMetadataValue(field.valueType, field.value);
-          return [
+          const baseAttrs = [
             `<bw:field`,
             ` key="${escapeXml(field.key)}"`,
             serialized.valueType ? ` type="${escapeXml(serialized.valueType)}"` : "",
-            `>${escapeXml(serialized.text)}</bw:field>`,
+            field.metadataPersistence && field.metadataPersistence !== "inherit"
+              ? ` metadataPersistence="${escapeXml(field.metadataPersistence)}"`
+              : "",
+            field.metadataPersistence === "external" && field.storageRef
+              ? ` storageRef="${escapeXml(field.storageRef)}"`
+              : "",
+            typeof field.metadataVersion === "number" &&
+            Number.isInteger(field.metadataVersion) &&
+            field.metadataVersion >= 0
+              ? ` metadataVersion="${field.metadataVersion.toString()}"`
+              : "",
           ].join("");
+
+          if (field.metadataPersistence === "external") {
+            return `${baseAttrs}/>`;
+          }
+
+          return `${baseAttrs}>${escapeXml(serialized.text)}</bw:field>`;
         })
         .join("\n"),
       2,
@@ -571,11 +859,17 @@ function parseWorkflowOverlay(xml: string): WorkflowOverlay | undefined {
     .map((match) => parseWorkflowWorkItem(match[1] ?? "", match[2] ?? ""))
     .filter((item): item is WorkflowWorkItem => item !== null);
 
+  const overlayMetadataPersistence = parseClosedEnum(
+    overlayAttributes.metadataPersistence,
+    ["internal", "external"] as const,
+  );
+
   return {
     overlayVersion: (overlayAttributes.overlayVersion as WorkflowOverlay["overlayVersion"]) ?? "workflow-overlay/1",
     activeWorkItemId: overlayAttributes.activeWorkItemId ?? null,
     scopes,
     ...(workItems.length > 0 ? { workItems } : {}),
+    ...(overlayMetadataPersistence !== undefined ? { metadataPersistence: overlayMetadataPersistence } : {}),
   };
 }
 
@@ -588,6 +882,11 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
   const anchor = anchorMatch
     ? parseWorkflowOverlayAnchor(anchorMatch[1] ?? "", anchorMatch[2] ?? "")
     : createDefaultRangeAnchor(0, 0);
+  const scopeMetadataPersistence = parseClosedEnum(
+    attributes.metadataPersistence,
+    ["internal", "external", "inherit"] as const,
+  );
+
   return {
     scopeId: attributes.id,
     version: attributes.version !== undefined ? Number(attributes.version) : undefined,
@@ -598,6 +897,7 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
     label: attributes.label,
     domain: attributes.domain as WorkflowScope["domain"],
     metadata: parseWorkflowScopeMetadata(body),
+    ...(scopeMetadataPersistence !== undefined ? { metadataPersistence: scopeMetadataPersistence } : {}),
   };
 }
 
@@ -606,7 +906,8 @@ function parseWorkflowScopeMetadata(body: string): WorkflowScope["metadata"] | u
   if (!metadataMatch) {
     return undefined;
   }
-  const fields = [...(metadataMatch[1] ?? "").matchAll(/<bw:field\b([^>]*)>([\s\S]*?)<\/bw:field>/gu)]
+  // Match both self-closing (<bw:field .../>) and body-bearing (<bw:field ...>body</bw:field>)
+  const fields = [...(metadataMatch[1] ?? "").matchAll(/<bw:field\b([^>]*)(?:\/>|>([\s\S]*?)<\/bw:field>)/gu)]
     .map((match) => parseWorkflowScopeMetadataField(match[1] ?? "", match[2] ?? ""))
     .filter((field): field is NonNullable<WorkflowScope["metadata"]>[number] => field !== null);
   return fields.length > 0 ? fields : undefined;
@@ -621,10 +922,19 @@ function parseWorkflowScopeMetadataField(
     return null;
   }
   const valueType = attributes.type as NonNullable<WorkflowScope["metadata"]>[number]["valueType"] | undefined;
+  const fieldMetadataPersistence = parseClosedEnum(
+    attributes.metadataPersistence,
+    ["internal", "external", "inherit"] as const,
+  );
+  const fieldStorageRef = attributes.storageRef;
+  const fieldMetadataVersion = parseNonNegativeInt(attributes.metadataVersion);
   return {
     key: attributes.key,
     ...(valueType ? { valueType } : {}),
     value: parseWorkflowScopeMetadataValue(valueType, body),
+    ...(fieldMetadataPersistence !== undefined ? { metadataPersistence: fieldMetadataPersistence } : {}),
+    ...(fieldStorageRef !== undefined ? { storageRef: fieldStorageRef } : {}),
+    ...(fieldMetadataVersion !== undefined ? { metadataVersion: fieldMetadataVersion } : {}),
   };
 }
 

package/src/runtime/awareness-identity.ts

@@ -0,0 +1,173 @@
+import type { Awareness } from "y-protocols/awareness";
+
+import type {
+  AwarenessIdentity,
+  AwarenessPeer,
+  CollabPosture,
+  PresenceSnapshot,
+  TransportStatus,
+} from "../api/awareness-identity-types.ts";
+
+const IDENTITY_FIELD = "identity";
+
+const ROLE_VOCAB = new Set<AwarenessIdentity["role"]>([
+  "author",
+  "reviewer",
+  "observer",
+]);
+const KIND_VOCAB = new Set<AwarenessIdentity["authorKind"]>([
+  "human",
+  "agent",
+  "system",
+]);
+
+/**
+ * Publishes the local client's `identity` record onto the Awareness
+ * channel. Every connected peer sees it through
+ * `getPresenceSnapshot`. Safe to call repeatedly — re-writes the
+ * field, which Awareness treats as a full replacement.
+ */
+export function setLocalIdentity(
+  awareness: Awareness,
+  identity: AwarenessIdentity,
+): void {
+  awareness.setLocalStateField(IDENTITY_FIELD, validate(identity));
+}
+
+/**
+ * Clears the local `identity` field. Typically called on disconnect or
+ * role downgrade so stale presence rows don't linger.
+ */
+export function clearLocalIdentity(awareness: Awareness): void {
+  awareness.setLocalStateField(IDENTITY_FIELD, null);
+}
+
+export interface PresenceSnapshotArgs {
+  awareness?: Awareness;
+  transportStatus?: TransportStatus;
+  queuedLocalEvents?: number;
+  /** Used to filter presence by the active story. When omitted, every peer is returned. */
+  activeStoryFilter?: string;
+}
+
+/**
+ * Builds a `PresenceSnapshot` from the current Awareness map + a
+ * host-supplied transport + queue signal. Unknown or malformed
+ * identity entries are silently dropped (fail-closed — never render a
+ * partially-trusted peer).
+ */
+export function getPresenceSnapshot(args: PresenceSnapshotArgs = {}): PresenceSnapshot {
+  const peers: AwarenessPeer[] = [];
+  if (args.awareness) {
+    for (const [clientId, state] of args.awareness.getStates()) {
+      const raw = (state as Record<string, unknown>)[IDENTITY_FIELD];
+      const identity = coerceIdentity(raw);
+      if (!identity) continue;
+      if (
+        args.activeStoryFilter !== undefined &&
+        identity.activeStoryId !== undefined &&
+        identity.activeStoryId !== args.activeStoryFilter
+      ) {
+        continue;
+      }
+      peers.push({ clientId, ...identity });
+    }
+  }
+  return {
+    peers,
+    transportStatus: args.transportStatus ?? "offline",
+    queuedLocalEvents: args.queuedLocalEvents ?? 0,
+  };
+}
+
+export interface CollabPostureArgs {
+  awareness?: Awareness;
+  transportStatus?: TransportStatus;
+}
+
+/**
+ * Derives the local user's posture from the Awareness map. Role comes
+ * from the local-state `identity`; transport comes from the
+ * host-supplied signal; peer count is the presence size minus self.
+ *
+ * Returns a default "unattached author" posture when no Awareness is
+ * wired — this matches the fail-open behaviour of the facet (host
+ * without a Y.Doc gets an author posture so single-user docs work).
+ */
+export function getCollabPosture(args: CollabPostureArgs = {}): CollabPosture {
+  if (!args.awareness) {
+    return { role: "author", transport: "none", peers: 0 };
+  }
+  const localClientId = args.awareness.clientID;
+  const localState = args.awareness.getLocalState() as
+    | Record<string, unknown>
+    | null;
+  const localIdentity = coerceIdentity(localState?.[IDENTITY_FIELD]);
+  const role = localIdentity?.role ?? "author";
+
+  let peers = 0;
+  for (const [clientId, state] of args.awareness.getStates()) {
+    if (clientId === localClientId) continue;
+    const identity = coerceIdentity(
+      (state as Record<string, unknown>)[IDENTITY_FIELD],
+    );
+    if (identity) peers += 1;
+  }
+
+  return {
+    role,
+    transport: args.transportStatus === "offline" ? "attached" : "attached",
+    peers,
+  };
+}
+
+function coerceIdentity(raw: unknown): AwarenessIdentity | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const candidate = raw as Record<string, unknown>;
+  const userId = candidate["userId"];
+  const displayName = candidate["displayName"];
+  const role = candidate["role"];
+  const authorKind = candidate["authorKind"];
+  if (
+    typeof userId !== "string" ||
+    userId === "" ||
+    typeof displayName !== "string" ||
+    displayName === "" ||
+    typeof role !== "string" ||
+    !ROLE_VOCAB.has(role as AwarenessIdentity["role"]) ||
+    typeof authorKind !== "string" ||
+    !KIND_VOCAB.has(authorKind as AwarenessIdentity["authorKind"])
+  ) {
+    return undefined;
+  }
+  const identity: AwarenessIdentity = {
+    userId,
+    displayName,
+    role: role as AwarenessIdentity["role"],
+    authorKind: authorKind as AwarenessIdentity["authorKind"],
+  };
+  const collabIdentity = candidate["collabIdentity"];
+  if (typeof collabIdentity === "string" && collabIdentity !== "") {
+    identity.collabIdentity = collabIdentity;
+  }
+  const activeStoryId = candidate["activeStoryId"];
+  if (typeof activeStoryId === "string" && activeStoryId !== "") {
+    identity.activeStoryId = activeStoryId;
+  }
+  return identity;
+}
+
+function validate(identity: AwarenessIdentity): AwarenessIdentity {
+  if (!identity.userId) throw new Error("awareness identity: userId required");
+  if (!identity.displayName)
+    throw new Error("awareness identity: displayName required");
+  if (!ROLE_VOCAB.has(identity.role)) {
+    throw new Error(`awareness identity: unknown role ${identity.role}`);
+  }
+  if (!KIND_VOCAB.has(identity.authorKind)) {
+    throw new Error(
+      `awareness identity: unknown authorKind ${identity.authorKind}`,
+    );
+  }
+  return identity;
+}

package/src/runtime/collab/event-types.ts

@@ -83,6 +83,33 @@ export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new S
   "change.reject",
   "change.accept-all",
   "change.reject-all",
+  "workflow.set-overlay",
+  "workflow.clear-overlay",
+  "workflow.set-metadata-definitions",
+  "workflow.clear-metadata-definitions",
+  "workflow.set-metadata-entries",
+  "workflow.clear-metadata-entries",
+  "host-annotation.set-overlay",
+  "host-annotation.clear-overlay",
+  "formatting.apply",
+  "style.set-paragraph",
+  "style.set-table",
+  "list.toggle",
+  "list.indent",
+  "list.outdent",
+  "list.restart-numbering",
+  "list.continue-numbering",
+  "table.apply-structure",
+  "image.insert",
+  "image.set-layout",
+  "image.set-frame",
+  "section.insert-break",
+  "section.delete-break",
+  "section.update-layout",
+  "section.set-page-numbering",
+  "section.set-header-footer-link",
+  "content.insert-page-break",
+  "content.insert-table",
 ]);
 
 /**