@ai-matrx/canvas 0.1.1 → 0.2.0

package/dist/controller-Dv6J6XZm.d.ts

@@ -0,0 +1,576 @@
+/**
+ * @ai-matrx/canvas — core types.
+ *
+ * The canvas is ONE docked column on the right edge of an application. It holds
+ * panes; panes hold tabs; every tab is one CanvasItem. A CanvasItem is
+ * identified by `kind` + `key`, so opening the same thing twice always lands on
+ * the existing tab instead of creating a duplicate.
+ *
+ * Everything in CanvasState is plain JSON: it lives in the host's Redux store
+ * (or the package's own standalone store), it is persisted between sessions,
+ * and it can be inspected. No functions, no class instances, no React nodes.
+ */
+/** Any value that survives JSON.stringify → JSON.parse unchanged. */
+type CanvasJson = string | number | boolean | null | readonly CanvasJson[] | {
+    readonly [key: string]: CanvasJson | undefined;
+};
+declare const itemIdBrand: unique symbol;
+declare const paneIdBrand: unique symbol;
+declare const splitIdBrand: unique symbol;
+declare const windowIdBrand: unique symbol;
+/** `${kind}::${key}` — the identity of one thing on the canvas. */
+type CanvasItemId = string & {
+    readonly [itemIdBrand]: true;
+};
+type CanvasPaneId = string & {
+    readonly [paneIdBrand]: true;
+};
+type CanvasSplitId = string & {
+    readonly [splitIdBrand]: true;
+};
+/**
+ * One application window that renders a canvas. Single-window hosts only ever
+ * see `CANVAS_MAIN_WINDOW`; a desktop host with one store in its main process
+ * gives every other window (a second app window, a popped-out tab) its own id.
+ */
+type CanvasWindowId = string & {
+    readonly [windowIdBrand]: true;
+};
+declare const CANVAS_MAIN_WINDOW: CanvasWindowId;
+interface CanvasItem {
+    readonly id: CanvasItemId;
+    /** Registered kind id (see `registerCanvasKind`). */
+    readonly kind: string;
+    /** Stable key inside the kind — an artifact id, a conversation id, "default". */
+    readonly key: string;
+    /** Explicit tab title. `null` ⇒ the kind's `title(data)` or its label. */
+    readonly title: string | null;
+    readonly data: CanvasJson;
+    readonly openedAt: number;
+    readonly updatedAt: number;
+}
+interface CanvasPane {
+    readonly id: CanvasPaneId;
+    readonly itemIds: readonly CanvasItemId[];
+    readonly activeItemId: CanvasItemId | null;
+}
+/** "horizontal" = children side by side; "vertical" = children stacked. */
+type CanvasOrientation = "horizontal" | "vertical";
+type CanvasLayoutNode = {
+    readonly type: "pane";
+    readonly paneId: CanvasPaneId;
+} | {
+    readonly type: "split";
+    readonly id: CanvasSplitId;
+    readonly orientation: CanvasOrientation;
+    readonly children: readonly CanvasLayoutNode[];
+    /** Fractions, one per child, summing to 1. */
+    readonly sizes: readonly number[];
+};
+/**
+ * What one window shows: its column's visibility, full screen, width and its
+ * own tree of panes. Panes and items are shared across windows (ids are
+ * global), so moving a tab between windows is an ordinary move.
+ */
+interface CanvasWindowFrame {
+    readonly isOpen: boolean;
+    /**
+     * "Expanded": the column fills everything the HOST gives it (the web: the
+     * whole window; the desktop: everything right of the sidebar). One flag —
+     * the host's placement decides what "everything" is.
+     */
+    readonly isFullscreen: boolean;
+    /** Column width in CSS pixels; null until the person drags it — the host's layout rule decides. */
+    readonly width: number | null;
+    readonly layout: CanvasLayoutNode;
+    readonly focusedPaneId: CanvasPaneId;
+}
+/** A window other than the main one. */
+interface CanvasExtraWindow extends CanvasWindowFrame {
+    readonly id: CanvasWindowId;
+    /**
+     * "window": another app window with its own column.
+     * "pop-out": a window holding tabs popped out of `home`; "Dock back" returns them there.
+     */
+    readonly role: "window" | "pop-out";
+    /** Where this window's tabs go when it closes or a tab docks back. */
+    readonly home: CanvasWindowId;
+}
+/**
+ * The whole canvas. The top-level frame fields ARE the main window's frame, so
+ * a single-window host reads `state.isOpen`, `state.layout`… exactly as before;
+ * every other window lives in `windows`.
+ */
+interface CanvasState extends CanvasWindowFrame {
+    readonly version: 1;
+    /** Windows other than the main one. Empty for single-window hosts. Never restored after a reload. */
+    readonly windows: {
+        readonly [windowId: string]: CanvasExtraWindow;
+    };
+    readonly panes: {
+        readonly [paneId: string]: CanvasPane;
+    };
+    readonly items: {
+        readonly [itemId: string]: CanvasItem;
+    };
+    /** Monotonic counter for minting pane/split ids — keeps the reducer pure. */
+    readonly seq: number;
+    /** True once a persisted snapshot was applied (or there was none). */
+    readonly hydrated: boolean;
+}
+/** Where a newly opened item goes. Existing items never move on open. */
+type CanvasOpenTarget = "focused" | "split-right" | "split-down" | {
+    readonly paneId: CanvasPaneId;
+};
+interface CanvasOpenInput {
+    readonly kind: string;
+    /** Which window a NEW item opens in. Default: the controller's window (main). An existing item stays where it is. */
+    readonly windowId?: CanvasWindowId | undefined;
+    readonly key: string;
+    readonly title?: string | null | undefined;
+    readonly data?: CanvasJson | undefined;
+    readonly target?: CanvasOpenTarget | undefined;
+    /** Reveal the canvas when it is put away. Default true. */
+    readonly reveal?: boolean | undefined;
+    /** Make the item the pane's active tab. Default true. */
+    readonly activate?: boolean | undefined;
+}
+declare const CANVAS_MIN_WIDTH = 360;
+declare const CANVAS_DEFAULT_WIDTH = 640;
+declare const CANVAS_MIN_SPLIT_FRACTION = 0.12;
+/** A rectangle in window CSS pixels (getBoundingClientRect coordinates). */
+interface CanvasRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+
+/**
+ * THE canvas reducer. Plain Redux-compatible reducer + action creators with no
+ * Redux Toolkit dependency, so it mounts in a host's RTK store
+ * (`canvasHost: canvasReducer`), runs inside the package's own standalone
+ * store, or runs in a desktop main process behind IPC — identical behaviour.
+ *
+ * Identity law: an item is `kind::key`. Opening an item that is already on the
+ * canvas never duplicates it — it refreshes its data/title, activates its tab
+ * and focuses its pane, wherever that pane is (in whichever window).
+ *
+ * Windows: the top-level frame fields are the MAIN window's; every other window
+ * (a second app window, a popped-out tab) lives in `state.windows`. Panes and
+ * items are global, so a tab moves between windows like between panes.
+ */
+
+declare const P = "matrxCanvas/";
+/** What happens to a closing window's tabs: back to its home window, or closed with it. */
+type CanvasWindowCloseMode = "dock" | "close";
+type CanvasAction = {
+    type: `${typeof P}open`;
+    payload: CanvasOpenInput & {
+        now: number;
+        splitShare?: number | undefined;
+    };
+} | {
+    type: `${typeof P}update`;
+    payload: {
+        itemId: CanvasItemId;
+        data?: CanvasJson | undefined;
+        title?: string | null | undefined;
+        now: number;
+    };
+} | {
+    type: `${typeof P}rekey`;
+    payload: {
+        itemId: CanvasItemId;
+        key: string;
+    };
+} | {
+    type: `${typeof P}closeItem`;
+    payload: {
+        itemId: CanvasItemId;
+    };
+} | {
+    type: `${typeof P}closeOthers`;
+    payload: {
+        itemId: CanvasItemId;
+    };
+} | {
+    type: `${typeof P}activate`;
+    payload: {
+        itemId: CanvasItemId;
+    };
+} | {
+    type: `${typeof P}focusPane`;
+    payload: {
+        paneId: CanvasPaneId;
+    };
+} | {
+    type: `${typeof P}moveItem`;
+    payload: {
+        itemId: CanvasItemId;
+        toPaneId: CanvasPaneId;
+        index?: number | undefined;
+    };
+} | {
+    type: `${typeof P}splitPane`;
+    payload: {
+        paneId: CanvasPaneId;
+        orientation: CanvasOrientation;
+        moveItemId?: CanvasItemId | undefined;
+        share?: number | undefined;
+    };
+} | {
+    type: `${typeof P}closePane`;
+    payload: {
+        paneId: CanvasPaneId;
+    };
+} | {
+    type: `${typeof P}resizeSplit`;
+    payload: {
+        splitId: CanvasSplitId;
+        sizes: readonly number[];
+    };
+} | {
+    type: `${typeof P}setOpen`;
+    payload: {
+        open: boolean;
+        windowId?: CanvasWindowId | undefined;
+    };
+} | {
+    type: `${typeof P}toggle`;
+    payload?: {
+        windowId?: CanvasWindowId | undefined;
+    } | undefined;
+} | {
+    type: `${typeof P}setFullscreen`;
+    payload: {
+        fullscreen: boolean;
+        windowId?: CanvasWindowId | undefined;
+    };
+} | {
+    type: `${typeof P}setWidth`;
+    payload: {
+        width: number;
+        windowId?: CanvasWindowId | undefined;
+    };
+} | {
+    type: `${typeof P}popOut`;
+    payload: {
+        itemId: CanvasItemId;
+        windowId: CanvasWindowId;
+    };
+} | {
+    type: `${typeof P}dockBack`;
+    payload: {
+        itemId: CanvasItemId;
+    };
+} | {
+    type: `${typeof P}closeWindow`;
+    payload: {
+        windowId: CanvasWindowId;
+        mode: CanvasWindowCloseMode;
+    };
+} | {
+    type: `${typeof P}hydrate`;
+    payload: {
+        snapshot: CanvasState | null;
+    };
+} | {
+    type: `${typeof P}reset`;
+};
+declare const canvasActions: {
+    readonly open: (input: CanvasOpenInput, options?: {
+        splitShare?: number | undefined;
+    }) => CanvasAction;
+    readonly update: (itemId: CanvasItemId, patch: {
+        data?: CanvasJson | undefined;
+        title?: string | null | undefined;
+    }) => CanvasAction;
+    /** Gives an item a new identity in place (e.g. a draft that was just saved and now has an id). */
+    readonly rekey: (itemId: CanvasItemId, key: string) => CanvasAction;
+    readonly closeItem: (itemId: CanvasItemId) => CanvasAction;
+    readonly closeOthers: (itemId: CanvasItemId) => CanvasAction;
+    readonly activate: (itemId: CanvasItemId) => CanvasAction;
+    readonly focusPane: (paneId: CanvasPaneId) => CanvasAction;
+    readonly moveItem: (itemId: CanvasItemId, toPaneId: CanvasPaneId, index?: number) => CanvasAction;
+    /** `share` = the existing pane's fraction of the space (layout rules' stackSplit / sideSplit). */
+    readonly splitPane: (paneId: CanvasPaneId, orientation: CanvasOrientation, moveItemId?: CanvasItemId, share?: number) => CanvasAction;
+    readonly closePane: (paneId: CanvasPaneId) => CanvasAction;
+    readonly resizeSplit: (splitId: CanvasSplitId, sizes: readonly number[]) => CanvasAction;
+    readonly setOpen: (open: boolean, windowId?: CanvasWindowId) => CanvasAction;
+    readonly toggle: (windowId?: CanvasWindowId) => CanvasAction;
+    readonly setFullscreen: (fullscreen: boolean, windowId?: CanvasWindowId) => CanvasAction;
+    readonly setWidth: (width: number, windowId?: CanvasWindowId) => CanvasAction;
+    /** Moves a tab into its own pop-out window `windowId` (made by the host's popOut port). */
+    readonly popOut: (itemId: CanvasItemId, windowId: CanvasWindowId) => CanvasAction;
+    /** Returns a popped-out tab to the window it came from. */
+    readonly dockBack: (itemId: CanvasItemId) => CanvasAction;
+    /** A host window closed: its tabs dock home (default) or close with it. The main window never closes. */
+    readonly closeWindow: (windowId: CanvasWindowId, mode?: CanvasWindowCloseMode) => CanvasAction;
+    readonly hydrate: (snapshot: CanvasState | null) => CanvasAction;
+    readonly reset: () => CanvasAction;
+};
+declare function isCanvasAction(action: unknown): action is CanvasAction;
+declare function createInitialCanvasState(): CanvasState;
+/** Every window id, main first. */
+declare function listCanvasWindowIds(state: CanvasState): CanvasWindowId[];
+/** A window's frame, or null when that window does not exist. */
+declare function canvasWindowFrame(state: CanvasState, windowId?: CanvasWindowId): CanvasWindowFrame | null;
+/** The window whose layout holds this pane. */
+declare function canvasWindowOfPane(state: CanvasState, paneId: CanvasPaneId): CanvasWindowId | null;
+/** The window an item is in right now (null when it is not on the canvas). */
+declare function canvasWindowOfItem(state: CanvasState, itemId: CanvasItemId): CanvasWindowId | null;
+/**
+ * Every window but the main one is a session thing: its tabs come home to the
+ * main window's focused pane (nothing is lost) and the window goes away. Used
+ * for what is saved and for what is restored.
+ */
+declare function foldCanvasWindows(state: CanvasState): CanvasState;
+/**
+ * Validates a persisted snapshot. Anything malformed is dropped back to the
+ * initial state rather than half-applied — a corrupt layout must never crash
+ * the shell. Extra windows are folded home; full screen never comes back.
+ */
+declare function sanitizeCanvasSnapshot(raw: unknown): CanvasState | null;
+declare function canvasReducer(state: CanvasState | undefined, action: {
+    type: string;
+}): CanvasState;
+
+/**
+ * The store seam. The canvas never owns a second copy of its state: it reads
+ * and writes through a CanvasStoreBinding.
+ *
+ *  - A host WITH Redux mounts `canvasReducer` in its root reducer and binds it:
+ *      bindCanvasToReduxStore(store, (root) => root.canvasHost)
+ *  - A host WITHOUT Redux (a Vite tool, an Electron window) calls
+ *      createCanvasStore()
+ *    which runs the very same reducer in a tiny standalone store.
+ */
+
+interface CanvasStoreBinding {
+    getState(): CanvasState;
+    dispatch(action: CanvasAction): void;
+    subscribe(listener: () => void): () => void;
+    /**
+     * "remote": the state lives in another process (createRemoteCanvasStore) —
+     * that process hydrates and saves it, so a controller over this binding
+     * never does. Absent means "local".
+     */
+    readonly authority?: "local" | "remote";
+}
+declare function createCanvasStore(initial?: CanvasState): CanvasStoreBinding;
+/** The minimum of a Redux store the canvas needs. */
+interface ReduxStoreLike<TRoot> {
+    getState(): TRoot;
+    dispatch(action: CanvasAction): unknown;
+    subscribe(listener: () => void): () => void;
+}
+declare function bindCanvasToReduxStore<TRoot>(store: ReduxStoreLike<TRoot>, select: (root: TRoot) => CanvasState): CanvasStoreBinding;
+
+/**
+ * Remembering the canvas between sessions — a table stake, never optional.
+ *
+ * The default port writes to localStorage under a versioned key. Items whose
+ * kind opts out (`restore: false`, e.g. a live session that cannot come back)
+ * are dropped from the snapshot, and panes they leave empty are dropped too.
+ */
+
+interface CanvasPersistencePort {
+    load(): CanvasState | null | Promise<CanvasState | null>;
+    save(snapshot: CanvasState): void | Promise<void>;
+}
+declare const CANVAS_STORAGE_KEY = "ai-matrx.canvas.v1";
+declare function createLocalStorageCanvasPersistence(key?: string, storage?: Pick<Storage, "getItem" | "setItem"> | null): CanvasPersistencePort;
+/**
+ * Memory over any key-value store — an Electron main process's `state/kv`,
+ * electron-store, IndexedDB behind a promise, a test map. Values are written
+ * as plain JSON objects (not strings) so a structured store keeps them
+ * inspectable; a string-only store can wrap this with JSON.stringify.
+ */
+interface CanvasKeyValueStore {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void | Promise<void>;
+}
+declare function createKeyValueCanvasPersistence(kv: CanvasKeyValueStore, key?: string): CanvasPersistencePort;
+/**
+ * Builds the snapshot that is actually written: only restorable items, and
+ * every window but the main one folded home (other windows never come back).
+ */
+declare function toPersistableSnapshot(state: CanvasState, isRestorable: (kind: string) => boolean): CanvasState;
+
+/**
+ * Layout rules — the host-tunable numbers behind the column's width and how its
+ * panes share space. Pure functions, so a desktop main process can place native
+ * views with exactly the numbers the renderer draws with.
+ *
+ * The canvas always shrinks FIRST: while the window narrows, the centre keeps
+ * `centreMinWidth` and the canvas gives way down to `minWidth`; only then does
+ * the centre squeeze. Side-by-side panes narrower than `paneMinWidth` stack
+ * instead of squeezing.
+ */
+interface CanvasLayoutRules {
+    /** Width before the person drags the edge: CSS px, or a fraction of the region the canvas shares. */
+    readonly defaultWidth: number | {
+        readonly fraction: number;
+    };
+    /** The narrowest the canvas column gets on a desktop-sized window. */
+    readonly minWidth: number;
+    /** Room the content beside the canvas always keeps (the canvas shrinks first). */
+    readonly centreMinWidth: number;
+    /** The FIRST pane's share when a pane splits down (stacked). 0.7 = the 70/30 divider. */
+    readonly stackSplit: number;
+    /** The first pane's share when a pane splits right (side by side). */
+    readonly sideSplit: number;
+    /** Side-by-side panes that would be narrower than this render stacked. 0 = never. */
+    readonly paneMinWidth: number;
+}
+/** The web app's numbers (the defaults). */
+declare const CANVAS_WEB_LAYOUT_RULES: CanvasLayoutRules;
+/** The desktop app's numbers (Claude desktop's proportions). */
+declare const CANVAS_DESKTOP_LAYOUT_RULES: CanvasLayoutRules;
+/** Fills missing fields from the web defaults and repairs nonsense values. */
+declare function resolveCanvasLayoutRules(rules?: Partial<CanvasLayoutRules> | null): CanvasLayoutRules;
+/** The width before the person chose one. `region` is the space the canvas shares (0 = unknown). */
+declare function defaultCanvasWidth(rules: CanvasLayoutRules, region: number): number;
+/**
+ * The column's width right now: the stored width (or the rule's default),
+ * fitted so the centre keeps `centreMinWidth` and the canvas never goes under
+ * `minWidth`. A width remembered on a wide monitor never crushes a laptop.
+ */
+declare function fitCanvasWidth(stored: number | null, region: number, rules: CanvasLayoutRules): number;
+/** Clamp for a dragged width: the same bounds as fitting. */
+declare function clampDraggedCanvasWidth(next: number, region: number, rules: CanvasLayoutRules): number;
+/** Whether a side-by-side split this wide (px) with this many children renders stacked. */
+declare function shouldStackSplit(width: number, children: number, rules: CanvasLayoutRules): boolean;
+
+/**
+ * The canvas controller: the ONE imperative API every caller uses. It wraps a
+ * store binding, validates what callers hand it (so the reducer stays pure and
+ * trusting), and owns hydration, autosave, pop-outs and session lifecycles.
+ *
+ * A controller acts for ONE window by default (`controller.windowId`, main
+ * unless the host says otherwise); `forWindow(id)` gives the same canvas seen
+ * from another window. Nothing fails silently: a refused open, a pop-out the
+ * host cannot do, a throwing session hook — each is reported through the
+ * error sink.
+ */
+
+interface CanvasErrorReport {
+    readonly code: "non-json-data" | "unknown-kind" | "persistence-load" | "persistence-save" | "pop-out-unavailable" | "pop-out-refused" | "pop-out-failed" | "session-hook";
+    readonly message: string;
+    readonly detail?: unknown;
+}
+type CanvasErrorSink = (report: CanvasErrorReport) => void;
+declare const consoleCanvasErrorSink: CanvasErrorSink;
+/**
+ * The host's window abilities. Without `popOut` a pop-out is refused aloud and
+ * no "Pop out" entry is shown.
+ */
+interface CanvasWindowPorts {
+    /**
+     * Opens a window (web: a floating panel; desktop: a BrowserWindow) that will
+     * render the canvas for the returned window id, then the package moves the
+     * item there. Resolve null to refuse.
+     */
+    readonly popOut?: ((item: CanvasItem) => Promise<{
+        readonly windowId: string;
+    } | null>) | undefined;
+    /** Called after a tab docked back out of `fromWindowId` (close that window when the state no longer lists it). */
+    readonly dockBack?: ((itemId: CanvasItemId, fromWindowId: CanvasWindowId) => void) | undefined;
+}
+/** Why a session-backed item attached or detached. */
+type CanvasSessionAttachReason = "open" | "restore" | "arrive";
+type CanvasSessionDetachReason = "close" | "leave" | "unmount";
+interface CanvasSessionEvent<R extends string> {
+    readonly item: CanvasItem;
+    readonly sessionKey: string;
+    /** The window the item is in (attach) or was in (detach). */
+    readonly windowId: CanvasWindowId;
+    readonly reason: R;
+}
+/**
+ * A kind with `restore: "session"`: its tab is a view onto a process the host
+ * keeps (a terminal). Closing the tab DETACHES (the process lives on); a
+ * restore or a move REATTACHES. The package only calls these; the host owns the
+ * process side.
+ */
+interface CanvasSessionHooks {
+    readonly sessionKey: (item: CanvasItem) => string | null;
+    readonly onAttach?: ((event: CanvasSessionEvent<CanvasSessionAttachReason>) => void) | undefined;
+    readonly onDetach?: ((event: CanvasSessionEvent<CanvasSessionDetachReason>) => void) | undefined;
+}
+interface CanvasControllerOptions {
+    readonly store: CanvasStoreBinding;
+    readonly persistence?: CanvasPersistencePort | null | undefined;
+    /** Kinds that may not come back after a reload. Default: every kind restores. */
+    readonly isRestorable?: ((kind: string) => boolean) | undefined;
+    /** When given, opens of an unregistered kind are refused and reported. */
+    readonly isKnownKind?: ((kind: string) => boolean) | undefined;
+    readonly onError?: CanvasErrorSink | undefined;
+    readonly saveDelayMs?: number | undefined;
+    /**
+     * Whether a remembered "open" may be restored right now. A host returns
+     * false where an open canvas would take the whole screen (a phone).
+     */
+    readonly mayRestoreOpen?: (() => boolean) | undefined;
+    /** The window this controller acts for by default. Default: the main window. */
+    readonly windowId?: string | undefined;
+    /** Width and split numbers (see CANVAS_WEB_LAYOUT_RULES / CANVAS_DESKTOP_LAYOUT_RULES). */
+    readonly layoutRules?: Partial<CanvasLayoutRules> | undefined;
+    /** Read on every use, so a provider can hand in its latest ports. */
+    readonly windowPorts?: (() => CanvasWindowPorts) | undefined;
+    /** Session hooks for a kind, or undefined when the kind is not session-backed. */
+    readonly sessions?: ((kind: string) => CanvasSessionHooks | undefined) | undefined;
+}
+interface CanvasController {
+    readonly store: CanvasStoreBinding;
+    /** The window this controller acts for by default. */
+    readonly windowId: CanvasWindowId;
+    readonly rules: CanvasLayoutRules;
+    /** The same canvas, acting for another window. */
+    forWindow(windowId: string): CanvasController;
+    getState(): CanvasState;
+    open(input: CanvasOpenInput): CanvasItemId | null;
+    update(itemId: CanvasItemId, patch: {
+        data?: CanvasJson | undefined;
+        title?: string | null | undefined;
+    }): boolean;
+    /** Gives an item a new identity in place (a draft that was saved and now has a durable id). */
+    rekey(itemId: CanvasItemId, key: string): CanvasItemId | null;
+    close(itemId: CanvasItemId): void;
+    closeOthers(itemId: CanvasItemId): void;
+    activate(itemId: CanvasItemId): void;
+    focusPane(paneId: CanvasPaneId): void;
+    moveItem(itemId: CanvasItemId, toPaneId: CanvasPaneId, index?: number): void;
+    /** Splits with the layout rules' share (stackSplit for "vertical", sideSplit for "horizontal"). */
+    splitPane(paneId: CanvasPaneId, orientation: CanvasOrientation, moveItemId?: CanvasItemId): void;
+    closePane(paneId: CanvasPaneId): void;
+    resizeSplit(splitId: CanvasSplitId, sizes: readonly number[]): void;
+    show(windowId?: CanvasWindowId): void;
+    hide(windowId?: CanvasWindowId): void;
+    toggle(windowId?: CanvasWindowId): void;
+    setFullscreen(fullscreen: boolean, windowId?: CanvasWindowId): void;
+    setWidth(width: number, windowId?: CanvasWindowId): void;
+    /** Moves a tab into its own window through the host's popOut port. Refused aloud without one. */
+    popOut(itemId: CanvasItemId): Promise<CanvasWindowId | null>;
+    /** Returns a popped-out tab to the window it came from. False when it is not popped out. */
+    dockBack(itemId: CanvasItemId): boolean;
+    /** A host window closed: its tabs dock home (default) or close with it. */
+    closeWindow(windowId: CanvasWindowId, mode?: CanvasWindowCloseMode): void;
+    /** Is this exact thing on the canvas right now (in any window)? */
+    has(kind: string, key: string): boolean;
+    /**
+     * Is a canvas column on screen (in this window, or in `windowId`)? A store
+     * can exist in a layout that shows no column (a kiosk, a meeting stage);
+     * opening there must be refused aloud.
+     */
+    isPresented(windowId?: CanvasWindowId): boolean;
+    /** Called by a column on mount; returns the unmount callback. */
+    registerPresentation(windowId?: CanvasWindowId): () => void;
+    subscribePresentation(listener: () => void): () => void;
+    /** Loads the persisted snapshot, starts autosave and session tracking. Returns a disposer. */
+    start(): () => void;
+}
+declare function createCanvasController(options: CanvasControllerOptions): CanvasController;
+
+export { foldCanvasWindows as $, type CanvasOrientation as A, type CanvasPersistencePort as B, type CanvasItemId as C, type CanvasRect as D, type CanvasSessionAttachReason as E, type CanvasSessionDetachReason as F, type CanvasSessionEvent as G, type CanvasSessionHooks as H, type CanvasSplitId as I, type CanvasWindowCloseMode as J, type CanvasWindowFrame as K, type CanvasWindowPorts as L, bindCanvasToReduxStore as M, canvasActions as N, canvasReducer as O, canvasWindowFrame as P, canvasWindowOfPane as Q, type ReduxStoreLike as R, clampDraggedCanvasWidth as S, consoleCanvasErrorSink as T, createCanvasController as U, createCanvasStore as V, createInitialCanvasState as W, createKeyValueCanvasPersistence as X, createLocalStorageCanvasPersistence as Y, defaultCanvasWidth as Z, fitCanvasWidth as _, type CanvasWindowId as a, isCanvasAction as a0, listCanvasWindowIds as a1, resolveCanvasLayoutRules as a2, sanitizeCanvasSnapshot as a3, shouldStackSplit as a4, toPersistableSnapshot as a5, type CanvasJson as b, type CanvasLayoutNode as c, type CanvasPaneId as d, type CanvasStoreBinding as e, type CanvasState as f, type CanvasAction as g, type CanvasController as h, type CanvasItem as i, type CanvasExtraWindow as j, type CanvasPane as k, canvasWindowOfItem as l, CANVAS_DEFAULT_WIDTH as m, CANVAS_DESKTOP_LAYOUT_RULES as n, CANVAS_MAIN_WINDOW as o, CANVAS_MIN_SPLIT_FRACTION as p, CANVAS_MIN_WIDTH as q, CANVAS_STORAGE_KEY as r, CANVAS_WEB_LAYOUT_RULES as s, type CanvasControllerOptions as t, type CanvasErrorReport as u, type CanvasErrorSink as v, type CanvasKeyValueStore as w, type CanvasLayoutRules as x, type CanvasOpenInput as y, type CanvasOpenTarget as z };