@compilr-dev/sdk 0.18.3 → 0.18.4

package/dist/capabilities/packs.js

@@ -243,10 +243,11 @@ export const CAPABILITY_PACKS = {
             'canvas_get',
             'canvas_delete',
             'canvas_validate',
+            'canvas_screenshot',
         ],
         readOnly: false,
         promptModules: ['platform-tool-hints'],
-        promptSnippet: "Visual canvases (infographic/carousel/board) rendered from sandboxed HTML/SVG. Create/replace with canvas_write (raw HTML only — host injects the CSP; inline <style>/<script> only, no network/remote assets; optional Tweaks controls manifest). EDIT via canvas_get (outline=true or startLine/maxLines) then canvas_edit (str_replace/append/prepend) — never re-send the whole document. After authoring, canvas_validate to catch won't-render content, off-canvas board nodes, and un-themed colors.",
+        promptSnippet: 'Visual canvases (infographic/carousel/board) rendered from sandboxed HTML/SVG. Create/replace with canvas_write (raw HTML only — host injects the CSP; inline <style>/<script> only, no network/remote assets; optional Tweaks controls manifest). EDIT via canvas_get (outline=true or startLine/maxLines) then canvas_edit (str_replace/append/prepend) — never re-send the whole document. After authoring, canvas_validate (static) then canvas_screenshot to SEE the render (vision models) — fix overflow/readability with canvas_edit.',
         estimatedPromptTokens: 150,
         estimatedToolTokens: 1500,
     },

package/dist/platform/context.d.ts

@@ -5,7 +5,7 @@
  * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
  */
 import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, ICanvasRepository } from './repositories.js';
-import type { IAnchorService, IArtifactService, IEpisodeService } from './services.js';
+import type { IAnchorService, IArtifactService, IEpisodeService, ICanvasRenderer } from './services.js';
 export interface PlatformContext {
     readonly projects: IProjectRepository;
     readonly workItems: IWorkItemRepository;
@@ -17,6 +17,8 @@ export interface PlatformContext {
     readonly episodes?: IEpisodeService;
     readonly canvases?: ICanvasRepository;
     readonly comments?: ICommentRepository;
+    /** Host-provided canvas → image renderer (for canvas_screenshot). */
+    readonly canvasRenderer?: ICanvasRenderer;
 }
 export interface PlatformHooks {
     /** Called when a project is resolved/selected as the current project */

package/dist/platform/services.d.ts

@@ -80,3 +80,27 @@ export interface IEpisodeService {
     getRecent(count: number): Promise<WorkEpisode[]>;
     getWorkSummary(): Promise<ProjectWorkSummary>;
 }
+/** A rendered canvas image, for the agent's visual self-review. */
+export interface RenderedCanvasImage {
+    /** Base64-encoded image data (no `data:` prefix). */
+    data: string;
+    /** MIME type, e.g. "image/png". */
+    mediaType: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Renders a canvas's HTML/SVG to a raster image so a vision-capable agent can
+ * SEE what it authored (`canvas_screenshot`). Host-provided — the SDK can't
+ * render HTML (the host does it via, e.g., an offscreen Electron window +
+ * capturePage). Absent in hosts that can't render canvases (e.g. the CLI),
+ * in which case canvas_screenshot degrades to a "not available here" note.
+ */
+export interface ICanvasRenderer {
+    renderToImage(input: {
+        /** Raw canvas HTML/SVG (the stored content). */
+        content: string;
+        /** Canvas type — the host sizes/wraps accordingly. */
+        type: 'infographic' | 'carousel' | 'board';
+    }): Promise<RenderedCanvasImage>;
+}

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

@@ -576,6 +576,55 @@ export function createCanvasTools(config) {
             }
         },
     });
+    // ---------------------------------------------------------------------------
+    // canvas_screenshot — render + SEE the canvas (visual self-review)
+    // ---------------------------------------------------------------------------
+    const canvasScreenshotTool = defineTool({
+        name: 'canvas_screenshot',
+        description: 'RENDER a canvas and SEE it — a visual self-review that static checks can’t do. Renders the stored canvas ' +
+            'to an image and returns it so you can inspect how it ACTUALLY looks: content overflow / cut-off, unreadable ' +
+            'or low-contrast text, cramped or empty areas, misaligned or broken layout. Run it after canvas_write / ' +
+            'canvas_edit (and canvas_validate) — if something is off, fix it with canvas_edit and screenshot again. ' +
+            'Only useful on a vision-capable model; unavailable in hosts that can’t render canvases.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The stored canvas to render and view.' },
+            },
+            required: ['canvas_id'],
+        },
+        execute: async (input) => {
+            try {
+                const renderer = ctx.canvasRenderer;
+                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);
+                if (!c)
+                    return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                const img = await renderer.renderToImage({ content: c.content, type: c.type });
+                return {
+                    success: true,
+                    result: `Rendered "${c.title}" (${c.type}). Review the image below — check for overflow / cut-off content, ` +
+                        'unreadable or low-contrast text, cramped or empty areas, and broken layout. If anything is off, fix it ' +
+                        'with canvas_edit and screenshot again.',
+                    imageBlocks: [
+                        {
+                            data: img.data,
+                            mediaType: img.mediaType,
+                            filename: `canvas-${String(c.id)}.png`,
+                            width: img.width,
+                            height: img.height,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return createErrorResult(`Failed to screenshot canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
     return [
         canvasWriteTool,
         canvasEditTool,
@@ -583,5 +632,6 @@ export function createCanvasTools(config) {
         canvasGetTool,
         canvasDeleteTool,
         canvasValidateTool,
+        canvasScreenshotTool,
     ];
 }

package/dist/skills/canvas-skills.js

@@ -67,9 +67,11 @@ export const canvasSkill = defineSkill({
 
 4. **To EDIT an existing canvas, do NOT re-send the whole document.** First call \`canvas_get\` with \`outline=true\` (or a \`startLine\`/\`maxLines\` slice) to find the exact snippet, then \`canvas_edit\` with \`operation=str_replace\` (old_str must be unique — include surrounding context — or set replace_all=true), or append/prepend. Reserve \`canvas_write\` with \`canvas_id\` for a full intentional rewrite.
 
-5. **Validate before you hand it off.** Once the canvas is composed, call \`canvas_validate\` (canvas_id) — a fast static check that catches content that won't render (Mermaid/Markdown/CDN), a board missing its \`data-board\` bounds or with nodes off-canvas, sparse output, and hardcoded colors that ignore the theme tokens. Fix any **errors** (they render broken) and address applicable **warnings**, then move on. (It doesn't judge looks — that's your eye.)
+5. **Validate before you hand it off.** Once the canvas is composed, call \`canvas_validate\` (canvas_id) — a fast static check that catches content that won't render (Mermaid/Markdown/CDN), a board missing its \`data-board\` bounds or with nodes off-canvas, sparse output, and hardcoded colors that ignore the theme tokens. Fix any **errors** (they render broken) and address applicable **warnings**, then move on.
 
-6. **After writing, tell the user what you made in one line** and point them at the Tweaks they can adjust. The canvas opens in its own tab.
+6. **See it before you trust it (if you can).** If you're vision-capable, call \`canvas_screenshot\` (canvas_id) — it renders the canvas and returns the image so you can catch what static checks can't: overflow / cut-off content, unreadable or low-contrast text, cramped or empty areas, broken layout. If something's off, fix it with \`canvas_edit\` and screenshot again. (No-op on text-only models / hosts that can't render.)
+
+7. **After writing, tell the user what you made in one line** and point them at the Tweaks they can adjust. The canvas opens in its own tab.
 
 ## Rules
 - CALL THE TOOL — don't describe the HTML you "would" write and stop. A canvas only exists once the tool succeeds.

package/dist/team/tool-config.js

@@ -295,6 +295,7 @@ export const TOOL_GROUPS = {
             'canvas_get',
             'canvas_delete',
             'canvas_validate',
+            'canvas_screenshot',
         ],
         readOnly: false,
         tier: 'meta',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.18.3",
+  "version": "0.18.4",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",