@compilr-dev/sdk 0.18.2 → 0.18.3

package/dist/capabilities/packs.js

@@ -236,10 +236,17 @@ export const CAPABILITY_PACKS = {
     canvas: {
         id: 'canvas',
         label: 'Visual Canvas',
-        tools: ['canvas_write', 'canvas_edit', 'canvas_list', 'canvas_get', 'canvas_delete'],
+        tools: [
+            'canvas_write',
+            'canvas_edit',
+            'canvas_list',
+            'canvas_get',
+            'canvas_delete',
+            'canvas_validate',
+        ],
         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.',
+        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.",
         estimatedPromptTokens: 150,
         estimatedToolTokens: 1500,
     },

package/dist/index.d.ts

@@ -45,7 +45,7 @@ export type { Preset } from './presets/index.js';
 export type { AnyTool } from './presets/types.js';
 export { resolveProvider, detectProviderFromEnv, createProviderFromType } from './provider.js';
 export { DEFAULT_MODELS, getContextWindow, DEFAULT_CONTEXT_WINDOW } from './models.js';
-export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER_INFO, isValidTier, type ThinkingFormat, type ModelStatus, type ModelInfo, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, type ProviderMetadata, type OthersProviderModel, PROVIDER_METADATA, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, getOthersProviders, getProviderMetadata, isOthersProvider, } from './models/index.js';
+export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER_INFO, isValidTier, type ThinkingFormat, type ModelStatus, type ModelInfo, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, modelSupportsImages, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, type ProviderMetadata, type OthersProviderModel, PROVIDER_METADATA, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, getOthersProviders, getProviderMetadata, isOthersProvider, } from './models/index.js';
 export { assembleTools, deduplicateTools } from './tools.js';
 export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, } from './meta-tools/index.js';
 export type { MetaToolStats, MetaTools, FallbackOptions } from './meta-tools/index.js';

package/dist/index.js

@@ -83,7 +83,7 @@ export { DEFAULT_MODELS, getContextWindow, DEFAULT_CONTEXT_WINDOW } from './mode
 // =============================================================================
 // Model Registry, Tiers, Providers (full model system)
 // =============================================================================
-export { MODEL_TIERS, TIER_INFO, isValidTier, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, 
+export { MODEL_TIERS, TIER_INFO, isValidTier, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, modelSupportsImages, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, 
 // Model tiers (pure, settings-free)
 getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, PROVIDER_METADATA, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, getOthersProviders, getProviderMetadata, isOthersProvider, } from './models/index.js';
 // =============================================================================

package/dist/models/index.d.ts

@@ -2,6 +2,6 @@
  * Models Module — Barrel Export
  */
 export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER_INFO, isValidTier, } from './types.js';
-export { type ThinkingFormat, type ModelStatus, type ModelInfo, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, } from './model-registry.js';
+export { type ThinkingFormat, type ModelStatus, type ModelInfo, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, modelSupportsImages, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, } from './model-registry.js';
 export { getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, } from './model-tiers.js';
 export { type ProviderMetadata, type OthersProviderModel, PROVIDER_METADATA, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, getOthersProviders, getProviderMetadata, isOthersProvider, } from './providers.js';

package/dist/models/index.js

@@ -4,7 +4,7 @@
 // Types & constants
 export { MODEL_TIERS, TIER_INFO, isValidTier, } from './types.js';
 // Model registry
-export { MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, } from './model-registry.js';
+export { MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, modelSupportsImages, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, } from './model-registry.js';
 // Model tiers (pure, settings-free)
 export { getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, } from './model-tiers.js';
 // Provider metadata

package/dist/models/model-registry.d.ts

@@ -31,6 +31,9 @@ export interface ModelInfo {
     description: string;
     /** Provider this model belongs to */
     provider: ProviderType;
+    /** Whether the model accepts image inputs (vision / multimodal). When unset,
+     *  callers fall back to a provider/id heuristic — see modelSupportsImages(). */
+    supportsImages?: boolean;
     /** Default tier mapping (fast/balanced/powerful) - undefined if not a default */
     defaultTier?: ModelTier;
     /** Thinking block format this model uses */
@@ -72,6 +75,17 @@ export declare function isKnownModel(modelId: string): boolean;
  * Returns false for unknown models (conservative default).
  */
 export declare function isModelSupported(modelId: string): boolean;
+/**
+ * Whether a model accepts image inputs (vision / multimodal).
+ *
+ * Uses the registry's `supportsImages` when set; otherwise infers from the
+ * provider/id — all modern Claude and Gemini are multimodal, as are OpenAI
+ * GPT-4o / GPT-4-turbo / GPT-4.1 / GPT-5; local/text llama·mistral·qwen·deepseek
+ * (and search models) are not. Defaults to FALSE for anything unrecognized —
+ * safe, because the caller then surfaces a warning rather than silently
+ * dropping an attached image (canvas-robustness: image on a text-only model).
+ */
+export declare function modelSupportsImages(modelId: string): boolean;
 /**
  * Get the thinking format for a model.
  * Returns 'none' for unknown models (safe default).

package/dist/models/model-registry.js

@@ -24,6 +24,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Haiku 4.5',
         description: 'Fast, low cost',
         provider: 'claude',
+        supportsImages: true,
         defaultTier: 'fast',
         thinkingFormat: 'claude',
         status: 'supported',
@@ -34,6 +35,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Sonnet 4.6',
         description: 'Balanced (recommended)',
         provider: 'claude',
+        supportsImages: true,
         defaultTier: 'balanced',
         thinkingFormat: 'claude',
         status: 'supported',
@@ -45,6 +47,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Opus 4.6',
         description: 'Most capable',
         provider: 'claude',
+        supportsImages: true,
         defaultTier: 'powerful',
         thinkingFormat: 'claude',
         status: 'supported',
@@ -57,6 +60,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Sonnet 4.5',
         description: 'Previous generation',
         provider: 'claude',
+        supportsImages: true,
         thinkingFormat: 'claude',
         status: 'supported',
         contextWindow: 200000,
@@ -67,6 +71,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Opus 4.5',
         description: 'Previous generation',
         provider: 'claude',
+        supportsImages: true,
         thinkingFormat: 'claude',
         status: 'supported',
         contextWindow: 200000,
@@ -77,6 +82,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Sonnet 4',
         description: 'Previous generation',
         provider: 'claude',
+        supportsImages: true,
         thinkingFormat: 'claude',
         status: 'supported',
         contextWindow: 200000,
@@ -92,6 +98,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Gemini 2.0 Flash',
         description: 'Fast, no thinking',
         provider: 'gemini',
+        supportsImages: true,
         thinkingFormat: 'none',
         status: 'supported',
         contextWindow: 1000000,
@@ -102,6 +109,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Gemini 2.5 Flash Lite',
         description: 'Fast, low cost',
         provider: 'gemini',
+        supportsImages: true,
         defaultTier: 'fast',
         thinkingFormat: 'gemini-v2',
         status: 'supported',
@@ -112,6 +120,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Gemini 2.5 Flash',
         description: 'Balanced (recommended)',
         provider: 'gemini',
+        supportsImages: true,
         defaultTier: 'balanced',
         thinkingFormat: 'gemini-v2',
         status: 'supported',
@@ -122,6 +131,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Gemini 2.5 Pro',
         description: 'Most capable',
         provider: 'gemini',
+        supportsImages: true,
         defaultTier: 'powerful',
         thinkingFormat: 'gemini-v2',
         status: 'supported',
@@ -133,6 +143,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Gemini 3 Flash (Preview)',
         description: 'Preview - may have stability issues',
         provider: 'gemini',
+        supportsImages: true,
         thinkingFormat: 'gemini-v3',
         status: 'supported',
         contextWindow: 1000000,
@@ -143,6 +154,7 @@ export const MODEL_REGISTRY = [
         displayName: 'Gemini 3 Pro (Preview)',
         description: 'Preview - may have stability issues',
         provider: 'gemini',
+        supportsImages: true,
         thinkingFormat: 'gemini-v3',
         status: 'supported',
         contextWindow: 1000000,
@@ -156,6 +168,7 @@ export const MODEL_REGISTRY = [
         displayName: 'GPT-4o',
         description: 'Balanced (recommended)',
         provider: 'openai',
+        supportsImages: true,
         defaultTier: 'balanced',
         thinkingFormat: 'none',
         status: 'supported',
@@ -166,6 +179,7 @@ export const MODEL_REGISTRY = [
         displayName: 'GPT-4o Mini',
         description: 'Fast, low cost',
         provider: 'openai',
+        supportsImages: true,
         defaultTier: 'fast',
         thinkingFormat: 'none',
         status: 'supported',
@@ -176,6 +190,7 @@ export const MODEL_REGISTRY = [
         displayName: 'GPT-4 Turbo',
         description: 'Most capable',
         provider: 'openai',
+        supportsImages: true,
         defaultTier: 'powerful',
         thinkingFormat: 'none',
         status: 'supported',
@@ -187,6 +202,7 @@ export const MODEL_REGISTRY = [
         displayName: 'GPT-5 Nano',
         description: 'Fast, experimental',
         provider: 'openai',
+        supportsImages: true,
         thinkingFormat: 'none',
         status: 'experimental',
         contextWindow: 128000,
@@ -197,6 +213,7 @@ export const MODEL_REGISTRY = [
         displayName: 'GPT-5 Mini',
         description: 'Balanced, experimental',
         provider: 'openai',
+        supportsImages: true,
         thinkingFormat: 'none',
         status: 'experimental',
         contextWindow: 128000,
@@ -207,6 +224,7 @@ export const MODEL_REGISTRY = [
         displayName: 'GPT-5.2',
         description: 'Most capable, experimental',
         provider: 'openai',
+        supportsImages: true,
         thinkingFormat: 'none',
         status: 'experimental',
         contextWindow: 128000,
@@ -499,6 +517,27 @@ export function isModelSupported(modelId) {
     const model = getModelInfo(modelId);
     return model?.status === 'supported';
 }
+/**
+ * Whether a model accepts image inputs (vision / multimodal).
+ *
+ * Uses the registry's `supportsImages` when set; otherwise infers from the
+ * provider/id — all modern Claude and Gemini are multimodal, as are OpenAI
+ * GPT-4o / GPT-4-turbo / GPT-4.1 / GPT-5; local/text llama·mistral·qwen·deepseek
+ * (and search models) are not. Defaults to FALSE for anything unrecognized —
+ * safe, because the caller then surfaces a warning rather than silently
+ * dropping an attached image (canvas-robustness: image on a text-only model).
+ */
+export function modelSupportsImages(modelId) {
+    const info = getModelInfo(modelId);
+    if (info?.supportsImages !== undefined)
+        return info.supportsImages;
+    const id = modelId.toLowerCase();
+    if (id.includes('claude') || id.includes('gemini'))
+        return true;
+    if (/gpt-4o|gpt-4-turbo|gpt-4\.1|gpt-5/.test(id))
+        return true;
+    return false;
+}
 /**
  * Get the thinking format for a model.
  * Returns 'none' for unknown models (safe default).

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

@@ -11,7 +11,7 @@
  * (ICanvasRepository); the current project is resolved like the document tools.
  */
 import type { PlatformToolsConfig } from '../context.js';
-import type { ControlManifest } from '../../canvas/types.js';
+import type { CanvasType, 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
@@ -24,6 +24,12 @@ import type { ControlManifest } from '../../canvas/types.js';
  * CSP actually blocks.
  */
 export declare function validateCanvasHtml(html: string): string | null;
+export interface CanvasIssue {
+    level: 'error' | 'warn';
+    message: string;
+}
+/** Run deterministic static checks on canvas content. No rendering. */
+export declare function runCanvasChecks(html: string, type: CanvasType): CanvasIssue[];
 export declare function createCanvasTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
     type: string;
     title: string;

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

@@ -95,6 +95,113 @@ export function validateCanvasHtml(html) {
     }
     return null;
 }
+/** Read a numeric `prop: Npx` from an inline style string. */
+function pxProp(style, prop) {
+    const m = new RegExp(`(?:^|;)\\s*${prop}\\s*:\\s*(-?[\\d.]+)px`, 'i').exec(style);
+    return m ? parseFloat(m[1]) : null;
+}
+/** Parse a board's declared width/height from its `data-board` element's style. */
+function parseBoardBounds(tag) {
+    const styleM = /\bstyle\s*=\s*(['"])([\s\S]*?)\1/i.exec(tag);
+    if (!styleM)
+        return null;
+    const w = pxProp(styleM[2], 'width');
+    const h = pxProp(styleM[2], 'height');
+    return w !== null && h !== null ? { w, h } : null;
+}
+/** Best-effort: inline-positioned nodes (left+top px) that fall outside bounds. */
+function offCanvasNodes(src, bounds) {
+    const out = [];
+    const re = /style\s*=\s*(['"])([^'"]*?\bleft\s*:\s*-?[\d.]+px[^'"]*?)\1/gi;
+    let m;
+    let seen = 0;
+    while ((m = re.exec(src)) !== null && seen < 200 && out.length < 5) {
+        seen++;
+        const style = m[2];
+        const left = pxProp(style, 'left');
+        const top = pxProp(style, 'top');
+        if (left === null || top === null)
+            continue;
+        const w = pxProp(style, 'width') ?? 0;
+        const h = pxProp(style, 'height') ?? 0;
+        if (left < 0 || top < 0 || left + w > bounds.w + 1 || top + h > bounds.h + 1) {
+            out.push(`A node at (${String(Math.round(left))}, ${String(Math.round(top))})` +
+                (w || h ? ` sized ${String(Math.round(w))}×${String(Math.round(h))}` : '') +
+                ` extends outside the ${String(bounds.w)}×${String(bounds.h)} board — move it inside or enlarge data-board.`);
+        }
+    }
+    return out;
+}
+/** Run deterministic static checks on canvas content. No rendering. */
+export function runCanvasChecks(html, type) {
+    const issues = [];
+    const src = html.trim();
+    if (!src) {
+        issues.push({ level: 'error', message: 'Canvas content is empty.' });
+        return issues;
+    }
+    const hasTag = /<[a-z][\s\S]*>/i.test(src);
+    if (!hasTag) {
+        issues.push({
+            level: 'error',
+            message: 'No HTML/SVG tags — the canvas renders raw HTML/SVG, not plain text or Markdown.',
+        });
+    }
+    // Won't-render shapes (Mermaid / Markdown / external CDN) — reuse the write guard.
+    const shape = validateCanvasHtml(src);
+    if (shape)
+        issues.push({ level: 'error', message: shape });
+    // Sparse / likely-incomplete.
+    const elementCount = (src.match(/<[a-z][a-z0-9]*\b/gi) ?? []).length;
+    if (hasTag && (src.length < 200 || elementCount < 3)) {
+        issues.push({
+            level: 'warn',
+            message: `Looks sparse (${String(elementCount)} elements, ${String(src.length)} chars) — is the canvas fully composed?`,
+        });
+    }
+    // Theme-awareness: hardcoded colors with no theme tokens won't adapt to the user's theme.
+    const hardColors = (src.match(/#[0-9a-f]{3,8}\b|\b(?:rgb|rgba|hsl|hsla)\s*\(/gi) ?? []).length;
+    const themeTokens = (src.match(/var\(\s*--canvas-/gi) ?? []).length;
+    if (hardColors >= 6 && themeTokens === 0) {
+        issues.push({
+            level: 'warn',
+            message: `${String(hardColors)} hardcoded colors and no theme tokens — the canvas won't adapt to the user's theme. ` +
+                'Use var(--canvas-accent | secondary | fg | bg | muted | border | card) for themeable surfaces (keep a fixed color only where one is intended).',
+        });
+    }
+    // Type-specific structure.
+    if (type === 'board') {
+        const board = /<[^>]*\bdata-board\b[^>]*>/i.exec(src);
+        if (!board) {
+            issues.push({
+                level: 'error',
+                message: 'A board must wrap its nodes in <div data-board style="position:relative;width:Wpx;height:Hpx"> — those bounds drive Fit and Export.',
+            });
+        }
+        else {
+            const bounds = parseBoardBounds(board[0]);
+            if (!bounds) {
+                issues.push({
+                    level: 'warn',
+                    message: 'data-board has no parseable width/height in its style — Fit/Export fall back to a default. Set width:Wpx;height:Hpx.',
+                });
+            }
+            else {
+                for (const msg of offCanvasNodes(src, bounds))
+                    issues.push({ level: 'warn', message: msg });
+            }
+        }
+    }
+    else if (type === 'carousel') {
+        if (!/\bdata-sheet\b/i.test(src)) {
+            issues.push({
+                level: 'warn',
+                message: 'No [data-sheet] elements — a carousel paginates on data-sheet blocks; without them it renders as one sheet.',
+            });
+        }
+    }
+    return issues;
+}
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function createCanvasTools(config) {
     const ctx = config.context;
@@ -396,5 +503,85 @@ export function createCanvasTools(config) {
             }
         },
     });
-    return [canvasWriteTool, canvasEditTool, canvasListTool, canvasGetTool, canvasDeleteTool];
+    // ---------------------------------------------------------------------------
+    // canvas_validate — deterministic self-review
+    // ---------------------------------------------------------------------------
+    const canvasValidateTool = defineTool({
+        name: 'canvas_validate',
+        description: 'Self-review a canvas for problems — a fast, deterministic STATIC check (no rendering). ' +
+            'Run it right after canvas_write to catch structural/technical faults: content that cannot render ' +
+            '(Mermaid/Markdown/external CDN), a board missing its data-board bounds or with nodes off-canvas, ' +
+            'sparse/empty output, and hardcoded colors that ignore the theme tokens. Pass canvas_id to check a ' +
+            'stored canvas, or html+type to check before writing. It does NOT judge visual/aesthetic quality — ' +
+            'errors mean "likely renders broken", warnings are quality nudges.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: {
+                    type: 'number',
+                    description: 'Stored canvas to validate. Omit to validate html+type directly.',
+                },
+                html: {
+                    type: 'string',
+                    description: 'Raw HTML/SVG to validate (when not using canvas_id).',
+                },
+                type: {
+                    type: 'string',
+                    enum: CANVAS_TYPES,
+                    description: 'Canvas type (required when passing html; defaults to infographic).',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                let html;
+                let type;
+                if (input.canvas_id !== undefined) {
+                    const c = await canvases.getById(input.canvas_id);
+                    if (!c)
+                        return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                    html = c.content;
+                    type = c.type;
+                }
+                else if (input.html !== undefined) {
+                    html = input.html;
+                    type = input.type ?? 'infographic';
+                }
+                else {
+                    return createErrorResult('Provide canvas_id (a stored canvas) or html (+ type) to validate.');
+                }
+                const issues = runCanvasChecks(html, type);
+                if (issues.length === 0) {
+                    return createSuccessResult('✓ Passed all static checks — no structural/technical issues. (Visual/aesthetic review is a separate pass.)');
+                }
+                const errors = issues.filter((i) => i.level === 'error');
+                const warns = issues.filter((i) => i.level === 'warn');
+                const lines = [];
+                if (errors.length > 0) {
+                    lines.push(`${String(errors.length)} error(s) — likely to render broken:`);
+                    for (const e of errors)
+                        lines.push(`  ✗ ${e.message}`);
+                }
+                if (warns.length > 0) {
+                    lines.push(`${String(warns.length)} warning(s):`);
+                    for (const w of warns)
+                        lines.push(`  ⚠ ${w.message}`);
+                }
+                lines.push('', 'Fix the errors (they break rendering); address warnings where they apply, then re-validate.');
+                return createSuccessResult(lines.join('\n'));
+            }
+            catch (error) {
+                return createErrorResult(`Failed to validate canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    return [
+        canvasWriteTool,
+        canvasEditTool,
+        canvasListTool,
+        canvasGetTool,
+        canvasDeleteTool,
+        canvasValidateTool,
+    ];
 }

package/dist/skills/canvas-skills.js

@@ -67,7 +67,9 @@ 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. **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.
+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.)
+
+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.
 
 ## 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

@@ -288,7 +288,14 @@ export const TOOL_GROUPS = {
         label: 'Visual Canvas',
         // Canvas tools are defined in @compilr-dev/sdk (createPlatformTools), not in
         // the agents-lib TOOL_NAMES registry, so they are referenced by literal name.
-        tools: ['canvas_write', 'canvas_edit', 'canvas_list', 'canvas_get', 'canvas_delete'],
+        tools: [
+            'canvas_write',
+            'canvas_edit',
+            'canvas_list',
+            'canvas_get',
+            'canvas_delete',
+            'canvas_validate',
+        ],
         readOnly: false,
         tier: 'meta',
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -25,6 +25,10 @@
     "./canvas": {
       "types": "./dist/canvas/index.d.ts",
       "import": "./dist/canvas/index.js"
+    },
+    "./models": {
+      "types": "./dist/models/index.d.ts",
+      "import": "./dist/models/index.js"
     }
   },
   "files": [