@pascal-app/mcp 0.2.0

package/dist/storage/sqlite-scene-store.js

@@ -0,0 +1,526 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { generateSlug, isValidSlug, sanitizeSlug } from './slug';
+import { openSqliteDatabase } from './sqlite-driver';
+import { SceneInvalidError, SceneNotFoundError, SceneTooLargeError, SceneVersionConflictError, } from './types';
+const DEFAULT_MAX_SCENE_BYTES = 10 * 1024 * 1024;
+const DEFAULT_LIST_LIMIT = 100;
+const MAX_NAME_LENGTH = 200;
+const MIN_NAME_LENGTH = 1;
+const GraphSchema = z.object({
+    nodes: z.record(z.string(), z.unknown()),
+    rootNodeIds: z.array(z.string()),
+    collections: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Resolves Pascal's local SQLite database path.
+ *
+ * Precedence:
+ * 1. `PASCAL_DB_PATH`
+ * 2. `PASCAL_DATA_DIR/pascal.db`
+ * 3. On Windows: `%APPDATA%/Pascal/data/pascal.db`
+ * 4. `$XDG_DATA_HOME/pascal/data/pascal.db`
+ * 5. `$HOME/.pascal/data/pascal.db`
+ */
+export function resolveDefaultDatabasePath(env = process.env) {
+    if (env.PASCAL_DB_PATH && env.PASCAL_DB_PATH.length > 0) {
+        return env.PASCAL_DB_PATH;
+    }
+    if (env.PASCAL_DATA_DIR && env.PASCAL_DATA_DIR.length > 0) {
+        return path.join(env.PASCAL_DATA_DIR, 'pascal.db');
+    }
+    if (process.platform === 'win32') {
+        const appData = env.APPDATA;
+        if (appData && appData.length > 0) {
+            return path.join(appData, 'Pascal', 'data', 'pascal.db');
+        }
+        return path.join(os.homedir(), '.pascal', 'data', 'pascal.db');
+    }
+    const xdg = env.XDG_DATA_HOME;
+    if (xdg && xdg.length > 0) {
+        return path.join(xdg, 'pascal', 'data', 'pascal.db');
+    }
+    return path.join(os.homedir(), '.pascal', 'data', 'pascal.db');
+}
+function resolveMaxSceneBytes(env, explicit) {
+    if (explicit !== undefined) {
+        if (!Number.isInteger(explicit) || explicit <= 0) {
+            throw new SceneInvalidError('maxSceneBytes must be a positive integer');
+        }
+        return explicit;
+    }
+    const raw = env?.PASCAL_MAX_SCENE_BYTES;
+    if (raw === undefined || raw === '')
+        return DEFAULT_MAX_SCENE_BYTES;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new SceneInvalidError('PASCAL_MAX_SCENE_BYTES must be a positive integer');
+    }
+    return parsed;
+}
+function rowToMeta(row) {
+    const editorUrl = editorUrlForScene(row.id);
+    return {
+        id: row.id,
+        name: row.name,
+        projectId: row.project_id,
+        ownerId: row.owner_id,
+        thumbnailUrl: row.thumbnail_url,
+        version: row.version,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        sizeBytes: row.size_bytes,
+        nodeCount: row.node_count,
+        editorUrl,
+        url: editorUrl,
+        published: true,
+        graphHash: hashGraphJson(row.graph_json),
+    };
+}
+function editorUrlForScene(id) {
+    return `/editor/${id}`;
+}
+function hashGraphJson(graphJson) {
+    return createHash('sha256').update(graphJson).digest('hex');
+}
+function rowToProjectStatus(row) {
+    const editorUrl = editorUrlForScene(row.id);
+    return {
+        id: row.id,
+        projectId: row.project_id ?? row.id,
+        name: row.name,
+        editorUrl,
+        url: editorUrl,
+        ownerId: row.owner_id,
+        thumbnailUrl: row.thumbnail_url,
+        publishedVersion: row.version,
+        latestVersion: row.version,
+        draftVersion: null,
+        browserVisibleVersion: row.version,
+        version: row.version,
+        isEmpty: row.node_count === 0,
+        sizeBytes: row.size_bytes,
+        nodeCount: row.node_count,
+        graphHash: hashGraphJson(row.graph_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function placeholderToProjectStatus(project) {
+    const editorUrl = editorUrlForScene(project.id);
+    return {
+        id: project.id,
+        projectId: project.id,
+        name: project.name,
+        editorUrl,
+        url: editorUrl,
+        ownerId: project.ownerId,
+        thumbnailUrl: project.thumbnailUrl,
+        publishedVersion: null,
+        latestVersion: null,
+        draftVersion: null,
+        browserVisibleVersion: null,
+        version: 0,
+        isEmpty: true,
+        sizeBytes: 0,
+        nodeCount: 0,
+        graphHash: null,
+        createdAt: project.createdAt,
+        updatedAt: project.updatedAt,
+    };
+}
+function assertValidName(name) {
+    if (typeof name !== 'string') {
+        throw new SceneInvalidError('Scene name must be a string');
+    }
+    const trimmed = name.trim();
+    if (trimmed.length < MIN_NAME_LENGTH || name.length > MAX_NAME_LENGTH) {
+        throw new SceneInvalidError(`Scene name must be ${MIN_NAME_LENGTH}-${MAX_NAME_LENGTH} characters (got ${name.length})`);
+    }
+}
+function serializeGraph(graph) {
+    return JSON.stringify(graph);
+}
+function parseGraph(raw, context) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new SceneInvalidError(`Failed to parse scene graph for ${context}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = GraphSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new SceneInvalidError(`Scene graph for ${context} has invalid shape: ${result.error}`);
+    }
+    const graph = result.data;
+    for (const [nodeId, node] of Object.entries(graph.nodes)) {
+        if (!node || typeof node !== 'object' || Array.isArray(node)) {
+            throw new SceneInvalidError(`Scene graph for ${context} has non-object node at "${nodeId}"`);
+        }
+        const typeField = node.type;
+        if (typeof typeField !== 'string' || typeField.length === 0) {
+            throw new SceneInvalidError(`Scene graph for ${context} has node "${nodeId}" missing a string "type"`);
+        }
+    }
+    return graph;
+}
+function asSceneRow(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    return value;
+}
+function rowToSceneEvent(row) {
+    return {
+        eventId: Number(row.event_id),
+        sceneId: row.scene_id,
+        version: Number(row.version),
+        kind: row.kind,
+        createdAt: row.created_at,
+        graph: parseGraph(row.graph_json, `${row.scene_id}@${row.version}`),
+    };
+}
+/**
+ * SQLite-backed implementation of `SceneStore`.
+ *
+ * Uses one local database file, WAL mode, and transaction-scoped version checks
+ * so a local editor and MCP process can safely share scenes on one machine.
+ */
+export class SqliteSceneStore {
+    backend = 'sqlite';
+    databasePath;
+    maxSceneBytes;
+    projectPlaceholders = new Map();
+    db = null;
+    dbPromise = null;
+    constructor(opts = {}) {
+        const env = opts.env ?? process.env;
+        this.databasePath = path.resolve(opts.databasePath ?? resolveDefaultDatabasePath(env));
+        this.maxSceneBytes = resolveMaxSceneBytes(env, opts.maxSceneBytes);
+    }
+    async createProject(opts) {
+        const db = await this.database();
+        assertValidName(opts.name);
+        const id = opts.id ? sanitizeSlug(opts.id) : this.generateUniqueId(db);
+        if (!isValidSlug(id)) {
+            throw new SceneInvalidError(`Invalid project id after sanitization: "${id}"`);
+        }
+        if (this.getRow(db, id)) {
+            throw new SceneInvalidError(`Project with id "${id}" already exists`);
+        }
+        const now = new Date().toISOString();
+        const project = {
+            id,
+            name: opts.name,
+            ownerId: opts.ownerId ?? null,
+            thumbnailUrl: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.projectPlaceholders.set(id, project);
+        return placeholderToProjectStatus(project);
+    }
+    async getProjectStatus(id) {
+        const db = await this.database();
+        const safeId = sanitizeSlug(id);
+        const row = this.getRow(db, safeId);
+        if (row)
+            return rowToProjectStatus(row);
+        const placeholder = this.projectPlaceholders.get(safeId);
+        return placeholder ? placeholderToProjectStatus(placeholder) : null;
+    }
+    async save(opts) {
+        return this.withWriteTransaction((db) => {
+            assertValidName(opts.name);
+            if (!opts.graph || typeof opts.graph !== 'object') {
+                throw new SceneInvalidError('graph is required');
+            }
+            const providedId = opts.id;
+            const id = providedId ? sanitizeSlug(providedId) : this.generateUniqueId(db);
+            if (!isValidSlug(id)) {
+                throw new SceneInvalidError(`Invalid scene id after sanitization: "${id}"`);
+            }
+            const existing = this.getRow(db, id);
+            const placeholder = this.projectPlaceholders.get(id);
+            if (existing && providedId !== undefined && opts.expectedVersion === undefined) {
+                throw new SceneInvalidError(`Scene with id "${id}" already exists. Pass a different id or provide expectedVersion to overwrite.`);
+            }
+            if (opts.expectedVersion !== undefined) {
+                const currentVersion = existing?.version ?? 0;
+                if (currentVersion !== opts.expectedVersion) {
+                    throw new SceneVersionConflictError(`Scene "${id}" version mismatch: expected ${opts.expectedVersion}, got ${currentVersion}`);
+                }
+            }
+            const graphJson = serializeGraph(opts.graph);
+            const sizeBytes = Buffer.byteLength(graphJson, 'utf8');
+            if (sizeBytes > this.maxSceneBytes) {
+                throw new SceneTooLargeError(`Scene "${id}" is ${sizeBytes} bytes, exceeds cap of ${this.maxSceneBytes} bytes`);
+            }
+            const now = new Date().toISOString();
+            const version = (existing?.version ?? 0) + 1;
+            const createdAt = existing?.created_at ?? placeholder?.createdAt ?? now;
+            const nodeCount = Object.keys(opts.graph.nodes ?? {}).length;
+            const projectId = opts.projectId ?? existing?.project_id ?? (placeholder ? id : null);
+            const ownerId = opts.ownerId ?? existing?.owner_id ?? placeholder?.ownerId ?? null;
+            const thumbnailUrl = opts.thumbnailUrl ?? existing?.thumbnail_url ?? placeholder?.thumbnailUrl ?? null;
+            if (existing) {
+                db.query(`UPDATE scenes
+             SET name = ?,
+                 project_id = ?,
+                 owner_id = ?,
+                 thumbnail_url = ?,
+                 version = ?,
+                 updated_at = ?,
+                 size_bytes = ?,
+                 node_count = ?,
+                 graph_json = ?
+           WHERE id = ?`).run(opts.name, projectId, ownerId, thumbnailUrl, version, now, sizeBytes, nodeCount, graphJson, id);
+            }
+            else {
+                db.query(`INSERT INTO scenes (
+             id, name, project_id, owner_id, thumbnail_url, version,
+             created_at, updated_at, size_bytes, node_count, graph_json
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, opts.name, projectId, ownerId, thumbnailUrl, version, createdAt, now, sizeBytes, nodeCount, graphJson);
+            }
+            db.query(`INSERT INTO scene_revisions (
+           scene_id, version, graph_json, author_kind, author_id, created_at
+         ) VALUES (?, ?, ?, ?, ?, ?)`).run(id, version, graphJson, 'mcp', ownerId, now);
+            this.projectPlaceholders.delete(id);
+            return {
+                id,
+                name: opts.name,
+                projectId,
+                ownerId,
+                thumbnailUrl,
+                version,
+                createdAt,
+                updatedAt: now,
+                sizeBytes,
+                nodeCount,
+                editorUrl: editorUrlForScene(id),
+                url: editorUrlForScene(id),
+                published: true,
+                graphHash: hashGraphJson(graphJson),
+            };
+        });
+    }
+    async load(id) {
+        const db = await this.database();
+        const row = this.getRow(db, sanitizeSlug(id));
+        if (!row)
+            return null;
+        return {
+            ...rowToMeta(row),
+            graph: parseGraph(row.graph_json, row.id),
+        };
+    }
+    async list(opts = {}) {
+        const clauses = [];
+        const bindings = [];
+        if (opts.projectId !== undefined) {
+            clauses.push('project_id = ?');
+            bindings.push(opts.projectId);
+        }
+        if (opts.ownerId !== undefined) {
+            clauses.push('owner_id = ?');
+            bindings.push(opts.ownerId);
+        }
+        const requestedLimit = opts.limit ?? DEFAULT_LIST_LIMIT;
+        const limit = Number.isInteger(requestedLimit) && requestedLimit >= 0 ? requestedLimit : 0;
+        bindings.push(limit);
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+        const db = await this.database();
+        const rows = db
+            .query(`SELECT id, name, project_id, owner_id, thumbnail_url, version,
+                created_at, updated_at, size_bytes, node_count, graph_json
+           FROM scenes
+           ${where}
+          ORDER BY updated_at DESC, id ASC
+          LIMIT ?`)
+            .all(...bindings);
+        return rows.map((row) => rowToMeta(row));
+    }
+    async delete(id, opts = {}) {
+        return this.withWriteTransaction((db) => {
+            const safeId = sanitizeSlug(id);
+            const existing = this.getRow(db, safeId);
+            if (!existing)
+                return false;
+            if (opts.expectedVersion !== undefined && existing.version !== opts.expectedVersion) {
+                throw new SceneVersionConflictError(`Scene "${safeId}" version mismatch: expected ${opts.expectedVersion}, got ${existing.version}`);
+            }
+            db.query('DELETE FROM scenes WHERE id = ?').run(safeId);
+            return true;
+        });
+    }
+    async rename(id, newName, opts = {}) {
+        return this.withWriteTransaction((db) => {
+            assertValidName(newName);
+            const safeId = sanitizeSlug(id);
+            const existing = this.getRow(db, safeId);
+            if (!existing) {
+                throw new SceneNotFoundError(`Scene "${safeId}" not found`);
+            }
+            if (opts.expectedVersion !== undefined && existing.version !== opts.expectedVersion) {
+                throw new SceneVersionConflictError(`Scene "${safeId}" version mismatch: expected ${opts.expectedVersion}, got ${existing.version}`);
+            }
+            const now = new Date().toISOString();
+            const nextVersion = existing.version + 1;
+            db.query('UPDATE scenes SET name = ?, version = ?, updated_at = ? WHERE id = ?').run(newName, nextVersion, now, safeId);
+            db.query(`INSERT INTO scene_revisions (
+             scene_id, version, graph_json, author_kind, author_id, created_at
+           ) VALUES (?, ?, ?, ?, ?, ?)`).run(safeId, nextVersion, existing.graph_json, 'mcp', existing.owner_id, now);
+            return {
+                ...rowToMeta(existing),
+                name: newName,
+                version: nextVersion,
+                updatedAt: now,
+            };
+        });
+    }
+    async appendSceneEvent(opts) {
+        return this.withWriteTransaction((db) => {
+            const safeId = sanitizeSlug(opts.sceneId);
+            const existing = this.getRow(db, safeId);
+            if (!existing) {
+                throw new SceneNotFoundError(`Scene "${safeId}" not found`);
+            }
+            const graphJson = serializeGraph(opts.graph);
+            const now = new Date().toISOString();
+            const result = db
+                .query(`INSERT INTO scene_events (
+             scene_id, version, kind, created_at, graph_json
+           ) VALUES (?, ?, ?, ?, ?)`)
+                .run(safeId, opts.version, opts.kind, now, graphJson);
+            return {
+                eventId: Number(result.lastInsertRowid),
+                sceneId: safeId,
+                version: opts.version,
+                kind: opts.kind,
+                createdAt: now,
+                graph: opts.graph,
+            };
+        });
+    }
+    async listSceneEvents(sceneId, opts = {}) {
+        const afterEventId = Math.max(0, opts.afterEventId ?? 0);
+        const requestedLimit = opts.limit ?? 100;
+        const limit = Number.isInteger(requestedLimit) && requestedLimit > 0 ? requestedLimit : 100;
+        const db = await this.database();
+        const rows = db
+            .query(`SELECT event_id, scene_id, version, kind, created_at, graph_json
+           FROM scene_events
+          WHERE scene_id = ?
+            AND event_id > ?
+          ORDER BY event_id ASC
+          LIMIT ?`)
+            .all(sanitizeSlug(sceneId), afterEventId, limit);
+        return rows.map((row) => rowToSceneEvent(row));
+    }
+    close() {
+        this.db?.close();
+        this.db = null;
+        this.dbPromise = null;
+    }
+    async database() {
+        if (this.db)
+            return this.db;
+        if (!this.dbPromise) {
+            this.dbPromise = (async () => {
+                mkdirSync(path.dirname(this.databasePath), { recursive: true });
+                const db = await openSqliteDatabase(this.databasePath);
+                db.exec('PRAGMA foreign_keys = ON');
+                db.exec('PRAGMA journal_mode = WAL');
+                db.exec('PRAGMA busy_timeout = 5000');
+                this.migrate(db);
+                this.db = db;
+                return db;
+            })();
+        }
+        return this.dbPromise;
+    }
+    migrate(db) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS scenes (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL CHECK (length(name) >= 1 AND length(name) <= 200),
+        project_id TEXT,
+        owner_id TEXT,
+        thumbnail_url TEXT,
+        version INTEGER NOT NULL CHECK (version >= 1),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        size_bytes INTEGER NOT NULL CHECK (size_bytes >= 0),
+        node_count INTEGER NOT NULL CHECK (node_count >= 0),
+        graph_json TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS scenes_project_updated_idx
+        ON scenes(project_id, updated_at DESC);
+
+      CREATE INDEX IF NOT EXISTS scenes_owner_updated_idx
+        ON scenes(owner_id, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS scene_revisions (
+        scene_id TEXT NOT NULL,
+        version INTEGER NOT NULL CHECK (version >= 1),
+        graph_json TEXT NOT NULL,
+        author_kind TEXT NOT NULL,
+        author_id TEXT,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (scene_id, version),
+        FOREIGN KEY (scene_id) REFERENCES scenes(id) ON DELETE CASCADE
+      );
+
+      CREATE TABLE IF NOT EXISTS scene_events (
+        event_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        scene_id TEXT NOT NULL,
+        version INTEGER NOT NULL CHECK (version >= 1),
+        kind TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        graph_json TEXT NOT NULL,
+        FOREIGN KEY (scene_id) REFERENCES scenes(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS scene_events_scene_event_idx
+        ON scene_events(scene_id, event_id);
+    `);
+    }
+    async withWriteTransaction(fn) {
+        const db = await this.database();
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = await fn(db);
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                // Ignore rollback errors so the original failure is preserved.
+            }
+            throw err;
+        }
+    }
+    getRow(db, id) {
+        return asSceneRow(db
+            .query(`SELECT id, name, project_id, owner_id, thumbnail_url, version,
+                  created_at, updated_at, size_bytes, node_count, graph_json
+             FROM scenes
+            WHERE id = ?`)
+            .get(id));
+    }
+    generateUniqueId(db) {
+        for (let attempt = 0; attempt < 20; attempt++) {
+            const id = generateSlug();
+            if (!this.getRow(db, id))
+                return id;
+        }
+        throw new SceneInvalidError('Failed to generate a unique scene id');
+    }
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,136 @@
+import type { SceneGraph } from '@pascal-app/core/clone-scene-graph';
+/**
+ * Slug-safe scene identifier: lowercase alphanumerics and hyphens, ≤ 64 chars.
+ */
+export type SceneId = string;
+export interface SceneMeta {
+    id: SceneId;
+    name: string;
+    projectId: string | null;
+    thumbnailUrl: string | null;
+    /** Browser-visible model version. Draft saves may update the same version repeatedly. */
+    version: number;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+    ownerId: string | null;
+    sizeBytes: number;
+    nodeCount: number;
+    /** Browser route agents should return to users. Hosted apps should prefer /editor/<projectId>. */
+    editorUrl?: string;
+    /** Backward-compatible alias for clients that still read url. */
+    url?: string;
+    /** True when this save is browser-visible without a separate publish call. */
+    published?: boolean;
+    /** True when the saved graph is still the mutable browser-visible draft. */
+    isDraft?: boolean;
+    /** How the scene was saved. Draft saves should not create meaningful history versions. */
+    saveMode?: SceneSaveMode;
+    /** Stable hash of the graph payload used for save/load/status matching. */
+    graphHash?: string;
+}
+export interface SceneWithGraph extends SceneMeta {
+    graph: SceneGraph;
+}
+export interface SceneEvent {
+    eventId: number;
+    sceneId: SceneId;
+    version: number;
+    kind: string;
+    createdAt: string;
+    graph: SceneGraph;
+}
+export interface SceneSaveOptions {
+    id?: SceneId;
+    name: string;
+    projectId?: string | null;
+    ownerId?: string | null;
+    graph: SceneGraph;
+    thumbnailUrl?: string | null;
+    /** When set, save fails with `SceneVersionConflictError` on mismatch. */
+    expectedVersion?: number;
+    /** `draft` updates the browser-visible working model; `checkpoint` records version history. */
+    saveMode?: SceneSaveMode;
+    /** Whether a checkpoint should become the published/browser-visible head. */
+    publish?: boolean;
+    /** Optional hosted MCP session id for project presence/debug metadata. */
+    agentSessionId?: string;
+    /** Optional high-level operation name for presence/debug metadata. */
+    operation?: string;
+}
+export type SceneSaveMode = 'draft' | 'checkpoint';
+export interface SceneListOptions {
+    projectId?: string;
+    ownerId?: string;
+    limit?: number;
+}
+export interface SceneMutateOptions {
+    expectedVersion?: number;
+}
+export interface SceneEventAppendOptions {
+    sceneId: SceneId;
+    version: number;
+    kind: string;
+    graph: SceneGraph;
+}
+export interface SceneEventListOptions {
+    afterEventId?: number;
+    limit?: number;
+}
+export interface ProjectCreateOptions {
+    id?: SceneId;
+    name: string;
+    ownerId?: string | null;
+    isPrivate?: boolean;
+}
+export interface ProjectStatus {
+    id: SceneId;
+    projectId: string;
+    name: string;
+    editorUrl: string;
+    url: string;
+    ownerId: string | null;
+    thumbnailUrl: string | null;
+    publishedVersion: number | null;
+    latestVersion: number | null;
+    draftVersion: number | null;
+    browserVisibleVersion: number | null;
+    /** Alias for the browser-visible/latest meaningful version. */
+    version: number;
+    isEmpty: boolean;
+    sizeBytes: number;
+    nodeCount: number;
+    graphHash: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SceneStore {
+    readonly backend: 'sqlite' | 'supabase';
+    createProject?(opts: ProjectCreateOptions): Promise<ProjectStatus>;
+    getProjectStatus?(id: SceneId): Promise<ProjectStatus | null>;
+    save(opts: SceneSaveOptions): Promise<SceneMeta>;
+    load(id: SceneId): Promise<SceneWithGraph | null>;
+    list(opts?: SceneListOptions): Promise<SceneMeta[]>;
+    delete(id: SceneId, opts?: SceneMutateOptions): Promise<boolean>;
+    rename(id: SceneId, newName: string, opts?: SceneMutateOptions): Promise<SceneMeta>;
+    appendSceneEvent?(opts: SceneEventAppendOptions): Promise<SceneEvent>;
+    listSceneEvents?(sceneId: SceneId, opts?: SceneEventListOptions): Promise<SceneEvent[]>;
+}
+export declare class SceneNotFoundError extends Error {
+    readonly code: "not_found";
+    constructor(message?: string);
+}
+export declare class SceneVersionConflictError extends Error {
+    readonly code: "version_conflict";
+    constructor(message?: string);
+}
+export declare class SceneInvalidError extends Error {
+    readonly code: "invalid";
+    constructor(message?: string);
+}
+export declare class SceneTooLargeError extends Error {
+    readonly code: "too_large";
+    constructor(message?: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"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"}

package/dist/storage/types.js

@@ -0,0 +1,28 @@
+export class SceneNotFoundError extends Error {
+    code = 'not_found';
+    constructor(message = 'Scene not found') {
+        super(message);
+        this.name = 'SceneNotFoundError';
+    }
+}
+export class SceneVersionConflictError extends Error {
+    code = 'version_conflict';
+    constructor(message = 'Scene version conflict') {
+        super(message);
+        this.name = 'SceneVersionConflictError';
+    }
+}
+export class SceneInvalidError extends Error {
+    code = 'invalid';
+    constructor(message = 'Scene invalid') {
+        super(message);
+        this.name = 'SceneInvalidError';
+    }
+}
+export class SceneTooLargeError extends Error {
+    code = 'too_large';
+    constructor(message = 'Scene too large') {
+        super(message);
+        this.name = 'SceneTooLargeError';
+    }
+}