@ai-matrx/canvas 0.1.0 → 0.2.0

package/dist/react.d.ts

@@ -1,283 +1,48 @@
 import * as react from 'react';
-import { ComponentType, ReactNode, CSSProperties } from 'react';
+import { ComponentType, ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, ReactElement } from 'react';
+import { D as CanvasRect, d as CanvasPaneId, C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, i as CanvasItem, h as CanvasController, G as CanvasSessionEvent, E as CanvasSessionAttachReason, F as CanvasSessionDetachReason, e as CanvasStoreBinding, B as CanvasPersistencePort, v as CanvasErrorSink, x as CanvasLayoutRules, f as CanvasState } from './controller-Dv6J6XZm.js';
 
-/**
- * @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;
-/** `${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;
-};
-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;
+/** One floating thing. Plain data, so a host can draw it in another process. */
+type CanvasFloating = {
+    readonly type: "tooltip";
+    readonly text: string;
+    readonly anchor: CanvasRect;
+    readonly side: "top" | "bottom";
 } | {
-    readonly type: "split";
-    readonly id: CanvasSplitId;
-    readonly orientation: CanvasOrientation;
-    readonly children: readonly CanvasLayoutNode[];
-    /** Fractions, one per child, summing to 1. */
-    readonly sizes: readonly number[];
-};
-interface CanvasState {
-    readonly version: 1;
-    readonly isOpen: boolean;
-    readonly isFullscreen: boolean;
-    /** Column width in CSS pixels (desktop). */
-    readonly width: number;
-    readonly layout: CanvasLayoutNode;
-    readonly panes: {
-        readonly [paneId: string]: CanvasPane;
-    };
-    readonly items: {
-        readonly [itemId: string]: CanvasItem;
-    };
-    readonly focusedPaneId: CanvasPaneId;
-    /** 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 type: "drop-indicator";
+    readonly rect: CanvasRect;
     readonly paneId: CanvasPaneId;
+} | {
+    readonly type: "tab-drag";
+    readonly itemId: CanvasItemId;
+    readonly title: string;
 };
-interface CanvasOpenInput {
-    readonly kind: string;
-    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;
+interface CanvasOverlayPort {
+    /** Shows a floating element above everything (native views included); returns its remover. */
+    show(element: CanvasFloating): () => void;
 }
-
-/**
- * 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`) or runs inside the package's own standalone
- * store with 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.
- */
-
-declare const P = "matrxCanvas/";
-type CanvasAction = {
-    type: `${typeof P}open`;
-    payload: CanvasOpenInput & {
-        now: number;
-    };
-} | {
-    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;
-    };
-} | {
-    type: `${typeof P}closePane`;
-    payload: {
-        paneId: CanvasPaneId;
-    };
-} | {
-    type: `${typeof P}resizeSplit`;
-    payload: {
-        splitId: CanvasSplitId;
-        sizes: readonly number[];
-    };
-} | {
-    type: `${typeof P}setOpen`;
-    payload: {
-        open: boolean;
-    };
-} | {
-    type: `${typeof P}toggle`;
-} | {
-    type: `${typeof P}setFullscreen`;
-    payload: {
-        fullscreen: boolean;
-    };
-} | {
-    type: `${typeof P}setWidth`;
-    payload: {
-        width: number;
-    };
-} | {
-    type: `${typeof P}hydrate`;
-    payload: {
-        snapshot: CanvasState | null;
-    };
+/** A serializable "…" menu: the package keeps the handlers, a host draws the entries. */
+type CanvasMenuEntry = {
+    readonly type: "item";
+    readonly id: string;
+    readonly label: string;
+    readonly destructive?: boolean;
 } | {
-    type: `${typeof P}reset`;
+    readonly type: "separator";
 };
-
-/**
- * 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;
+/** Shows a menu at `anchor` (e.g. Electron `Menu.popup`); resolves the chosen entry id, or null. */
+type CanvasShowMenu = (entries: readonly CanvasMenuEntry[], anchor: CanvasRect) => Promise<string | null>;
+/** A native body's frame: window CSS pixels plus the device pixel ratio. */
+interface CanvasNativeRect extends CanvasRect {
+    readonly devicePixelRatio: number;
 }
-
-/**
- * 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>;
-}
-
-/**
- * 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.
- *
- * Nothing fails silently: a refused open (non-JSON data, unknown kind) is
- * reported through the error sink and returns false.
- */
-
-interface CanvasErrorReport {
-    readonly code: "non-json-data" | "unknown-kind" | "persistence-load" | "persistence-save";
-    readonly message: string;
-    readonly detail?: unknown;
-}
-type CanvasErrorSink = (report: CanvasErrorReport) => void;
-interface CanvasController {
-    readonly store: CanvasStoreBinding;
-    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;
-    splitPane(paneId: CanvasPaneId, orientation: CanvasOrientation, moveItemId?: CanvasItemId): void;
-    closePane(paneId: CanvasPaneId): void;
-    resizeSplit(splitId: CanvasSplitId, sizes: readonly number[]): void;
-    show(): void;
-    hide(): void;
-    toggle(): void;
-    setFullscreen(fullscreen: boolean): void;
-    setWidth(width: number): void;
-    /** Is this exact thing on the canvas right now? */
-    has(kind: string, key: string): boolean;
-    /**
-     * Is a canvas column on screen? A store can exist in a layout that shows no
-     * column (a kiosk, a meeting stage); opening there must be refused aloud.
-     */
-    isPresented(): boolean;
-    /** Called by a column on mount; returns the unmount callback. */
-    registerPresentation(): () => void;
-    subscribePresentation(listener: () => void): () => void;
-    /** Loads the persisted snapshot and starts autosave. Returns a disposer. */
-    start(): () => void;
+interface CanvasNativeBodyInfo {
+    /** False while package DOM floats over the canvas (a DOM menu, a tab drag): hide the native view. */
+    readonly visible: boolean;
+    readonly windowId: CanvasWindowId;
 }
+/** Reports where a native body sits; null when it is hidden or gone. Called in the frame the layout changed. */
+type CanvasNativeBodyFrame = (itemId: CanvasItemId, rect: CanvasNativeRect | null, info: CanvasNativeBodyInfo) => void;
 
 /**
  * THE canvas kind registry. A kind is one sort of thing the canvas can show —
@@ -301,7 +66,9 @@ interface CanvasKindProps<TData extends CanvasJson = CanvasJson> {
     readonly data: TData;
     readonly paneId: CanvasPaneId;
     readonly isFocused: boolean;
+    /** The canvas, acting for the window this pane is in. */
     readonly canvas: CanvasController;
+    readonly windowId: CanvasWindowId;
 }
 interface CanvasMenuItem {
     readonly id: string;
@@ -317,7 +84,7 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     readonly icon: ComponentType<{
         className?: string;
     }>;
-    /** Eager component. Provide this OR `load`. */
+    /** Eager component. Provide this OR `load` (optional for a native body or an `unavailable` placeholder). */
     readonly component?: ComponentType<CanvasKindProps<TData>>;
     /** Lazy component — the kind's code loads only when a tab of it renders. */
     readonly load?: () => Promise<{
@@ -325,16 +92,45 @@ interface CanvasKind<TData extends CanvasJson = CanvasJson> {
     }>;
     /** Tab title from the item's data. Falls back to the item's title, then `label`. */
     readonly title?: (data: TData, item: CanvasItem) => string;
-    /** Comes back after a reload. Default true; false for live sessions that cannot resume. */
-    readonly restore?: boolean;
+    /**
+     * Comes back after a reload. Default true; false for live things that cannot
+     * resume. "session": the tab is a view onto a process the HOST keeps (a
+     * terminal) — it comes back, closing it DETACHES (onDetach) instead of
+     * killing, and a restore or a move REATTACHES (onAttach).
+     */
+    readonly restore?: boolean | "session";
+    /** restore "session": the session's key. Default: `data.sessionKey` when it is a string. */
+    readonly sessionKey?: (data: TData, item: CanvasItem) => string | null;
+    /** restore "session": the tab now shows this session ("open" | "restore" | "arrive"). */
+    readonly onAttach?: (event: CanvasSessionEvent<CanvasSessionAttachReason>) => void;
+    /** restore "session": the tab no longer shows it ("close" | "leave" | "unmount"). Never kill the process here. */
+    readonly onDetach?: (event: CanvasSessionEvent<CanvasSessionDetachReason>) => void;
     /** Stays mounted while its tab is in the background (live chat, a running tool). */
     readonly keepAlive?: boolean;
+    /**
+     * "native": the body is drawn by the HOST outside the DOM (an Electron
+     * WebContentsView). The pane renders a placeholder and reports its rect
+     * through the provider's `onNativeBodyFrame`. Default "dom".
+     */
+    readonly body?: "dom" | "native";
+    /**
+     * An honest one-line state instead of the body while its backend is not
+     * there ("Files · next release", "No changes to show"). Return null to show
+     * the body. Read on every render.
+     */
+    readonly unavailable?: (data: TData, item: CanvasItem) => string | null;
     /** When set, the kind is offered in an empty pane's launcher. */
     readonly launcher?: {
         readonly key: string;
         readonly data: TData;
         readonly title?: string;
     };
+    /**
+     * Controls at the START of the pane header, after the title or tabs: a
+     * "+ new terminal", a browser's back / forward / reload / address bar. The
+     * slot grows to fill the header.
+     */
+    readonly HeaderLeading?: ComponentType<CanvasKindProps<TData>>;
     /** The kind's own button, rendered left of the pane's "…" menu. */
     readonly HeaderAction?: ComponentType<CanvasKindProps<TData>>;
     /** Kind-specific entries for the pane's "…" menu. */
@@ -347,6 +143,8 @@ type AnyCanvasKind = CanvasKind<CanvasJson>;
  * the registry stores the erased form (the cast is the one registration seam).
  */
 declare function defineCanvasKind<TData extends CanvasJson>(kind: CanvasKind<TData>): AnyCanvasKind;
+/** The session key of an item of a session kind (`kind.sessionKey`, else `data.sessionKey`). */
+declare function canvasSessionKey(kind: AnyCanvasKind, item: CanvasItem): string | null;
 /** Registers (or replaces) a kind. Returns an unregister function. */
 declare function registerCanvasKind(kind: AnyCanvasKind): () => void;
 declare function registerCanvasKinds(kinds: readonly AnyCanvasKind[]): () => void;
@@ -354,33 +152,75 @@ declare function getCanvasKind(id: string): AnyCanvasKind | undefined;
 declare function listCanvasKinds(): AnyCanvasKind[];
 
 /**
- * Host capabilities that apply to EVERY kind — this is how saving, sharing and
- * history are "handled globally": the host answers them once, here, and every
- * item that qualifies gets the entries in its "…" menu.
+ * What the host answers ONCE for every kind. Saving, sharing and history are
+ * "handled globally" here; the window ports let a desktop host draw floating
+ * things and native bodies its own way. Every port has a working default.
  */
 interface CanvasHostPorts {
     /** Extra "…" menu entries for an item (share, save to cloud, version history…). */
-    readonly itemActions?: (item: CanvasItem, kind: AnyCanvasKind | undefined) => readonly CanvasMenuItem[];
-    /** Pops an item out into a floating window. Absent ⇒ no "Pop out" entry. */
-    readonly popOut?: (item: CanvasItem) => void;
+    readonly itemActions?: ((item: CanvasItem, kind: AnyCanvasKind | undefined) => readonly CanvasMenuItem[]) | undefined;
+    /**
+     * Opens a window that renders this canvas for the returned window id (web: a
+     * floating panel with <CanvasWindowScope>; desktop: a BrowserWindow with its
+     * own provider). The item then moves there. Absent ⇒ no "Pop out" entry, and
+     * `controller.popOut` is refused aloud.
+     */
+    readonly popOut?: ((item: CanvasItem) => Promise<{
+        readonly windowId: string;
+    } | null>) | undefined;
+    /** A tab docked back out of `fromWindowId`. Close that window once the state no longer lists it. */
+    readonly dockBack?: ((itemId: CanvasItemId, fromWindowId: CanvasWindowId) => void) | undefined;
+    /** Draws the "…" menu (Electron `Menu.popup`). Default: the package's DOM menu. */
+    readonly showMenu?: CanvasShowMenu | undefined;
+    /** Draws tooltips, drop indicators and tab drags above native views. Default: in the DOM. */
+    readonly overlay?: CanvasOverlayPort | undefined;
+    /** Where each native-body kind's view goes, reported in the frame the layout changed. */
+    readonly onNativeBodyFrame?: CanvasNativeBodyFrame | undefined;
 }
+type CanvasTabStripMode = "auto" | "always";
 interface CanvasProviderProps extends CanvasHostPorts {
     readonly children: ReactNode;
-    /** A Redux-bound store (bindCanvasToReduxStore). Omit for a standalone store. */
+    /** A Redux-bound store (bindCanvasToReduxStore), a remote one (createRemoteCanvasStore), or omit for a standalone store. */
     readonly store?: CanvasStoreBinding;
-    /** `null` turns memory off. Default: localStorage. */
+    /** `null` turns memory off. Default: localStorage. Ignored for a remote store (its owner saves). */
     readonly persistence?: CanvasPersistencePort | null;
     readonly onError?: CanvasErrorSink;
-    /** ⌘\ / Ctrl+\ toggles the canvas; Escape leaves full screen. Default true. */
+    /** Binds the shortcut table's web shortcuts (⌘\ toggles, Esc leaves expand…). Default true. */
     readonly hotkeys?: boolean;
+    /** The window this provider renders. Default: the main window. */
+    readonly windowId?: string;
+    /** Width and split numbers, read once. Default: CANVAS_WEB_LAYOUT_RULES. */
+    readonly layoutRules?: Partial<CanvasLayoutRules>;
+    /** Live width of the region the canvas shares with the content beside it (desktop: right of the sidebar). Default: the window. */
+    readonly regionWidth?: number | null;
+    /** "auto": a pane with one tab shows a title instead of a tab strip. Default "auto". */
+    readonly tabStrip?: CanvasTabStripMode;
 }
-declare function CanvasProvider({ children, store, persistence, onError, hotkeys, itemActions, popOut, }: CanvasProviderProps): react.JSX.Element;
-/** The controller: open, close, toggle, split… */
+declare function CanvasProvider({ children, store, persistence, onError, hotkeys, windowId: windowIdProp, layoutRules, regionWidth, tabStrip, ...hostPorts }: CanvasProviderProps): react.JSX.Element;
+/**
+ * Renders a subtree as ANOTHER window of the same canvas — the web host's
+ * pop-out panel: `<CanvasWindowScope windowId={id}><CanvasColumn placement="fill"/></CanvasWindowScope>`.
+ */
+declare function CanvasWindowScope({ windowId, children }: {
+    windowId: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/** The controller (acting for this window): open, close, toggle, split… */
 declare function useCanvas(): CanvasController;
 /** Same as useCanvas, but null outside a provider (for components that may render anywhere). */
 declare function useOptionalCanvas(): CanvasController | null;
+/** The window this subtree renders. */
+declare function useCanvasWindowId(): CanvasWindowId;
 declare function useCanvasHostPorts(): CanvasHostPorts;
-/** True when a canvas column is on screen in this tree — the ONE availability answer. */
+/**
+ * Native-body controls. `remeasure()` re-reports every native body's frame now —
+ * call it on each animation frame while the host animates its own layout (a
+ * sidebar collapsing moves the canvas without resizing it).
+ */
+declare function useCanvasNativeBodies(): {
+    readonly remeasure: () => void;
+};
+/** True when a canvas column is on screen for this window — the ONE availability answer. */
 declare function useCanvasIsPresented(): boolean;
 /** Subscribes to a slice of canvas state. The selector must return stable values. */
 declare function useCanvasState<T>(selector: (state: CanvasState) => T): T;
@@ -394,22 +234,24 @@ declare function useOptionalCanvasState<T>(selector: (state: CanvasState) => T,
 declare function useCanvasKinds(): readonly AnyCanvasKind[];
 declare function useCanvasKind(id: string): AnyCanvasKind | undefined;
 
-/** The column's rendered width in px: 0 when put away, null when full screen. */
+/** The column's rendered width in px for this window: 0 when put away, null when expanded. */
 declare function useCanvasColumnWidth(): number | null;
 interface CanvasColumnProps {
     readonly className?: string;
     readonly style?: CSSProperties;
     /** Called with the live width while the edge is dragged, then null — lets a host shell reflow in step. */
     readonly onLiveWidth?: (width: number | null) => void;
+    /** "docked": the right-edge column with a width handle. "fill": fills its container (a pop-out window). */
+    readonly placement?: "docked" | "fill";
 }
-declare function CanvasColumn({ className, style, onLiveWidth }: CanvasColumnProps): react.JSX.Element | null;
-/** THE one button that opens and puts away the canvas. */
+declare function CanvasColumn({ className, style, onLiveWidth, placement }: CanvasColumnProps): react.JSX.Element | null;
+/** THE one button that opens and puts away the canvas (this window's). */
 declare function CanvasToggle({ className }: {
     className?: string;
 }): react.JSX.Element;
 /**
  * For hosts without their own shell (a Vite app, an Electron window): the app
- * on the left, the canvas column on the right, full screen handled.
+ * on the left, the canvas column on the right, expand handled.
  */
 declare function CanvasFrame({ children, className }: {
     children: ReactNode;
@@ -421,4 +263,105 @@ declare function CanvasPaneView({ paneId }: {
     paneId: CanvasPaneId;
 }): react.JSX.Element | null;
 
-export { type AnyCanvasKind, CanvasColumn, type CanvasColumnProps, CanvasFrame, type CanvasHostPorts, type CanvasKind, type CanvasKindProps, type CanvasMenuItem, CanvasPaneView, CanvasProvider, type CanvasProviderProps, CanvasToggle, defineCanvasKind, getCanvasKind, itemTitle, listCanvasKinds, registerCanvasKind, registerCanvasKinds, useCanvas, useCanvasColumnWidth, useCanvasHostPorts, useCanvasIsPresented, useCanvasKind, useCanvasKinds, useCanvasState, useOptionalCanvas, useOptionalCanvasState };
+interface CanvasHeaderButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "title"> {
+    /** Accessible name and tooltip. */
+    readonly label: string;
+    /** Appended to the tooltip, e.g. "⌘\\". */
+    readonly shortcut?: string | null | undefined;
+    /** False draws the button dimmed and inert (a browser's Back with no history). Default true. */
+    readonly available?: boolean;
+    /** "sm" = a pane-header action (24px); "md" = a browser bar button (28px). */
+    readonly size?: "sm" | "md";
+    readonly pressed?: boolean;
+    readonly children: ReactNode;
+}
+/** The one icon button of the canvas chrome. */
+declare const CanvasHeaderButton: react.ForwardRefExoticComponent<CanvasHeaderButtonProps & react.RefAttributes<HTMLButtonElement>>;
+interface CanvasPanelProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    readonly panelId: string;
+    /** The header title (a single-tab pane, a panel with no tabs). */
+    readonly title: ReactNode;
+    /** Controls after the title or tabs: "+ new terminal", a browser's bar. Grows to fill the header. */
+    readonly leading?: ReactNode;
+    /** A custom start of the header instead of the title (a tab strip). `leading` still follows it. */
+    readonly header?: ReactNode;
+    /** Controls just before the "…" menu (a kind's own button). */
+    readonly actions?: ReactNode;
+    /** The "…" menu: the host renders its own menu around the trigger it receives. */
+    readonly renderMenu?: ((trigger: ReactElement) => ReactNode) | undefined;
+    readonly expanded?: boolean | undefined;
+    readonly onToggleExpand?: (() => void) | undefined;
+    readonly expandShortcut?: string | null | undefined;
+    /** Phones only: put the canvas away without closing anything. */
+    readonly onHide?: (() => void) | undefined;
+    readonly onClose?: (() => void) | undefined;
+    readonly closeLabel?: string | undefined;
+    readonly focused?: boolean | undefined;
+    /** Where the header's own body element goes (the pane body). */
+    readonly bodyProps?: HTMLAttributes<HTMLDivElement> | undefined;
+}
+/** The menu trigger every panel shares. */
+declare const CanvasMenuTrigger: react.ForwardRefExoticComponent<Omit<CanvasHeaderButtonProps, "children" | "label"> & {
+    label?: string;
+} & react.RefAttributes<HTMLButtonElement>>;
+/** The frame every canvas panel shares: header (title or tabs · leading · actions · … · expand · close) over a body. */
+declare const CanvasPanel: react.ForwardRefExoticComponent<CanvasPanelProps & react.RefAttributes<HTMLElement>>;
+/** The one-line honest state of a panel with nothing to show, or whose backend has not shipped. */
+declare function CanvasPanelEmpty({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): react.JSX.Element;
+interface CanvasTabProps extends Omit<HTMLAttributes<HTMLDivElement>, "title" | "onSelect"> {
+    readonly title: string;
+    readonly icon: ReactNode;
+    /** Small trailing state after the title, e.g. "exited". */
+    readonly note?: string | undefined;
+    readonly active: boolean;
+    readonly onSelect: () => void;
+    /** Absent ⇒ no close button. */
+    readonly onClose?: (() => void) | undefined;
+}
+/** One tab of a strip. */
+declare const CanvasTab: react.ForwardRefExoticComponent<CanvasTabProps & react.RefAttributes<HTMLDivElement>>;
+interface BrowserTab {
+    readonly id: string;
+    readonly title: string;
+    /** A favicon URL; a globe is drawn without one. */
+    readonly icon?: string | null | undefined;
+    /** A glyph instead of a favicon (a terminal tab draws its prompt icon). */
+    readonly glyph?: ReactNode;
+    /** Small trailing state after the title, e.g. "exited". */
+    readonly note?: string | undefined;
+}
+interface BrowserTabsProps {
+    readonly tabs: readonly BrowserTab[];
+    readonly activeId: string | null;
+    readonly onSelect: (id: string) => void;
+    readonly onClose: (id: string) => void;
+    /** Absent ⇒ no "+" button. */
+    readonly onNew?: (() => void) | undefined;
+    /** The "+" button's name (default "New tab"). */
+    readonly newLabel?: string;
+    /** The tab list's name (default "Tabs"). */
+    readonly label?: string;
+    readonly className?: string;
+}
+/** A tab strip for any panel with its own tabs: a browser's pages, a terminal's shells. */
+declare function BrowserTabs({ tabs, activeId, onSelect, onClose, onNew, newLabel, label, className }: BrowserTabsProps): react.JSX.Element;
+interface BrowserBarProps {
+    readonly url: string;
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+    readonly onBack: () => void;
+    readonly onForward: () => void;
+    readonly onReload: () => void;
+    /** Called with the typed address when the person presses Enter. */
+    readonly onNavigate: (address: string) => void;
+    /** Controls after the address (screenshot, open in your browser, more). */
+    readonly trailing?: ReactNode;
+    readonly className?: string;
+}
+/** A browser's back · forward · reload · address bar, for a kind's leading slot or its body. */
+declare function BrowserBar({ url, canGoBack, canGoForward, onBack, onForward, onReload, onNavigate, trailing, className }: BrowserBarProps): react.JSX.Element;
+
+export { type AnyCanvasKind, BrowserBar, type BrowserBarProps, type BrowserTab, BrowserTabs, type BrowserTabsProps, CanvasColumn, type CanvasColumnProps, type CanvasFloating, CanvasFrame, CanvasHeaderButton, type CanvasHeaderButtonProps, type CanvasHostPorts, type CanvasKind, type CanvasKindProps, type CanvasMenuEntry, type CanvasMenuItem, CanvasMenuTrigger, type CanvasNativeBodyFrame, type CanvasNativeBodyInfo, type CanvasNativeRect, type CanvasOverlayPort, CanvasPaneView, CanvasPanel, CanvasPanelEmpty, type CanvasPanelProps, CanvasProvider, type CanvasProviderProps, type CanvasShowMenu, CanvasTab, type CanvasTabProps, type CanvasTabStripMode, CanvasToggle, CanvasWindowScope, canvasSessionKey, defineCanvasKind, getCanvasKind, itemTitle, listCanvasKinds, registerCanvasKind, registerCanvasKinds, useCanvas, useCanvasColumnWidth, useCanvasHostPorts, useCanvasIsPresented, useCanvasKind, useCanvasKinds, useCanvasNativeBodies, useCanvasState, useCanvasWindowId, useOptionalCanvas, useOptionalCanvasState };