@compilr-dev/sdk 0.29.8 → 0.30.0

package/dist/platform/tools/canvas-tools.js

@@ -23,7 +23,41 @@ import { validateControlManifest } from '../../canvas/validate.js';
 import { canvasMacro, infographicMacro, carouselMacro, boardMacro, canvasStylesMacro, } from '../../skills/canvas-macros.js';
 import { canvasExemplarInfographicMacro, canvasExemplarAppScreenMacro, } from '../../skills/canvas-exemplars.js';
 import { canvasIconsMacro } from '../../skills/canvas-icons.js';
-const CANVAS_TYPES = ['infographic', 'carousel', 'board'];
+import { HTML_CANVAS_TYPES } from '../../canvas/types.js';
+import { validateScene, normalizeScene, describeScene } from '../../canvas/scene.js';
+import { sceneOutline, screenshotScene } from './scene-tools.js';
+/**
+ * The HTML canvas types. `scene` is deliberately NOT here: a scene's content is JSON written
+ * through the scene writer, and canvas_write/canvas_edit on it is how a scene gets corrupted.
+ */
+const CANVAS_TYPES = [...HTML_CANVAS_TYPES];
+/** The refusal every HTML-content tool gives for a scene — names the tools that do work. */
+function sceneRefusal(c) {
+    return (`Canvas ${String(c.id)} is a 3D scene; its content is JSON, not HTML. Edit it with ` +
+        'scene_update_object / scene_add_object / scene_remove_object (read it first with scene_get).');
+}
+/** Scenes carry no images (P1); the asset tools say so and point at the scene tools. */
+function sceneAssetRefusal(c) {
+    return (`Canvas ${String(c.id)} is a 3D scene; scenes have no images. Shape it with ` +
+        'scene_add_object / scene_update_object instead.');
+}
+/** Static checks for scene JSON (canvas_validate on a scene) — the scene validator's errors. */
+function sceneContentIssues(content) {
+    let raw;
+    try {
+        raw = JSON.parse(content);
+    }
+    catch (e) {
+        return [
+            {
+                level: 'error',
+                message: `Scene content is not valid JSON (${e instanceof Error ? e.message : String(e)}).`,
+            },
+        ];
+    }
+    const v = validateScene(raw);
+    return v.ok ? [] : v.errors.map((message) => ({ level: 'error', message }));
+}
 /** Render content as numbered lines (1-based), optionally a slice. */
 function numberedLines(content, startLine, maxLines) {
     const lines = content.split('\n');
@@ -142,6 +176,9 @@ function offCanvasNodes(src, bounds) {
 }
 /** Run deterministic static checks on canvas content. No rendering. */
 export function runCanvasChecks(html, type, manifest) {
+    // A scene is JSON, not HTML: none of the HTML checks below apply.
+    if (type === 'scene')
+        return sceneContentIssues(html);
     const issues = [];
     const src = html.trim();
     if (!src) {
@@ -285,6 +322,10 @@ export function createCanvasTools(config, imageConfig) {
         },
         execute: async (input) => {
             try {
+                if (input.type === 'scene') {
+                    return createErrorResult('canvas_write authors HTML canvases. 3D scenes are JSON — create one with scene_create, ' +
+                        'then build it with scene_add_object.');
+                }
                 // Reject content that can't render in the sandbox (Mermaid/Markdown/
                 // external-CDN) with a corrective message → the agent retries with
                 // inline HTML/SVG instead of persisting a blank canvas.
@@ -298,6 +339,9 @@ export function createCanvasTools(config, imageConfig) {
                     }
                 }
                 if (input.canvas_id !== undefined) {
+                    const existing = await canvases.getById(input.canvas_id);
+                    if (existing?.type === 'scene')
+                        return createErrorResult(sceneRefusal(existing));
                     const updated = await canvases.update(input.canvas_id, {
                         title: input.title,
                         content: input.html,
@@ -408,6 +452,20 @@ export function createCanvasTools(config, imageConfig) {
                 const c = await canvases.getById(input.canvas_id);
                 if (!c)
                     return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                if (c.type === 'scene') {
+                    // A scene is JSON — an outline of its objects, and the tool that reads it whole.
+                    let body;
+                    try {
+                        const v = validateScene(JSON.parse(c.content));
+                        body = v.ok
+                            ? `${describeScene(v.scene)}\n\n--- objects (id · type · name) ---\n${sceneOutline(normalizeScene(v.scene))}`
+                            : `The stored scene is invalid (${v.errors[0] ?? 'unknown error'}).`;
+                    }
+                    catch {
+                        body = 'The stored scene is not valid JSON.';
+                    }
+                    return createSuccessResult(`Canvas "${c.title}" (scene)\nID: ${String(c.id)}  |  ${body}\n\nRead the full scene with scene_get.`);
+                }
                 const totalLines = c.content.split('\n').length;
                 const header = `Canvas "${c.title}" (${c.type})\n` +
                     `ID: ${String(c.id)}  |  Controls: ${String(c.controls.controls.length)}  |  Lines: ${String(totalLines)}\n\n`;
@@ -474,6 +532,9 @@ export function createCanvasTools(config, imageConfig) {
                 const c = await canvases.getById(input.canvas_id);
                 if (!c)
                     return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                // str_replace on scene JSON is exactly how a scene gets corrupted.
+                if (c.type === 'scene')
+                    return createErrorResult(sceneRefusal(c));
                 let next;
                 let summary;
                 if (input.operation === 'str_replace') {
@@ -559,8 +620,8 @@ export function createCanvasTools(config, imageConfig) {
                 },
                 type: {
                     type: 'string',
-                    enum: CANVAS_TYPES,
-                    description: 'Canvas type (required when passing html; defaults to infographic).',
+                    enum: [...CANVAS_TYPES, 'scene'],
+                    description: 'Canvas type (required when passing html; defaults to infographic). For "scene", pass the scene JSON as html.',
                 },
             },
             required: [],
@@ -649,13 +710,41 @@ export function createCanvasTools(config, imageConfig) {
         execute: async (input) => {
             try {
                 const renderer = ctx.canvasRenderer;
+                // A scene goes to the 3D renderer — either tool works on a scene (3d-canvas-spec §3.1).
+                const maybeScene = await canvases.getById(input.canvas_id);
+                if (maybeScene?.type === 'scene') {
+                    let scene;
+                    try {
+                        const v = validateScene(JSON.parse(maybeScene.content));
+                        if (!v.ok)
+                            return createErrorResult(`${v.errors[0] ?? 'Invalid scene.'} Read it with scene_get.`);
+                        scene = normalizeScene(v.scene);
+                    }
+                    catch {
+                        return createErrorResult('The stored scene is not valid JSON. Read it with scene_get.');
+                    }
+                    const shot = await screenshotScene(ctx, {
+                        canvasId: maybeScene.id,
+                        title: maybeScene.title,
+                        scene,
+                    });
+                    if (!shot.available)
+                        return createSuccessResult(shot.text);
+                    return {
+                        success: true,
+                        result: shot.text,
+                        imageBlocks: [{ ...shot.image, filename: `scene-${String(maybeScene.id)}.png` }],
+                    };
+                }
                 if (!renderer) {
                     return createSuccessResult('Canvas rendering is not available in this environment — a visual self-review can’t be produced here. ' +
                         'Rely on canvas_validate (static checks) instead.');
                 }
-                const c = await canvases.getById(input.canvas_id);
+                const c = maybeScene;
                 if (!c)
                     return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                // Scenes returned above; what is left is an HTML canvas.
+                const htmlType = c.type;
                 /*
                   ⚠️ Resolve assets HERE, not in the host renderer. This tool has the canvas id and
                   the repository; `renderToImage` receives only html, so pushing substitution into
@@ -666,7 +755,7 @@ export function createCanvasTools(config, imageConfig) {
                 const shotAssets = canvases.listAssets ? await canvases.listAssets(c.id) : [];
                 const img = await renderer.renderToImage({
                     content: resolveCanvasAssets(c.content, shotAssets),
-                    type: c.type,
+                    type: htmlType,
                 });
                 return {
                     success: true,
@@ -812,6 +901,8 @@ export function createCanvasTools(config, imageConfig) {
             const canvas = await canvases.getById(input.canvas_id);
             if (!canvas)
                 return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+            if (canvas.type === 'scene')
+                return createErrorResult(sceneAssetRefusal(canvas));
             const filePath = pathNode.isAbsolute(input.path)
                 ? input.path
                 : pathNode.resolve(resolveCwd(config.cwd), input.path);
@@ -894,6 +985,8 @@ export function createCanvasTools(config, imageConfig) {
             const canvas = await canvases.getById(input.canvas_id);
             if (!canvas)
                 return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+            if (canvas.type === 'scene')
+                return createErrorResult(sceneAssetRefusal(canvas));
             const assets = await canvases.listAssets(input.canvas_id);
             if (assets.length === 0) {
                 return createSuccessResult('No images on this canvas. Add one with canvas_asset_add.');
@@ -925,6 +1018,9 @@ export function createCanvasTools(config, imageConfig) {
             if (!canvases.deleteAsset) {
                 return createErrorResult('This host does not support canvas assets.');
             }
+            const target = await canvases.getById(input.canvas_id);
+            if (target?.type === 'scene')
+                return createErrorResult(sceneAssetRefusal(target));
             const gone = await canvases.deleteAsset(input.canvas_id, input.ref.toLowerCase());
             return gone
                 ? createSuccessResult(`Removed "${input.ref}".`)

package/dist/platform/tools/index.d.ts

@@ -32,5 +32,6 @@ export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
 export { createCanvasTools } from './canvas-tools.js';
+export { createSceneTools, SCENE_TOOL_NAMES, sceneOutline } from './scene-tools.js';
 export { createImageTools } from './image-tools.js';
 export type { ImageToolsConfig, ImageResizer } from './image-tools.js';

package/dist/platform/tools/index.js

@@ -17,6 +17,8 @@ import { createAnchorTools } from './anchor-tools.js';
 import { createArtifactTools } from './artifact-tools.js';
 import { createEpisodeTools } from './episode-tools.js';
 import { createCanvasTools } from './canvas-tools.js';
+import { createSceneTools } from './scene-tools.js';
+import { createSceneWriter } from '../scene-writer.js';
 import { createImageTools } from './image-tools.js';
 /**
  * Create all platform tools operating against the given context.
@@ -63,8 +65,21 @@ export function createPlatformTools(config, options) {
         tools.push(...createEpisodeTools(config));
     }
     if (config.context.canvases) {
-        // The resizer is shared with view_image — canvas_asset_add resizes to display size.
-        tools.push(...createCanvasTools(config, imageConfig));
+        const surfaces = config.canvasSurfaces ?? {};
+        if (surfaces.html !== false) {
+            // The resizer is shared with view_image — canvas_asset_add resizes to display size.
+            tools.push(...createCanvasTools(config, imageConfig));
+        }
+        if (surfaces.scene !== false) {
+            /*
+              One writer for the scene tools — the host's own when given (Desktop's inspector must
+              share it), else one built here, ONCE, so every scene tool shares its lock and journal.
+              ⚠️ Passed alongside, never by spreading a new context: hosts mutate
+              `context.currentProjectId` after the tools are built, and a copy would freeze it.
+            */
+            const sceneWriter = config.context.sceneWriter ?? createSceneWriter(config.context.canvases);
+            tools.push(...createSceneTools(config, { writer: sceneWriter }));
+        }
     }
     return tools;
 }
@@ -78,4 +93,5 @@ export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
 export { createCanvasTools } from './canvas-tools.js';
+export { createSceneTools, SCENE_TOOL_NAMES, sceneOutline } from './scene-tools.js';
 export { createImageTools } from './image-tools.js';

package/dist/platform/tools/scene-tools.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Scene Tools — agents build 3D scenes as validated JSON (3d-canvas-spec §6).
+ *
+ * 7 tools: scene_create, scene_get, scene_add_object, scene_update_object,
+ * scene_remove_object, scene_set_camera, scene_screenshot.
+ *
+ * Every edit goes through the scene writer (`platform/scene-writer.ts`) — the same instance the
+ * host's inspector uses — so user and agent edits serialise and the agent is TOLD about the
+ * user's changes: a successful result starts with "The user edited this scene since your last
+ * call: …" when there are any.
+ *
+ * Names carry the `scene_` prefix: generic names (`add_object`) collide with MCP servers, and
+ * hosts refresh views on tool-name prefixes.
+ */
+import type { PlatformContext, PlatformToolsConfig } from '../context.js';
+import { type ISceneWriter } from '../scene-writer.js';
+import { type SceneFile } from '../../canvas/scene.js';
+export declare const SCENE_TOOL_NAMES: readonly ["scene_create", "scene_get", "scene_add_object", "scene_update_object", "scene_remove_object", "scene_set_camera", "scene_screenshot"];
+/** "sofa · box · Sofa" rows, indented under their group parent. */
+export declare function sceneOutline(scene: SceneFile): string;
+/**
+ * Render a scene through the host's `renderSceneToImage` — shared by scene_screenshot and
+ * canvas_screenshot (either tool works on a scene).
+ */
+export declare function screenshotScene(ctx: PlatformContext, args: {
+    canvasId: number;
+    title: string;
+    scene: SceneFile;
+    width?: number;
+    height?: number;
+}): Promise<{
+    available: false;
+    text: string;
+} | {
+    available: true;
+    text: string;
+    image: {
+        data: string;
+        mediaType: string;
+        width?: number;
+        height?: number;
+    };
+}>;
+export declare function createSceneTools(config: PlatformToolsConfig, options?: {
+    writer?: ISceneWriter;
+}): (import("@compilr-dev/agents").Tool<{
+    title: string;
+    scene?: unknown;
+    project_id?: number;
+}> | import("@compilr-dev/agents").Tool<Record<string, unknown> & {
+    canvas_id: number;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    id: string;
+    patch: Record<string, unknown>;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    position?: unknown;
+    target?: unknown;
+    fit?: boolean;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    width?: number;
+    height?: number;
+}>)[];