@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/api/v3/ui/_types.ts

@@ -0,0 +1,520 @@
+/**
+ * @endStateApi v3 — UI API types.
+ *
+ * The UI API (layer 10 per `docs/architecture/10-ui-api.md`) is the
+ * first-class public face of the runtime for mounted-surface consumption —
+ * session binding, selection/viewport hooks, geometry-backed overlay
+ * primitives, chrome posture composition, debug-service attachment.
+ *
+ * Slice 1 reserves the type surface + entry shells. The shells throw
+ * `NOT_IMPLEMENTED` until Slices 2–5 wire them through `RuntimeApiHandle`
+ * (runtime reads) + `GeometryFacet` (overlay anchors) + `InteractionGuardSnapshot`
+ * (chrome posture) + `runtime.debug` (debug attachment).
+ *
+ * Contracts (per architecture 10):
+ *   U1 — no DOM or PM truth reads. UI API consumes runtime state through
+ *        RuntimeApiHandle + Geometry + Workflow/Review.
+ *   U2 — bound to a controller, not React internals.
+ *   U3 — selection + viewport are the only bidirectional channels.
+ *   U4 — overlays derive anchors from geometry, never DOM.
+ *   U5 — chrome posture composed once per read.
+ *   U6 — debug attachment opt-in; gated by `debugMode` prop, default "off".
+ *   U7 — subscribers fire on runtime state changes + coalesced rAF.
+ *   U8 — no access to internal controllers.
+ */
+
+import type {
+  OverlayKind,
+  ScopeBundle,
+  SelectionSnapshot,
+  WorkflowMarkupMode,
+} from "../../public-types.ts";
+import type { GeometryRect } from "../../../runtime/geometry/geometry-types.ts";
+import type {
+  ChromeComposition,
+  ChromeCompositionInput,
+  EditorRailTab,
+} from "./chrome-composition.ts";
+
+/**
+ * Re-export the layer-05 GeometryRect so UI API consumers can type overlay
+ * returns without importing from `src/runtime/geometry/**` themselves.
+ */
+export type { GeometryRect };
+
+/**
+ * Re-export the class-A `OverlayKind` closed union from public-types so
+ * U9 consumers can import everything they need from the UI API barrel.
+ * The canonical definition lives at `src/api/public-types.ts` because
+ * layer-06 policies also key off it.
+ */
+export type { OverlayKind };
+
+/**
+ * Re-export the class-A `WorkflowMarkupMode` closed union from
+ * public-types so X5 consumers can import everything they need from the
+ * UI API barrel. Composed with the class-C local preference in
+ * `ui.viewport.getEffectiveMarkupMode()`.
+ */
+export type { WorkflowMarkupMode };
+
+/* ================================================================== */
+/*  Session binding                                                   */
+/* ================================================================== */
+
+/**
+ * Opaque controller handle. The UI API does not care whether a React
+ * component, a Playwright test, or a remote debug session is driving it —
+ * only that the caller is responsible for the lifecycle.
+ */
+export type UiControllerKind = "runtime-direct" | "window-debug" | "playwright";
+
+/**
+ * Opaque controller handle. Three dispatch hooks (all optional) let the
+ * bind-side wire concrete host behavior for the bidirectional channels in
+ * U3 — selection + viewport/scroll. Missing hooks cause the matching UI
+ * API methods to throw rather than silently no-op, so consumers notice
+ * misconfigured bindings immediately.
+ *
+ * - `runtime-direct` — a React editor mount binds a controller whose
+ *   `dispatchSelection` routes through the command bridge and whose
+ *   `dispatchScroll` calls `scrollIntoView` on the geometry target.
+ * - `window-debug` — the debug service binds a controller that RPCs to
+ *   the editor instance via `window.__debug`.
+ * - `playwright` — a Playwright test driver binds a controller whose
+ *   hooks enqueue events for the test runner to observe.
+ */
+export interface UiController {
+  readonly kind: UiControllerKind;
+  readonly id: string;
+  /**
+   * Bidirectional channel U3 — UI → runtime selection dispatch. Called by
+   * `ui.surface.setSelection`. Throwing here (or omitting the hook) is a
+   * configuration bug; the UI API surfaces the error verbatim.
+   */
+  readonly dispatchSelection?: (range: SelectionRangeInput) => void;
+  /**
+   * Bidirectional channel U3 — UI → runtime/viewport scroll dispatch.
+   * Called by `ui.surface.scrollTo`. Returns a promise that resolves when
+   * the scroll settles (or immediately for `behavior: "instant"`).
+   */
+  readonly dispatchScroll?: (target: ScrollTarget) => Promise<void>;
+  /**
+   * Viewport provider. Optional. Slice 2 reads viewport through this when
+   * present; a geometry-backed path lands when `RuntimeApiHandle` gains a
+   * `geometry` accessor (tracked on `refactor/runtime-api`).
+   */
+  readonly getViewport?: () => ViewportState;
+  /**
+   * Viewport subscription — rAF-coalesced updates for scroll / zoom / DPR
+   * changes. `ui.viewport.subscribe` delegates here; the bind-side is
+   * responsible for producing one event per rAF tick (U7). Omitting the
+   * hook causes `ui.viewport.subscribe` to throw a configuration-clear
+   * error rather than silently no-op.
+   */
+  readonly subscribeViewport?: (listener: UiListener<ViewportState>) => UiUnsubscribe;
+  /**
+   * Overlay invalidation subscription. Fires when geometry invalidation
+   * ranges overlap attached overlay queries (U7). `ui.overlays.subscribe`
+   * delegates here; bind-side wires the runtime's layout-invalidation
+   * events to this hook.
+   */
+  readonly subscribeOverlays?: (
+    listener: UiListener<OverlayAnchorQuery>,
+  ) => UiUnsubscribe;
+  /**
+   * Overlay anchor resolver. Expected to be a direct projection of the
+   * geometry facet (U4 — overlays derive from geometry, not DOM). Returns
+   * null when geometry is unavailable or the query does not resolve. The
+   * bind-side wires this to `GeometryFacet.getAnchor` with the appropriate
+   * OverlayAnchorQuery → AnchorQuery translation.
+   *
+   * This controller hook exists as a seam until `RuntimeApiHandle` gains
+   * a `geometry` accessor (tracked on `refactor/runtime-api`); at that
+   * point `ui.overlays.getAnchor` can call through the handle directly
+   * and downgrade this hook to a fallback.
+   */
+  readonly getOverlayAnchor?: (query: OverlayAnchorQuery) => GeometryRect | null;
+  /**
+   * Overlay multi-rect resolver. Used for scope envelopes and spanning
+   * selections (U4). Returns the empty array when geometry is unavailable
+   * or the query does not resolve.
+   */
+  readonly getOverlayRects?: (query: OverlayAnchorQuery) => readonly GeometryRect[];
+  /**
+   * Host-provided chrome posture slice — the fields that live outside the
+   * runtime (host props like reviewMode / markupDisplay / debugMode /
+   * chromePreset). `ui.chrome.getPosture` composes this with the runtime's
+   * guard snapshot + session/render state into the final ChromePosture.
+   *
+   * Default values when the hook is missing or returns undefined:
+   *   reviewMode      — "observer"
+   *   markupDisplay   — "final"
+   *   debugMode       — "off"  (gated per U6; default MUST remain "off")
+   *   chromePreset    — undefined
+   */
+  readonly getHostPosture?: () => ChromeHostPosture | undefined;
+  /**
+   * Pinned-surface enumeration. The bind-side wraps the existing
+   * `chrome-preset-model` logic and returns the current list. When the
+   * hook is absent, `ui.chrome.getPinnedSurfaces()` returns [].
+   */
+  readonly getPinnedSurfaces?: () => readonly ChromeSurface[];
+  /**
+   * Posture change subscription. Fires on guard snapshot change, session
+   * state change, or host posture change (U7). `ui.chrome.subscribe`
+   * delegates here.
+   */
+  readonly subscribeChrome?: (
+    listener: UiListener<ChromePosture>,
+  ) => UiUnsubscribe;
+  /**
+   * Debug attachment. The bind-side wires the runtime's telemetry bus and
+   * projector to the mounted debug surface (Phase Q — see
+   * `src/ui-tailwind/debug/`). Returns a cleanup function. Omitting the
+   * hook causes `ui.debug.attach` to throw rather than silently ignoring
+   * the request.
+   */
+  readonly attachDebug?: (session: DebugSession) => () => void;
+}
+
+/**
+ * Factory signature consumed by `createUiApi(handle, factory)` and by
+ * `createApiV3(handle, { ui: factory })` (refactor/07 Slice 2 wiring per the
+ * staircase in master plan §2).
+ *
+ * The factory receives the `RuntimeApiHandle` the UI API will operate
+ * against; the returned `UiController` provides the mounted-surface
+ * dispatch + subscription hooks. Passing `RuntimeApiHandle` (not
+ * `unknown`) means bind-side code gets the same typed seam v3 family
+ * modules use — no ad-hoc casts to reach the runtime shape.
+ */
+export type UiControllerFactory = (handle: import("../_runtime-handle.ts").RuntimeApiHandle) => UiController;
+
+export interface UiBinding {
+  readonly controller: UiController;
+  /**
+   * Release this specific binding. Idempotent — subsequent calls are no-ops.
+   * If the UI API has since been bound to a different controller, releasing
+   * an older binding does not affect the newer one.
+   */
+  readonly release: () => void;
+}
+
+/* ================================================================== */
+/*  Surface — selection + viewport (bidirectional, U3)                */
+/* ================================================================== */
+
+export interface ViewportState {
+  readonly scrollTop: number;
+  readonly scrollLeft: number;
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Physical pixel density — pixels per OOXML twip (the geometry facet's
+   * `pxPerTwip`). NOT a 1.0-is-100% zoom ratio. Review M1 (2026-04-22)
+   * flagged the naming as misleading: when the first semantic consumer
+   * reads this field, either (a) rename to `pxPerTwip`, or (b) divide
+   * by a known baseline at the composition site so `zoom: 1.0 = 100%`.
+   * No consumer reads this semantically today — keep the name for now
+   * because renaming is a breaking surface change.
+   */
+  readonly zoom: number;
+  readonly devicePixelRatio: number;
+}
+
+export type ScrollTargetBehavior = "auto" | "smooth" | "instant";
+
+export type ScrollTarget =
+  | { kind: "offset"; value: number; behavior?: ScrollTargetBehavior }
+  | { kind: "block"; value: string; behavior?: ScrollTargetBehavior }
+  | { kind: "scope"; value: string; behavior?: ScrollTargetBehavior }
+  | { kind: "comment"; value: string; behavior?: ScrollTargetBehavior }
+  | { kind: "revision"; value: string; behavior?: ScrollTargetBehavior }
+  | { kind: "page"; value: number; behavior?: ScrollTargetBehavior };
+
+export interface SelectionRangeInput {
+  readonly anchor: number;
+  readonly head: number;
+  readonly storyTarget?: SelectionSnapshot["storyTarget"];
+}
+
+/* ================================================================== */
+/*  Overlays — U4: anchor derivation from geometry                    */
+/* ================================================================== */
+
+export type OverlayAnchorQuery =
+  | { kind: "block"; value: string }
+  | { kind: "scope"; value: string }
+  | { kind: "comment"; value: string }
+  | { kind: "revision"; value: string }
+  | { kind: "page"; value: number }
+  | { kind: "selection" };
+
+/* ================================================================== */
+/*  Overlay visibility — U9 (state-classes X3)                        */
+/* ================================================================== */
+
+/**
+ * Composed overlay visibility per `OverlayKind`. Returned by
+ * `ui.overlays.getVisibility(kind)` after merging:
+ *   - class-A policy       → `handle.getVisibilityPolicy(kind)` (L06)
+ *   - class-C local pref   → per-mounted-session preference (L10)
+ *
+ * Four discriminated states:
+ *   - `"visible"` / `"hidden"` — policy ceded to preference (or defaulted).
+ *     `reason` carries whether it was the authored default or the user's
+ *     explicit preference.
+ *   - `"forced-on"` / `"forced-off"` — policy enforcement won; local
+ *     preference has no effect. `reason` is always `"policy-enforcement"`.
+ *
+ * The closed union makes it impossible for a consumer to render a toggle
+ * that would silently fail — `forced-*` states communicate "your click
+ * won't change this" before the user clicks.
+ */
+export type OverlayVisibility =
+  | { readonly state: "visible";   readonly reason: "policy-default" | "user-preference" }
+  | { readonly state: "hidden";    readonly reason: "policy-default" | "user-preference" }
+  | { readonly state: "forced-on";  readonly reason: "policy-enforcement" }
+  | { readonly state: "forced-off"; readonly reason: "policy-enforcement" };
+
+/* ================================================================== */
+/*  Chrome posture — U5                                               */
+/* ================================================================== */
+
+export type ChromeDocumentMode = "edit" | "suggest" | "comment" | "view";
+export type ChromeMarkupDisplay = "final" | "markup" | "original";
+export type ChromeReviewMode = "author" | "reviewer" | "observer";
+export type ChromeDebugMode = "off" | "top-bar" | "full";
+
+export interface ChromePosture {
+  readonly effectiveMode: ChromeDocumentMode | "blocked";
+  readonly documentMode: ChromeDocumentMode;
+  readonly readOnly: boolean;
+  readonly reviewMode: ChromeReviewMode;
+  readonly markupDisplay: ChromeMarkupDisplay;
+  readonly debugMode: ChromeDebugMode;
+  readonly chromePreset?: string;
+  readonly blockedReasons: readonly string[];
+}
+
+export type ChromeSurfaceKind =
+  | "toolbar"
+  | "rail"
+  | "sidebar"
+  | "command-palette"
+  | "context-menu"
+  | "top-nav";
+
+export interface ChromeSurface {
+  readonly kind: ChromeSurfaceKind;
+  readonly id: string;
+  readonly visible: boolean;
+  readonly pinned: boolean;
+}
+
+/**
+ * Host-provided slice of ChromePosture. Returned by the bind-side through
+ * `UiController.getHostPosture`. The runtime-sourced fields (effectiveMode,
+ * documentMode, readOnly, blockedReasons) come from the handle; these fields
+ * are the host's responsibility.
+ */
+export interface ChromeHostPosture {
+  readonly reviewMode?: ChromeReviewMode;
+  readonly markupDisplay?: ChromeMarkupDisplay;
+  /** MUST default to "off" at the caller level (U6); see CLAUDE.md Protected Invariants. */
+  readonly debugMode?: ChromeDebugMode;
+  readonly chromePreset?: string;
+}
+
+/* ================================================================== */
+/*  Debug attachment — U6                                             */
+/* ================================================================== */
+
+export interface DebugSession {
+  readonly id: string;
+  readonly channels: readonly string[];
+}
+
+export interface DebugAttachment {
+  readonly session: DebugSession;
+  readonly detach: () => void;
+}
+
+/* ================================================================== */
+/*  Subscription                                                      */
+/* ================================================================== */
+
+export type UiUnsubscribe = () => void;
+export type UiListener<T> = (value: T) => void;
+
+/* ================================================================== */
+/*  Namespace shape                                                   */
+/* ================================================================== */
+
+export interface ApiV3UiSession {
+  bind(controller: UiController): UiBinding;
+  getController(): UiController | null;
+  release(): void;
+}
+
+export interface ApiV3UiSurface {
+  getSelection(): SelectionSnapshot | null;
+  setSelection(range: SelectionRangeInput): void;
+  getViewport(): ViewportState;
+  scrollTo(target: ScrollTarget): Promise<void>;
+}
+
+export interface ApiV3UiViewport {
+  get(): ViewportState;
+  subscribe(listener: UiListener<ViewportState>): UiUnsubscribe;
+
+  /**
+   * X5 · Composed effective markup mode. Merges L06's class-A
+   * `WorkflowMarkupModePolicy` (via `handle.getMarkupModePolicy()`)
+   * with this instance's class-C local preference.
+   *
+   * Composition rules (parallels U9 overlay visibility):
+   *   - `policy.enforcement === "always"` → the policy's mode wins.
+   *   - `"authored-default"` cedes to the local preference; when none
+   *     is set, `policy.mode` is the default.
+   *   - No policy yet authored → `"all"` (intrinsic default: show all
+   *     markup so a user who hasn't toggled anything sees changes).
+   */
+  getEffectiveMarkupMode(): WorkflowMarkupMode;
+  /** Set the per-session local preference (class C). */
+  setLocalMarkupMode(mode: WorkflowMarkupMode): void;
+  /** Clear the local preference; subsequent reads fall back to policy. */
+  resetLocalMarkupMode(): void;
+  /**
+   * Subscribe to effective-markup-mode changes. Fires on local-pref
+   * mutation AND on L06 policy-change (chained through
+   * `handle.subscribeMarkupModePolicy`). Returns unsubscribe.
+   */
+  subscribeEffectiveMarkupMode(
+    listener: UiListener<WorkflowMarkupMode>,
+  ): UiUnsubscribe;
+}
+
+export interface ApiV3UiOverlays {
+  /** Returns null when geometry is unavailable — never falls back to DOM (U4). */
+  getAnchor(query: OverlayAnchorQuery): GeometryRect | null;
+  /** Multi-rect coverage for scope envelopes. Empty array when unavailable. */
+  getRects(query: OverlayAnchorQuery): readonly GeometryRect[];
+  subscribe(listener: UiListener<OverlayAnchorQuery>): UiUnsubscribe;
+
+  /**
+   * U9 · Composed overlay visibility. Merges the class-A policy from
+   * `handle.getVisibilityPolicy(kind)` with the class-C local preference
+   * stored per UI API instance. `"debug-panel"` has an extra gate:
+   * local preference is ignored when `ChromePosture.debugMode === "off"`
+   * (CLAUDE.md Protected Invariant).
+   */
+  getVisibility(kind: OverlayKind): OverlayVisibility;
+  /** Set the per-session local preference (class C). */
+  setLocalPreference(kind: OverlayKind, visible: boolean): void;
+  /** Clear the local preference; subsequent reads fall back to policy. */
+  resetLocalPreference(kind: OverlayKind): void;
+  /**
+   * Subscribe to visibility changes for a specific `OverlayKind`. Fires
+   * when the local preference for that kind changes (via
+   * `setLocalPreference` / `resetLocalPreference`). Policy changes and
+   * `debugMode` changes are not fanned out in this slice — consumers
+   * that need those should re-read on their own cadence. Returns an
+   * unsubscribe function.
+   */
+  subscribeVisibility(
+    kind: OverlayKind,
+    listener: UiListener<OverlayVisibility>,
+  ): UiUnsubscribe;
+}
+
+export interface ApiV3UiChrome {
+  /**
+   * Runtime-sourced chrome posture (U5.a). Narrow slice — effectiveMode,
+   * documentMode, readOnly, blocked reasons, plus the host-provided
+   * reviewMode / markupDisplay / debugMode / chromePreset.
+   */
+  getPosture(): ChromePosture;
+  /**
+   * Full presentation-shaped chrome composition (U5.b). Takes a host-
+   * supplied `ChromeCompositionInput` and returns the single
+   * `ChromeComposition` every chrome surface reads.
+   *
+   * Rail state (`activeRailTab`, `pinnedRailTabs`) is read from the UI
+   * API's class-C local state when the caller omits those fields; if
+   * the caller supplies them, they override. That means chrome consumers
+   * can call `getComposition({ chromePreset, chromeOptions, reviewMode,
+   * role })` without re-tracking rail state — the UI API owns it.
+   *
+   * Pure under equal inputs + rail state — memoize at the caller
+   * boundary against whatever inputs change per render, plus the
+   * result of `getActiveRailTab()` / `getPinnedRailTabs()` if those
+   * feed into the render.
+   */
+  getComposition(input: ChromeCompositionInput): ChromeComposition;
+  getPinnedSurfaces(): readonly ChromeSurface[];
+  subscribe(listener: UiListener<ChromePosture>): UiUnsubscribe;
+
+  /**
+   * Class-C local rail state — which rail tab is active. Null means
+   * "no tab is active" (rail closed or preset suppresses rail). The UI
+   * API owns this state; consumers that set it expect composition
+   * reads to reflect the change on next call.
+   */
+  getActiveRailTab(): EditorRailTab | null;
+  /**
+   * Explicitly set the active rail tab. `null` closes the rail (no
+   * active tab). Subsequent `getComposition()` calls reflect this
+   * unless the caller supplies an explicit `activeRailTab` override.
+   */
+  setActiveRailTab(tab: EditorRailTab | null): void;
+
+  /** Snapshot of currently-pinned rail tabs (class C). */
+  getPinnedRailTabs(): ReadonlySet<EditorRailTab>;
+  /** Pin a rail tab so it stays visible even when empty. Idempotent. */
+  pinRailTab(tab: EditorRailTab): void;
+  /** Unpin a rail tab. Idempotent. */
+  unpinRailTab(tab: EditorRailTab): void;
+
+  /**
+   * Subscribe to rail-state changes (active tab or pinned set). Fires
+   * after every `setActiveRailTab` / `pinRailTab` / `unpinRailTab` call
+   * that actually mutated state. Payload is the new active tab; consumers
+   * that need the pinned set read via `getPinnedRailTabs()`.
+   */
+  subscribeRailState(
+    listener: UiListener<EditorRailTab | null>,
+  ): UiUnsubscribe;
+}
+
+export interface ApiV3UiDebug {
+  attach(session: DebugSession): DebugAttachment;
+  detach(): void;
+}
+
+/**
+ * Scope seam — mounted-path scope-bundle reads. MVP surface unblocked
+ * by L07's `compileScopeBundleById` handle primitive (2026-04-23).
+ */
+export interface ApiV3UiScope {
+  /**
+   * Read the full `ScopeBundle` for a scope by id. Returns `null` when
+   * the scope does not enumerate today (handle drift, synthetic scope,
+   * marker-backed scope on a different story target, etc.). Ergonomic
+   * single-call wrapper — callers that need replay-deterministic
+   * `generatedAtUtc` use `api.ai.getScopeBundle` directly with an
+   * explicit clock.
+   */
+  getBundle(scopeId: string): ScopeBundle | null;
+}
+
+export interface ApiV3Ui {
+  readonly session: ApiV3UiSession;
+  readonly surface: ApiV3UiSurface;
+  readonly viewport: ApiV3UiViewport;
+  readonly overlays: ApiV3UiOverlays;
+  readonly chrome: ApiV3UiChrome;
+  readonly debug: ApiV3UiDebug;
+  readonly scope: ApiV3UiScope;
+}