@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/shell/ref-utilities.ts

@@ -0,0 +1,48 @@
+/**
+ * Shell re-export module — the seam that hosts substrate-reach-through
+ * helpers `WordReviewEditor` still consumes after the Track A
+ * ref-bridge carve-out. Layer 11 presentation code (`src/ui/**` +
+ * `src/ui-tailwind/**`) imports from this module instead of reaching
+ * directly into `src/core/**` or `src/runtime/**`, which retires
+ * those imports from the L11 boundary register.
+ *
+ * The shell layer is an allowed substrate consumer (handoff §3,
+ * designsystem.md §8.8 "Mounted shell" stratum); presentation
+ * reads through it.
+ *
+ * Each binding below is a straight re-export — no runtime wrapping,
+ * no behavioral change, no perf cost. Hot-path consumers
+ * (`dispatchTextCommand` called on every keystroke) retain identity
+ * stability; the ESM re-export binding is folded at module load.
+ *
+ * Track D + G · refactor/11 — closes the WRE-side substrate leakage
+ * that Track A (ref-bridge carve-out) did not touch. After this
+ * module ships, `WordReviewEditor.tsx` still holds ~2 direct
+ * substrate imports for trivial type-only use that routes cleanly
+ * through `src/api/public-types.ts`; the rest travel through here.
+ */
+
+export { storyTargetsEqual } from "../core/selection/mapping.ts";
+export { getFormattingStateFromRenderSnapshot } from "../core/commands/formatting-commands.ts";
+export {
+  dispatchTextCommand,
+  type DispatchTextCommand,
+} from "../runtime/edit-dispatch/index.ts";
+export { getTableStructureContext } from "../core/commands/table-structure-commands.ts";
+export { getStoryBlocks } from "../runtime/story-targeting.ts";
+export { deriveCapabilities } from "../runtime/session-capabilities";
+export {
+  resolveCurrentContextAnalyticsQuery,
+  runtimeContextAnalyticsSnapshotsEqual,
+} from "../runtime/context-analytics.ts";
+export {
+  createEditorViewStateSnapshot,
+  createViewState,
+} from "../runtime/view-state.ts";
+export { wrapRefForTelemetry } from "../runtime/debug/wrap-ref-for-telemetry.ts";
+export {
+  conflictKey,
+  convertScopesToInternal,
+  convertScopesToExternal,
+  type PendingConflict,
+} from "../runtime/workflow/metadata-persistence.ts";

package/src/shell/search.ts

@@ -0,0 +1,51 @@
+/**
+ * Shell helper — document search projections.
+ *
+ * Two thin projections used by the React editor ref (`findText`,
+ * `searchDocument`) plus the in-component search effects. Both take
+ * the mounted runtime and return public-API shapes.
+ *
+ * Lives in `src/shell/` rather than `src/ui/` so the underlying
+ * `src/runtime/document-search.ts` value import is a consumer
+ * relationship rather than an L11 register offender.
+ */
+
+import type { EditorAnchorProjection, SearchOptions, SearchResultSnapshot } from "../api/public-types.ts";
+import { findTextMatches, searchDocument } from "../runtime/document-search.ts";
+import type { WordReviewEditorRuntime } from "./session-bootstrap.ts";
+import type { TwProseMirrorSurfaceRef } from "../ui-tailwind/editor-surface/tw-prosemirror-surface";
+
+export function findTextMatchesForRuntime(
+  runtime: WordReviewEditorRuntime,
+  query: string,
+  options: SearchOptions | undefined,
+): EditorAnchorProjection[] {
+  const snapshot = runtime.getRenderSnapshot();
+  return findTextMatches(
+    runtime.getSessionState().canonicalDocument,
+    snapshot.selection,
+    query,
+    options ?? {},
+  );
+}
+
+export function searchRuntimeDocument(
+  runtime: WordReviewEditorRuntime,
+  mountedSurface: TwProseMirrorSurfaceRef | null,
+  query: string,
+  options: SearchOptions = {},
+): SearchResultSnapshot[] {
+  if (mountedSurface) {
+    return mountedSurface.search(query, options);
+  }
+
+  const snapshot = runtime.getRenderSnapshot();
+  return searchDocument(
+    runtime.getSessionState().canonicalDocument,
+    snapshot.selection,
+    snapshot.activeStory,
+    runtime.getDocumentNavigationSnapshot(),
+    query,
+    options,
+  );
+}

package/src/{ui/editor-runtime-boundary.ts → shell/session-bootstrap.ts}

@@ -29,7 +29,11 @@ import {
   editorSessionStateFromPersistedSnapshot,
   persistedSnapshotFromEditorSessionState,
 } from "../api/session-state.ts";
-import { createCanonicalDocumentId } from "../core/state/editor-state.ts";
+import {
+  createCanonicalDocumentId,
+  createDefaultCanonicalDocument,
+  createSelectionSnapshot,
+} from "../core/state/editor-state.ts";
 import {
   createDocumentRuntime,
   type DocumentRuntimeEvent,
@@ -41,15 +45,31 @@ import {
   type RuntimeCommandAppliedBridge,
 } from "../runtime/collab/runtime-collab-sync.ts";
 import { createInertLayoutFacet } from "../runtime/layout/index.ts";
+import { createInertGeometryFacet } from "../runtime/geometry/index.ts";
+import { TelemetryBus } from "../runtime/debug/telemetry-bus.ts";
 import {
-  loadDocxEditorSession,
-  loadDocxEditorSessionAsync,
-} from "../io/docx-session.ts";
+  createRuntimeDebugFacet,
+  type RuntimeDebugFacet,
+} from "../runtime/debug/runtime-debug-facet.ts";
+// Slice 5c flipped the async DOM warm path to `DocxSession.open()`.
+// The two remaining sync call sites (SSR/Node `createRuntime`
+// fallback + `resolvePackageBackedExportSession`) were isolated
+// behind `src/session/_sync-legacy.ts` in Slice 5e-3 so the UI layer
+// no longer imports directly from the legacy file. The shim + its
+// debt exception in `ci-check-session-layer-purity.mjs` go away at
+// Slice 5e-9 together with the legacy file.
+import type { CacheEnvelope } from "../runtime/prerender/cache-envelope.ts";
 import { tryReadLaycacheEnvelope } from "../runtime/prerender/customxml-probe.ts";
-import {
-  createLoadScheduler,
-  type LoadScheduler,
-} from "../io/load-scheduler.ts";
+import { createEditorSurfaceSnapshot } from "../runtime/surface-projection.ts";
+import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import type { ProgressiveSurfaceProjector } from "../session/types.ts";
+import { DocxSession } from "../session/index.ts";
+// Slice 5e-11 item-4: `_internal-legacy.ts` retired. All fields that
+// were reached through `getLegacyOpenView` are now public on
+// `OpenResult` directly; a tiny local adapter maps `OpenResult` into
+// the `LoadedDocxEditorSession` shape the downstream shell code
+// still expects.
+import { openDocxSync } from "../session/_sync-legacy.ts";
 import {
   decodePersistedSourcePackageBytes,
   hasValidPersistedSourcePackageDigest,
@@ -65,7 +85,7 @@ import {
 import {
   downloadExportResult,
   withExportDelivery,
-} from "./browser-export";
+} from "../ui/browser-export";
 
 export interface ResolvedSource {
   source: "docx" | "session" | "snapshot";
@@ -80,7 +100,7 @@ export interface ResolvedSource {
    * load. Undefined in SSR / Node test fallback — `createRuntime` then
    * does the classic synchronous load.
    */
-  preloadedDocxSession?: ReturnType<typeof loadDocxEditorSession>;
+  preloadedDocxSession?: ReturnType<typeof openDocxSync>;
   /**
    * L7 Phase 2.7 — when the editor-runtime-boundary probe finds a
    * laycache envelope in `/customXml/item1.xml`, its `graph` is stashed
@@ -128,7 +148,7 @@ type InternalWordReviewEditorRuntime = WordReviewEditorRuntime & {
   ) => boolean;
 };
 
-type PackageBackedDocxSession = ReturnType<typeof loadDocxEditorSession>;
+type PackageBackedDocxSession = ReturnType<typeof openDocxSync>;
 
 interface SnapshotExportBarrier {
   reason:
@@ -324,9 +344,11 @@ export function useEditorRuntimeBoundary(
     useRef<EditorSessionState["canonicalDocument"] | null>(null);
   const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastSavedRevisionTokenRef = useRef<string | null>(null);
-  // Fastload P6: scheduler used by the DOM-side async docx loader. Held
-  // here so it can be disposed on unmount / source change.
-  const loadSchedulerRef = useRef<LoadScheduler | null>(null);
+  // Fastload P6: load-scheduler disposer handed back from
+  // `DocxSession.open()` via `LegacyOpenView.dispose`. Held here so
+  // unmount / source-change can cancel pending idle chart-preview
+  // callbacks (CLAUDE.md Performance Invariant 9).
+  const loadDisposeRef = useRef<(() => void) | null>(null);
   const hostAdapterRef = useRef(hostAdapter);
   const datastoreRef = useRef(datastore);
   const onEventRef = useRef(onEvent);
@@ -407,8 +429,8 @@ export function useEditorRuntimeBoundary(
       runtimeRef.current = null;
       // Fastload P6: dispose any scheduler held from a previous mount /
       // source cycle before allocating a fresh one for this load.
-      loadSchedulerRef.current?.dispose();
-      loadSchedulerRef.current = null;
+      loadDisposeRef.current?.();
+      loadDisposeRef.current = null;
       setRuntime(null);
 
       try {
@@ -429,37 +451,28 @@ export function useEditorRuntimeBoundary(
           return;
         }
 
-        // Fastload P6: in a DOM environment, preload the docx via the
-        // async loader so normalize-body yields mid-walk and the browser
-        // can paint the skeleton while the rest of the parse finishes.
-        // SSR / Node tests fall through to the synchronous load inside
-        // `createRuntime`.
+        // Fastload P6: in a DOM environment, preload the docx via
+        // `DocxSession.open()` so normalize-body yields mid-walk and the
+        // browser can paint the skeleton while the rest of the parse
+        // finishes. SSR / Node tests fall through to the synchronous
+        // load inside `createRuntime`.
         //
-        // L7 Phase 2.7 — Plan B read-path wiring. Before invoking the
-        // async loader, probe the docx for a laycache envelope stashed
-        // in `/customXml/item1.xml` (shipped by Plan B Slice 2). When the
-        // probe returns a validated envelope, pass it to the loader so
-        // the five expensive parse stages short-circuit against the
-        // cached `canonicalDocument`. Measured win on 138-pp extra-large
-        // CCEP: ~947 ms cold → ~590 ms warm (Δ 376 ms), same delta the
-        // Node-side `prerender-cache.bench.ts` records. Probe is ~20–50 ms;
-        // `tryReadLaycacheEnvelope` returns null on any rejection path
-        // (missing part, stale structural hash, schema mismatch) and the
-        // loader falls through to the full parse.
+        // L7 Phase 2.7 — Plan B read-path wiring. `tryLaycacheEnvelope:
+        // true` tells the session to probe `/customXml/item1.xml` for a
+        // cached envelope and short-circuit the five expensive parse
+        // stages on a hit (CLAUDE.md Performance Invariant 10 — probe
+        // and loader are now colocated inside the session; no blocking
+        // work between them). Measured win on 138-pp extra-large CCEP:
+        // ~947 ms cold → ~590 ms warm (Δ 376 ms).
+        //
+        // `onProgressiveSnapshot` is passed unconditionally — the
+        // loader gates it on `laycacheEnvelope === undefined`, so the
+        // warm-path short-circuit skips the synthesis automatically.
         if (
           source.initialDocx !== undefined &&
           source.preloadedDocxSession === undefined &&
           typeof document !== "undefined"
         ) {
-          const scheduler = createLoadScheduler();
-          loadSchedulerRef.current = scheduler;
-          const probeResult = await tryReadLaycacheEnvelope(source.initialDocx);
-          if (cancelled) {
-            scheduler.dispose();
-            loadSchedulerRef.current = null;
-            return;
-          }
-          recordPerfSample("loadSession.laycacheProbe");
           const handleChartPreviewsReady = (
             resolvedDocument: EditorSessionState["canonicalDocument"],
           ): void => {
@@ -481,34 +494,89 @@ export function useEditorRuntimeBoundary(
               runtimeRef.current as InternalWordReviewEditorRuntime | null
             )?.hydrateChartPreviews?.(resolvedDocument);
           };
-          const preloaded = await loadDocxEditorSessionAsync({
+          // Slice 5e-7.b — runtime-side port that lets the session
+          // layer synthesize the progressive surface without importing
+          // `src/runtime/surface-projection.ts` directly. The adapter
+          // binds in a default collapsed selection + `MAIN_STORY_TARGET`
+          // + a provisional canonical envelope so the session only
+          // passes the body-stage root content + viewport counts.
+          const surfaceProjector: ProgressiveSurfaceProjector = ({
+            rootContent,
+            documentId: providedDocumentId,
+            blocksRealized,
+            blocksTotal,
+          }) => {
+            const provisionalDoc = {
+              ...createDefaultCanonicalDocument(
+                providedDocumentId,
+                new Date().toISOString(),
+              ),
+              content: rootContent,
+            };
+            return createEditorSurfaceSnapshot(
+              provisionalDoc,
+              createSelectionSnapshot(0, 0),
+              MAIN_STORY_TARGET,
+              blocksRealized < blocksTotal
+                ? { viewportBlockRange: { start: 0, end: blocksRealized } }
+                : undefined,
+            );
+          };
+          const openResult = await new DocxSession().open(source.initialDocx, {
             documentId,
             sourceLabel: source.sourceLabel,
-            bytes: source.initialDocx,
             editorBuild: "dev",
-            scheduler,
+            tryLaycacheEnvelope: true,
+            // Slice 5e-11 item-1: probe injection. Session no longer
+            // imports from `src/runtime/prerender/**`; the shell
+            // supplies the probe. See `cross-layer-coord-01 §1`.
+            laycacheProbe: tryReadLaycacheEnvelope,
             onChartPreviewsReady: handleChartPreviewsReady,
-            ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {
-              // C2c: on the cold path (no cached envelope), emit the first
-              // viewport surface as soon as body-normalize completes so the
-              // UI can show the first page before the full session is ready.
-              // Wrapped in startTransition so React treats this as a
-              // low-priority update — the full setRuntime commit (urgent)
-              // will preempt it if it arrives before React flushes the
-              // transition.
-              onProgressiveSnapshot: (partial) => {
-                React.startTransition(() => {
-                  setProgressiveSurface(partial.surface);
-                });
-              },
-            }),
+            surfaceProjector,
+            // C2c: on the cold path the loader fires this once after
+            // body-normalize with a viewport-windowed surface; on the
+            // warm path (envelope resolved) it is silently skipped.
+            // Performance Invariant 8: MUST be wrapped in
+            // `startTransition` so React treats it as low-priority;
+            // the full `setRuntime` commit preempts it.
+            onProgressiveSnapshot: (partial) => {
+              React.startTransition(() => {
+                setProgressiveSurface(partial.surface ?? null);
+              });
+            },
           });
+          // Slice 5e-11 item-4: adapter maps `OpenResult` → the
+          // `LoadedDocxEditorSession` shape the downstream shell
+          // code expects. Two field-name mismatches exist:
+          // `sessionState` / `initialSessionState`, and
+          // `embeddedDocuments` / `embeddedDocumentManifests`.
+          const preloadView: ReturnType<typeof openDocxSync> = {
+            initialSessionState: openResult.sessionState,
+            initialSnapshot: openResult.initialSnapshot,
+            readOnly: openResult.readOnly,
+            ...(openResult.fatalError !== undefined
+              ? { fatalError: openResult.fatalError }
+              : {}),
+            protectionSnapshot: openResult.protectionSnapshot,
+            exportDocx: openResult.exportDocx,
+            embeddedDocumentManifests: openResult.embeddedDocuments,
+            ...(openResult.initialEditorStatePayload !== undefined
+              ? {
+                  initialEditorStatePayload:
+                    openResult.initialEditorStatePayload as NonNullable<
+                      ReturnType<typeof openDocxSync>["initialEditorStatePayload"]
+                    >,
+                }
+              : {}),
+          };
+          loadDisposeRef.current = openResult.dispose ?? null;
           if (cancelled) {
-            scheduler.dispose();
-            loadSchedulerRef.current = null;
+            openResult.dispose?.();
+            loadDisposeRef.current = null;
             return;
           }
-          source.preloadedDocxSession = preloaded;
+          recordPerfSample("loadSession.laycacheProbe");
+          source.preloadedDocxSession = preloadView;
           if (pendingChartPreviewDocRef.current) {
             source.preloadedDocxSession.initialSessionState = {
               ...source.preloadedDocxSession.initialSessionState,
@@ -519,8 +587,10 @@ export function useEditorRuntimeBoundary(
               canonicalDocument: pendingChartPreviewDocRef.current,
             };
           }
-          if (probeResult) {
-            source.preloadedLaycacheGraph = probeResult.envelope.graph;
+          if (openResult.laycacheEnvelope) {
+            source.preloadedLaycacheGraph = (
+              openResult.laycacheEnvelope as CacheEnvelope
+            ).graph;
           }
         }
 
@@ -643,8 +713,8 @@ export function useEditorRuntimeBoundary(
       // Fastload P6: release any pending idle callbacks the load scheduler
       // registered so React unmount doesn't leak setTimeout/IdleCallback
       // handles.
-      loadSchedulerRef.current?.dispose();
-      loadSchedulerRef.current = null;
+      loadDisposeRef.current?.();
+      loadDisposeRef.current = null;
     };
   }, []);
 
@@ -740,7 +810,7 @@ function createRuntime(
   const docxSession =
     args.source.preloadedDocxSession ??
     (args.source.initialDocx
-      ? loadDocxEditorSession({
+      ? openDocxSync({
           documentId: args.documentId,
           sourceLabel: args.source.sourceLabel,
           bytes: args.source.initialDocx,
@@ -985,6 +1055,7 @@ function createLoadingRuntimeBridge(input: {
   progressiveSurfaceRef?: React.RefObject<EditorSurfaceSnapshot | null>;
 }): WordReviewEditorRuntime {
   const inertLayoutFacet = createInertLayoutFacet();
+  const inertGeometryFacet = createInertGeometryFacet();
   const emptyFieldSnapshot: FieldSnapshot = {
     totalCount: 0,
     supportedCount: 0,
@@ -1027,6 +1098,7 @@ function createLoadingRuntimeBridge(input: {
     getFontEntry: (name: string) =>
       input.sessionState.canonicalDocument.fontTable?.fonts[name],
     replaceText: () => undefined,
+    applyScopeReplacement: () => undefined,
     insertFragment: () => undefined,
     copy: () => undefined,
     cut: () => undefined,
@@ -1066,6 +1138,9 @@ function createLoadingRuntimeBridge(input: {
       throw createLoadingBoundaryError(input.snapshot.documentId, "scope");
     },
     getScope: () => null,
+    compileScopeBundleById: () => null,
+    getMarkerBackedScopeIds: () => new Set<string>(),
+    debug: createLoadingDebugFacet(),
     removeScope: () => undefined,
     acceptChange: () => undefined,
     rejectChange: () => undefined,
@@ -1086,6 +1161,13 @@ function createLoadingRuntimeBridge(input: {
     getPageLayoutSnapshot: () => null,
     getDocumentNavigationSnapshot: () => input.navigation,
     layout: inertLayoutFacet,
+    workflow: {
+      getRailSegments: () => [],
+      getAllRailSegments: () => [],
+      getAllScopeCardModels: () => [],
+    },
+    geometry: inertGeometryFacet,
+    getLayoutFacet: () => inertLayoutFacet,
     getCurrentLocation: () => null,
     getLocationForSelection: () => null,
     getLocationForAnchor: () => null,
@@ -1156,6 +1238,18 @@ function createLoadingRuntimeBridge(input: {
       definitions: [],
       entries: [],
     }),
+    // W10 — class-A overlay-visibility policy. Loading bridge: no
+    // authored policy until the real runtime mounts.
+    getVisibilityPolicy: () => null,
+    getVisibilityPolicies: () => [],
+    setVisibilityPolicy: () => false,
+    clearVisibilityPolicy: () => false,
+    subscribeVisibilityPolicy: () => () => undefined,
+    getMarkupModePolicy: () => null,
+    setMarkupModePolicy: () => false,
+    subscribeMarkupModePolicy: () => () => undefined,
+    setEffectiveMarkupModeProvider: () => undefined,
+    invalidateForMarkupModeChange: () => undefined,
     queryScopes: () => [],
     findScopesAt: () => [],
     findScopesIntersecting: () => [],
@@ -1200,6 +1294,88 @@ function createLoadingRuntimeBridge(input: {
   };
 }
 
+/**
+ * Loading-bridge debug facet. Exposes an all-off `TelemetryBus` and a
+ * projector that only renders the current loading state. Consumers that
+ * connect the debug facet before the runtime is live (e.g. the Phase 2
+ * service during cold-open) see an honest empty bundle, not an error.
+ */
+function createLoadingDebugFacet(): RuntimeDebugFacet {
+  const bus = new TelemetryBus();
+  return {
+    bus,
+    getSnapshot() {
+      return {
+        schemaVersion: 1,
+        generatedAtUtc: new Date().toISOString(),
+        session: {
+          documentId: "",
+          sessionId: "",
+          dirty: false,
+          exportBlocked: true,
+          activeStory: { kind: "main" },
+          workspaceMode: "canvas",
+          viewMode: "loading",
+          documentMode: "loading",
+          measurementFidelity: null,
+          currentPage: null,
+        },
+        health: {
+          compatibility: {
+            exportAllowed: false,
+            exportPlan: "full",
+            featureBlocked: false,
+            warnings: [],
+            features: [],
+            summary: { blockedCount: 0, preserveOnlyCount: 0, warningCount: 0 },
+            generatedAt: new Date().toISOString(),
+            blockedFeatureKeys: [],
+            preserveOnlyFeatureKeys: [],
+          } as never,
+          warnings: [],
+          blockedReasons: [],
+          fatalError: null,
+          readOnly: false,
+        },
+        context: null,
+        selection: { anchor: null, location: null },
+        workflow: {
+          overlay: null,
+          activeWorkItemId: null,
+          metadataPersistenceMode: null,
+          candidateCount: 0,
+          scopeCount: 0,
+          markerBackedCount: 0,
+          overlayOnlyCount: 0,
+          detachedCount: 0,
+        },
+        scopes: [],
+        review: {
+          unresolvedCommentCount: 0,
+          pendingRevisionCount: 0,
+          detachedCommentCount: 0,
+          detachedRevisionCount: 0,
+        },
+        layout: { pageCount: null, sectionCount: null, storyCount: 0 },
+        channels: bus.getChannels(),
+      };
+    },
+    tail(n = 64) {
+      return bus.tailAll(n);
+    },
+    tailChannel(channel, n = 64) {
+      return bus.tail(channel, n);
+    },
+    setChannels(flags) {
+      bus.setChannels(flags);
+      return bus.getChannels();
+    },
+    getChannels() {
+      return bus.getChannels();
+    },
+  };
+}
+
 function createLoadingBoundaryError(
   documentId: string,
   target: "comment" | "session" | "snapshot" | "export" | "scope",
@@ -1717,7 +1893,7 @@ function resolvePackageBackedExportSession(args: CreateRuntimeArgs): {
       };
     }
 
-    const session = loadDocxEditorSession({
+    const session = openDocxSync({
       documentId: args.documentId,
       sourceLabel: sourcePackage.sourceLabel ?? args.source.sourceLabel,
       bytes,

package/src/shell/ui-subscriber-channels.ts

@@ -0,0 +1,81 @@
+/**
+ * Shell-side subscriber-emitter channels for the mounted UI API
+ * controller hooks (`subscribeChrome`, `subscribeViewport`,
+ * `subscribeOverlays`).
+ *
+ * Why this exists
+ *
+ * `ui.chrome.subscribe` / `ui.viewport.subscribe` / `ui.overlays.subscribe`
+ * delegate to their respective controller hooks. Until 2026-04-23 those
+ * hooks were `undefined` on the mounted path, causing each subscribe to
+ * throw with a configuration-clear error. That's fine for consumer
+ * discovery but it means Playwright drivers, the debug service, and any
+ * non-React consumer that wants to observe posture / viewport /
+ * overlay-invalidation over time couldn't actually do it on the mounted
+ * editor.
+ *
+ * The three channels here are **stable per-mount** emitter triples:
+ *
+ *   - `subscribe(listener) → unsubscribe`
+ *   - `emit(value)` — called by the shell at event time
+ *   - `size` — count of current listeners (test + telemetry hook)
+ *
+ * The shell creates one of each via `useRef` at mount, wires `subscribeX`
+ * on the UI controller factory to the emitter's `subscribe`, and calls
+ * `.emit(value)` from the appropriate React effect / DOM listener when
+ * the underlying state changes. The factory's controller identity stays
+ * stable because the emitter object identity is stable (a ref box).
+ *
+ * U7 compliance: viewport and overlay emitters are **rAF-coalesced at
+ * the shell-call-site level**, not inside the emitter. The emitter is a
+ * dumb fan-out; coalescing is the responsibility of whatever is calling
+ * `.emit()`. Posture is microtask-coalesced because the posture sources
+ * are synchronous React state / props and batching is React's default.
+ *
+ * Isolation: each emitter holds its own listener set. Teardown at
+ * unmount clears the set so a stale listener can't leak across remounts.
+ */
+
+export interface UiSubscriberChannel<T> {
+  /** Register a listener; returns an unsubscribe fn. Idempotent add. */
+  readonly subscribe: (listener: (value: T) => void) => () => void;
+  /** Fire every registered listener with `value`. Errors isolated. */
+  readonly emit: (value: T) => void;
+  /** Clear the listener set (call on unmount). Subsequent emits no-op. */
+  readonly dispose: () => void;
+  /** Current listener count (test / telemetry). */
+  readonly size: () => number;
+}
+
+/**
+ * Build a stable emitter channel. Listeners are held in a Set so
+ * registration is idempotent (adding the same fn twice leaves one
+ * entry). Removal is O(1). Emission isolates listener throws so one
+ * broken consumer can't break the fan-out.
+ */
+export function createUiSubscriberChannel<T>(): UiSubscriberChannel<T> {
+  const listeners = new Set<(value: T) => void>();
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    emit(value) {
+      for (const listener of listeners) {
+        try {
+          listener(value);
+        } catch {
+          // One broken listener must not break the fan-out.
+        }
+      }
+    },
+    dispose() {
+      listeners.clear();
+    },
+    size() {
+      return listeners.size;
+    },
+  };
+}