@ai-matrx/summon 0.1.11 → 0.1.12

package/dist/gate-O-00kToO.d.ts

@@ -0,0 +1,851 @@
+import { OverlayHostTypes, OverlayRegistry } from '@ai-matrx/summon';
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import { Reducer, 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).
+ */
+
+/** 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 } }
+ */
+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[]>;
+    /**
+     * Every saved value at once (key → value), for stores where one read is cheaper than several.
+     * When present, restoring an identity costs exactly this one call: the workspace and every
+     * saved component state come out of it, and `load`/`list` are not called on boot.
+     */
+    loadAll?(): Promise<ReadonlyMap<string, StoredValue>>;
+}
+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 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 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;
+}
+/** Raw reducer payload: untyped ids + the registry defaults the creator resolved. */
+interface RawOpenPayload {
+    overlayId: string;
+    instanceId?: string;
+    data?: unknown;
+    defaults?: Readonly<Record<string, unknown>>;
+}
+interface SummonAction<P> {
+    type: string;
+    payload: P;
+    /** Structurally a Redux `UnknownAction`. */
+    [extra: string]: unknown;
+}
+type Creator<Args extends unknown[], P> = ((...args: Args) => SummonAction<P>) & {
+    readonly type: string;
+    match(action: unknown): action is SummonAction<P>;
+};
+/** A creator whose call signature stays generic (the inferred `creator` form erases `Id`). */
+type Generic<F> = F & {
+    readonly type: string;
+    match(action: unknown): action is SummonAction<unknown>;
+};
+declare const openOverlay: Generic<(<Id extends OverlayId>(payload: OpenOverlayPayload<Id>) => SummonAction<RawOpenPayload>)>;
+declare const closeOverlay: Generic<(<Id extends OverlayId>(payload: CloseOverlayPayload<Id>) => SummonAction<{
+    overlayId: string;
+    instanceId?: string;
+}>)>;
+declare const toggleOverlay: Generic<(<Id extends OverlayId>(payload: ToggleOverlayPayload<Id>) => SummonAction<RawOpenPayload>)>;
+declare const closeAllInstancesOfOverlay: Generic<(<Id extends OverlayId>(payload: CloseAllInstancesPayload<Id>) => SummonAction<{
+    overlayId: string;
+}>)>;
+/** 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: Creator<[payload?: Partial<CloseOverlaysBoundToPagePayload> | undefined], CloseOverlaysBoundToPagePayload>;
+declare const closeAllOverlays: Creator<[], undefined>;
+declare const pruneStaleInstances: Creator<[payload: PruneStaleInstancesPayload], PruneStaleInstancesPayload>;
+declare const focusWindow$1: Creator<[payload: string], string>;
+declare const restoreWindow$1: Creator<[payload: string], string>;
+declare const toggleWindowsHidden$1: Creator<[], undefined>;
+declare const restoreAll$1: Creator<[], undefined>;
+declare const minimizeAll$1: Creator<[payload: {
+    viewportWidth: number;
+    viewportHeight: number;
+}], {
+    viewportWidth: number;
+    viewportHeight: number;
+}>;
+interface ArrangeActiveWindowsPayload {
+    layout: GlobalLayoutType;
+    viewportWidth: number;
+    viewportHeight: number;
+    dirX?: "ltr" | "rtl";
+    dirY?: "ttb" | "btt";
+    primary?: "horizontal" | "vertical";
+}
+declare const arrangeActiveWindows$1: Creator<[payload: ArrangeActiveWindowsPayload], ArrangeActiveWindowsPayload>;
+interface UrlSyncEntryPayload {
+    typeKey: string;
+    instanceId: string;
+    args?: Readonly<Record<string, string>>;
+}
+declare const registerSyncEntry: Creator<[payload: UrlSyncEntryPayload], UrlSyncEntryPayload>;
+declare const unregisterSyncEntry: Creator<[payload: {
+    typeKey: string;
+    instanceId: string;
+}], {
+    typeKey: string;
+    instanceId: string;
+}>;
+/** Every slice key the summon reducers own; an action under one of them needs the runtime. */
+declare const SUMMON_SLICE_KEYS: readonly ["overlays", "windowManager", "urlSync", "overlayState"];
+declare function isSummonAction(action: unknown): action is {
+    type: string;
+};
+
+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$1: (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;
+} & {
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    argsMemoize: typeof _reduxjs_toolkit.weakMapMemoize;
+};
+/** All registered windows sorted by zIndex descending (most-recently-focused first). */
+declare const selectAllWindows$1: ((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;
+} & {
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    argsMemoize: typeof _reduxjs_toolkit.weakMapMemoize;
+};
+/** True when every registered window is minimized (or there are none). */
+declare const selectAllMinimized$1: ((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;
+} & {
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    argsMemoize: 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;
+} & {
+    memoize: typeof _reduxjs_toolkit.weakMapMemoize;
+    argsMemoize: typeof _reduxjs_toolkit.weakMapMemoize;
+};
+declare const windowManagerReducer: _reduxjs_toolkit.Reducer<WindowManagerState>;
+
+interface OverlayInstance {
+    isOpen: boolean;
+    data: unknown;
+    /** Unix ms of the last open (pruneStaleInstances reads it). */
+    lastUsedAt?: number;
+}
+interface OverlayState {
+    overlays: Record<string, Record<string, OverlayInstance>>;
+}
+/** The slice of any store these selectors need (absent until the summon runtime is installed). */
+type StateWithOverlays = {
+    overlays?: OverlayState;
+} | object;
+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 open instances of an overlay 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`). */
+declare function listOpenInstanceKeys(state: StateWithOverlays): string[];
+/** True once anything has ever been opened in this store (a key exists in the slice). */
+declare function selectAnyOverlayTouched(state: StateWithOverlays): boolean;
+/** The global hide-all flag (false before the runtime is installed). */
+declare const selectWindowsHidden: (state: object) => boolean;
+type WindowLike = WindowEntry;
+/** Every registered window, topmost first (empty before the runtime is installed). Memoized on the map. */
+declare function selectAllWindows<W extends WindowLike = WindowLike>(state: object): readonly W[];
+/** True when windows exist and every one is minimized (false before the runtime is installed). */
+declare function selectAllMinimized(state: object): boolean;
+
+/** What the core hands the gate when it loads. */
+interface SummonCore {
+    readonly reducers: Readonly<Record<string, Reducer>>;
+    createMiddleware(ports?: Partial<SummonPorts>): Middleware[];
+}
+/** Dispatched once after the slices are injected into a live store, so they hold their initial state. */
+declare const SUMMON_INSTALLED_ACTION = "@@summon/installed";
+/** Called by the core module when it evaluates (idempotent). */
+declare function installSummonCore(core: SummonCore): void;
+declare function isSummonInstalled(): boolean;
+declare function subscribeSummonInstalled(listener: () => void): () => void;
+/** Load the summon core (one import(), shared by every caller). Resolves once it is installed. */
+declare function ensureSummonRuntime(): Promise<void>;
+/** Start loading the core without waiting (idle, pointer intent). Errors surface on the next real request. */
+declare function prefetchSummonRuntime(): void;
+interface SummonGate {
+    /** Put this in the host store's middleware chain. */
+    readonly middleware: Middleware;
+    /**
+     * Give the gate the host root reducer's inject function — before `configureStore`, so a core
+     * that is already loaded (a page that imported the window section) is injected before the
+     * store's first state exists.
+     */
+    attachReducer(inject: (reducers: Readonly<Record<string, Reducer>>) => void): void;
+}
+interface CreateSummonGateOptions {
+    /** Ports for the summon middleware (render watchdog: notify, errors, debug). */
+    readonly ports?: Partial<SummonPorts>;
+}
+declare function createSummonGate(options?: CreateSummonGateOptions): SummonGate;
+
+export { allOverlayMeta as $, type AnyOverlayMeta as A, type StoredValue as B, type CloseOverlaysBoundToPagePayload as C, DEFAULT_INSTANCE_ID as D, type ErrorSinkPort as E, TRAY_CHIP_W as F, type GlobalLayoutType as G, type HydratedWindowSession as H, type InstanceKey as I, type ToggleOverlayPayload as J, type KeepAlive as K, type LinkHydrateContext as L, type MobilePresentation as M, type NotifyOptions as N, type OverlayState as O, type PruneStaleInstancesPayload as P, type Unsubscribe as Q, type RawOpenPayload as R, type SummonPorts as S, TRAY_CHIP_H as T, type UnbiddenHomeRoute as U, WINDOW_SESSION_SCHEMA_VERSION as V, type WindowManagerState as W, type WindowPersistenceRegistration as X, type WindowPersistenceState as Y, type WindowPreservation as Z, type WindowState as _, type StateWithOverlays as a, selectIsPoppedOut as a$, anonymousIdentity as a0, arrangeActiveWindows as a1, buildDockWindowPayload as a2, clampAllWindowRects as a3, clampWindowRect as a4, clearWindowPersistenceState as a5, closeAllInstancesOfOverlay as a6, closeOverlay as a7, closeOverlaysBoundToPage as a8, computeGlobalArrangement as a9, listOpenInstanceKeys as aA, locationRouter as aB, markWindowClosing as aC, maximizeWindow as aD, minimizeAll as aE, minimizeWindow as aF, moveTraySlot as aG, openOverlay as aH, overlayIdsBoundToPage as aI, parseInstanceKey as aJ, popOutWindow as aK, raiseTransientWindow as aL, recomputeTrayPositions as aM, registerOverlayMeta as aN, registerWindow as aO, releaseTransientWindow as aP, resetOverlayRegistry as aQ, resolvePorts as aR, restoreAll as aS, restoreWindow as aT, restoreWindowState as aU, revealWindow as aV, selectActivePipWindowId as aW, selectAllMinimized$1 as aX, selectAllWindows$1 as aY, selectDockedWindows as aZ, selectIsOverlayOpen as a_, confirmWindowRestored as aa, consoleErrorSink as ab, consoleNotify as ac, debugOff as ad, defaultWindowIdFor as ae, discardPendingWindowSession as af, dockWindow as ag, focusWindow as ah, getGrid12Rect as ai, getGrid4Rect as aj, getGrid6Rect as ak, getGrid8Rect as al, getGrid9Rect as am, getOverlayMeta as an, getOverlayMetaByLinkKey as ao, getStackedLeft2Rect as ap, getStackedLeft3Rect as aq, getStackedLeft4Rect as ar, getStackedLeft5Rect as as, getStackedRight2Rect as at, getStackedRight3Rect as au, getStackedRight4Rect as av, getStackedRight5Rect as aw, hydrateWindowSessions as ax, instanceKey as ay, isRegisteredOverlay as az, type WindowEntry as b, selectOpenInstances as b0, selectOverlay as b1, selectOverlayData as b2, selectPendingWindowRestores as b3, selectPopoutCandidateId as b4, selectPopoutMode as b5, selectPrePopoutRect as b6, selectTransientZIndex as b7, selectTraySlotWidth as b8, selectTrayWindows as b9, createSummonGate as bA, ensureSummonRuntime as bB, focusWindow$1 as bC, installSummonCore as bD, isSummonAction as bE, isSummonInstalled as bF, minimizeAll$1 as bG, prefetchSummonRuntime as bH, pruneStaleInstances as bI, registerSyncEntry as bJ, restoreAll$1 as bK, restoreWindow$1 as bL, selectAllMinimized as bM, selectAllWindows as bN, selectAnyOverlayTouched as bO, selectWindowsHidden as bP, subscribeSummonInstalled as bQ, toggleWindowsHidden$1 as bR, unregisterSyncEntry as bS, selectWindow as ba, selectWindowPersistence as bb, selectWindowRect as bc, selectWindowState as bd, selectWindowTitle as be, selectWindowZIndex as bf, selectWindowsHidden$1 as bg, setPopoutCandidate as bh, subscribeToOverlayRegistry as bi, toggleOverlay as bj, toggleWindowsHidden as bk, unregisterWindow as bl, updateWindowPersistence as bm, updateWindowRect as bn, updateWindowTitle as bo, windowManagerReducer as bp, windowSessionKey as bq, type ArrangeActiveWindowsPayload as br, type CreateSummonGateOptions as bs, SUMMON_INSTALLED_ACTION as bt, SUMMON_SLICE_KEYS as bu, type SummonAction as bv, type SummonGate as bw, type UrlSyncEntryPayload as bx, arrangeActiveWindows$1 as by, closeAllOverlays as bz, type WindowRect as c, type OverlayDefinitionMeta as d, type SummonCore as e, type CloseAllInstancesPayload as f, type CloseOverlayPayload as g, DEFAULT_PORTS as h, type DebugPort as i, type DockWindowPayload as j, type IdentityPort as k, type InstanceMode as l, type NotifyPort as m, type OpenInstanceView as n, type OpenOverlayPayload as o, type OverlayDataOf as p, type OverlayHostDispatch as q, type OverlayId as r, type OverlayInstance as s, type OverlayLinkSpec as t, type OverlayPersistencePort as u, type OverlayRawData as v, type OverlayWindowOptions as w, type PersistedWindowSession as x, type PopoutMode as y, type RouterPort as z };