@compilr-dev/sdk 0.18.0 → 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,13 +106,18 @@ 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 ' +
             '[data-show="param"] visibility; for computed updates define window.applyParams(values) in a <script>. ' +
             'Omit canvas_id to create. To EDIT an existing canvas, prefer canvas_edit (str_replace) — it avoids ' +
-            're-sending the whole document; only use canvas_write with canvas_id for a full intentional replace.',
+            're-sending the whole document; only use canvas_write with canvas_id for a full intentional replace. ' +
+            'Before creating a NEW canvas, gather the essentials from the user (purpose, type, key content, style) ' +
+            'with ask_user unless they already specified them — authoring on guessed requirements wastes a full pass.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -82,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',
@@ -112,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/skills/canvas-skills.js

@@ -35,7 +35,13 @@ export const canvasSkill = defineSkill({
 
 ## STEPS
 
-1. **Clarify only if needed.** If the request is concrete, go straight to authoring. If the subject or type is ambiguous, ask ONE short question (what should it show, or which type) — do not run a long interview.
+1. **Collect the essentials from the user FIRST — this is the standard approach.** A canvas is an expensive authoring pass; building it on guessed requirements wastes that pass and lands wide of what the user wanted. So before you author, use **\`ask_user\`** (batch several questions into ONE call) to gather what the canvas needs:
+   - **Purpose & audience** — what is it for, who reads it?
+   - **Canvas type** — infographic, carousel, or board? (Offer the choice unless obvious.)
+   - **Key content / data** — the actual points, numbers, sections, or slides to include. Don't invent data.
+   - **Style / brand** — theme-matched (default) or a specific palette/brand?
+   For open design directions (which layout, which visual approach), present concrete options with **\`propose_alternatives\`** instead of guessing.
+   **Skip questions the user already answered**, and if they gave full detail or explicitly said "just make it / surprise me / your call", go straight to authoring. Keep it to ONE focused round — a short question batch, never a long interview — then build.
 
 2. **Build the canvas in small steps — never one giant tool call.** A canvas is HTML/SVG you emit as tool arguments; a single very large \`canvas_write\` can overrun the output limit, get cut off mid-arguments, and fail. So author it incrementally, and emit each tool call immediately with NO prose preamble (narration competes with the HTML for the same output budget):
    - **2a. First \`canvas_write\`** (type, title, html) = a COMPACT skeleton: the \`<style>\` block, the overall layout, and just the first section or heading. This is the ONLY way to create a canvas — describing it in chat does nothing.

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.0",
+  "version": "0.18.2",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",