@ai-matrx/summon 0.1.10 → 0.1.12

package/dist/gate-CfjdNWP6.d.ts

@@ -1,397 +0,0 @@
-import { OverlayHostTypes, OverlayRegistry } from '@ai-matrx/summon';
-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 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>;
-};
-declare const openOverlay: Creator<[payload: OpenOverlayPayload<string>], RawOpenPayload>;
-declare const closeOverlay: Creator<[payload: CloseOverlayPayload<string>], {
-    overlayId: string;
-    instanceId?: never;
-} | {
-    overlayId: string;
-    instanceId: string;
-}>;
-declare const toggleOverlay: Creator<[payload: ToggleOverlayPayload<string>], RawOpenPayload>;
-declare const closeAllInstancesOfOverlay: Creator<[payload: CloseAllInstancesPayload<string>], {
-    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: Creator<[payload: string], string>;
-declare const restoreWindow: Creator<[payload: string], string>;
-declare const toggleWindowsHidden: Creator<[], undefined>;
-declare const restoreAll: Creator<[], undefined>;
-declare const minimizeAll: Creator<[payload: {
-    viewportWidth: number;
-    viewportHeight: number;
-}], {
-    viewportWidth: number;
-    viewportHeight: number;
-}>;
-/** 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 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;
-};
-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: {
-    windowManager?: {
-        windowsHidden: boolean;
-    };
-}) => 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 { locationRouter as $, type AnyOverlayMeta as A, closeOverlay as B, type CloseOverlaysBoundToPagePayload as C, DEFAULT_INSTANCE_ID as D, type ErrorSinkPort as E, closeOverlaysBoundToPage as F, consoleErrorSink as G, consoleNotify as H, type InstanceKey as I, debugOff 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, defaultWindowIdFor as Q, type RawOpenPayload as R, type SummonPorts as S, type ToggleOverlayPayload as T, type UnbiddenHomeRoute as U, getOverlayMeta as V, type WindowPreservation as W, getOverlayMetaByLinkKey as X, instanceKey as Y, isRegisteredOverlay as Z, listOpenInstanceKeys as _, type StateWithOverlays as a, openOverlay as a0, overlayIdsBoundToPage as a1, parseInstanceKey as a2, registerOverlayMeta as a3, resetOverlayRegistry as a4, resolvePorts as a5, selectIsOverlayOpen as a6, selectOpenInstances as a7, selectOverlay as a8, selectOverlayData as a9, subscribeToOverlayRegistry as aa, toggleOverlay as ab, type CreateSummonGateOptions as ac, SUMMON_INSTALLED_ACTION as ad, SUMMON_SLICE_KEYS as ae, type SummonAction as af, type SummonGate as ag, closeAllOverlays as ah, createSummonGate as ai, ensureSummonRuntime as aj, focusWindow as ak, installSummonCore as al, isSummonAction as am, isSummonInstalled as an, minimizeAll as ao, prefetchSummonRuntime as ap, pruneStaleInstances as aq, restoreAll as ar, restoreWindow as as, selectAnyOverlayTouched as at, selectWindowsHidden as au, subscribeSummonInstalled as av, toggleWindowsHidden as aw, type OverlayDefinitionMeta as b, type SummonCore as c, type CloseAllInstancesPayload as d, type CloseOverlayPayload as e, DEFAULT_PORTS as f, type DebugPort as g, type IdentityPort as h, type InstanceMode as i, type NotifyPort as j, type OpenInstanceView as k, type OpenOverlayPayload as l, type OverlayDataOf as m, type OverlayHostDispatch as n, type OverlayId as o, type OverlayInstance as p, type OverlayLinkSpec as q, type OverlayPersistencePort as r, type OverlayRawData as s, type OverlayWindowOptions as t, type RouterPort as u, type StoredValue as v, type Unsubscribe as w, allOverlayMeta as x, anonymousIdentity as y, closeAllInstancesOfOverlay as z };