@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/ui-tailwind/chrome/local-surface-arbiter.ts

@@ -0,0 +1,534 @@
+/**
+ * Local-surface arbiter — single authority over the editor's floating
+ * surfaces.
+ *
+ * Problem (audit §2.7 + RC-3): the editor mounts many floating
+ * surfaces — scope cards, suggestion cards, blocked-command cards,
+ * workflow cards, comment previews, selection-format tools, right-click
+ * context menus.  Before this arbiter landed the only coordinator was
+ * the 150ms dwell timer inside `tw-selection-tool-host.tsx` (which only
+ * kept the selection toolbar from thrashing).  Overlapping requests
+ * from peer surfaces regressed into visual thrash — two floats visible
+ * at once, or a high-priority surface losing to a lower-priority peer
+ * that rendered first.
+ *
+ * Contract:
+ *   1. At most ONE non-pinned surface is active per frame.
+ *   2. Priority is fixed and declared in `LOCAL_SURFACE_PRIORITY`;
+ *      a higher-priority request displaces the current active peer and
+ *      fires the displaced handle's `onDismiss` callback.
+ *   3. Equal-priority requests respect insertion order — first request
+ *      wins; the later one is queued.  Dismissing the active surface
+ *      promotes the highest queued peer.
+ *   4. A PINNED surface is tracked separately from the single active
+ *      slot.  Pinned scope cards may coexist with any other active
+ *      surface (e.g. the rail detail) — they are orthogonal slots.
+ *      Only one pinned surface at a time; a second pinned request
+ *      displaces the prior pin.
+ *   5. Subscribers are notified via a single rAF-coalesced tick —
+ *      50 `request()` calls in one synchronous block fire listeners
+ *      exactly once.  This is perf invariant #4: no widening of the
+ *      wholesale-snapshot path.
+ *   6. The arbiter itself NEVER subscribes to PM transactions.  It
+ *      consumes user-event-driven `request()` calls only.
+ *
+ * Surface landscape (audit §2.7):
+ *
+ *   scope-card > suggestion-card > blocked-card > workflow-card >
+ *   comment-preview > selection-format > context-menu
+ *
+ * Usage: callers create a request and gate rendering on the returned
+ * handle's `isActive()` flag.  Dismiss the handle (explicitly or on
+ * unmount) to release the slot.
+ */
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useSyncExternalStore,
+} from "react";
+
+export type LocalSurfaceKind =
+  | "scope-card"
+  | "suggestion-card"
+  | "blocked-card"
+  | "workflow-card"
+  | "comment-preview"
+  | "selection-format"
+  | "context-menu";
+
+/**
+ * Priority ladder per audit §2.7.  Higher number wins.  Tweaking this
+ * table is a design contract change — update the audit and the docs
+ * before the code.
+ */
+export const LOCAL_SURFACE_PRIORITY: Readonly<Record<LocalSurfaceKind, number>> =
+  Object.freeze({
+    "scope-card": 7,
+    "suggestion-card": 6,
+    "blocked-card": 5,
+    "workflow-card": 4,
+    "comment-preview": 3,
+    "selection-format": 2,
+    "context-menu": 1,
+  });
+
+export interface LocalSurfaceRequest {
+  readonly kind: LocalSurfaceKind;
+  /**
+   * Optional caller-provided id.  Defaulted to a monotonic token when
+   * omitted.  Useful for tests + audit tooling that wants to correlate
+   * a rendered surface with its request.
+   */
+  readonly id?: string;
+  /**
+   * When true, the surface is tracked in the pinned slot instead of the
+   * single active slot — it coexists with any other active surface.
+   * Used for pinned scope cards.
+   */
+  readonly pinned?: boolean;
+  /**
+   * Called when the arbiter releases the slot via priority displacement,
+   * `dismissTopmost`, or `dismissAll`.  NOT called when the caller
+   * voluntarily invokes `handle.dismiss()` — that path is self-managed
+   * by the caller.
+   */
+  readonly onDismiss?: () => void;
+}
+
+export interface ArbiterState {
+  readonly activeKind: LocalSurfaceKind | null;
+  readonly activeId: string | null;
+  readonly pinnedKind: LocalSurfaceKind | null;
+  readonly pinnedId: string | null;
+}
+
+export interface LocalSurfaceHandle {
+  readonly kind: LocalSurfaceKind;
+  readonly id: string;
+  readonly pinned: boolean;
+  /** Whether this handle currently owns the active slot (or a pinned slot). */
+  isActive(): boolean;
+  /** Release this handle's slot without calling onDismiss. */
+  dismiss(): void;
+}
+
+export interface LocalSurfaceArbiter {
+  /** Submit a surface request.  Returns a handle for gating + release. */
+  request(req: LocalSurfaceRequest): LocalSurfaceHandle;
+  /** Subscribe to arbiter state changes.  Returns an unsubscribe fn. */
+  subscribe(listener: (state: ArbiterState) => void): () => void;
+  /** Synchronous state snapshot. */
+  getState(): ArbiterState;
+  /** Dismiss the non-pinned active slot; leaves pinned surface intact. */
+  dismissTopmost(): void;
+  /** Dismiss every tracked surface, pinned and active. */
+  dismissAll(): void;
+}
+
+interface InternalEntry {
+  /**
+   * Populated immediately after the entry is constructed — see the
+   * `request()` initialisation sequence.  Typed as `LocalSurfaceHandle
+   * | undefined` rather than a non-null cast so no read site silently
+   * dereferences a pre-assignment entry (M2 — type safety).
+   */
+  handle: LocalSurfaceHandle | undefined;
+  readonly kind: LocalSurfaceKind;
+  readonly id: string;
+  readonly pinned: boolean;
+  readonly onDismiss?: () => void;
+  readonly sequence: number;
+  released: boolean;
+}
+
+/**
+ * rAF-coalesced dispatcher.  All state mutations enqueue a single
+ * dispatch in the next animation frame; synchronous callers see the
+ * updated `getState()` immediately, but subscribers receive one tick
+ * per frame regardless of how many mutations happened.
+ *
+ * We check `typeof` before using `requestAnimationFrame` because the
+ * arbiter runs in test environments (node:test) that do not expose rAF.
+ * In that case we fall back to a microtask; tests can await it with
+ * `setTimeout(0)` and see exactly one notification per synchronous
+ * burst.  This mirrors the pattern in
+ * `tw-page-stack-overlay-layer.tsx:327-344`.
+ */
+function scheduleFrame(cb: () => void): void {
+  if (typeof globalThis.requestAnimationFrame === "function") {
+    globalThis.requestAnimationFrame(cb);
+    return;
+  }
+  // Fallback: microtask.  Tests and non-browser runtimes take this
+  // path; production never does because DOM always exposes rAF.
+  queueMicrotask(cb);
+}
+
+let sequenceCounter = 0;
+function nextSequence(): number {
+  sequenceCounter += 1;
+  return sequenceCounter;
+}
+
+export function createLocalSurfaceArbiter(): LocalSurfaceArbiter {
+  const entries: InternalEntry[] = [];
+  const listeners = new Set<(state: ArbiterState) => void>();
+  let pendingFrame = false;
+  // Last state emitted to subscribers — used to suppress redundant
+  // ticks when a mutation doesn't change the computed `ArbiterState`
+  // (N1 — a lower-priority request that simply queues behind an
+  // existing active would otherwise fire one subscriber tick per
+  // request even though no consumer's `isActive()` changed).
+  let lastEmittedSnapshot: string | null = null;
+
+  // Consumer `onDismiss` callbacks typically do `setState` on the
+  // dismissed surface's host (see `useContextMenuController.dismiss`).
+  // Priority displacement fires during another component's render
+  // (the requester that owns the slot now) because `useLocalSurfaceRequest`
+  // issues the request synchronously in render body to get first-paint
+  // correct behavior.  A synchronous `setState` across components during
+  // render triggers React's "Cannot update a component while rendering
+  // a different component" warning and can be dropped in concurrent
+  // retry passes.  Defer every consumer-triggered `onDismiss` by one
+  // microtask — the arbiter state itself already updated synchronously
+  // (entry.released = true), so the next subscriber tick + next
+  // `isActive()` read already see the correct verdict; only the
+  // cross-component state sync needs the microtask boundary.
+  function scheduleOnDismiss(cb: () => void): void {
+    queueMicrotask(cb);
+  }
+
+  function recomputeState(): ArbiterState {
+    let pinned: InternalEntry | null = null;
+    let active: InternalEntry | null = null;
+    for (const entry of entries) {
+      if (entry.released) continue;
+      if (entry.pinned) {
+        if (!pinned || entry.sequence > pinned.sequence) {
+          pinned = entry;
+        }
+      }
+    }
+    for (const entry of entries) {
+      if (entry.released || entry.pinned) continue;
+      if (!active) {
+        active = entry;
+        continue;
+      }
+      const activeP = LOCAL_SURFACE_PRIORITY[active.kind];
+      const candidateP = LOCAL_SURFACE_PRIORITY[entry.kind];
+      if (
+        candidateP > activeP ||
+        (candidateP === activeP && entry.sequence < active.sequence)
+      ) {
+        active = entry;
+      }
+    }
+    return {
+      activeKind: active ? active.kind : null,
+      activeId: active ? active.id : null,
+      pinnedKind: pinned ? pinned.kind : null,
+      pinnedId: pinned ? pinned.id : null,
+    };
+  }
+
+  function scheduleDispatch(): void {
+    if (pendingFrame) return;
+    pendingFrame = true;
+    scheduleFrame(() => {
+      pendingFrame = false;
+      const state = recomputeState();
+      // N1 — skip the subscriber tick when the snapshot is identical
+      // to the last one we emitted.  Subscribers only need wake-ups on
+      // observable state transitions.  Cheap stable serialization
+      // because the snapshot has exactly four primitive fields.
+      const serialized = `${state.activeKind ?? ""}:${state.activeId ?? ""}:${state.pinnedKind ?? ""}:${state.pinnedId ?? ""}`;
+      if (serialized === lastEmittedSnapshot) return;
+      lastEmittedSnapshot = serialized;
+      for (const listener of listeners) {
+        listener(state);
+      }
+    });
+  }
+
+  function currentHolders(): { active: InternalEntry | null; pinned: InternalEntry | null } {
+    const state = recomputeState();
+    const active =
+      entries.find((e) => !e.released && !e.pinned && e.id === state.activeId) ?? null;
+    const pinned =
+      entries.find((e) => !e.released && e.pinned && e.id === state.pinnedId) ?? null;
+    return { active, pinned };
+  }
+
+  function request(req: LocalSurfaceRequest): LocalSurfaceHandle {
+    const id = req.id ?? `local-surface-${nextSequence()}`;
+    const pinned = req.pinned ?? false;
+
+    // A new pinned request displaces any prior pinned entry — invariant
+    // "only one pinned surface at a time" per §2.7.  Consumer onDismiss
+    // is deferred via `scheduleOnDismiss` to avoid cross-component
+    // setState during the requester's render (see C1 fix above).
+    if (pinned) {
+      for (const existing of entries) {
+        if (existing.released || !existing.pinned) continue;
+        existing.released = true;
+        const dismissCb = existing.onDismiss;
+        if (dismissCb) scheduleOnDismiss(dismissCb);
+      }
+    }
+
+    // For the non-pinned slot, priority rules apply.  A higher-priority
+    // request displaces the current active; lower-priority requests
+    // simply queue and `isActive` returns false until they win.
+    if (!pinned) {
+      const { active } = currentHolders();
+      if (active) {
+        const activeP = LOCAL_SURFACE_PRIORITY[active.kind];
+        const candidateP = LOCAL_SURFACE_PRIORITY[req.kind];
+        if (candidateP > activeP) {
+          active.released = true;
+          const dismissCb = active.onDismiss;
+          if (dismissCb) scheduleOnDismiss(dismissCb);
+        }
+      }
+    }
+
+    const entry: InternalEntry = {
+      kind: req.kind,
+      id,
+      pinned,
+      sequence: nextSequence(),
+      released: false,
+      ...(req.onDismiss ? { onDismiss: req.onDismiss } : {}),
+      // Assigned immediately below.  Typed as optional so no read path
+      // silently dereferences a pre-assignment entry.
+      handle: undefined,
+    };
+
+    const handle: LocalSurfaceHandle = {
+      kind: req.kind,
+      id,
+      pinned,
+      isActive: () => {
+        if (entry.released) return false;
+        const state = recomputeState();
+        return entry.pinned ? state.pinnedId === id : state.activeId === id;
+      },
+      dismiss: () => {
+        if (entry.released) return;
+        entry.released = true;
+        scheduleDispatch();
+      },
+    };
+    entry.handle = handle;
+
+    entries.push(entry);
+    scheduleDispatch();
+    return handle;
+  }
+
+  function subscribe(listener: (state: ArbiterState) => void): () => void {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  function dismissTopmost(): void {
+    const { active } = currentHolders();
+    if (active) {
+      active.released = true;
+      const dismissCb = active.onDismiss;
+      if (dismissCb) scheduleOnDismiss(dismissCb);
+      scheduleDispatch();
+    }
+  }
+
+  function dismissAll(): void {
+    let changed = false;
+    for (const entry of entries) {
+      if (entry.released) continue;
+      entry.released = true;
+      const dismissCb = entry.onDismiss;
+      if (dismissCb) scheduleOnDismiss(dismissCb);
+      changed = true;
+    }
+    if (changed) scheduleDispatch();
+  }
+
+  // Cache the most recent state snapshot so successive `getState()` calls
+  // return reference-equal results — required by `useSyncExternalStore`,
+  // which calls `getSnapshot` on every render and bails out on
+  // `Object.is` equality. Without this cache, `useLocalSurfaceArbiterState`
+  // (Chrome Closure Pass · Task 2) re-renders on every commit and the
+  // host hits "Maximum update depth exceeded".
+  let cachedSnapshot: ArbiterState | null = null;
+  let cachedSnapshotKey: string | null = null;
+
+  function getStateCached(): ArbiterState {
+    const fresh = recomputeState();
+    const key = `${fresh.activeKind ?? ""}:${fresh.activeId ?? ""}:${fresh.pinnedKind ?? ""}:${fresh.pinnedId ?? ""}`;
+    if (cachedSnapshot && cachedSnapshotKey === key) {
+      return cachedSnapshot;
+    }
+    cachedSnapshot = fresh;
+    cachedSnapshotKey = key;
+    return fresh;
+  }
+
+  return {
+    request,
+    subscribe,
+    getState: getStateCached,
+    dismissTopmost,
+    dismissAll,
+  };
+}
+
+/**
+ * App-wide default arbiter — fallback for consumers that render outside
+ * the `LocalSurfaceArbiterContext.Provider` wrapped by `TwReviewWorkspace`.
+ *
+ * **Production contract:** the workspace always supplies a per-instance
+ * arbiter via context, so every in-tree chrome consumer gets workspace
+ * isolation for free.  The default singleton exists for two narrow
+ * cases:
+ *   1. unit tests that render a consumer component directly without
+ *      wrapping it in the provider;
+ *   2. host integrations that mount chrome components outside the
+ *      `TwReviewWorkspace` subtree (rare, but supported).
+ *
+ * **Known limitation:** multiple `TwReviewWorkspace` instances on the
+ * same page each create their own arbiter (isolated); any two
+ * components that fall through to this default instead of a provider
+ * will share its slot table — symptoms are cross-editor priority
+ * displacement.  Wrap every mount point in a provider to avoid.
+ */
+export const defaultLocalSurfaceArbiter: LocalSurfaceArbiter =
+  createLocalSurfaceArbiter();
+
+/**
+ * React context for the per-editor arbiter.  `TwReviewWorkspace`
+ * creates a stable instance (via `useRef`) and provides it here so
+ * every local surface inside the workspace coordinates through the
+ * same object.  Consumers read via `useLocalSurfaceArbiter()` which
+ * falls back to the default singleton when no provider exists.
+ */
+export const LocalSurfaceArbiterContext =
+  createContext<LocalSurfaceArbiter | null>(null);
+
+/**
+ * Resolve the arbiter from context, falling back to the default
+ * singleton.  This is the canonical entry point for floating-surface
+ * consumers.
+ */
+export function useLocalSurfaceArbiter(): LocalSurfaceArbiter {
+  return useContext(LocalSurfaceArbiterContext) ?? defaultLocalSurfaceArbiter;
+}
+
+/**
+ * Subscribe to arbiter state for read-only consumers (Chrome Closure
+ * Pass · Task 2). Returns the current `ArbiterState` and re-renders
+ * the consumer when it changes. Used by `TwContextMenuPortal` /
+ * `TwContextMenu` to project active + pinned `LocalSurfaceKind` into
+ * the menu's `ContextMenuContext` for dedupe-without-suppression
+ * (designsystem.md §6.24 — context menu must not vanish when local
+ * chrome is visible).
+ */
+export function useLocalSurfaceArbiterState(): ArbiterState {
+  const arbiter = useLocalSurfaceArbiter();
+  return useSyncExternalStore(
+    arbiter.subscribe,
+    arbiter.getState,
+    arbiter.getState,
+  );
+}
+
+/**
+ * Declarative hook: given a request (or `null` when no surface is
+ * needed) returns whether the consumer currently owns its slot.  The
+ * hook requests synchronously on first render so initial paint already
+ * reflects the arbiter's verdict — callers that read the rendered DOM
+ * in the same frame (e.g. imperative layoutEffect positioners) see the
+ * final active state, not the lag-one-render state that a plain
+ * `useState` + `useEffect` pair would produce.
+ *
+ * Passing `null` releases any prior handle.  The hook intentionally
+ * reads the arbiter from context, not from a parameter, so tests that
+ * want isolation wrap consumers in a `LocalSurfaceArbiterContext.Provider`
+ * with a fresh arbiter.
+ */
+export function useLocalSurfaceRequest(
+  request: LocalSurfaceRequest | null,
+): boolean {
+  const arbiter = useLocalSurfaceArbiter();
+
+  // Request shape we last issued to the arbiter.  When the caller passes
+  // a new (kind, id, pinned) triple the hook dismisses the prior handle
+  // and issues a fresh one — synchronously, inside render — so the first
+  // paint sees the real verdict.  Side effects in render are usually
+  // forbidden, but this is idempotent: repeated calls with the same key
+  // skip the request, and strict-mode double-invocation dismisses the
+  // spare on the cleanup pass.
+  //
+  // I3 fix — the dedup key intentionally excludes `onDismiss` identity
+  // so a consumer that rebuilds the callback per render doesn't thrash
+  // the arbiter.  To prevent stale-closure leaks, the hook keeps the
+  // consumer's latest `onDismiss` in a ref and forwards it via a stable
+  // wrapper that the arbiter holds — the arbiter's view of "onDismiss"
+  // always reads through the ref, so priority-displacement callbacks
+  // see the freshest closure.
+  const handleRef = useRef<LocalSurfaceHandle | null>(null);
+  const onDismissRef = useRef<(() => void) | undefined>(request?.onDismiss);
+  onDismissRef.current = request?.onDismiss;
+  const currentKey =
+    request === null
+      ? null
+      : `${request.kind}:${request.id ?? ""}:${request.pinned ? "p" : "a"}`;
+  const lastKeyRef = useRef<string | null>(null);
+
+  if (currentKey !== lastKeyRef.current) {
+    handleRef.current?.dismiss();
+    if (request !== null) {
+      const { onDismiss: _consumerOnDismiss, ...rest } = request;
+      handleRef.current = arbiter.request({
+        ...rest,
+        onDismiss: () => onDismissRef.current?.(),
+      });
+    } else {
+      handleRef.current = null;
+    }
+    lastKeyRef.current = currentKey;
+  }
+
+  // Unmount cleanup — React runs this on component unmount, so the
+  // handle releases its arbiter slot.  We re-issue in the render body
+  // above when `currentKey` changes, so this effect has an empty dep
+  // list intentionally.
+  useEffect(() => {
+    return () => {
+      handleRef.current?.dismiss();
+      handleRef.current = null;
+      lastKeyRef.current = null;
+    };
+  }, []);
+
+  // Subscribe via `useSyncExternalStore` so React suspends on arbiter
+  // state and paints the correct value on the first frame.
+  //
+  // The server snapshot reads the same `handleRef.current?.isActive()`
+  // as the client — the request is issued synchronously in the render
+  // body above, so the handle already exists when SSR / static rendering
+  // (e.g. `renderToStaticMarkup`) asks for the initial state.  Returning
+  // `false` unconditionally here would cause static renders to skip
+  // every arbiter-gated consumer (regressed rail-scope-sync in Phase G
+  // full-suite run).
+  return useSyncExternalStore(
+    (listener) => arbiter.subscribe(listener),
+    () => handleRef.current?.isActive() ?? false,
+    () => handleRef.current?.isActive() ?? false,
+  );
+}