@compilr-dev/sdk 0.18.1 → 0.18.2

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

@@ -12,6 +12,18 @@
  */
 import type { PlatformToolsConfig } from '../context.js';
 import type { ControlManifest } from '../../canvas/types.js';
+/**
+ * Guard the `html` arg against shapes that CANNOT render in the sandboxed
+ * canvas iframe (canvas-robustness-spec §3.3). Returns a corrective error
+ * string (which the agent sees as a tool error and retries on), or null if OK.
+ *
+ * Deliberately conservative — only rejects clear cases so valid HTML/SVG is
+ * never blocked. In particular it does NOT trip on SVG namespaces
+ * (`xmlns="http://www.w3.org/2000/svg"`), inline `<script>`/`<style>`, or
+ * `<a href="http…">` anchors (those are all fine); it targets the loaders the
+ * CSP actually blocks.
+ */
+export declare function validateCanvasHtml(html: string): string | null;
 export declare function createCanvasTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
     type: string;
     title: string;

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

@@ -53,6 +53,48 @@ function countOccurrences(haystack, needle) {
     }
     return count;
 }
+/**
+ * Guard the `html` arg against shapes that CANNOT render in the sandboxed
+ * canvas iframe (canvas-robustness-spec §3.3). Returns a corrective error
+ * string (which the agent sees as a tool error and retries on), or null if OK.
+ *
+ * Deliberately conservative — only rejects clear cases so valid HTML/SVG is
+ * never blocked. In particular it does NOT trip on SVG namespaces
+ * (`xmlns="http://www.w3.org/2000/svg"`), inline `<script>`/`<style>`, or
+ * `<a href="http…">` anchors (those are all fine); it targets the loaders the
+ * CSP actually blocks.
+ */
+export function validateCanvasHtml(html) {
+    const src = html.trim();
+    if (!src)
+        return null; // emptiness is handled by the caller/schema
+    const hasTag = /<[a-z][\s\S]*>/i.test(src);
+    // 1. Mermaid source (diagram keyword at the very start, and no HTML tags).
+    const mermaidStart = /^(?:%%\{[^}]*\}%%\s*)?(?:graph\s|flowchart\s|sequenceDiagram|classDiagram|stateDiagram|erDiagram|gantt|mindmap|journey|pie\s|gitGraph|timeline|quadrantChart)/i;
+    if (!hasTag && mermaidStart.test(src)) {
+        return ('That looks like Mermaid, not HTML. The canvas renders raw HTML/SVG in a sandbox — ' +
+            'Mermaid does not run. Re-author as HTML, or draw the diagram as inline <svg> ' +
+            '(boxes with <rect>/<text>, connectors with <line>/<path>).');
+    }
+    // 2. Markdown source (a fenced block, or headings/lists) with no HTML tags.
+    if (!hasTag && (/^```/.test(src) || /^#{1,6}\s/.test(src) || /^[-*]\s/m.test(src))) {
+        return ('That looks like Markdown, not HTML. The canvas renders raw HTML/SVG — author it as ' +
+            'HTML (e.g. <h1>, <p>, <ul><li>), not Markdown.');
+    }
+    // 3. External / CDN resources. The sandbox CSP is script-src/style-src/img-src
+    //    'self' 'unsafe-inline' data: blob: — no network, no CDN — so these load
+    //    attempts are silently blocked and the canvas renders blank. Only match a
+    //    URL immediately after a loader attribute (src=/href=/@import/fetch) so SVG
+    //    xmlns and anchor hrefs don't false-positive.
+    const externalLoader = /(?:<script\b[^>]*\bsrc|<link\b[^>]*\bhref|<img\b[^>]*\bsrc|@import\s+(?:url\()?)\s*=?\s*["'(]?\s*(?:https?:)?\/\//i;
+    const externalFetch = /\bfetch\s*\(\s*["'`](?:https?:)?\/\//i;
+    if (externalLoader.test(src) || externalFetch.test(src)) {
+        return ('The canvas sandbox blocks external scripts, styles, and images (no network / CDN). ' +
+            'Inline everything: use inline <svg> instead of a CDN library like Mermaid or Chart.js, ' +
+            'inline <style>/<script>, and data: URIs (or inline SVG) for images.');
+    }
+    return null;
+}
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function createCanvasTools(config) {
     const ctx = config.context;
@@ -64,7 +106,10 @@ export function createCanvasTools(config) {
     // ---------------------------------------------------------------------------
     const canvasWriteTool = defineTool({
         name: 'canvas_write',
-        description: 'Create or update a visual canvas (infographic, carousel, or board) rendered from HTML/SVG. ' +
+        description: 'Create or update a visual canvas — use this for ANY visual deliverable: a mockup, UI layout, ' +
+            'diagram, poster, infographic, slide deck, board, or a DESIGN PROPOSAL / REVAMP the user asks to "sketch", ' +
+            '"visualize", "propose a layout", or "redesign". (For a plain list of text options to pick from, that is ' +
+            'propose_alternatives, not this.) The canvas is authored as raw HTML/SVG (infographic, carousel, or board). ' +
             'Optionally declare a controls manifest ("Tweaks") of live parameters the user can adjust: ' +
             'each control is { type: slider|number|toggle|select|color|text, param, label, default, ...type config }. ' +
             'Bind params in your HTML via CSS custom properties var(--param), [data-bind="param"] text, and ' +
@@ -84,8 +129,11 @@ export function createCanvasTools(config) {
                 title: { type: 'string', description: 'Canvas title (shown in the library and tab).' },
                 html: {
                     type: 'string',
-                    description: 'The canvas content as HTML/SVG. Raw content only — the app injects the sandbox/CSP. ' +
-                        'May include a <script> defining window.applyParams(values) for live recompute.',
+                    description: 'The canvas content as RAW HTML/SVG — NOT Mermaid, NOT Markdown. The app renders it in a ' +
+                        'sandboxed iframe with a strict CSP: NO external scripts/styles/images and NO network, so ' +
+                        'inline everything (inline <style>/<script>, inline <svg> instead of a CDN chart/diagram ' +
+                        'library, data: URIs for images). May include a <script> defining window.applyParams(values) ' +
+                        'for live recompute.',
                 },
                 controls: {
                     type: 'object',
@@ -114,6 +162,12 @@ export function createCanvasTools(config) {
         },
         execute: async (input) => {
             try {
+                // 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.
+                const htmlError = validateCanvasHtml(input.html);
+                if (htmlError)
+                    return createErrorResult(htmlError);
                 if (input.controls) {
                     const check = validateControlManifest(input.controls);
                     if (!check.ok) {

package/dist/tools/propose-alternatives-tool.js

@@ -25,10 +25,12 @@ import { defineTool } from '@compilr-dev/agents';
 export function createProposeAlternativesTool(handler) {
     return defineTool({
         name: 'propose_alternatives',
-        description: 'Present 2-3 alternatives for the user to compare and choose from. ' +
-            "Use when there are multiple valid approaches and the user's preference matters. " +
-            'Each alternative can include rich content (code, markdown, mermaid diagrams) for visual comparison. ' +
-            'Include pros and cons to help the user decide. The user picks one or provides feedback.',
+        description: 'Present 2-3 alternatives for the user to COMPARE and CHOOSE from — a DECISION tool for when ' +
+            "multiple valid approaches exist and the user's preference matters. Each alternative is a short " +
+            'text/code summary with pros and cons; the user picks one or gives feedback. ' +
+            'Do NOT use this to produce a visual deliverable — a mockup, UI layout, poster, diagram, or a ' +
+            'design PROPOSAL/REVAMP the user wants to SEE rendered. For anything visual, use the canvas ' +
+            '(canvas_write), even when the request says "propose" or "alternatives".',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

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