@compilr-dev/sdk 0.18.10 → 0.19.0

package/dist/canvas/quality-checks.js

@@ -0,0 +1,217 @@
+import { parseColor, contrastRatio, isNeutral, hueAngle, AA_TEXT } from './color.js';
+/** Every `style="…"` attribute body and every `{…}` CSS rule body, as separate scopes. */
+function declarationScopes(html) {
+    const scopes = [];
+    for (const m of html.matchAll(/style\s*=\s*"([^"]*)"/gi))
+        scopes.push(m[1]);
+    for (const m of html.matchAll(/style\s*=\s*'([^']*)'/gi))
+        scopes.push(m[1]);
+    for (const m of html.matchAll(/\{([^{}]*)\}/g))
+        scopes.push(m[1]);
+    return scopes;
+}
+const declaration = (scope, property) => {
+    const m = property.exec(scope);
+    return m ? m[1].trim() : null;
+};
+const TEXT_COLOR = /(?:^|[;{\s])color\s*:\s*([^;}]+)/i;
+const BACKGROUND = /(?:^|[;{\s])background(?:-color)?\s*:\s*([^;}]+)/i;
+/**
+ * The custom properties a value actually USES — primaries only, never fallbacks.
+ *
+ * ⚠️ THIS EXISTS BECAUSE A SUBSTRING TEST GETS IT BACKWARDS. The handoff tells authors to
+ * write `var(--canvas-surface-1, var(--canvas-card))` so a canvas degrades on a host
+ * without the ramp, and to KEEP that fallback afterwards. A plain
+ * `/var\(--canvas-card/` test matches the fallback and fires the surface error on the
+ * exact corrected form the error message asks for — a validator that punishes compliance
+ * teaches an agent to ignore it. Caught by the negative test, not by reading the regex.
+ *
+ * So: walk to each `var(`, take the name up to the first comma, then skip the whole
+ * fallback by tracking paren depth.
+ */
+export function primaryVarNames(value) {
+    const names = [];
+    for (let i = value.indexOf('var('); i !== -1; i = value.indexOf('var(', i)) {
+        let j = i + 4;
+        while (j < value.length && /\s/.test(value[j]))
+            j++;
+        let name = '';
+        while (j < value.length && /[-\w]/.test(value[j]))
+            name += value[j++];
+        if (name.startsWith('--'))
+            names.push(name);
+        // Skip to the matching close paren — the fallback is deliberately not scanned.
+        let depth = 1;
+        while (j < value.length && depth > 0) {
+            if (value[j] === '(')
+                depth++;
+            else if (value[j] === ')')
+                depth--;
+            j++;
+        }
+        i = j;
+    }
+    return names;
+}
+const usesVar = (value, name) => primaryVarNames(value).some((n) => n.toLowerCase() === name);
+/**
+ * A card that shares its ground's value is a rectangle of text.
+ *
+ * ⚠️ This flags the TOKEN PAIRING, not a measured delta, and that is the whole point:
+ * whether `--canvas-card` is 0.0% or 2.1% from `--canvas-bg` depends on the user's
+ * theme, and it is under 4% on every palette anyone measured. The fix is the same in
+ * all of them — use the ramp — so the check needs no palette to be right.
+ */
+export function checkSurfaceTokens(html) {
+    const usesCardAsSurface = declarationScopes(html).some((scope) => {
+        const bg = declaration(scope, BACKGROUND);
+        return bg !== null && usesVar(bg, '--canvas-card');
+    });
+    if (!usesCardAsSurface)
+        return [];
+    return [
+        {
+            level: 'error',
+            message: 'A card is filled with var(--canvas-card) over a var(--canvas-bg) ground. On a ' +
+                'theme-derived palette those two sit within a few percent of each other, so the ' +
+                'card disappears and only its border holds the layout together. Use the elevation ' +
+                'ramp instead: background: var(--canvas-surface-1, var(--canvas-card)) for a raised ' +
+                'card, var(--canvas-surface-2, var(--canvas-card)) for an inset area (tables, code), ' +
+                'and border-color: var(--canvas-hairline, var(--canvas-border)). Keep the fallbacks ' +
+                'so the canvas still renders on a host that has not shipped the ramp.',
+        },
+    ];
+}
+/** Near-white, for the "white on the accent" trap. */
+function isNearWhite(value) {
+    if (/^\s*white\s*$/i.test(value))
+        return true;
+    const c = parseColor(value);
+    return c !== null && c.r > 0.85 && c.g > 0.85 && c.b > 0.85;
+}
+/**
+ * Text that cannot be read on the surface it actually sits on.
+ *
+ * Two halves, both palette-free:
+ *   - a literal colour on a literal background, measured exactly;
+ *   - white on `var(--canvas-accent)`, which is a pairing rather than a measurement —
+ *     the accent is a mid-tone in every theme we ship (#FF5722 gives 3.2:1), so the pair
+ *     is wrong whatever it resolves to.
+ */
+export function checkTextContrast(html) {
+    const issues = [];
+    let whiteOnAccent = false;
+    const failures = [];
+    for (const scope of declarationScopes(html)) {
+        const fg = declaration(scope, TEXT_COLOR);
+        const bg = declaration(scope, BACKGROUND);
+        if (fg === null || bg === null)
+            continue;
+        if (usesVar(bg, '--canvas-accent') && isNearWhite(fg)) {
+            whiteOnAccent = true;
+            continue;
+        }
+        const fgc = parseColor(fg);
+        const bgc = parseColor(bg);
+        // ⚠️ A null here means a token or a keyword, NOT a failure — skip rather than guess.
+        if (!fgc || !bgc)
+            continue;
+        const ratio = contrastRatio(fgc, bgc);
+        if (ratio < AA_TEXT) {
+            failures.push(`${fg.trim()} on ${bg.trim()} — ${ratio.toFixed(1)}:1`);
+        }
+    }
+    if (whiteOnAccent) {
+        issues.push({
+            level: 'error',
+            message: 'White text on var(--canvas-accent). The accent is a mid-tone in every theme — ' +
+                'on the default it is 3.2:1, below the 4.5:1 floor. Either put a dark ink label on ' +
+                'the accent fill, or drop the fill and use the accent as the text colour on the ' +
+                'page ground.',
+        });
+    }
+    if (failures.length) {
+        issues.push({
+            level: 'error',
+            message: `Text below the 4.5:1 floor against the surface it sits on: ${failures.slice(0, 4).join('; ')}` +
+                (failures.length > 4 ? ` (+${String(failures.length - 4)} more)` : '') +
+                '. Check a muted grey against the INSET surface, not the page — one that passes on ' +
+                'white will fail on surface-2.',
+        });
+    }
+    return issues;
+}
+/** Hues within this many degrees are the same hue wearing two tints. */
+const HUE_BUCKET = 30;
+/**
+ * More hues than reasons.
+ *
+ * ⚠️ Greys never count. They are the ground a composition sits on, and a palette of six
+ * greys is a perfectly good canvas — what makes one look machine-made is four competing
+ * *hues* with nothing to distinguish. Warn, never error: multiple hues are legitimate
+ * when they encode categories a reader must tell apart.
+ */
+export function checkHueCount(html) {
+    const buckets = new Set();
+    for (const m of html.matchAll(/#[0-9a-f]{3,8}\b|\b(?:rgb|hsl)a?\s*\([^)]*\)/gi)) {
+        const c = parseColor(m[0]);
+        if (!c || isNeutral(c))
+            continue;
+        buckets.add(Math.round(hueAngle(c) / HUE_BUCKET));
+    }
+    if (buckets.size <= 2)
+        return [];
+    return [
+        {
+            level: 'warn',
+            message: `${String(buckets.size)} distinct hues are hardcoded in this canvas. Count the hues, then ` +
+                'count the reasons — if there are more hues than things a reader must tell apart, ' +
+                'colour is decoration. One accent marking the finding, and greys for everything else.',
+        },
+    ];
+}
+/**
+ * A Tweak the user can drag that changes nothing.
+ *
+ * ⚠️ SKIPPED ENTIRELY WHEN THE CANVAS DEFINES `applyParams`. That is the host bridge's
+ * fourth binding path — a canvas can take the whole params object in JS and do what it
+ * likes with it, in which case no static reference to the param name need exist. Without
+ * this guard the check would report confident errors about a legitimate pattern, which is
+ * worse than not checking at all.
+ */
+export function checkDeadTweaks(html, manifest) {
+    const controls = manifest?.controls ?? [];
+    if (controls.length === 0)
+        return [];
+    if (/\bapplyParams\s*[=:(]/.test(html))
+        return [];
+    const dead = controls
+        .map((c) => c.param)
+        .filter((param) => {
+        if (!param)
+            return false;
+        const safe = param.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const bound = new RegExp(`var\\(\\s*--${safe}\\b|data-bind\\s*=\\s*["']${safe}["']|data-show\\s*=\\s*["']${safe}["']`, 'i');
+        return !bound.test(html);
+    });
+    if (dead.length === 0)
+        return [];
+    return [
+        {
+            level: 'error',
+            message: `Tweak${dead.length > 1 ? 's' : ''} declared but bound to nothing: ${dead.join(', ')}. ` +
+                'A control the user can drag that changes nothing reads as a broken canvas. Either ' +
+                'reference it — var(--param) in CSS, data-bind="param" for text, data-show="param" ' +
+                'to toggle — or remove it from the manifest.',
+        },
+    ];
+}
+/** Every quality check, in the order their messages should be read. */
+export function runQualityChecks(html, manifest) {
+    return [
+        ...checkSurfaceTokens(html),
+        ...checkTextContrast(html),
+        ...checkHueCount(html),
+        ...checkDeadTweaks(html, manifest),
+    ];
+}

package/dist/canvas/ramp.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The surface ramp the host injects.
+ *
+ * ⚠️ WHY THE HOST AND NOT CSS. A single `color-mix` cannot serve both polarities: a light
+ * theme's ground has no headroom above it (Catppuccin Latte sits at ~95% lightness, so a
+ * card 6% "above" it would be past white), while a dark theme's has plenty. CSS cannot
+ * branch on a palette's polarity. Whatever computes this has to know the luminance, so it
+ * lives here — pure, testable, and shared with the validator so the two cannot disagree
+ * about what "5–7% apart" means.
+ *
+ * ⚠️ THE GROUND MOVES ONLY WHEN IT MUST. The handoff's worked examples darken the ground
+ * in every case; this does it only when there is no room for the raised surface, so a
+ * dark theme's canvas keeps exactly the background its theme specifies and nothing about
+ * an existing canvas shifts. Latte has no room, so it darkens — there is no alternative
+ * that also keeps the card raised, which is the point of the ramp.
+ */
+import { type Rgb } from './color.js';
+export interface SurfaceRamp {
+    /** The page ground. Equal to the input unless there was no room for the ramp. */
+    bg: string;
+    /** Raised — cards. */
+    surface1: string;
+    /** Inset — tables, code, an app screen's work area. */
+    surface2: string;
+    /** 1px borders. */
+    hairline: string;
+}
+/**
+ * The same colour at a different perceived lightness.
+ *
+ * ⚠️ Binary search over a mix toward white or black rather than an OKLab inverse. It
+ * keeps the hue of the ground (a tinted terminal ground stays tinted, which is most of
+ * why these palettes look like themselves) and cannot produce an out-of-gamut value,
+ * which an inverse transform can.
+ */
+export declare function withLightness(color: Rgb, targetL: number): Rgb;
+/**
+ * Derive the three ramp tokens from a theme's ground and foreground.
+ *
+ * Raised is always lighter and inset always darker, in both polarities — a card that
+ * recedes from its page does not read as a card. When the ground cannot support both
+ * steps, the ground itself is moved just far enough to make room, and the returned `bg`
+ * says so.
+ */
+export declare function deriveSurfaceRamp(bgInput: string, fgInput: string): SurfaceRamp | null;

package/dist/canvas/ramp.js

@@ -0,0 +1,98 @@
+/**
+ * The surface ramp the host injects.
+ *
+ * ⚠️ WHY THE HOST AND NOT CSS. A single `color-mix` cannot serve both polarities: a light
+ * theme's ground has no headroom above it (Catppuccin Latte sits at ~95% lightness, so a
+ * card 6% "above" it would be past white), while a dark theme's has plenty. CSS cannot
+ * branch on a palette's polarity. Whatever computes this has to know the luminance, so it
+ * lives here — pure, testable, and shared with the validator so the two cannot disagree
+ * about what "5–7% apart" means.
+ *
+ * ⚠️ THE GROUND MOVES ONLY WHEN IT MUST. The handoff's worked examples darken the ground
+ * in every case; this does it only when there is no room for the raised surface, so a
+ * dark theme's canvas keeps exactly the background its theme specifies and nothing about
+ * an existing canvas shifts. Latte has no room, so it darkens — there is no alternative
+ * that also keeps the card raised, which is the point of the ramp.
+ */
+import { parseColor, oklabLightness, SURFACE_DELTA_TARGET, HAIRLINE_MIN_PCT, HAIRLINE_MAX_PCT, } from './color.js';
+const hex = (n) => Math.round(Math.min(1, Math.max(0, n)) * 255)
+    .toString(16)
+    .padStart(2, '0');
+const toHex = ({ r, g, b }) => `#${hex(r)}${hex(g)}${hex(b)}`;
+const mix = (a, b, t) => ({
+    r: a.r + (b.r - a.r) * t,
+    g: a.g + (b.g - a.g) * t,
+    b: a.b + (b.b - a.b) * t,
+});
+const WHITE = { r: 1, g: 1, b: 1 };
+const BLACK = { r: 0, g: 0, b: 0 };
+/**
+ * The same colour at a different perceived lightness.
+ *
+ * ⚠️ Binary search over a mix toward white or black rather than an OKLab inverse. It
+ * keeps the hue of the ground (a tinted terminal ground stays tinted, which is most of
+ * why these palettes look like themselves) and cannot produce an out-of-gamut value,
+ * which an inverse transform can.
+ */
+export function withLightness(color, targetL) {
+    const current = oklabLightness(color);
+    if (Math.abs(current - targetL) < 0.001)
+        return color;
+    const toward = targetL > current ? WHITE : BLACK;
+    let lo = 0;
+    let hi = 1;
+    let out = color;
+    for (let i = 0; i < 24; i++) {
+        const mid = (lo + hi) / 2;
+        out = mix(color, toward, mid);
+        const l = oklabLightness(out);
+        if (Math.abs(l - targetL) < 0.0005)
+            break;
+        if (targetL > current ? l < targetL : l > targetL)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return out;
+}
+/**
+ * Derive the three ramp tokens from a theme's ground and foreground.
+ *
+ * Raised is always lighter and inset always darker, in both polarities — a card that
+ * recedes from its page does not read as a card. When the ground cannot support both
+ * steps, the ground itself is moved just far enough to make room, and the returned `bg`
+ * says so.
+ */
+export function deriveSurfaceRamp(bgInput, fgInput) {
+    const bg = parseColor(bgInput);
+    const fg = parseColor(fgInput);
+    if (!bg || !fg)
+        return null;
+    const step = SURFACE_DELTA_TARGET / 100;
+    let ground = oklabLightness(bg);
+    /*
+      Keep both steps inside the gamut by sliding the ground, never by shrinking the step —
+      a 3% ramp is the defect this exists to fix, so the separation is the invariant and the
+      ground's exact value is not.
+    */
+    const headroom = 1 - (ground + step);
+    const footroom = ground - step;
+    if (headroom < 0)
+        ground += headroom;
+    else if (footroom < 0)
+        ground -= footroom;
+    const groundRgb = withLightness(bg, ground);
+    /*
+      The hairline sits a fixed fraction of the way toward the foreground. Terminal palettes
+      derive their border from a comment or selection colour, which lands 35–100% of the way
+      there — that is the "hard borders" complaint, and it is why this ignores
+      --canvas-border entirely rather than trying to soften it.
+    */
+    const hairlineMix = (HAIRLINE_MIN_PCT + HAIRLINE_MAX_PCT) / 2 / 100;
+    return {
+        bg: toHex(groundRgb),
+        surface1: toHex(withLightness(groundRgb, ground + step)),
+        surface2: toHex(withLightness(groundRgb, ground - step)),
+        hairline: toHex(mix(groundRgb, fg, hairlineMix)),
+    };
+}

package/dist/capabilities/packs.js

@@ -244,11 +244,25 @@ export const CAPABILITY_PACKS = {
             'canvas_delete',
             'canvas_validate',
             'canvas_screenshot',
+            'canvas_guide',
+            'canvas_asset_add',
+            'canvas_asset_list',
+            'canvas_asset_delete',
         ],
         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 (static) then canvas_screenshot to SEE the render (vision models) — fix overflow/readability with canvas_edit.',
-        estimatedPromptTokens: 150,
+        promptSnippet: 'Visual canvases (infographic/carousel/board) rendered from sandboxed HTML/SVG. ' +
+            // ⚠️ FIRST, and stated as a requirement rather than a suggestion. The craft guides
+            // used to be reachable only when a user typed /canvas, so most canvases were
+            // authored with no design guidance at all — see canvas_guide.
+            'START by calling canvas_guide("canvas") — the design rules live there, not here, and a ' +
+            'canvas authored without them renders correctly and still reads as generic. Then ' +
+            'canvas_guide on the type you pick. ' +
+            // ⚠️ Real images go in as ASSETS, never as base64 in the markup.
+            'When the user has supplied real images, put them in with canvas_asset_add and reference ' +
+            'them as <img src="asset:REF"> — never paste base64, never draw a grey box instead. ' +
+            '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: 190,
         estimatedToolTokens: 1500,
     },
     plans: {

package/dist/platform/context.d.ts

@@ -45,8 +45,22 @@ export interface PlatformHooks {
 export interface PlatformToolsConfig {
     /** Data access layer */
     context: PlatformContext;
-    /** Working directory override (defaults to process.cwd()) */
-    cwd?: string;
+    /**
+     * Working directory override (defaults to process.cwd()).
+     * Accepts a getter, because platform tools are memoised and a host's active
+     * project can change after they are built.
+     */
+    cwd?: string | (() => string | undefined | null);
     /** Optional hooks for CLI-specific side effects */
     hooks?: PlatformHooks;
 }
+/**
+ * Resolve a `cwd` that may be a value or a getter.
+ *
+ * ⚠️ Platform tools are built once and memoised by every host, so a plain string is
+ * captured at construction. In Desktop that meant relative paths resolved against
+ * whichever project was open when the tools were first requested — for the rest of the
+ * session, across every project switch. Hosts whose working directory moves pass a
+ * getter; this is the one place that unwraps it.
+ */
+export declare function resolveCwd(cwd?: string | (() => string | undefined | null)): string;

package/dist/platform/context.js

@@ -4,4 +4,16 @@
  * Provides a single entry point for data access, abstracting over the
  * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
  */
-export {};
+/**
+ * Resolve a `cwd` that may be a value or a getter.
+ *
+ * ⚠️ Platform tools are built once and memoised by every host, so a plain string is
+ * captured at construction. In Desktop that meant relative paths resolved against
+ * whichever project was open when the tools were first requested — for the rest of the
+ * session, across every project switch. Hosts whose working directory moves pass a
+ * getter; this is the one place that unwraps it.
+ */
+export function resolveCwd(cwd) {
+    const value = typeof cwd === 'function' ? cwd() : cwd;
+    return value ?? process.cwd();
+}

package/dist/platform/repositories.d.ts

@@ -7,6 +7,7 @@
  */
 import type { Project, WorkItem, WorkItemComment, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateCommentInput, UpdateCommentInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, ProjectStatus, WorkItemType, WorkItemStatus, DocumentType, PlanStatus } from './types.js';
 import type { CanvasRecord, CanvasSummary, CreateCanvasInput, UpdateCanvasInput } from '../canvas/types.js';
+import type { CanvasAsset, CreateCanvasAssetInput } from '../canvas/assets.js';
 export interface IProjectRepository {
     create(input: CreateProjectInput): Promise<Project>;
     getById(id: number): Promise<Project | null>;
@@ -53,6 +54,9 @@ export interface ICanvasRepository {
     listByProject(projectId: number): Promise<CanvasSummary[]>;
     update(id: number, input: UpdateCanvasInput): Promise<CanvasRecord | null>;
     delete(id: number): Promise<boolean>;
+    addAsset?(input: CreateCanvasAssetInput): Promise<CanvasAsset>;
+    listAssets?(canvasId: number): Promise<CanvasAsset[]>;
+    deleteAsset?(canvasId: number, ref: string): Promise<boolean>;
 }
 export interface IPlanRepository {
     create(input: CreatePlanInput): Promise<Plan>;

package/dist/platform/sqlite/canvas-repository.d.ts

@@ -5,6 +5,7 @@
  * SQL reserved word, so it is always quoted as "values" in statements.
  */
 import type Database from 'better-sqlite3';
+import type { CanvasAsset, CreateCanvasAssetInput } from '../../canvas/assets.js';
 import type { ICanvasRepository } from '../repositories.js';
 import type { CanvasRecord, CanvasSummary, CreateCanvasInput, UpdateCanvasInput } from '../../canvas/types.js';
 export declare class SQLiteCanvasRepository implements ICanvasRepository {
@@ -15,4 +16,12 @@ export declare class SQLiteCanvasRepository implements ICanvasRepository {
     listByProject(projectId: number): Promise<CanvasSummary[]>;
     update(id: number, input: UpdateCanvasInput): Promise<CanvasRecord | null>;
     delete(id: number): Promise<boolean>;
+    /**
+     * ⚠️ UPSERT on (canvas_id, ref). Re-adding the same handle REPLACES the image rather
+     * than failing on the unique index — an agent correcting a photo should not have to
+     * delete first, and a half-applied fix is worse than an overwrite.
+     */
+    addAsset(input: CreateCanvasAssetInput): Promise<CanvasAsset>;
+    listAssets(canvasId: number): Promise<CanvasAsset[]>;
+    deleteAsset(canvasId: number, ref: string): Promise<boolean>;
 }

package/dist/platform/sqlite/canvas-repository.js

@@ -92,4 +92,56 @@ export class SQLiteCanvasRepository {
         const result = this.db.prepare('DELETE FROM canvases WHERE id = ?').run(id);
         return Promise.resolve(result.changes > 0);
     }
+    // ---------------------------------------------------------------------------
+    // Assets — images stored beside the canvas, referenced from its markup as
+    // `asset:<ref>` and substituted by the host at render and export.
+    // ---------------------------------------------------------------------------
+    /**
+     * ⚠️ UPSERT on (canvas_id, ref). Re-adding the same handle REPLACES the image rather
+     * than failing on the unique index — an agent correcting a photo should not have to
+     * delete first, and a half-applied fix is worse than an overwrite.
+     */
+    addAsset(input) {
+        this.db
+            .prepare(`INSERT INTO canvas_assets (canvas_id, ref, media_type, data, width, height, bytes, source_path)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(canvas_id, ref) DO UPDATE SET
+           media_type = excluded.media_type,
+           data = excluded.data,
+           width = excluded.width,
+           height = excluded.height,
+           bytes = excluded.bytes,
+           source_path = excluded.source_path`)
+            .run(input.canvasId, input.ref, input.mediaType, input.data, input.width ?? null, input.height ?? null, input.bytes, input.sourcePath ?? null);
+        const row = this.db
+            .prepare('SELECT * FROM canvas_assets WHERE canvas_id = ? AND ref = ?')
+            .get(input.canvasId, input.ref);
+        return Promise.resolve(toAsset(row));
+    }
+    listAssets(canvasId) {
+        const rows = this.db
+            .prepare('SELECT * FROM canvas_assets WHERE canvas_id = ? ORDER BY id')
+            .all(canvasId);
+        return Promise.resolve(rows.map(toAsset));
+    }
+    deleteAsset(canvasId, ref) {
+        const result = this.db
+            .prepare('DELETE FROM canvas_assets WHERE canvas_id = ? AND ref = ?')
+            .run(canvasId, ref);
+        return Promise.resolve(result.changes > 0);
+    }
+}
+function toAsset(row) {
+    return {
+        id: row.id,
+        canvasId: row.canvas_id,
+        ref: row.ref,
+        mediaType: row.media_type,
+        data: row.data,
+        width: row.width ?? undefined,
+        height: row.height ?? undefined,
+        bytes: row.bytes,
+        sourcePath: row.source_path ?? undefined,
+        createdAt: new Date(row.created_at),
+    };
 }

package/dist/platform/sqlite/db.js

@@ -180,4 +180,33 @@ function runMigrations(db, fromVersion, toVersion) {
         db.exec(`ALTER TABLE canvases ADD COLUMN page_size TEXT;`);
         db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(9);
     }
+    if (fromVersion < 10 && toVersion >= 10) {
+        /*
+          Canvas assets — images stored BESIDE a canvas rather than inside it.
+    
+          ⚠️ The markup references `asset:<ref>` and the host substitutes a data URI at render
+          and at export. Inlining base64 into `content` would also render (the CSP allows
+          data:) but would put hundreds of KB in the middle of a document agents read as an
+          outline and patch with str_replace — the editing discipline that keeps canvas
+          authoring reliable stops working at that size.
+        */
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS canvas_assets (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        canvas_id INTEGER NOT NULL,
+        ref TEXT NOT NULL,
+        media_type TEXT NOT NULL,
+        data TEXT NOT NULL,
+        width INTEGER,
+        height INTEGER,
+        bytes INTEGER NOT NULL,
+        source_path TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (canvas_id) REFERENCES canvases(id) ON DELETE CASCADE
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_canvas_assets_ref
+        ON canvas_assets(canvas_id, ref);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(10);
+    }
 }

package/dist/platform/sqlite/schema.d.ts

@@ -4,7 +4,7 @@
  * Shared between CLI and Desktop — both access ~/.compilr-dev/projects.db
  * Schema version must be kept in sync across all consumers.
  */
-export declare const SCHEMA_VERSION = 9;
+export declare const SCHEMA_VERSION = 10;
 export declare const SCHEMA_SQL = "\n-- Schema version tracking\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\n-- Projects table\nCREATE TABLE IF NOT EXISTS projects (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  name TEXT UNIQUE NOT NULL,\n  display_name TEXT NOT NULL,\n  description TEXT,\n  type TEXT DEFAULT 'general',\n  status TEXT DEFAULT 'active',\n  path TEXT NOT NULL,\n  docs_path TEXT,\n  repo_pattern TEXT DEFAULT 'single',\n  language TEXT,\n  framework TEXT,\n  package_manager TEXT,\n  runtime_version TEXT,\n  commands TEXT,\n  git_remote TEXT,\n  git_branch TEXT DEFAULT 'main',\n  workflow_mode TEXT DEFAULT 'flexible',\n  lifecycle_state TEXT DEFAULT 'setup',\n  current_item_id TEXT,\n  last_context TEXT,\n  metadata TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_activity_at DATETIME\n);\n\n-- Work items (backlog items, tasks, bugs)\nCREATE TABLE IF NOT EXISTS work_items (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n  item_number INTEGER NOT NULL,\n  item_id TEXT NOT NULL,\n  type TEXT NOT NULL,\n  status TEXT DEFAULT 'backlog',\n  priority TEXT DEFAULT 'medium',\n  guided_step TEXT,\n  owner TEXT,\n  title TEXT NOT NULL,\n  description TEXT,\n  estimated_effort TEXT,\n  actual_minutes INTEGER,\n  completed_at DATETIME,\n  completed_by TEXT,\n  commit_hash TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  UNIQUE (project_id, item_id)\n);\n\n-- Project documents (PRD, architecture, plans, etc.)\nCREATE TABLE IF NOT EXISTS project_documents (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n  doc_type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  content TEXT NOT NULL,\n  status TEXT,\n  work_item_id INTEGER,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE SET NULL\n);\n\n-- Work item history (audit trail)\nCREATE TABLE IF NOT EXISTS work_item_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  work_item_id INTEGER NOT NULL,\n  project_id INTEGER NOT NULL,\n  action TEXT NOT NULL,\n  old_value TEXT,\n  new_value TEXT,\n  notes TEXT,\n  changed_by TEXT,\n  changed_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\n\n-- Indexes\nCREATE INDEX IF NOT EXISTS idx_projects_path ON projects(path);\nCREATE INDEX IF NOT EXISTS idx_projects_docs_path ON projects(docs_path);\nCREATE INDEX IF NOT EXISTS idx_projects_status ON projects(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_project ON work_items(project_id);\nCREATE INDEX IF NOT EXISTS idx_work_items_status ON work_items(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_priority ON work_items(priority);\nCREATE INDEX IF NOT EXISTS idx_work_items_owner ON work_items(owner);\nCREATE INDEX IF NOT EXISTS idx_project_documents_project ON project_documents(project_id);\nCREATE INDEX IF NOT EXISTS idx_project_documents_type ON project_documents(doc_type);\nCREATE INDEX IF NOT EXISTS idx_project_documents_status ON project_documents(status);\nCREATE INDEX IF NOT EXISTS idx_project_documents_work_item ON project_documents(work_item_id);\nCREATE INDEX IF NOT EXISTS idx_work_item_history_item ON work_item_history(work_item_id);\n\n-- Terminal sessions (multi-terminal awareness)\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER,\n  pid INTEGER NOT NULL,\n  tty_path TEXT,\n  label TEXT,\n  started_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_heartbeat DATETIME DEFAULT CURRENT_TIMESTAMP,\n  active_agent TEXT DEFAULT 'default',\n  agents_json TEXT DEFAULT '[]',\n  status TEXT DEFAULT 'active',\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE SET NULL\n);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_id);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_status ON terminal_sessions(status);\n\n-- File locks (multi-terminal file lock awareness)\nCREATE TABLE IF NOT EXISTS file_locks (\n  path TEXT NOT NULL,\n  project_id INTEGER NOT NULL,\n  session_id TEXT NOT NULL,\n  agent_id TEXT NOT NULL,\n  locked_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  PRIMARY KEY (path, project_id),\n  FOREIGN KEY (session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_file_locks_session ON file_locks(session_id);\n\n-- Session notifications (cross-session notifications)\nCREATE TABLE IF NOT EXISTS session_notifications (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER NOT NULL,\n  from_session_id TEXT NOT NULL,\n  to_session_id TEXT,\n  type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  message TEXT,\n  payload_json TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  read_at DATETIME,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (from_session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_project ON session_notifications(project_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_to_session ON session_notifications(to_session_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_unread ON session_notifications(read_at);\n\n-- Work item comments\nCREATE TABLE IF NOT EXISTS work_item_comments (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  work_item_id INTEGER NOT NULL,\n  project_id INTEGER NOT NULL,\n  author TEXT NOT NULL,\n  content TEXT NOT NULL,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_work_item_comments_work_item ON work_item_comments(work_item_id);\nCREATE INDEX IF NOT EXISTS idx_work_item_comments_project ON work_item_comments(project_id);\n\n-- Canvases (visual reasoning surfaces: infographic / carousel / board)\nCREATE TABLE IF NOT EXISTS canvases (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n  type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  content TEXT NOT NULL,\n  controls TEXT NOT NULL DEFAULT '{\"controls\":[]}',\n  \"values\" TEXT NOT NULL DEFAULT '{}',\n  page_size TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_canvases_project ON canvases(project_id);\n";
 export interface ProjectRecord {
     id: number;

package/dist/platform/sqlite/schema.js

@@ -4,7 +4,7 @@
  * Shared between CLI and Desktop — both access ~/.compilr-dev/projects.db
  * Schema version must be kept in sync across all consumers.
  */
-export const SCHEMA_VERSION = 9;
+export const SCHEMA_VERSION = 10;
 export const SCHEMA_SQL = `
 -- Schema version tracking
 CREATE TABLE IF NOT EXISTS schema_version (

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

@@ -10,6 +10,7 @@
  * manifest (validated here). Persistence is delegated to ctx.canvases
  * (ICanvasRepository); the current project is resolved like the document tools.
  */
+import type { ImageResizer } from './image-tools.js';
 import type { PlatformToolsConfig } from '../context.js';
 import type { CanvasType, ControlManifest } from '../../canvas/types.js';
 /**
@@ -29,8 +30,10 @@ export interface CanvasIssue {
     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<{
+export declare function runCanvasChecks(html: string, type: CanvasType, manifest?: ControlManifest): CanvasIssue[];
+export declare function createCanvasTools(config: PlatformToolsConfig, imageConfig?: {
+    resizer?: ImageResizer;
+}): (import("@compilr-dev/agents").Tool<{
     type: string;
     title: string;
     html: string;
@@ -50,4 +53,11 @@ export declare function createCanvasTools(config: PlatformToolsConfig): (import(
     new_str?: string;
     content?: string;
     replace_all?: boolean;
+}> | import("@compilr-dev/agents").Tool<{
+    topic: string;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    path: string;
+    ref: string;
+    max_width?: number;
 }>)[];