@portel/photon 1.20.0 → 1.21.0

package/dist/photons/canvas.photon.d.ts

@@ -0,0 +1,400 @@
+/**
+ * Canvas — co-creative scene graph
+ *
+ * Shared canvas where AI agents and humans collaboratively place,
+ * move, resize, and update rendered elements. Either party can start,
+ * either can edit, control passes back and forth fluidly.
+ *
+ * Each element renders using the runtime's 50+ format renderers
+ * (metric, chart:bar, table, gauge, timeline, etc.).
+ *
+ * @description Co-creative canvas for AI and humans
+ * @icon 🎨
+ * @stateful
+ */
+export default class Canvas {
+    emit: (data: any) => void;
+    formats: Record<string, {
+        data: string;
+        example: unknown;
+    }>;
+    memory: {
+        get<T>(key: string, scope?: string): Promise<T | null>;
+        set<T>(key: string, value: T, scope?: string): Promise<void>;
+        delete(key: string, scope?: string): Promise<boolean>;
+        keys(scope?: string): Promise<string[]>;
+    };
+    /** Scene graph: element ID → element */
+    private _scene;
+    private _nextZ;
+    private _loaded;
+    /** Turn state: who has control */
+    private _turn;
+    /** Max snapshots to keep per canvas */
+    private static MAX_SNAPSHOTS;
+    /** Load scene from persistent storage (or from fork data) */
+    private _load;
+    /** Save scene to persistent storage + auto-snapshot */
+    private _save;
+    /**
+     * Open the canvas
+     * @ui canvas
+     * @readOnly
+     */
+    main(): Promise<{
+        elements: {
+            id: string;
+            format: string;
+            data: any;
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            z: number;
+            label?: string;
+            locked?: string;
+            createdBy?: string;
+            updatedAt: number;
+        }[];
+        turn: {
+            agent: string;
+            message?: string;
+            since: number;
+        };
+    }>;
+    /**
+     * Place or update an element on the canvas.
+     * Creates if new, merges if exists — only provided fields change.
+     *
+     * @param id Element identifier
+     * @param format Renderer format (metric, chart:bar, table, gauge, etc.)
+     * @param data Data matching the format spec
+     * @param x Horizontal position in pixels
+     * @param y Vertical position in pixels
+     * @param w Width in pixels
+     * @param h Height in pixels
+     * @param z Z-order layer (higher = on top)
+     * @param label Human-readable label shown on the element
+     */
+    put({ id, format, data, x, y, w, h, z, label, }: {
+        id: string;
+        format?: string;
+        data?: any;
+        x?: number;
+        y?: number;
+        w?: number;
+        h?: number;
+        z?: number;
+        label?: string;
+    }): Promise<{
+        id: string;
+        format: string;
+        data: any;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        z: number;
+        label: string | undefined;
+        createdBy: string;
+        updatedAt: number;
+    }>;
+    /**
+     * Remove an element from the canvas
+     * @param id Element identifier to remove
+     */
+    remove({ id }: {
+        id: string;
+    }): Promise<{
+        removed: boolean;
+        id: string;
+    }>;
+    /**
+     * Clear all elements from the canvas
+     * @destructive
+     */
+    clear(): Promise<{
+        cleared: number;
+    }>;
+    /**
+     * Get the full scene graph — all elements with positions, sizes, and data
+     * @readOnly
+     */
+    scene(): Promise<{
+        elements: {
+            id: string;
+            format: string;
+            data: any;
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            z: number;
+            label?: string;
+            locked?: string;
+            createdBy?: string;
+            updatedAt: number;
+        }[];
+        count: number;
+        turn: {
+            agent: string;
+            message?: string;
+            since: number;
+        };
+    }>;
+    /**
+     * Pass control to another agent or back to the human.
+     * The recipient sees a status banner with the optional message.
+     *
+     * @param to Who gets control next (e.g. 'human', 'ai', agent name)
+     * @param message Optional message explaining what to do next
+     */
+    pass({ to, message }: {
+        to: string;
+        message?: string;
+    }): Promise<{
+        agent: string;
+        message?: string;
+        since: number;
+    }>;
+    /**
+     * Lock an element so only the specified agent can modify it.
+     *
+     * @param id Element to lock
+     * @param agent Agent name claiming the lock
+     */
+    lock({ id, agent }: {
+        id: string;
+        agent: string;
+    }): Promise<{
+        id: string;
+        format: string;
+        data: any;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        z: number;
+        label?: string;
+        locked?: string;
+        createdBy?: string;
+        updatedAt: number;
+    } | {
+        error: string;
+        id: string;
+    }>;
+    /**
+     * Unlock an element, allowing anyone to modify it.
+     *
+     * @param id Element to unlock
+     */
+    unlock({ id }: {
+        id: string;
+    }): Promise<{
+        id: string;
+        format: string;
+        data: any;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        z: number;
+        label?: string;
+        locked?: string;
+        createdBy?: string;
+        updatedAt: number;
+    } | {
+        error: string;
+        id: string;
+    }>;
+    /**
+     * Describe the current canvas layout in natural language.
+     * Useful for AI agents to understand spatial arrangement without a screenshot.
+     * @readOnly
+     */
+    describe(): Promise<{
+        description: string;
+        count: number;
+        elements?: undefined;
+        bounds?: undefined;
+        turn?: undefined;
+    } | {
+        description: string;
+        elements: string[];
+        bounds: {
+            width: number;
+            height: number;
+        };
+        turn: {
+            agent: string;
+            message?: string;
+            since: number;
+        };
+        count: number;
+    }>;
+    private _groupBy;
+    /**
+     * Request a screenshot from the canvas UI.
+     * Returns the latest captured screenshot as a base64 data URL.
+     * The UI captures the screenshot and sends it back via the capture method.
+     * @readOnly
+     */
+    screenshot(): Promise<{
+        available: boolean;
+        dataUrl: string | null;
+        hint: string;
+    }>;
+    /**
+     * Store a screenshot captured by the canvas UI.
+     * Called by the client after a screenshot-request event.
+     * @internal
+     * @param dataUrl Base64 data URL of the captured image
+     */
+    capture({ dataUrl }: {
+        dataUrl: string;
+    }): Promise<{
+        stored: boolean;
+    }>;
+    /**
+     * Register a custom component that can be used as a format on the canvas.
+     * Once registered, use the component name as the format in put().
+     *
+     * @param name Component name (used as format value in put)
+     * @param html HTML template string. Use {{key}} placeholders for data binding.
+     * @param defaults Default data values for the component
+     */
+    registerComponent({ name, html, defaults, }: {
+        name: string;
+        html: string;
+        defaults?: Record<string, any>;
+    }): Promise<{
+        registered: string;
+    }>;
+    /**
+     * List registered custom components with their templates
+     * @readOnly
+     */
+    listComponents(): Promise<{
+        name: string;
+        html: any;
+        defaults: any;
+    }[]>;
+    /**
+     * View the canvas timeline — a history of every change.
+     * Each entry has a timestamp, action label, and element count.
+     * @readOnly
+     */
+    history(): Promise<{
+        index: number;
+        time: string;
+        action: string;
+        elements: number;
+    }[]>;
+    /**
+     * Get the full timeline with scene data for animated playback.
+     * Each frame contains the complete scene state so the client can
+     * compute Magic Move transitions between consecutive frames.
+     * @readOnly
+     * @internal
+     */
+    playback(): Promise<{
+        index: number;
+        action: string;
+        elements: any[];
+    }[]>;
+    /**
+     * Save a named checkpoint at the current state.
+     * Checkpoints appear in the timeline with a label for easy reference.
+     *
+     * @param label Name for this checkpoint (e.g. 'before reorganizing')
+     */
+    checkpoint({ label }: {
+        label: string;
+    }): Promise<{
+        checkpointed: string;
+        elements: number;
+    }>;
+    /**
+     * Restore the canvas to a previous point in the timeline.
+     * Replaces the current scene with the snapshot at that index.
+     *
+     * @param index Timeline index to restore (from history())
+     */
+    restore({ index }: {
+        index: number;
+    }): Promise<{
+        error: string;
+        restored?: undefined;
+        action?: undefined;
+        time?: undefined;
+        elements?: undefined;
+    } | {
+        restored: number;
+        action: string;
+        time: string;
+        elements: number;
+        error?: undefined;
+    }>;
+    /**
+     * Fork the canvas at a timeline point into a new instance.
+     * Creates a new canvas instance with the scene from that snapshot.
+     *
+     * @param name New instance name (e.g. 'dashboard-v2')
+     * @param index Timeline index to fork from (defaults to current state)
+     */
+    fork({ name, index }: {
+        name: string;
+        index?: number;
+    }): Promise<{
+        error: string;
+        forked?: undefined;
+        from?: undefined;
+        elements?: undefined;
+        hint?: undefined;
+    } | {
+        forked: string;
+        from: string;
+        elements: number;
+        hint: string;
+        error?: undefined;
+    }>;
+    /**
+     * Export the current canvas as a standalone photon.
+     * Compiles the scene graph into a .photon.ts (data methods) and
+     * .photon.html (CSS grid layout with format renderers).
+     *
+     * @param name Photon name for the exported file (e.g. 'my-dashboard')
+     * @param description One-line description of the exported photon
+     * @readOnly
+     */
+    export({ name, description }: {
+        name: string;
+        description?: string;
+    }): Promise<{
+        error: string;
+        name?: undefined;
+        files?: undefined;
+        elements?: undefined;
+        grid?: undefined;
+    } | {
+        name: string;
+        files: {
+            [x: string]: string;
+        };
+        elements: number;
+        grid: string;
+        error?: undefined;
+    }>;
+    private _detectRows;
+    private _toPascalCase;
+    /**
+     * List all available render formats with expected data shapes
+     * @readOnly
+     * @format table
+     */
+    listFormats(): {
+        format: string;
+        data: any;
+    }[];
+}
+//# sourceMappingURL=canvas.photon.d.ts.map

package/dist/photons/canvas.photon.d.ts.map

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