pmx-canvas 0.1.22 → 0.1.24

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -24,6 +24,7 @@ export declare function resolveExtAppContainerDimensions(target: ExtAppHostDimen
     height: number;
 };
 export declare function shouldApplyExtAppSizeChange(height: unknown, isExpanded: boolean): height is number;
+export declare function resolveExtAppInlineFrameHeight(appHeight: number, hostHeight: number): number;
 export declare function ExtAppFrame({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;

package/dist/types/client/nodes/iframe-document-url.d.ts

@@ -0,0 +1,8 @@
+export declare function createIframeDocumentUrl(html: string, sandbox: string): Promise<string>;
+export declare function useIframeDocument(html: string, sandbox: string): {
+    attributes: {
+        src?: string;
+    };
+    ready: boolean;
+    key: string;
+};

package/dist/types/client/state/intent-bridge.d.ts

@@ -22,6 +22,10 @@ export declare function openWorkbenchFile(path: string): Promise<{
 }>;
 /** Fetch canvas state from server. */
 export declare function fetchCanvasState(): Promise<Record<string, unknown>>;
+export declare function saveCanvasTheme(theme: string): Promise<{
+    ok: boolean;
+    theme?: string;
+}>;
 /** Fetch available slash commands for prompt completion. */
 export declare function fetchSlashCommands(): Promise<Array<{
     name: string;

package/dist/types/client/types.d.ts

@@ -58,6 +58,7 @@ export declare const EXCALIDRAW_CREATE_VIEW_TOOL = "create_view";
 export declare function isExcalidrawNode(node: CanvasNodeState): boolean;
 export interface CanvasLayout {
     viewport: ViewportState;
+    theme?: 'dark' | 'light' | 'high-contrast';
     nodes: CanvasNodeState[];
     edges: CanvasEdge[];
     annotations?: CanvasAnnotation[];

package/dist/types/json-render/catalog.d.ts

@@ -287,8 +287,8 @@ export declare const allComponentDefinitions: {
         props: z.ZodObject<{
             text: z.ZodString;
             variant: z.ZodNullable<z.ZodEnum<{
-                default: "default";
                 error: "error";
+                default: "default";
                 success: "success";
                 secondary: "secondary";
                 destructive: "destructive";

package/dist/types/mcp/canvas-access.d.ts

@@ -1,4 +1,5 @@
 import { type CanvasLayout, type CanvasNodeState, type CanvasSnapshot, type PmxCanvas } from '../server/index.js';
+import type { PmxAxSource } from '../server/ax-state.js';
 type AddNodeInput = Parameters<PmxCanvas['addNode']>[0];
 type AddWebpageNodeInput = Parameters<PmxCanvas['addWebpageNode']>[0];
 type RefreshWebpageNodeResult = Awaited<ReturnType<PmxCanvas['refreshWebpageNode']>>;
@@ -20,6 +21,9 @@ type ArrangeLayout = Parameters<PmxCanvas['arrange']>[0];
 type FocusNodeResult = ReturnType<PmxCanvas['focusNode']>;
 type FitViewOptions = Parameters<PmxCanvas['fitView']>[0];
 type FitViewResult = ReturnType<PmxCanvas['fitView']>;
+type AxStateResult = ReturnType<PmxCanvas['getAxState']>;
+type AxContextResult = ReturnType<PmxCanvas['getAxContext']>;
+type SetAxFocusResult = ReturnType<PmxCanvas['setAxFocus']>;
 type SearchResult = ReturnType<PmxCanvas['search']>;
 type UndoRedoResult = Awaited<ReturnType<PmxCanvas['undo']>>;
 type HistoryResult = ReturnType<PmxCanvas['getHistory']>;
@@ -68,6 +72,11 @@ export interface CanvasAccess {
         noPan?: boolean;
     }): Promise<FocusNodeResult>;
     fitView(options?: FitViewOptions): Promise<FitViewResult>;
+    getAxState(): Promise<AxStateResult>;
+    getAxContext(): Promise<AxContextResult>;
+    setAxFocus(nodeIds: string[], options?: {
+        source?: PmxAxSource;
+    }): Promise<SetAxFocusResult>;
     clear(): Promise<void>;
     search(query: string): Promise<SearchResult>;
     undo(): Promise<UndoRedoResult>;

package/dist/types/server/ax-context.d.ts

@@ -0,0 +1,3 @@
+import { type PmxAxContext, type PmxAxPinnedContext } from './ax-state.js';
+export declare function buildCanvasAxPinnedContext(): PmxAxPinnedContext;
+export declare function buildCanvasAxContext(): PmxAxContext;

package/dist/types/server/ax-state.d.ts

@@ -0,0 +1,43 @@
+import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
+import type { AgentContextNode } from './agent-context.js';
+export type PmxAxSource = 'agent' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
+export interface PmxAxFocusState {
+    nodeIds: string[];
+    primaryNodeId: string | null;
+    updatedAt: string | null;
+    source: PmxAxSource | null;
+}
+export interface PmxAxState {
+    version: 1;
+    focus: PmxAxFocusState;
+}
+export interface PmxAxPinnedContext {
+    preamble: string;
+    nodeIds: string[];
+    count: number;
+    nodes: AgentContextNode[];
+}
+export interface PmxAxFocusContext extends PmxAxFocusState {
+    nodes: AgentContextNode[];
+}
+export interface PmxAxContext {
+    version: 1;
+    generatedAt: string;
+    surface: {
+        nodeCount: number;
+        edgeCount: number;
+    };
+    pinned: PmxAxPinnedContext;
+    focus: PmxAxFocusContext;
+}
+export declare function createEmptyAxFocusState(): PmxAxFocusState;
+export declare function createEmptyAxState(): PmxAxState;
+export declare function normalizeAxFocusState(input: unknown, validNodeIds?: Set<string>): PmxAxFocusState;
+export declare function normalizeAxState(input: unknown, validNodeIds?: Set<string>): PmxAxState;
+export declare function buildAxContext(input: {
+    layout: CanvasLayout;
+    pinned: PmxAxPinnedContext;
+    focus: PmxAxFocusState;
+    focusNodes: AgentContextNode[];
+}): PmxAxContext;
+export declare function nodeSetFromLayout(nodes: CanvasNodeState[]): Set<string>;

package/dist/types/server/canvas-db.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SQLite persistence layer for canvas state.
+ *
+ * Uses Bun's built-in `bun:sqlite` for zero-dependency, synchronous,
+ * WAL-mode persistence. Replaces the previous JSON file-based approach.
+ */
+import { Database } from 'bun:sqlite';
+import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, CanvasSnapshot, CanvasSnapshotListOptions, ViewportState } from './canvas-state.js';
+import { type PmxAxState } from './ax-state.js';
+export type CanvasTheme = 'dark' | 'light' | 'high-contrast';
+export declare function normalizeCanvasTheme(value: unknown, fallback?: CanvasTheme): CanvasTheme;
+export interface PersistedCanvasState {
+    version: number;
+    theme?: CanvasTheme;
+    viewport: ViewportState;
+    nodes: CanvasNodeState[];
+    edges: CanvasEdge[];
+    annotations?: CanvasAnnotation[];
+    contextPins: string[];
+    ax?: PmxAxState;
+}
+export declare function openCanvasDb(dbPath: string): Database;
+export declare function checkpointCanvasDb(db: Database): void;
+export declare function finalizeCanvasDbForClose(db: Database): void;
+export declare function saveStateToDB(db: Database, state: PersistedCanvasState): void;
+/** Check if the DB has been populated with canvas state at least once. */
+export declare function isDbPopulated(db: Database): boolean;
+export declare function loadStateFromDB(db: Database): PersistedCanvasState | null;
+export declare function saveSnapshotToDB(db: Database, snapshot: CanvasSnapshot, state: PersistedCanvasState): void;
+export declare function loadSnapshotFromDB(db: Database, idOrName: string): {
+    snapshot: CanvasSnapshot;
+    state: PersistedCanvasState;
+} | null;
+export declare function listSnapshotsFromDB(db: Database, options?: CanvasSnapshotListOptions): CanvasSnapshot[];
+export declare function deleteSnapshotFromDB(db: Database, id: string): boolean;
+export declare function writeBlobToDB(db: Database, sha256: string, jsonValue: string): number;
+export declare function readBlobFromDB(db: Database, sha256: string): string | null;
+export declare function hasBlobInDB(db: Database, sha256: string): boolean;

package/dist/types/server/canvas-state.d.ts

@@ -5,9 +5,12 @@
  * - Agent tools (Phase 3) can read/mutate canvas state
  * - Client syncs bidirectionally (SSE for server→client, POST for client→server)
  *
- * Persistence: canvas state auto-saves to `.pmx-canvas/state.json` in the
- * workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
+ * Persistence: canvas state auto-saves to `.pmx-canvas/canvas.db` (SQLite WAL mode)
+ * in the workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
+ * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
  */
+import { type PersistedCanvasState, type CanvasTheme } from './canvas-db.js';
+import { type PmxAxFocusState, type PmxAxSource, type PmxAxState } from './ax-state.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -17,14 +20,7 @@ export interface PersistedBlobRef {
     bytes: number;
     jsonBytes: number;
 }
-interface PersistedCanvasState {
-    version: number;
-    viewport: ViewportState;
-    nodes: CanvasNodeState[];
-    edges: CanvasEdge[];
-    annotations?: CanvasAnnotation[];
-    contextPins: string[];
-}
+export type { PersistedCanvasState } from './canvas-db.js';
 interface LoadFromDiskOptions {
     clearExisting?: boolean;
 }
@@ -106,6 +102,7 @@ export interface CanvasAnnotation {
 }
 export interface CanvasLayout {
     viewport: ViewportState;
+    theme: CanvasTheme;
     nodes: CanvasNodeState[];
     edges: CanvasEdge[];
     annotations: CanvasAnnotation[];
@@ -123,9 +120,9 @@ export interface CanvasNodeUpdate {
     collapsed?: boolean;
     dockPosition?: 'left' | 'right' | null;
 }
-export type CanvasChangeType = 'pins' | 'nodes';
+export type CanvasChangeType = 'pins' | 'nodes' | 'ax';
 export interface MutationRecordInfo {
-    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
     description: string;
     forward: () => void;
     inverse: () => void;
@@ -143,7 +140,9 @@ declare class CanvasStateManager {
     private edges;
     private annotations;
     private _viewport;
+    private _theme;
     private _contextPinnedNodeIds;
+    private _axState;
     private _workspaceRoot;
     private _changeListeners;
     /** Register a listener for state changes. Used by MCP server to emit resource notifications. */
@@ -158,6 +157,9 @@ declare class CanvasStateManager {
     /** Create a closure that runs with recording suppressed. */
     private suppressed;
     private recordMutation;
+    private currentNodeIdSet;
+    private normalizeAxForCurrentNodes;
+    private applyAxState;
     private applyResolvedGroupBounds;
     private getGroupSnapshot;
     private normalizeNode;
@@ -166,6 +168,7 @@ declare class CanvasStateManager {
     private recomputeParentGroupBounds;
     private compactGroupChildren;
     private _stateFilePath;
+    private _db;
     private _saveTimer;
     /** Set the workspace root to enable auto-persistence. */
     setWorkspaceRoot(workspaceRoot: string): void;
@@ -185,15 +188,22 @@ declare class CanvasStateManager {
      * No-op when the new layout already exists.
      */
     private migrateLegacyLayout;
+    /**
+     * One-time migration: import state.json + snapshot JSON files + blob files
+     * into the SQLite database. Renames originals to `.bak`.
+     */
+    private migrateJsonToSqlite;
     getWorkspaceRoot(): string;
     private emptyPersistedState;
-    /** Load canvas state from disk. Call once on server startup. */
+    /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
-    /** Debounced save — coalesces rapid mutations into a single disk write. */
+    /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;
-    /** Write current state to disk immediately. */
+    /** Write current state to SQLite immediately. */
     private saveToDisk;
+    /** Close the SQLite database cleanly. Call on server shutdown. */
+    close(): void;
     private get snapshotsDir();
     private applyPersistedState;
     private readResolvedSnapshot;
@@ -217,6 +227,8 @@ declare class CanvasStateManager {
     } | null;
     /** Delete a snapshot. */
     deleteSnapshot(id: string): boolean;
+    /** Remove all snapshots from the DB. Used by test teardown. */
+    clearAllSnapshots(): void;
     get viewport(): ViewportState;
     addNode(node: CanvasNodeState): void;
     addJsonRenderNode(node: CanvasNodeState): void;
@@ -240,7 +252,16 @@ declare class CanvasStateManager {
         skipped: number;
     };
     setViewport(v: Partial<ViewportState>): void;
+    get theme(): CanvasTheme;
+    setTheme(theme: CanvasTheme): CanvasTheme;
     get contextPinnedNodeIds(): Set<string>;
+    getAxState(): PmxAxState;
+    getAxFocus(): PmxAxFocusState;
+    setAxFocus(nodeIds: string[], options?: {
+        source?: PmxAxSource;
+        recordHistory?: boolean;
+    }): PmxAxFocusState;
+    clearAxFocus(): PmxAxFocusState;
     setContextPins(nodeIds: string[]): void;
     clearContextPins(): void;
     /** Move child nodes into a group. Sets data.parentGroup on children and data.children on the group. */
@@ -250,4 +271,3 @@ declare class CanvasStateManager {
     clear(): void;
 }
 export declare const canvasState: CanvasStateManager;
-export {};

package/dist/types/server/index.d.ts

@@ -1,5 +1,6 @@
 import { EventEmitter } from 'node:events';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
+import type { PmxAxContext, PmxAxFocusState, PmxAxSource, PmxAxState } from './ax-state.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
@@ -104,6 +105,11 @@ export declare class PmxCanvas extends EventEmitter {
         focused: string;
         panned: boolean;
     } | null;
+    getAxState(): PmxAxState;
+    getAxContext(): PmxAxContext;
+    setAxFocus(nodeIds: string[], options?: {
+        source?: PmxAxSource;
+    }): PmxAxFocusState;
     fitView(options?: {
         width?: number;
         height?: number;

package/dist/types/server/mutation-history.d.ts

@@ -12,7 +12,7 @@
  * - _replaying flag prevents undo/redo from recording new entries
  */
 import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
-export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
+export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
 export interface MutationEntry {
     id: string;
     timestamp: string;

package/docs/cli.md

@@ -112,6 +112,19 @@ pmx-canvas focus <node-id>            # Pan viewport to a node
 pmx-canvas focus <node-id> --no-pan   # Select/raise without panning
 ```
 
+## AX context
+
+AX commands expose the host-agnostic context contract used by adapters. Pins
+remain the explicit human-curated context set; AX focus is the current
+attention target and persists with canvas state and snapshots.
+
+```bash
+pmx-canvas ax status                  # Persisted AX state
+pmx-canvas ax context                 # Pinned + focused agent context
+pmx-canvas ax focus node-1 node-2      # Set AX focus
+pmx-canvas ax focus --clear           # Clear AX focus
+```
+
 ## WebView automation
 
 Drive a headless Bun.WebView (Chromium or WebKit) pointed at the workbench:

package/docs/http-api.md

@@ -93,6 +93,30 @@ curl -X POST http://localhost:4313/api/canvas/context-pins \
 curl http://localhost:4313/api/canvas/pinned-context
 ```
 
+## AX context and focus
+
+AX context is the host-agnostic agent-experience layer. It combines existing
+context pins with a persisted focus node set that adapters can inject into
+their native prompt/context hooks.
+
+```bash
+# Get persisted AX state
+curl http://localhost:4313/api/canvas/ax
+
+# Get agent-readable pinned + focused context
+curl http://localhost:4313/api/canvas/ax/context
+
+# Set AX focus
+curl -X POST http://localhost:4313/api/canvas/ax/focus \
+  -H "Content-Type: application/json" \
+  -d '{"nodeIds":["node-1"],"source":"api"}'
+
+# Patch AX focus through the state endpoint
+curl -X PATCH http://localhost:4313/api/canvas/ax \
+  -H "Content-Type: application/json" \
+  -d '{"focus":{"nodeIds":["node-1"],"source":"api"}}'
+```
+
 ## Diagrams (Excalidraw preset)
 
 ```bash

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **42 tools** + **8 core resources**,
+PMX Canvas ships an MCP stdio server with **45 tools** + **9 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
@@ -51,6 +51,8 @@ searchable and readable in pinned/spatial context.
 | `canvas_arrange` | Auto-arrange (grid/column/flow) |
 | `canvas_validate` | Validate collisions, containment, and missing edge endpoints |
 | `canvas_focus_node` | Pan viewport to a node; use CLI `focus --no-pan` when you only need to select/raise |
+| `canvas_get_ax` | Read the PMX AX state plus pinned/focused context |
+| `canvas_set_ax_focus` | Set the host-agnostic AX focus node set; adapters can pass a source such as `codex` |
 | `canvas_pin_nodes` | Pin nodes to include in agent context |
 | `canvas_clear` | Clear all nodes and edges |
 | `canvas_snapshot` | Save current canvas as a named snapshot |
@@ -80,6 +82,8 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 | Resource | Description |
 |----------|-------------|
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
+| `canvas://ax` | PMX AX state, currently including persisted focus |
+| `canvas://ax-context` | Agent-readable pinned and focused AX context |
 | `canvas://schema` | Running-server create schemas and json-render catalog metadata |
 | `canvas://layout` | Full canvas state (all nodes, edges, viewport) |
 | `canvas://summary` | Compact overview: counts, pinned titles, viewport |
@@ -93,13 +97,27 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 The MCP server emits `notifications/resources/updated` whenever canvas state
 changes:
 
-- Pin changes notify `canvas://pinned-context`
+- Pin changes notify `canvas://pinned-context`, `canvas://ax`, and `canvas://ax-context`
+- AX focus changes notify `canvas://ax` and `canvas://ax-context`
 - All mutations notify `canvas://layout`, `canvas://summary`,
   `canvas://spatial-context`, `canvas://history`, and `canvas://code-graph`
 
 This closes the human-to-agent loop: spatial curation in the browser becomes
 an immediate signal in the agent's context.
 
+## Codex App Adapter
+
+In the Codex app, PMX Canvas runs natively through the existing Codex surfaces:
+MCP for tools/resources and the in-app Browser for the live `/workbench` view.
+No separate PMX renderer is needed. Prefer MCP over the CLI for Codex-native
+operation; keep the CLI for fallback scripts and manual debugging.
+
+Use `canvas://ax-context` or `canvas_get_ax` to read pinned/focused context.
+When Codex-hosted steering sets the current attention target, call
+`canvas_set_ax_focus` with `source: "codex"` so the AX state records where the
+focus came from. The full workflow lives in
+`skills/pmx-canvas/references/codex-app-adapter.md`.
+
 ## Annotation Visibility
 
 Human-drawn canvas annotations are rendered as browser SVG ink. MCP resources