@ai-matrx/summon 0.0.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1259 @@
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import { PayloadAction, Reducer, UnknownAction, Middleware } from '@reduxjs/toolkit';
+
+/**
+ * The shared vocabulary of @ai-matrx/summon. Framework-free: no React, no Redux imports.
+ *
+ * An OVERLAY is any component rendered on top of the app by dispatch — a window, dialog, sheet,
+ * light floating window, toast-like card, anything. It is identified by an `OverlayId` and opened
+ * as one or more INSTANCES (`instanceId`, "default" for single-instance overlays).
+ */
+/**
+ * The host's overlay registry: overlay id → the data its opener accepts. Hosts extend it by
+ * module augmentation so every open call is type-checked:
+ *
+ *   declare module "@ai-matrx/summon" {
+ *     interface OverlayRegistry { notesWindow: { noteId?: string } }
+ *   }
+ *
+ * `defineOverlay` emits nothing at runtime for this; the augmentation is the host's one-line
+ * declaration per overlay (the converter writes it next to each definition).
+ */
+interface OverlayRegistry {
+}
+/** Every registered overlay id; plain `string` until the host augments the registry. */
+type OverlayId = [keyof OverlayRegistry] extends [never] ? string : Extract<keyof OverlayRegistry, string>;
+/** The open-data type declared for an overlay id. */
+type OverlayDataOf<Id extends string> = Id extends keyof OverlayRegistry ? OverlayRegistry[Id] : Record<string, unknown>;
+/**
+ * Data as it arrives at render time. It crossed Redux, a URL or storage, so it is NOT trusted to
+ * match the opener's type: render code narrows it (or the definition supplies `parse`).
+ */
+type OverlayRawData = Readonly<Record<string, unknown>> | null;
+declare const DEFAULT_INSTANCE_ID = "default";
+/** `single`: one instance ("default"). `multi`: any number, each with its own instanceId. */
+type InstanceMode = "single" | "multi";
+/**
+ * What closing does to a mounted overlay (Arman, 2026-10-16, C38 R3):
+ *   none    — unmount (default).
+ *   hidden  — stay mounted but hidden; reopening shows the same live component (LRU-capped).
+ *   restore — unmount, but values saved with `useOverlayState` come back on reopen.
+ * Minimizing a window always keeps its component mounted, whatever this says.
+ */
+type KeepAlive = "none" | "hidden" | "restore";
+/** `overlayId:instanceId` — the one key every subsystem uses for an open instance. */
+type InstanceKey = `${string}:${string}`;
+declare function instanceKey(overlayId: string, instanceId?: string): InstanceKey;
+declare function parseInstanceKey(key: string): {
+    overlayId: string;
+    instanceId: string;
+} | null;
+type MobilePresentation = "fullscreen" | "drawer" | "card" | "hidden";
+/**
+ * Default-deny allowlist of the open data a window may save and restore. A window with no
+ * preservation entry restores geometry only.
+ */
+interface WindowPreservation {
+    readonly dataKeys: readonly string[];
+    readonly requiredDataKeys?: readonly string[];
+    readonly allowedDataValues?: Readonly<Record<string, readonly (string | number | boolean | null)[]>>;
+    /** Default 32 KiB. */
+    readonly maxDataBytes?: number;
+}
+/** One declared home for an unbidden (system-raised) window: a route prefix, or one exact page. */
+type UnbiddenHomeRoute = string | {
+    readonly route: string;
+    readonly exact: true;
+};
+interface OverlayWindowOptions {
+    readonly mobile?: MobilePresentation;
+    readonly mobileSidebarAs?: "drawer" | "inline";
+    /** Never saved or restored (debug panels, one-shot tools, callback-bound editors). */
+    readonly ephemeral?: boolean;
+    readonly preservation?: WindowPreservation;
+    /**
+     * Values merged under saved data when a window is RESTORED (reload, another device). Unlike the
+     * definition's `defaults`, never applied to a normal open.
+     */
+    readonly restoreDefaults?: Readonly<Record<string, unknown>>;
+    /**
+     * The window-manager id the WindowPanel registers under for the default instance. Default: the
+     * overlay id. The render watchdog reveals and inspects this id until the panel acks its own.
+     */
+    readonly windowId?: string;
+    readonly deprecated?: {
+        readonly replacement?: string;
+        readonly reason?: string;
+    };
+    /**
+     * Where a window nobody opened (system-raised) may raise itself. Default deny: no home → it may
+     * not raise itself anywhere (`mayRaiseUnbidden` in the window section).
+     */
+    readonly unbiddenHome?: readonly UnbiddenHomeRoute[];
+}
+/**
+ * Host-specific types the package passes through untouched. A Redux host augments `dispatch`
+ * with its thunk-aware dispatch so link hydrators can dispatch its thunks without casts:
+ *
+ *   declare module "@ai-matrx/summon" { interface OverlayHostTypes { dispatch: AppDispatch } }
+ */
+interface OverlayHostTypes {
+}
+type OverlayHostDispatch = OverlayHostTypes extends {
+    dispatch: infer D;
+} ? D : (action: unknown) => unknown;
+interface LinkHydrateContext<Data> {
+    /** The id segment of the link token (`notes:<id>`). */
+    readonly id: string;
+    /** Decoded `k-v` arguments of the token. */
+    readonly args: Readonly<Record<string, string>>;
+    /** Open this overlay. */
+    open(options?: {
+        readonly instanceId?: string;
+        readonly data?: Data;
+    }): void;
+    /** The host store's dispatch, for thunks a hydrator needs (loading a record first). Typed by
+     *  augmenting `OverlayHostTypes` with the host's dispatch type. */
+    readonly dispatch: OverlayHostDispatch;
+}
+interface OverlayLinkSpec<Data> {
+    /** The token type key in `?panels=key:id`. Unique across the host. */
+    readonly key: string;
+    /** Older keys that still resolve to this overlay. */
+    readonly aliases?: readonly string[];
+    /** Turn a link token into an open overlay (and its data). `"refused"` keeps the token and says why. */
+    hydrate(context: LinkHydrateContext<Data>): void | "refused" | Promise<void | "refused">;
+}
+interface OverlayDefinitionMeta<Id extends string = string, Data = Record<string, unknown>> {
+    readonly id: Id;
+    /** Human label: tray, menus, diagnostics. */
+    readonly label: string;
+    readonly instance?: InstanceMode;
+    readonly keepAlive?: KeepAlive;
+    /** Close when the route changes — the overlay shows a piece of the page that opened it. */
+    readonly closesOnNavigation?: boolean;
+    /** Present only for overlays that render a WindowPanel. */
+    readonly window?: OverlayWindowOptions;
+    readonly link?: OverlayLinkSpec<Data>;
+    /** Defaults merged under open data (replaces the old per-overlay schema registry). */
+    readonly defaults?: Partial<Data>;
+}
+/** The window-manager id a singleton window overlay registers under (`window.windowId ?? id`). */
+declare function defaultWindowIdFor(meta: Pick<OverlayDefinitionMeta, "id" | "window">): string;
+
+/**
+ * Everything the overlays system needs from its host, as ports. Every port ships a working
+ * default, so a bare host gets a working system with zero wiring (package standard rule 8); a
+ * host overrides only what it has: identity, navigation, notifications, error sink, debug flag,
+ * persistence. Framework-free.
+ */
+type Unsubscribe = () => void;
+/** Who the person is, for isolating saved state. `key` changes → everything saved is swapped. */
+interface IdentityPort {
+    current(): {
+        readonly key: string;
+        readonly ready: boolean;
+    };
+    subscribe(listener: () => void): Unsubscribe;
+}
+/** The address bar: route changes (close-on-navigation) and the `?panels=` link channel. */
+interface RouterPort {
+    pathname(): string;
+    search(): string;
+    /** Replace the query string without navigating or remounting the page. */
+    replaceSearch(nextSearch: string): void;
+    subscribe(listener: () => void): Unsubscribe;
+}
+interface NotifyOptions {
+    readonly id?: string;
+    readonly description?: string;
+    /** How long the notice stays up (ms). Hosts without timed notices ignore it. */
+    readonly duration?: number;
+    /** One action button (e.g. the render watchdog's "Show it"). Hosts without actions ignore it. */
+    readonly action?: {
+        readonly label: string;
+        readonly onClick: () => void;
+    };
+}
+interface NotifyPort {
+    info(message: string, options?: NotifyOptions): void;
+    warn(message: string, options?: NotifyOptions): void;
+    error(message: string, options?: NotifyOptions): void;
+    /** Withdraw a notice by id (optional). */
+    dismiss?(id: string): void;
+}
+interface ErrorSinkPort {
+    capture(error: unknown, context: Readonly<Record<string, unknown>>): void;
+}
+interface DebugPort {
+    enabled(): boolean;
+    subscribe?(listener: () => void): Unsubscribe;
+}
+/** A stored value with its optimistic-concurrency version (0 when the store has none). */
+interface StoredValue<T = unknown> {
+    readonly value: T;
+    readonly version: number;
+}
+/**
+ * Where saved overlay state lives when persistence is on. Keys are already scoped to the
+ * identity by the caller (`<identityKey>/<key>`) for stores that are not per-person themselves.
+ * Implementations: the browser-local store (`./persistence`), `@ai-matrx/data` over
+ * `users.user_surface_state` (`./persistence/data`), or any host database.
+ */
+interface OverlayPersistencePort {
+    /**
+     * True when the store is per-person itself (rows scoped to the signed-in person, e.g. the
+     * `@ai-matrx/data` adapter): the persistence section then passes plain keys (`workspace`,
+     * `state:<instanceKey>`) instead of `<identityKey>/<key>`, and defaults to `scope: "person"`.
+     */
+    readonly perPerson?: boolean;
+    load<T = unknown>(key: string): Promise<StoredValue<T> | null>;
+    save<T = unknown>(key: string, value: T, options?: {
+        readonly expectedVersion?: number;
+    }): Promise<{
+        readonly version: number;
+    }>;
+    remove(key: string): Promise<void>;
+    list?(prefix: string): Promise<readonly string[]>;
+}
+interface SummonPorts {
+    readonly identity: IdentityPort;
+    readonly router: RouterPort;
+    readonly notify: NotifyPort;
+    readonly errors: ErrorSinkPort;
+    readonly debug: DebugPort;
+    /** `null` = persistence off (R6). */
+    readonly persistence: OverlayPersistencePort | null;
+}
+declare const anonymousIdentity: IdentityPort;
+/** `window.location` + `history.replaceState`; inert on the server. */
+declare const locationRouter: RouterPort;
+declare const consoleNotify: NotifyPort;
+declare const consoleErrorSink: ErrorSinkPort;
+declare const debugOff: DebugPort;
+declare const DEFAULT_PORTS: SummonPorts;
+declare function resolvePorts(overrides: Partial<SummonPorts> | undefined): SummonPorts;
+
+/**
+ * A definition's meta with its data type erased, so definitions of every data shape share one
+ * registry without casts. (`never` erasure made `defaults` unassignable.)
+ */
+interface AnyOverlayMeta extends Omit<OverlayDefinitionMeta<string, unknown>, "defaults"> {
+    readonly defaults?: object | undefined;
+}
+type AnyMeta = AnyOverlayMeta;
+/**
+ * Register (or re-register) definitions. Re-registering an id replaces it (hot reload). A link
+ * key claimed by two different ids is a host bug and throws, naming both.
+ */
+declare function registerOverlayMeta(definitions: readonly AnyOverlayMeta[]): void;
+declare function getOverlayMeta(overlayId: string): AnyMeta | undefined;
+declare function getOverlayMetaByLinkKey(linkKey: string): AnyMeta | undefined;
+declare function allOverlayMeta(): readonly AnyMeta[];
+declare function isRegisteredOverlay(overlayId: string): boolean;
+declare function subscribeToOverlayRegistry(listener: () => void): () => void;
+/** Test-only. */
+declare function resetOverlayRegistry(): void;
+
+interface OpenOverlayPayload<Id extends OverlayId = OverlayId> {
+    overlayId: Id;
+    instanceId?: string;
+    data?: OverlayDataOf<Id> | null;
+}
+interface CloseOverlayPayload<Id extends OverlayId = OverlayId> {
+    overlayId: Id;
+    instanceId?: string;
+}
+type ToggleOverlayPayload<Id extends OverlayId = OverlayId> = OpenOverlayPayload<Id>;
+interface CloseAllInstancesPayload<Id extends OverlayId = OverlayId> {
+    overlayId: Id;
+}
+interface CloseOverlaysBoundToPagePayload {
+    /** Overlay ids whose definitions say `closesOnNavigation`. */
+    overlayIds: readonly string[];
+}
+interface PruneStaleInstancesPayload {
+    olderThanMs: number;
+}
+interface OverlayInstance {
+    isOpen: boolean;
+    data: unknown;
+    /**
+     * Unix ms timestamp of the last open action. Used by `pruneStaleInstances` to GC
+     * long-forgotten closed entries. Set on every open, untouched on close.
+     */
+    lastUsedAt?: number;
+}
+interface OverlayState {
+    overlays: Record<string, Record<string, OverlayInstance>>;
+}
+/** Raw reducer payloads: untyped ids + the registry defaults the action creator resolved. */
+interface RawOpenPayload {
+    overlayId: string;
+    instanceId?: string;
+    data?: unknown;
+    defaults?: Readonly<Record<string, unknown>>;
+}
+declare const overlaysReducer: _reduxjs_toolkit.Reducer<OverlayState>;
+/** The raw slice action creators (untyped ids). Use for `.match` / `.type`; dispatch the typed ones. */
+declare const overlaysRawActions: _reduxjs_toolkit.CaseReducerActions<{
+    openOverlay: (state: {
+        overlays: {
+            [x: string]: {
+                [x: string]: {
+                    isOpen: boolean;
+                    data: unknown;
+                    lastUsedAt?: number;
+                };
+            };
+        };
+    }, action: PayloadAction<RawOpenPayload>) => void;
+    closeOverlay: (state: {
+        overlays: {
+            [x: string]: {
+                [x: string]: {
+                    isOpen: boolean;
+                    data: unknown;
+                    lastUsedAt?: number;
+                };
+            };
+        };
+    }, action: PayloadAction<{
+        overlayId: string;
+        instanceId?: string;
+    }>) => void;
+    closeAllOverlays: (state: {
+        overlays: {
+            [x: string]: {
+                [x: string]: {
+                    isOpen: boolean;
+                    data: unknown;
+                    lastUsedAt?: number;
+                };
+            };
+        };
+    }) => void;
+    toggleOverlay: (state: {
+        overlays: {
+            [x: string]: {
+                [x: string]: {
+                    isOpen: boolean;
+                    data: unknown;
+                    lastUsedAt?: number;
+                };
+            };
+        };
+    }, action: PayloadAction<RawOpenPayload>) => void;
+    /** Removes every instance of an overlay id (e.g. an editor that spawned many tabs). */
+    closeAllInstancesOfOverlay: (state: {
+        overlays: {
+            [x: string]: {
+                [x: string]: {
+                    isOpen: boolean;
+                    data: unknown;
+                    lastUsedAt?: number;
+                };
+            };
+        };
+    }, action: PayloadAction<{
+        overlayId: string;
+    }>) => void;
+    /**
+     * Route change: close every open instance of the listed overlays — each shows a piece of the
+     * page that opened it, so after navigating away it would float over a page it does not
+     * belong to. Every other overlay is a workbench tool and stays open.
+     */
+    closeOverlaysBoundToPage: (state: {
+        overlays: {
+            [x: string]: {
+                [x: string]: {
+                    isOpen: boolean;
+                    data: unknown;
+                    lastUsedAt?: number;
+                };
+            };
+        };
+    }, action: PayloadAction<CloseOverlaysBoundToPagePayload>) => void;
+    /**
+     * GC pass — removes closed instances last used more than `olderThanMs` ago. Singleton slots
+     * are kept regardless so selectors returning stable references don't thrash.
+     */
+    pruneStaleInstances: (state: {
+        overlays: {
+            [x: string]: {
+                [x: string]: {
+                    isOpen: boolean;
+                    data: unknown;
+                    lastUsedAt?: number;
+                };
+            };
+        };
+    }, action: PayloadAction<PruneStaleInstancesPayload>) => void;
+}, "overlays">;
+declare const openOverlay: (<Id extends OverlayId>(payload: OpenOverlayPayload<Id>) => {
+    payload: RawOpenPayload;
+    type: "overlays/openOverlay";
+}) & Pick<_reduxjs_toolkit.ActionCreatorWithPayload<RawOpenPayload, "overlays/openOverlay">, "type" | "match">;
+declare const closeOverlay: (<Id extends OverlayId>(payload: CloseOverlayPayload<Id>) => {
+    payload: {
+        overlayId: string;
+        instanceId?: string;
+    };
+    type: "overlays/closeOverlay";
+}) & Pick<_reduxjs_toolkit.ActionCreatorWithPayload<{
+    overlayId: string;
+    instanceId?: string;
+}, "overlays/closeOverlay">, "type" | "match">;
+declare const toggleOverlay: (<Id extends OverlayId>(payload: ToggleOverlayPayload<Id>) => {
+    payload: RawOpenPayload;
+    type: "overlays/toggleOverlay";
+}) & Pick<_reduxjs_toolkit.ActionCreatorWithPayload<RawOpenPayload, "overlays/toggleOverlay">, "type" | "match">;
+declare const closeAllInstancesOfOverlay: (<Id extends OverlayId>(payload: CloseAllInstancesPayload<Id>) => {
+    payload: {
+        overlayId: string;
+    };
+    type: "overlays/closeAllInstancesOfOverlay";
+}) & Pick<_reduxjs_toolkit.ActionCreatorWithPayload<{
+    overlayId: string;
+}, "overlays/closeAllInstancesOfOverlay">, "type" | "match">;
+/** Ids of every registered overlay whose definition says `closesOnNavigation`. */
+declare function overlayIdsBoundToPage(): string[];
+/** Close page-bound overlays. Omit the ids to use the registry's `closesOnNavigation` list. */
+declare const closeOverlaysBoundToPage: ((payload?: Partial<CloseOverlaysBoundToPagePayload>) => {
+    payload: CloseOverlaysBoundToPagePayload;
+    type: "overlays/closeOverlaysBoundToPage";
+}) & Pick<_reduxjs_toolkit.ActionCreatorWithPayload<CloseOverlaysBoundToPagePayload, "overlays/closeOverlaysBoundToPage">, "type" | "match">;
+declare const closeAllOverlays: _reduxjs_toolkit.ActionCreatorWithoutPayload<"overlays/closeAllOverlays">;
+declare const pruneStaleInstances: _reduxjs_toolkit.ActionCreatorWithPayload<PruneStaleInstancesPayload, "overlays/pruneStaleInstances">;
+/** The slice of any store these selectors need. */
+type StateWithOverlays = {
+    overlays: OverlayState;
+};
+interface OpenInstanceView {
+    instanceId: string;
+    data: unknown;
+}
+declare const selectOverlay: (state: StateWithOverlays, overlayId: string, instanceId?: string) => OverlayInstance;
+declare const selectIsOverlayOpen: (state: StateWithOverlays, overlayId: string, instanceId?: string) => boolean;
+declare const selectOverlayData: (state: StateWithOverlays, overlayId: string, instanceId?: string) => unknown;
+/**
+ * All currently-open instances of an overlay id. Memoized per id: the array reference is stable
+ * while the open set is unchanged.
+ */
+declare const selectOpenInstances: (state: StateWithOverlays, overlayId: string) => readonly OpenInstanceView[];
+/** Every open instance key (`overlayId:instanceId`) in the state. */
+declare function listOpenInstanceKeys(state: StateWithOverlays): string[];
+
+interface WindowRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/**
+ * Calculates a 4-grid quadrant (2x2).
+ * @param index 0: top-left, 1: top-right, 2: bottom-left, 3: bottom-right
+ */
+declare function getGrid4Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates a 6-grid partition (3 columns x 2 rows).
+ * @param index 0-5. 0-2 is top row (left-to-right), 3-5 is bottom row.
+ */
+declare function getGrid6Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates an 8-window grid (4 columns, 2 a rows)
+ */
+declare function getGrid8Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates a 9-window grid (3 columns, 3 rows)
+ */
+declare function getGrid9Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates a 12-window grid (4 columns, 3 rows)
+ */
+declare function getGrid12Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 2 stacked windows on the right edge.
+ * @param index 0: top right half, 1: bottom right half
+ */
+declare function getStackedRight2Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 3 stacked windows on the right edge.
+ * @param index 0, 1, 2 top-to-bottom on the right third of the screen.
+ */
+declare function getStackedRight3Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 4 stacked windows on the right edge.
+ * @param index 0,1,2,3 top-to-bottom on the right quarter of the screen.
+ */
+declare function getStackedRight4Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 5 stacked windows on the right edge.
+ */
+declare function getStackedRight5Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 2 stacked windows on the left edge.
+ * @param index 0: top left half, 1: bottom left half
+ */
+declare function getStackedLeft2Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 3 stacked windows on the left edge.
+ * @param index 0, 1, 2 top-to-bottom on the left third of the screen.
+ */
+declare function getStackedLeft3Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 4 stacked windows on the left edge.
+ * @param index 0,1,2,3 top-to-bottom on the left quarter of the screen.
+ */
+declare function getStackedLeft4Rect(index: number, vw: number, vh: number): WindowRect;
+/**
+ * Calculates 5 stacked windows on the left edge.
+ */
+declare function getStackedLeft5Rect(index: number, vw: number, vh: number): WindowRect;
+type GlobalLayoutType = "grid4" | "grid6" | "grid8" | "grid9" | "grid12" | "stackRight2" | "stackRight3" | "stackRight4" | "stackRight5" | "stackLeft2" | "stackLeft3" | "stackLeft4" | "stackLeft5";
+/**
+ * Helper: Applies global arrangement to an array of windows logic.
+ * Returns an array of updates to batch dispatch.
+ */
+declare function computeGlobalArrangement(layout: GlobalLayoutType, windowIds: string[], vw: number, vh: number, dirX?: "ltr" | "rtl", dirY?: "ttb" | "btt", primary?: "horizontal" | "vertical"): {
+    id: string;
+    rect: WindowRect;
+}[];
+
+interface DockWindowPayload {
+    id: string;
+    viewportWidth: number;
+    viewportHeight: number;
+}
+/** Build a dock action payload from the live parent viewport. Client-only. */
+declare function buildDockWindowPayload(windowId: string): DockWindowPayload;
+
+type WindowState = "windowed" | "maximized" | "minimized";
+declare const WINDOW_SESSION_SCHEMA_VERSION: 1;
+/** Canonical persistence identity. Runtime window ids and registry slugs are not identities. */
+declare function windowSessionKey(overlayId: string, instanceId: string): string;
+interface WindowPersistenceRegistration {
+    overlayId: string;
+    instanceId: string;
+    data: Record<string, unknown>;
+    sidebarOpen: boolean;
+    sidebarSize: number | null;
+}
+interface WindowPersistenceState extends WindowPersistenceRegistration {
+    /** Explicit close suppresses every later snapshot/unmount path. */
+    closing: boolean;
+}
+/** Compact, JSON-only record written to the local window workspace cache. */
+interface PersistedWindowSession {
+    schemaVersion: typeof WINDOW_SESSION_SCHEMA_VERSION;
+    sessionKey: string;
+    overlayId: string;
+    instanceId: string;
+    /** Runtime id is diagnostic/matching metadata, never the canonical identity. */
+    windowId: string;
+    title: string;
+    state: WindowState;
+    /** Always the full windowed rect, never minimized-card geometry. */
+    windowedRect: WindowRect;
+    traySlot: number | null;
+    zIndex: number;
+    sidebarOpen: boolean;
+    sidebarSize: number | null;
+    data: Record<string, unknown>;
+    savedAt: number;
+}
+/** Viewport-normalized session staged for a live WindowPanel registration. */
+interface HydratedWindowSession extends PersistedWindowSession {
+    /** Current-viewport render rect; tray geometry is recomputed, never stored. */
+    renderRect: WindowRect;
+}
+/**
+ * Pop-out mode for windows that have been detached into a separate browser
+ * window. Orthogonal to `WindowState` — a popped-out window still has a
+ * "logical" docked state remembered on `prePopoutRect` for the dock-back path.
+ *
+ * - `"pip"`: Document Picture-in-Picture (Chromium) — frameless, always-on-top.
+ *   Subject to the single-PiP-per-origin constraint enforced via
+ *   `activePipWindowId`.
+ * - `"popup"`: `window.open()` fallback for browsers without DPiP support
+ *   (Safari, Firefox). Shows browser chrome.
+ * - `null`: Window is docked inside the parent viewport (the default).
+ */
+type PopoutMode = "pip" | "popup" | null;
+interface WindowEntry {
+    id: string;
+    title: string;
+    state: WindowState;
+    /** Last windowed size/position — restored when coming back from max/min */
+    windowed: WindowRect;
+    /** Saved rect before minimize so restore can return to the original size */
+    preMinimizedRect: WindowRect | null;
+    /** z-index order — higher = on top */
+    zIndex: number;
+    /** Order in the minimized tray (0-based). */
+    traySlot: number | null;
+    /**
+     * Pop-out mode. `null` while docked. When set, the window is rendered into
+     * a separate browser window via Document PiP or `window.open()` fallback.
+     * Never written to the local workspace cache — always reset on hydration
+     * (see `restoreWindowState`).
+     */
+    popoutMode: PopoutMode;
+    /**
+     * Saved windowed rect at popout time. Restored to `windowed` on dock-back
+     * via `dockWindow`. `null` while docked (matches `preMinimizedRect` pattern).
+     */
+    prePopoutRect: WindowRect | null;
+    /** Present only for registry entries explicitly approved for preservation. */
+    persistence?: WindowPersistenceState;
+}
+interface WindowManagerState {
+    windows: Record<string, WindowEntry>;
+    /** Validated sessions waiting for their WindowPanel registration. */
+    pendingRestores: Record<string, HydratedWindowSession>;
+    /** Next z-index to assign when a window is focused */
+    nextZIndex: number;
+    /** How many slots are currently occupied in the tray */
+    trayCount: number;
+    /** Last viewport used to place tray cards; enables safe reflow on removal. */
+    trayViewport: {
+        width: number;
+        height: number;
+    } | null;
+    /** Global show/hide toggle — windows stay mounted but are visually hidden */
+    windowsHidden: boolean;
+    /**
+     * The id of the window currently occupying the single Document PiP slot
+     * (Chromium allows only one DPiP window per origin at a time). `null` when
+     * the slot is free. Windows in `"popup"` mode do NOT count toward this slot.
+     */
+    activePipWindowId: string | null;
+    /**
+     * The id of the window currently being dragged outside the viewport beyond
+     * the popout threshold. Used purely for visual feedback ("Release to pop
+     * out" outline + ghost label). Cleared on every `pointerup`.
+     */
+    popoutCandidateId: string | null;
+    /**
+     * Z-index lane for LITE windows (`MatrxDynamicPanelHost presentation="floating"`).
+     *
+     * They are deliberately NOT entries in `windows`: a lite window is a
+     * transient form/picker host with no tray chip, no minimize and no
+     * persistence, so joining `windows` would put a half-typed create form into
+     * "minimize all" and the tray — the lost-work trap the lite window exists to
+     * avoid. Keeping them in their own map means every tray/minimize/arrange
+     * selector excludes them BY CONSTRUCTION rather than by a flag somebody must
+     * remember to filter on.
+     *
+     * They still draw from the SAME `nextZIndex` counter, so there is one
+     * z-order: a lite window opened from a WindowPanel always lands above it,
+     * and clicking the WindowPanel afterwards raises it above the lite window.
+     */
+    transientZ: Record<string, number>;
+}
+declare const TRAY_CHIP_W = 240;
+declare const TRAY_CHIP_H = 160;
+declare const raiseTransientWindow: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/raiseTransientWindow">;
+declare const releaseTransientWindow: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/releaseTransientWindow">;
+declare const registerWindow: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    title?: string;
+    initial: WindowRect;
+    initialState?: "windowed" | "minimized";
+    persistence?: WindowPersistenceRegistration;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}, "windowManager/registerWindow">;
+declare const unregisterWindow: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/unregisterWindow">;
+declare const focusWindow: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/focusWindow">;
+declare const restoreWindow: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/restoreWindow">;
+declare const revealWindow: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    viewportWidth: number;
+    viewportHeight: number;
+}, "windowManager/revealWindow">;
+declare const maximizeWindow: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/maximizeWindow">;
+declare const minimizeWindow: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    viewportWidth: number;
+    viewportHeight: number;
+}, "windowManager/minimizeWindow">;
+declare const minimizeAll: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    viewportWidth: number;
+    viewportHeight: number;
+}, "windowManager/minimizeAll">;
+declare const restoreAll: _reduxjs_toolkit.ActionCreatorWithoutPayload<"windowManager/restoreAll">;
+declare const recomputeTrayPositions: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    viewportWidth: number;
+    viewportHeight: number;
+}, "windowManager/recomputeTrayPositions">;
+declare const updateWindowRect: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    rect: Partial<WindowRect>;
+}, "windowManager/updateWindowRect">;
+declare const updateWindowTitle: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    title: string;
+}, "windowManager/updateWindowTitle">;
+declare const toggleWindowsHidden: _reduxjs_toolkit.ActionCreatorWithoutPayload<"windowManager/toggleWindowsHidden">;
+declare const moveTraySlot: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    toSlot: number;
+}, "windowManager/moveTraySlot">;
+declare const arrangeActiveWindows: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    layout: GlobalLayoutType;
+    viewportWidth: number;
+    viewportHeight: number;
+    dirX?: "ltr" | "rtl";
+    dirY?: "ttb" | "btt";
+    primary?: "horizontal" | "vertical";
+}, "windowManager/arrangeActiveWindows">;
+declare const popOutWindow: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    mode: "pip" | "popup";
+}, "windowManager/popOutWindow">;
+declare const dockWindow: _reduxjs_toolkit.ActionCreatorWithPayload<DockWindowPayload, "windowManager/dockWindow">;
+declare const setPopoutCandidate: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string | null;
+}, "windowManager/setPopoutCandidate">;
+declare const clampWindowRect: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    viewportWidth: number;
+    viewportHeight: number;
+}, "windowManager/clampWindowRect">;
+declare const clampAllWindowRects: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    viewportWidth: number;
+    viewportHeight: number;
+}, "windowManager/clampAllWindowRects">;
+declare const restoreWindowState: _reduxjs_toolkit.ActionCreatorWithPayload<Record<string, WindowEntry>, "windowManager/restoreWindowState">;
+declare const hydrateWindowSessions: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    sessions: HydratedWindowSession[];
+    viewportWidth: number;
+    viewportHeight: number;
+}, "windowManager/hydrateWindowSessions">;
+declare const confirmWindowRestored: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/confirmWindowRestored">;
+declare const discardPendingWindowSession: _reduxjs_toolkit.ActionCreatorWithPayload<string, "windowManager/discardPendingWindowSession">;
+declare const updateWindowPersistence: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    id: string;
+    data?: Record<string, unknown>;
+    sidebarOpen?: boolean;
+    sidebarSize?: number | null;
+}, "windowManager/updateWindowPersistence">;
+declare const markWindowClosing: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    overlayId: string;
+    instanceId: string;
+}, "windowManager/markWindowClosing">;
+declare const clearWindowPersistenceState: _reduxjs_toolkit.ActionCreatorWithoutPayload<"windowManager/clearWindowPersistenceState">;
+type StateWithWM = {
+    windowManager: WindowManagerState;
+};
+declare const selectPendingWindowRestores: (state: StateWithWM) => Record<string, HydratedWindowSession>;
+declare const selectWindowPersistence: (id: string) => (state: StateWithWM) => WindowPersistenceState | undefined;
+declare const selectWindow: (id: string) => (state: StateWithWM) => WindowEntry | undefined;
+declare const selectWindowState: (id: string) => (state: StateWithWM) => WindowState | undefined;
+declare const selectWindowRect: (id: string) => (state: StateWithWM) => WindowRect | undefined;
+declare const selectWindowZIndex: (id: string) => (state: StateWithWM) => number;
+/** z-index for a transient (lite) window; BASE_Z until it has been raised. */
+declare const selectTransientZIndex: (id: string) => (state: StateWithWM) => number;
+declare const selectWindowTitle: (id: string) => (state: StateWithWM) => string;
+declare const selectTraySlotWidth: () => number;
+declare const selectWindowsHidden: (state: StateWithWM) => boolean;
+/**
+ * Minimized windows sorted by tray slot ascending.
+ * Memoized — only recalculates when the windows map reference changes.
+ */
+declare const selectTrayWindows: ((state: StateWithWM) => WindowEntry[]) & {
+    clearCache: () => void;
+    resultsCount: () => number;
+    resetResultsCount: () => void;
+} & {
+    resultFunc: (resultFuncArgs_0: Record<string, WindowEntry>) => WindowEntry[];
+    memoizedResultFunc: ((resultFuncArgs_0: Record<string, WindowEntry>) => WindowEntry[]) & {
+        clearCache: () => void;
+        resultsCount: () => number;
+        resetResultsCount: () => void;
+    };
+    lastResult: () => WindowEntry[];
+    dependencies: [(state: StateWithWM) => Record<string, WindowEntry>];
+    recomputations: () => number;
+    resetRecomputations: () => void;
+    dependencyRecomputations: () => number;
+    resetDependencyRecomputations: () => void;
+} & {
+    argsMemoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+};
+/** All registered windows sorted by zIndex descending (most-recently-focused first). */
+declare const selectAllWindows: ((state: StateWithWM) => WindowEntry[]) & {
+    clearCache: () => void;
+    resultsCount: () => number;
+    resetResultsCount: () => void;
+} & {
+    resultFunc: (resultFuncArgs_0: Record<string, WindowEntry>) => WindowEntry[];
+    memoizedResultFunc: ((resultFuncArgs_0: Record<string, WindowEntry>) => WindowEntry[]) & {
+        clearCache: () => void;
+        resultsCount: () => number;
+        resetResultsCount: () => void;
+    };
+    lastResult: () => WindowEntry[];
+    dependencies: [(state: StateWithWM) => Record<string, WindowEntry>];
+    recomputations: () => number;
+    resetRecomputations: () => void;
+    dependencyRecomputations: () => number;
+    resetDependencyRecomputations: () => void;
+} & {
+    argsMemoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+};
+/** True when every registered window is minimized (or there are none). */
+declare const selectAllMinimized: ((state: StateWithWM) => boolean) & {
+    clearCache: () => void;
+    resultsCount: () => number;
+    resetResultsCount: () => void;
+} & {
+    resultFunc: (resultFuncArgs_0: Record<string, WindowEntry>) => boolean;
+    memoizedResultFunc: ((resultFuncArgs_0: Record<string, WindowEntry>) => boolean) & {
+        clearCache: () => void;
+        resultsCount: () => number;
+        resetResultsCount: () => void;
+    };
+    lastResult: () => boolean;
+    dependencies: [(state: StateWithWM) => Record<string, WindowEntry>];
+    recomputations: () => number;
+    resetRecomputations: () => void;
+    dependencyRecomputations: () => number;
+    resetDependencyRecomputations: () => void;
+} & {
+    argsMemoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+};
+/** Current popout mode for a window. Returns `null` if docked or unknown id. */
+declare const selectPopoutMode: (id: string) => (state: StateWithWM) => "pip" | "popup" | null;
+/** True if the window is currently popped out (either pip or popup mode). */
+declare const selectIsPoppedOut: (id: string) => (state: StateWithWM) => boolean;
+/** The id of the window holding the single Document PiP slot, or `null`. */
+declare const selectActivePipWindowId: (state: StateWithWM) => string | null;
+/**
+ * The id of the window currently being dragged outside the viewport beyond
+ * the popout threshold. Used by WindowPanel to render the "Release to pop
+ * out" outline.
+ */
+declare const selectPopoutCandidateId: (state: StateWithWM) => string | null;
+/** Saved rect to dock back to. `null` while docked or after dock-back. */
+declare const selectPrePopoutRect: (id: string) => (state: StateWithWM) => WindowRect | null;
+/**
+ * All windows currently docked (popoutMode === null), sorted by zIndex
+ * descending. Used by arrange/tray logic so popped-out windows don't get
+ * assigned slots in parent-viewport layouts.
+ */
+declare const selectDockedWindows: ((state: StateWithWM) => WindowEntry[]) & {
+    clearCache: () => void;
+    resultsCount: () => number;
+    resetResultsCount: () => void;
+} & {
+    resultFunc: (resultFuncArgs_0: Record<string, WindowEntry>) => WindowEntry[];
+    memoizedResultFunc: ((resultFuncArgs_0: Record<string, WindowEntry>) => WindowEntry[]) & {
+        clearCache: () => void;
+        resultsCount: () => number;
+        resetResultsCount: () => void;
+    };
+    lastResult: () => WindowEntry[];
+    dependencies: [(state: StateWithWM) => Record<string, WindowEntry>];
+    recomputations: () => number;
+    resetRecomputations: () => void;
+    dependencyRecomputations: () => number;
+    resetDependencyRecomputations: () => void;
+} & {
+    argsMemoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+};
+declare const windowManagerReducer: _reduxjs_toolkit.Reducer<WindowManagerState>;
+
+interface UrlSyncEntry {
+    typeKey: string;
+    instanceId: string;
+    args?: Record<string, string>;
+}
+interface UrlSyncState {
+    /** Keyed by `${typeKey}:${instanceId}`. */
+    entries: Record<string, UrlSyncEntry>;
+    isHydrated: boolean;
+}
+declare const linksReducer: _reduxjs_toolkit.Reducer<UrlSyncState>;
+declare const setHydrated: _reduxjs_toolkit.ActionCreatorWithoutPayload<"urlSync/setHydrated">;
+declare const registerSyncEntry: _reduxjs_toolkit.ActionCreatorWithPayload<UrlSyncEntry, "urlSync/registerSyncEntry">;
+declare const unregisterSyncEntry: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    typeKey: string;
+    instanceId: string;
+}, "urlSync/unregisterSyncEntry">;
+type StateWithUrlSync = {
+    urlSync: UrlSyncState;
+};
+declare const selectUrlSyncEntries: (state: StateWithUrlSync) => Record<string, UrlSyncEntry>;
+declare const selectIsUrlHydrated: (state: StateWithUrlSync) => boolean;
+
+interface OverlayStateEntry {
+    values: Record<string, unknown>;
+    updatedAt: number;
+}
+interface OverlayStateState {
+    entries: Record<string, OverlayStateEntry>;
+}
+interface SetOverlayStateValuePayload {
+    key: InstanceKey;
+    name: string;
+    value: unknown;
+}
+interface ReplaceOverlayStatePayload {
+    key: InstanceKey;
+    values: Record<string, unknown>;
+}
+interface HydrateOverlayStatePayload {
+    /** Entries to load. Existing keys are replaced; others are left alone. */
+    entries: Record<string, {
+        values: Record<string, unknown>;
+        updatedAt?: number;
+    }>;
+}
+declare const overlayStateReducer: _reduxjs_toolkit.Reducer<OverlayStateState>;
+declare const setOverlayStateValue: _reduxjs_toolkit.ActionCreatorWithPayload<SetOverlayStateValuePayload, "overlayState/setOverlayStateValue">;
+declare const replaceOverlayState: _reduxjs_toolkit.ActionCreatorWithPayload<ReplaceOverlayStatePayload, "overlayState/replaceOverlayState">;
+declare const clearOverlayState: _reduxjs_toolkit.ActionCreatorWithPayload<{
+    key: InstanceKey;
+}, "overlayState/clearOverlayState">;
+declare const hydrateOverlayState: _reduxjs_toolkit.ActionCreatorWithPayload<HydrateOverlayStatePayload, "overlayState/hydrateOverlayState">;
+type StateWithOverlayState = {
+    overlayState: OverlayStateState;
+};
+/** One saved value, `undefined` when never set. */
+declare const selectOverlayStateValue: (state: StateWithOverlayState, key: InstanceKey, name: string) => unknown;
+/** Every saved value of an instance (stable empty object when none). */
+declare const selectOverlayStateFor: (state: StateWithOverlayState, key: InstanceKey) => Readonly<Record<string, unknown>>;
+
+/** The four overlays reducers at their canonical root keys. */
+declare const summonReducers: {
+    overlays: Reducer<OverlayState>;
+    windowManager: Reducer<WindowManagerState>;
+    urlSync: Reducer<UrlSyncState>;
+    overlayState: Reducer<OverlayStateState>;
+};
+type SummonRootState = {
+    [K in keyof typeof summonReducers]: ReturnType<(typeof summonReducers)[K]>;
+};
+/** The overlays middleware, in order: close lifecycle, then the render watchdog. */
+declare function createSummonMiddleware(ports?: Partial<SummonPorts>): Middleware[];
+interface CreateOverlaysStoreOptions {
+    ports?: Partial<SummonPorts>;
+    preloadedState?: Partial<SummonRootState>;
+    /** More reducers mounted beside the overlays keys (a small host that wants one store). */
+    extraReducers?: Record<string, Reducer>;
+}
+/** A store holding the overlays slices and middleware. */
+declare function createSummonStore(options?: CreateOverlaysStoreOptions): _reduxjs_toolkit.EnhancedStore<SummonRootState, UnknownAction, _reduxjs_toolkit.Tuple<[_reduxjs_toolkit.StoreEnhancer<{
+    dispatch: _reduxjs_toolkit.ThunkDispatch<SummonRootState, undefined, UnknownAction>;
+}>, _reduxjs_toolkit.StoreEnhancer]>>;
+type SummonStore = ReturnType<typeof createSummonStore>;
+type SummonDispatch = SummonStore["dispatch"];
+
+/**
+ * Close lifecycle — what happens, in one place, when an overlay instance closes:
+ *
+ *   1. Window preservation identities are tombstoned (`markWindowClosing`) so no later snapshot or
+ *      unmount path re-saves a window the person closed (ported from matrx-frontend
+ *      `features/window-panels/persistence/windowPersistenceCloseMiddleware.ts`).
+ *   2. Every handle owned by the closed instance (`overlayId:instanceId`) is disposed — pending
+ *      requests reject, channels drop their subscribers — so no opener disposes by hand.
+ *   3. The instance's `overlayState` is cleared, unless its definition says `keepAlive:
+ *      "restore"` (values come back on reopen). `keepAlive: "hidden"` instances stay mounted, so
+ *      they keep both their handles and their state until the React host evicts them
+ *      (`releaseOverlayInstance`).
+ *   4. Registered close flushers run (the persistence section writes the post-close workspace).
+ *
+ * Close actions: closeOverlay, toggleOverlay (when it closed), closeAllOverlays,
+ * closeAllInstancesOfOverlay, closeOverlaysBoundToPage. Closed instances are found by diffing the
+ * open set before and after the reducer, so every path is covered the same way.
+ */
+
+interface CloseIdentity {
+    overlayId: string;
+    instanceId: string;
+}
+/** What a close meant, for persistence: one exact instance, every instance of an id, or all. */
+type WindowCloseIntent = ({
+    scope: "exact";
+} & CloseIdentity) | {
+    scope: "overlay";
+    overlayId: string;
+} | {
+    scope: "all";
+};
+interface CloseEvent {
+    /** The intent(s) behind this close (empty when only a page-bound or toggle path closed). */
+    readonly intents: readonly WindowCloseIntent[];
+    /** Every instance that went from open to closed in this action. */
+    readonly closedKeys: readonly InstanceKey[];
+    /** The dispatched action's type. */
+    readonly actionType: string;
+}
+type CloseFlusher = (event: CloseEvent) => void;
+/**
+ * Run `flush` synchronously after every close, once tombstones and disposal are done. Replaces the
+ * app's `registerWindowPersistenceFlusher`; any number may be registered. Returns the unregister.
+ */
+declare function registerCloseFlusher(flush: CloseFlusher): () => void;
+type CloseRootState = StateWithOverlays & Partial<StateWithOverlayState> & {
+    windowManager?: WindowManagerState;
+};
+/**
+ * Release an instance's handles and saved state now (the React host calls this when it evicts a
+ * kept-alive hidden instance). `keepState` keeps `overlayState` (keepAlive "restore").
+ */
+declare function releaseOverlayInstance(dispatch: (action: UnknownAction) => unknown, key: InstanceKey, options?: {
+    keepState?: boolean;
+}): void;
+/** The close-lifecycle middleware (framework-free; one per overlays store). */
+declare const closeLifecycleMiddleware: Middleware<object, CloseRootState>;
+
+/**
+ * overlayRenderWatchdog
+ *
+ * Makes "a panel was triggered but silently never appeared" structurally
+ * impossible to ship unnoticed. Two responsibilities, one middleware:
+ *
+ *  1. REVEAL — on every open of a window-kind overlay, dispatch `revealWindow`
+ *     so an already-registered window that is minimized, dragged off-screen, or
+ *     suppressed by the global hide-all is brought back into view. Re-opening a
+ *     window must never be a silent no-op.
+ *
+ *  2. DETECT — after the open, inspect actual Redux + viewport state and
+ *     confirm a *visible* panel is on screen. If not, SCREAM (console.error)
+ *     and surface a self-healing toast. This is the loud recovery layer
+ *     mandated by CLAUDE.md: a recovery firing means a real bug got past the
+ *     proactive layer.
+ *
+ * The one state a fixed timer cannot distinguish is "lazy chunk still loading"
+ * vs "never mounted" — every window component enters through `next/dynamic`,
+ * and a cold dev compile (or a slow network fetch in prod) can take far longer
+ * than any polite delay. The watchdog therefore treats the WindowPanel mount
+ * acknowledgement (`ackOverlayRender`, called from WindowPanel's mount effect,
+ * i.e. strictly after the dynamic import settled) as the chunk-settle signal:
+ * while no ack exists it WAITS for one (bounded by a hard no-mount deadline)
+ * instead of screaming, and diagnoses geometry only once the ack arrives. A
+ * false scream trains people to ignore the real ones.
+ *
+ * If a scream does fire and the panel becomes visible afterwards anyway, the
+ * toast is auto-dismissed and a recovery note is logged — the loud layer never
+ * lingers past the failure it reported.
+ *
+ * The detector is intentionally scoped to SINGLETON window-kind overlays — the
+ * surfaces that render through `WindowPanel` and join the window manager. Non-
+ * window overlays (dialogs/sheets/toasts) don't register geometry and would
+ * false-positive, so they're skipped. Multi-instance windows carry per-instance
+ * ids we don't track here and are skipped too.
+ *
+ * The pure decision (`diagnoseOverlayRender`) is exported separately so it can
+ * be unit-tested without a store, a DOM, or timers.
+ *
+ * Ported from matrx-frontend `features/window-panels/diagnostics/overlayRenderWatchdog.ts`.
+ * Seams inverted: toast → `ports.notify`, the console scream → `ports.errors`, the window
+ * metadata lookup → the core definition registry (`meta.window` = window kind, `meta.instance`,
+ * `defaultWindowIdFor(meta)` = the old registry slug). Ack/waiter/watch maps live in a global
+ * slot instead of module scope. The middleware is a factory over ports.
+ */
+
+/**
+ * Hard ceiling on waiting for a lazily mounted window: one constant for every subsystem that
+ * waits on that physical event (the link manager waits on the same one).
+ */
+declare const LAZY_WINDOW_MOUNT_DEADLINE_MS: number;
+declare const RENDER_WATCHDOG_SLOT = "ai-matrx.summon.renderWatchdog";
+declare function ackOverlayRender(overlayId: string, windowId: string): void;
+declare function clearOverlayRender(overlayId: string, windowId: string): void;
+declare function ackOverlaySurfaceRender(overlayId: string): void;
+declare function clearOverlaySurfaceRender(overlayId: string): void;
+type RenderFailureReason = "no-window-registered" | "all-windows-hidden" | "zero-size" | "off-screen";
+type RenderDiagnosis = {
+    ok: true;
+    reason: null;
+} | {
+    ok: false;
+    reason: RenderFailureReason;
+};
+/** A window counts as on-screen if a usable strip of it intersects the
+ *  viewport (matches the spirit of `clampRectToViewport`'s safe margin). */
+declare function rectOnScreen(rect: WindowRect, viewportWidth: number, viewportHeight: number): boolean;
+/**
+ * Given the window's geometry entry and global state, decide whether a visible
+ * panel is actually on screen. Pure — no store, DOM, or timers.
+ */
+declare function diagnoseOverlayRender(args: {
+    entry: WindowEntry | undefined;
+    windowsHidden: boolean;
+    viewportWidth: number;
+    viewportHeight: number;
+    surfaceAcknowledged?: boolean;
+}): RenderDiagnosis;
+type WMState = {
+    overlays: OverlayState;
+    windowManager: WindowManagerState;
+};
+type WatchdogPorts = Pick<SummonPorts, "notify" | "errors">;
+/**
+ * Does the watchdog verify this open? Only SINGLETON window-kind overlays: a
+ * multi-instance window renders under a per-instance window id
+ * (`transcription-cleanup-<instanceId>`) that is never the registry slug and
+ * never acks under the overlay id — so watching it, even when it was opened on
+ * the "default" instance (the Tools grid / URL hydration open that way), can
+ * only end in a false "didn't appear" toast over a window that is on screen.
+ */
+declare function watchdogTracksOpen(meta: Pick<OverlayDefinitionMeta, "window" | "instance"> | undefined, instanceId: string): boolean;
+/** The render watchdog for a store whose host supplied `ports` (notify + error sink). */
+declare function createOverlayRenderWatchdogMiddleware(ports: WatchdogPorts): Middleware<object, WMState>;
+/** Test-only: cancel every in-flight watch and forget all acks. */
+declare function resetOverlayRenderWatchdog(): void;
+
+/**
+ * rectClamp — viewport-safe geometry restoration.
+ *
+ * When hydrating window geometry from the DB (or the legacy localStorage
+ * migration), a rect saved at a larger viewport size or on a different
+ * device can land partially or entirely off-screen. This utility clamps
+ * stored rects into a sensible shape for the current viewport:
+ *
+ *  - Width/height capped to viewport minus safe margins.
+ *  - Position nudged into bounds so the complete usable window stays visible.
+ *  - If the stored rect is entirely nonsensical (e.g. width 0, negative
+ *    coords with huge values), fall back to a centered default.
+ */
+interface WindowRectLike {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ViewportDims {
+    vw: number;
+    vh: number;
+    /**
+     * True when the measurement was unusable (0, negative, non-finite, or SSR)
+     * and `vw`/`vh` are invented fallbacks rather than a real screen.
+     *
+     * **Anything that WRITES geometry state from a viewport read must check this
+     * and bail without writing.** Inventing 1280×800 is right for "give me
+     * something to render against"; it is wrong for "persist this as the user's
+     * geometry", because the invented value then has to be undone by the next
+     * real measurement — and a write per measurement is how a
+     * measure → write → re-measure cycle starts.
+     */
+    degenerate: boolean;
+}
+/**
+ * Viewport dimensions that are safe to derive or judge window geometry from.
+ *
+ * `window.innerWidth/innerHeight` can measure 0 (hidden or prerendered page,
+ * a background/undisplayed tab, pre-layout read, headless run). Deriving an
+ * initial rect from that turns "90vw" into width 0 — the window registers a
+ * 0×0 rect, renders as nothing, and stays invisible until something
+ * re-clamps it (the "window opens invisible" class, watchdog reason:
+ * zero-size). Judging on-screen position against a 0×0 viewport is just as wrong:
+ * every on-screen rect reads as off-screen. A degenerate measurement is never
+ * a real screen — fall back to sane dimensions, warn once, and tell the
+ * caller so writers can stand down (`degenerate`).
+ */
+declare function safeViewportDims(): ViewportDims;
+/**
+ * Clamp a rect into the current viewport. Pure — caller passes both the
+ * rect and the viewport so this works in tests without DOM globals.
+ *
+ * A zero/negative viewport is a degenerate MEASUREMENT (hidden or embedded
+ * pane, pre-layout read, headless run) — never a real screen. Clamping
+ * against it collapses any rect to `{x:-48, y:0, width:120, height:80}` and
+ * that garbage then gets rendered and persisted, so instead we keep the
+ * caller's geometry (sanitising only non-finite values) and scream once.
+ *
+ * @param rect      Stored rect from DB / LS.
+ * @param viewport  { width, height } in CSS pixels.
+ */
+declare function clampRectToViewport(rect: WindowRectLike, viewport: {
+    width: number;
+    height: number;
+}): WindowRectLike;
+/**
+ * Center a rect in the viewport, preserving (clamped) width/height.
+ * Used when docking a popped-out window back into the parent page.
+ */
+declare function centerRectInViewport(rect: WindowRectLike, viewport: {
+    width: number;
+    height: number;
+}): WindowRectLike;
+/**
+ * Convenience wrapper that reads the current window dimensions. Only safe
+ * to call on the client.
+ */
+declare function clampRectToCurrentViewport(rect: WindowRectLike): WindowRectLike;
+/** Exact rect equality. Used to skip no-op geometry writes. */
+declare function rectsEqual(a: WindowRectLike, b: WindowRectLike): boolean;
+
+/**
+ * Tray layout constants.
+ *
+ * Hardcoded previously inside `windowManagerSlice.ts` and `WindowTray.tsx`.
+ * Centralised here so the mobile-responsive sizing path can derive chip
+ * dimensions from a single source.
+ *
+ * Note: `windowManagerSlice` re-exports `TRAY_CHIP_W` and `TRAY_CHIP_H` for
+ * backward compatibility — external consumers should still import from here
+ * going forward.
+ */
+/** Desktop minimized-card width in px. */
+declare const TRAY_CHIP_W_DESKTOP = 240;
+/** Desktop minimized-card height in px. */
+declare const TRAY_CHIP_H_DESKTOP = 160;
+/** Horizontal gap between chips. */
+declare const TRAY_GAP_X = 8;
+/** Vertical gap between rows of chips. */
+declare const TRAY_GAP_Y = 8;
+/** Gap from the right viewport edge. */
+declare const TRAY_MARGIN_R = 20;
+/** Gap from the bottom viewport edge. */
+declare const TRAY_MARGIN_B = 20;
+/** Left boundary: cards never flow farther left than this. */
+declare const TRAY_MARGIN_L = 8;
+/** Header-only height used when full cards no longer fit in the viewport. */
+declare const TRAY_COMPACT_H = 32;
+/** Tighter gap for the overflow overview grid. */
+declare const TRAY_COMPACT_GAP = 4;
+/**
+ * Mobile chip width target. The tray becomes a horizontal-scroll strip on
+ * mobile, so the width is a target upper bound clamped against the viewport.
+ */
+declare const TRAY_CHIP_W_MOBILE_MAX = 180;
+/** Mobile chip height — slightly shorter to fit tight screens. */
+declare const TRAY_CHIP_H_MOBILE = 72;
+/** Viewport width below which the mobile tray layout takes over. */
+declare const TRAY_MOBILE_BREAKPOINT = 768;
+/**
+ * Compute the chip width for a given viewport. On mobile, fits ~2 chips
+ * across with safe-area padding; never exceeds the desktop size on wider
+ * screens.
+ */
+declare function computeTrayChipWidth(viewportWidth: number): number;
+/** Chip height for a given viewport. */
+declare function computeTrayChipHeight(viewportWidth: number): number;
+/** Number of cards that fit in a tray row at the current viewport width. */
+declare function trayChipsPerRow(viewportWidth: number): number;
+/**
+ * Compute the visual rectangle for a tray slot. Slot zero starts at the
+ * bottom-right; later slots grow left, then wrap upward into additional rows.
+ */
+declare function traySlotRect(slot: number, viewportWidth: number, viewportHeight: number, totalSlots?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+export { type AnyOverlayMeta, type CloseAllInstancesPayload, type CloseEvent, type CloseFlusher, type CloseOverlayPayload, type CloseOverlaysBoundToPagePayload, type CreateOverlaysStoreOptions, DEFAULT_INSTANCE_ID, DEFAULT_PORTS, type DebugPort, type DockWindowPayload, type ErrorSinkPort, type GlobalLayoutType, type HydrateOverlayStatePayload, type HydratedWindowSession, type IdentityPort, type InstanceKey, type InstanceMode, type KeepAlive, LAZY_WINDOW_MOUNT_DEADLINE_MS, type LinkHydrateContext, type MobilePresentation, type NotifyOptions, type NotifyPort, type OpenInstanceView, type OpenOverlayPayload, type OverlayDataOf, type OverlayDefinitionMeta, type OverlayHostDispatch, type OverlayHostTypes, type OverlayId, type OverlayInstance, type OverlayLinkSpec, type OverlayPersistencePort, type OverlayRawData, type OverlayRegistry, type OverlayState, type OverlayStateEntry, type OverlayStateState, type OverlayWindowOptions, type PersistedWindowSession, type PopoutMode, type PruneStaleInstancesPayload, RENDER_WATCHDOG_SLOT, type RenderDiagnosis, type RenderFailureReason, type ReplaceOverlayStatePayload, type RouterPort, type SetOverlayStateValuePayload, type StateWithOverlayState, type StateWithOverlays, type StateWithUrlSync, type StoredValue, type SummonDispatch, type SummonPorts, type SummonRootState, type SummonStore, TRAY_CHIP_H, TRAY_CHIP_H_DESKTOP, TRAY_CHIP_H_MOBILE, TRAY_CHIP_W, TRAY_CHIP_W_DESKTOP, TRAY_CHIP_W_MOBILE_MAX, TRAY_COMPACT_GAP, TRAY_COMPACT_H, TRAY_GAP_X, TRAY_GAP_Y, TRAY_MARGIN_B, TRAY_MARGIN_L, TRAY_MARGIN_R, TRAY_MOBILE_BREAKPOINT, type ToggleOverlayPayload, type UnbiddenHomeRoute, type Unsubscribe, type UrlSyncEntry, type UrlSyncState, type ViewportDims, WINDOW_SESSION_SCHEMA_VERSION, type WindowCloseIntent, type WindowEntry, type WindowManagerState, type WindowPersistenceRegistration, type WindowPersistenceState, type WindowPreservation, type WindowRect, type WindowRectLike, type WindowState, ackOverlayRender, ackOverlaySurfaceRender, allOverlayMeta, anonymousIdentity, arrangeActiveWindows, buildDockWindowPayload, centerRectInViewport, clampAllWindowRects, clampRectToCurrentViewport, clampRectToViewport, clampWindowRect, clearOverlayRender, clearOverlayState, clearOverlaySurfaceRender, clearWindowPersistenceState, closeAllInstancesOfOverlay, closeAllOverlays, closeLifecycleMiddleware, closeOverlay, closeOverlaysBoundToPage, computeGlobalArrangement, computeTrayChipHeight, computeTrayChipWidth, confirmWindowRestored, consoleErrorSink, consoleNotify, createOverlayRenderWatchdogMiddleware, createSummonMiddleware, createSummonStore, debugOff, defaultWindowIdFor, diagnoseOverlayRender, discardPendingWindowSession, dockWindow, focusWindow, getGrid12Rect, getGrid4Rect, getGrid6Rect, getGrid8Rect, getGrid9Rect, getOverlayMeta, getOverlayMetaByLinkKey, getStackedLeft2Rect, getStackedLeft3Rect, getStackedLeft4Rect, getStackedLeft5Rect, getStackedRight2Rect, getStackedRight3Rect, getStackedRight4Rect, getStackedRight5Rect, hydrateOverlayState, hydrateWindowSessions, instanceKey, isRegisteredOverlay, linksReducer, listOpenInstanceKeys, locationRouter, markWindowClosing, maximizeWindow, minimizeAll, minimizeWindow, moveTraySlot, openOverlay, overlayIdsBoundToPage, overlayStateReducer, overlaysRawActions, overlaysReducer, parseInstanceKey, popOutWindow, pruneStaleInstances, raiseTransientWindow, recomputeTrayPositions, rectOnScreen, rectsEqual, registerCloseFlusher, registerOverlayMeta, registerSyncEntry, registerWindow, releaseOverlayInstance, releaseTransientWindow, replaceOverlayState, resetOverlayRegistry, resetOverlayRenderWatchdog, resolvePorts, restoreAll, restoreWindow, restoreWindowState, revealWindow, safeViewportDims, selectActivePipWindowId, selectAllMinimized, selectAllWindows, selectDockedWindows, selectIsOverlayOpen, selectIsPoppedOut, selectIsUrlHydrated, selectOpenInstances, selectOverlay, selectOverlayData, selectOverlayStateFor, selectOverlayStateValue, selectPendingWindowRestores, selectPopoutCandidateId, selectPopoutMode, selectPrePopoutRect, selectTransientZIndex, selectTraySlotWidth, selectTrayWindows, selectUrlSyncEntries, selectWindow, selectWindowPersistence, selectWindowRect, selectWindowState, selectWindowTitle, selectWindowZIndex, selectWindowsHidden, setHydrated, setOverlayStateValue, setPopoutCandidate, subscribeToOverlayRegistry, summonReducers, toggleOverlay, toggleWindowsHidden, trayChipsPerRow, traySlotRect, unregisterSyncEntry, unregisterWindow, updateWindowPersistence, updateWindowRect, updateWindowTitle, watchdogTracksOpen, windowManagerReducer, windowSessionKey };