@ai-matrx/canvas 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.1
+
+- Build core and React declarations together so branded pane IDs, stores and controllers retain one type identity across entries.
+- Add packed ESM and CommonJS consumer type checks joining both entry points.
+
+### Consumer action
+
+- Update to latest before adopting the npm package; no app API changes are required.
+
 ## 0.1.0
 
 - Publish the existing Canvas implementation as an independently installable package with dual ESM/CommonJS entries and packaged styles.

package/dist/controller-oY84BN2c.d.cts

@@ -0,0 +1,345 @@
+/**
+ * @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;
+} | {
+    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 paneId: CanvasPaneId;
+};
+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;
+}
+declare const CANVAS_MIN_WIDTH = 360;
+declare const CANVAS_DEFAULT_WIDTH = 640;
+declare const CANVAS_MIN_SPLIT_FRACTION = 0.12;
+
+/**
+ * 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;
+    };
+} | {
+    type: `${typeof P}reset`;
+};
+declare const canvasActions: {
+    readonly open: (input: CanvasOpenInput) => 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;
+    readonly splitPane: (paneId: CanvasPaneId, orientation: CanvasOrientation, moveItemId?: CanvasItemId) => CanvasAction;
+    readonly closePane: (paneId: CanvasPaneId) => CanvasAction;
+    readonly resizeSplit: (splitId: CanvasSplitId, sizes: readonly number[]) => CanvasAction;
+    readonly setOpen: (open: boolean) => CanvasAction;
+    readonly toggle: () => CanvasAction;
+    readonly setFullscreen: (fullscreen: boolean) => CanvasAction;
+    readonly setWidth: (width: number) => CanvasAction;
+    readonly hydrate: (snapshot: CanvasState | null) => CanvasAction;
+    readonly reset: () => CanvasAction;
+};
+declare function isCanvasAction(action: unknown): action is CanvasAction;
+declare function createInitialCanvasState(): 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.
+ */
+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;
+}
+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;
+/** Builds the snapshot that is actually written: only restorable items. */
+declare function toPersistableSnapshot(state: CanvasState, isRestorable: (kind: string) => boolean): CanvasState;
+
+/**
+ * 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;
+declare const consoleCanvasErrorSink: CanvasErrorSink;
+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;
+}
+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;
+}
+declare function createCanvasController(options: CanvasControllerOptions): CanvasController;
+
+export { createCanvasStore as A, createInitialCanvasState as B, type CanvasItemId as C, createLocalStorageCanvasPersistence as D, isCanvasAction as E, sanitizeCanvasSnapshot as F, toPersistableSnapshot as G, type ReduxStoreLike as R, type CanvasJson as a, type CanvasLayoutNode as b, type CanvasPaneId as c, type CanvasState as d, type CanvasItem as e, type CanvasPane as f, CANVAS_DEFAULT_WIDTH as g, CANVAS_MIN_SPLIT_FRACTION as h, CANVAS_MIN_WIDTH as i, CANVAS_STORAGE_KEY as j, type CanvasAction as k, type CanvasController as l, type CanvasControllerOptions as m, type CanvasErrorReport as n, type CanvasErrorSink as o, type CanvasOpenInput as p, type CanvasOpenTarget as q, type CanvasOrientation as r, type CanvasPersistencePort as s, type CanvasSplitId as t, type CanvasStoreBinding as u, bindCanvasToReduxStore as v, canvasActions as w, canvasReducer as x, consoleCanvasErrorSink as y, createCanvasController as z };