@compilr-dev/sdk 0.18.11 → 0.20.0

package/dist/canvas/assets.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Canvas assets — images stored beside a canvas, not inside it.
+ *
+ * ⚠️ WHY NOT JUST A data: URI IN THE HTML. The sandbox CSP is `img-src data: blob:`, so a
+ * data URI is the ONLY thing that renders — but the canvas document is stored in sqlite
+ * and edited with `canvas_edit`'s str_replace. Four product photos inline is a few hundred
+ * KB of base64 sitting in the middle of the document the agent has to read an outline of
+ * and patch by hand. The editing discipline that makes canvases reliable stops working.
+ *
+ * So the markup carries a REFERENCE and the bytes live in a side table:
+ *
+ *     <img src="asset:hero" alt="…">
+ *
+ * and the host substitutes real data URIs at the two moments the canvas becomes pixels:
+ * rendering into the iframe, and exporting to PDF/HTML/PNG. `resolveCanvasAssets` below is
+ * that substitution, shared by both so they cannot disagree — the same reason the token
+ * block had to be extracted.
+ *
+ * ⚠️ `asset:` IS NOT A REAL SCHEME. If a host forgets to substitute, the CSP blocks it and
+ * the image silently does not render. That is the failure mode to design against, which is
+ * why `canvas_validate` errors on a reference with no matching asset, and why the renderer
+ * and exporter share one function rather than each implementing the regex.
+ */
+/** An image stored against a canvas. */
+export interface CanvasAsset {
+    id: number;
+    canvasId: number;
+    /** The handle the markup references as `asset:<ref>`. */
+    ref: string;
+    mediaType: string;
+    /** base64, no data: prefix. */
+    data: string;
+    width?: number;
+    height?: number;
+    /** Encoded size in bytes — what the canvas actually costs to render. */
+    bytes: number;
+    /** Where it came from, for provenance when someone asks "which file is this?". */
+    sourcePath?: string;
+    createdAt: Date;
+}
+export interface CreateCanvasAssetInput {
+    canvasId: number;
+    ref: string;
+    mediaType: string;
+    data: string;
+    width?: number;
+    height?: number;
+    bytes: number;
+    sourcePath?: string;
+}
+/**
+ * A ref is a short handle an agent types into markup, so it has to be safe to embed in an
+ * attribute and easy to get right: lowercase word characters and dashes.
+ */
+export declare const ASSET_REF: RegExp;
+export declare const isValidAssetRef: (ref: string) => boolean;
+/** Every asset ref the markup uses, deduplicated, in document order. */
+export declare function referencedAssets(html: string): string[];
+/**
+ * Replace every `asset:<ref>` with a real data URI.
+ *
+ * A reference with no matching asset is LEFT ALONE rather than blanked: the CSP will drop
+ * it either way, and leaving it makes the cause visible in devtools instead of presenting
+ * an empty `src` that looks like an authoring mistake.
+ */
+export declare function resolveCanvasAssets(html: string, assets: readonly Pick<CanvasAsset, 'ref' | 'mediaType' | 'data'>[]): string;
+/**
+ * Refs used by the markup that no asset satisfies.
+ *
+ * ⚠️ This is the check that makes the indirection safe. Without it a typo produces a
+ * canvas that renders with a hole in it and no error anywhere.
+ */
+export declare function missingAssetRefs(html: string, assets: readonly Pick<CanvasAsset, 'ref'>[]): string[];
+/**
+ * The total encoded weight of the assets a canvas actually uses.
+ * Unreferenced assets are excluded — they cost storage, not render time.
+ */
+export declare function assetPayloadBytes(html: string, assets: readonly Pick<CanvasAsset, 'ref' | 'bytes'>[]): number;
+/**
+ * ⚠️ A BUDGET, because every byte here is paid twice — once in the stored canvas and once
+ * in every export. Four photos at card size land around 200KB; a single un-resized phone
+ * photo is 4MB on its own. The tool refuses above this and says what to do.
+ */
+export declare const ASSET_BUDGET_BYTES = 2000000;
+/** Display width an image is resized to before storing, unless the caller says otherwise. */
+export declare const DEFAULT_ASSET_WIDTH = 640;
+/**
+ * The inverse of `resolveCanvasAssets`: turn embedded data URIs back into `asset:<ref>`.
+ *
+ * ⚠️ THIS IS NOT OPTIONAL, it is what keeps the indirection from unravelling. The host
+ * bridge serializes the live iframe's DOM back to be persisted after a visual edit — and
+ * that DOM holds the RESOLVED data URIs. Without this pass, one visual edit writes every
+ * image into the stored document as base64: exactly the state the asset table exists to
+ * prevent, arrived at by the back door, and silently.
+ *
+ * Matching is on the base64 payload rather than the whole URI, so a media type rewritten
+ * by the browser still maps home.
+ */
+export declare function dereferenceCanvasAssets(html: string, assets: readonly Pick<CanvasAsset, 'ref' | 'data'>[]): string;

package/dist/canvas/assets.js

@@ -0,0 +1,111 @@
+/**
+ * Canvas assets — images stored beside a canvas, not inside it.
+ *
+ * ⚠️ WHY NOT JUST A data: URI IN THE HTML. The sandbox CSP is `img-src data: blob:`, so a
+ * data URI is the ONLY thing that renders — but the canvas document is stored in sqlite
+ * and edited with `canvas_edit`'s str_replace. Four product photos inline is a few hundred
+ * KB of base64 sitting in the middle of the document the agent has to read an outline of
+ * and patch by hand. The editing discipline that makes canvases reliable stops working.
+ *
+ * So the markup carries a REFERENCE and the bytes live in a side table:
+ *
+ *     <img src="asset:hero" alt="…">
+ *
+ * and the host substitutes real data URIs at the two moments the canvas becomes pixels:
+ * rendering into the iframe, and exporting to PDF/HTML/PNG. `resolveCanvasAssets` below is
+ * that substitution, shared by both so they cannot disagree — the same reason the token
+ * block had to be extracted.
+ *
+ * ⚠️ `asset:` IS NOT A REAL SCHEME. If a host forgets to substitute, the CSP blocks it and
+ * the image silently does not render. That is the failure mode to design against, which is
+ * why `canvas_validate` errors on a reference with no matching asset, and why the renderer
+ * and exporter share one function rather than each implementing the regex.
+ */
+/**
+ * A ref is a short handle an agent types into markup, so it has to be safe to embed in an
+ * attribute and easy to get right: lowercase word characters and dashes.
+ */
+export const ASSET_REF = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const isValidAssetRef = (ref) => ASSET_REF.test(ref);
+/**
+ * ⚠️ Matches `asset:<ref>` ONLY inside an attribute value, not anywhere in the document.
+ * A canvas that mentions `asset:hero` in a code sample or a caption must not have its text
+ * rewritten into a 200KB base64 blob.
+ */
+const REFERENCE = /(["'])asset:([a-z0-9][a-z0-9-]{0,39})\1/gi;
+/** Every asset ref the markup uses, deduplicated, in document order. */
+export function referencedAssets(html) {
+    const seen = new Set();
+    for (const m of html.matchAll(REFERENCE))
+        seen.add(m[2].toLowerCase());
+    return [...seen];
+}
+/**
+ * Replace every `asset:<ref>` with a real data URI.
+ *
+ * A reference with no matching asset is LEFT ALONE rather than blanked: the CSP will drop
+ * it either way, and leaving it makes the cause visible in devtools instead of presenting
+ * an empty `src` that looks like an authoring mistake.
+ */
+export function resolveCanvasAssets(html, assets) {
+    if (assets.length === 0)
+        return html;
+    const byRef = new Map(assets.map((a) => [a.ref.toLowerCase(), a]));
+    return html.replace(REFERENCE, (whole, quote, ref) => {
+        const asset = byRef.get(ref.toLowerCase());
+        if (!asset)
+            return whole;
+        return `${quote}data:${asset.mediaType};base64,${asset.data}${quote}`;
+    });
+}
+/**
+ * Refs used by the markup that no asset satisfies.
+ *
+ * ⚠️ This is the check that makes the indirection safe. Without it a typo produces a
+ * canvas that renders with a hole in it and no error anywhere.
+ */
+export function missingAssetRefs(html, assets) {
+    const have = new Set(assets.map((a) => a.ref.toLowerCase()));
+    return referencedAssets(html).filter((ref) => !have.has(ref));
+}
+/**
+ * The total encoded weight of the assets a canvas actually uses.
+ * Unreferenced assets are excluded — they cost storage, not render time.
+ */
+export function assetPayloadBytes(html, assets) {
+    const used = new Set(referencedAssets(html));
+    return assets
+        .filter((a) => used.has(a.ref.toLowerCase()))
+        .reduce((total, a) => total + a.bytes, 0);
+}
+/**
+ * ⚠️ A BUDGET, because every byte here is paid twice — once in the stored canvas and once
+ * in every export. Four photos at card size land around 200KB; a single un-resized phone
+ * photo is 4MB on its own. The tool refuses above this and says what to do.
+ */
+export const ASSET_BUDGET_BYTES = 2_000_000;
+/** Display width an image is resized to before storing, unless the caller says otherwise. */
+export const DEFAULT_ASSET_WIDTH = 640;
+/**
+ * The inverse of `resolveCanvasAssets`: turn embedded data URIs back into `asset:<ref>`.
+ *
+ * ⚠️ THIS IS NOT OPTIONAL, it is what keeps the indirection from unravelling. The host
+ * bridge serializes the live iframe's DOM back to be persisted after a visual edit — and
+ * that DOM holds the RESOLVED data URIs. Without this pass, one visual edit writes every
+ * image into the stored document as base64: exactly the state the asset table exists to
+ * prevent, arrived at by the back door, and silently.
+ *
+ * Matching is on the base64 payload rather than the whole URI, so a media type rewritten
+ * by the browser still maps home.
+ */
+export function dereferenceCanvasAssets(html, assets) {
+    let out = html;
+    for (const asset of assets) {
+        if (!asset.data)
+            continue;
+        // `data:<anything>;base64,<payload>` → asset:<ref>, in any attribute quoting.
+        const pattern = new RegExp(`data:[^"'\\s]*?base64,${asset.data.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'g');
+        out = out.replace(pattern, `asset:${asset.ref}`);
+    }
+    return out;
+}

package/dist/canvas/index.d.ts

@@ -10,3 +10,5 @@ export { runQualityChecks, checkSurfaceTokens, checkTextContrast, checkHueCount,
 export type { QualityIssue } from './quality-checks.js';
 export { deriveSurfaceRamp, withLightness } from './ramp.js';
 export type { SurfaceRamp } from './ramp.js';
+export { resolveCanvasAssets, dereferenceCanvasAssets, referencedAssets, missingAssetRefs, assetPayloadBytes, isValidAssetRef, ASSET_BUDGET_BYTES, DEFAULT_ASSET_WIDTH, } from './assets.js';
+export type { CanvasAsset, CreateCanvasAssetInput } from './assets.js';

package/dist/canvas/index.js

@@ -14,3 +14,9 @@ export * from './validate.js';
 export { parseColor, relativeLuminance, contrastRatio, oklabLightness, lightnessDeltaPct, isNeutral, hueAngle, AA_TEXT, SURFACE_DELTA_MIN, SURFACE_DELTA_TARGET, SURFACE_DELTA_MAX, HAIRLINE_MIN_PCT, HAIRLINE_MAX_PCT, } from './color.js';
 export { runQualityChecks, checkSurfaceTokens, checkTextContrast, checkHueCount, checkDeadTweaks, primaryVarNames, } from './quality-checks.js';
 export { deriveSurfaceRamp, withLightness } from './ramp.js';
+/*
+  Assets — images stored beside a canvas. `resolveCanvasAssets` is renderer-safe and is
+  shared by the host's live iframe AND its export path; they must not each implement the
+  substitution, for the same reason the theme token block had to be extracted.
+*/
+export { resolveCanvasAssets, dereferenceCanvasAssets, referencedAssets, missingAssetRefs, assetPayloadBytes, isValidAssetRef, ASSET_BUDGET_BYTES, DEFAULT_ASSET_WIDTH, } from './assets.js';

package/dist/capabilities/packs.js

@@ -245,6 +245,9 @@ export const CAPABILITY_PACKS = {
             'canvas_validate',
             'canvas_screenshot',
             'canvas_guide',
+            'canvas_asset_add',
+            'canvas_asset_list',
+            'canvas_asset_delete',
         ],
         readOnly: false,
         promptModules: ['platform-tool-hints'],
@@ -255,6 +258,9 @@ export const CAPABILITY_PACKS = {
             '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,

package/dist/index.d.ts

@@ -35,8 +35,8 @@
  */
 export { createCompilrAgent } from './agent.js';
 export type { CompilrAgentConfig, CompilrAgent, RunOptions, RunResult, ToolCallRecord, ToolConfig, UsageInfo, ProviderType, PermissionCallback, GuardrailConfig, ContextConfig, CapabilitiesConfig, } from './config.js';
-export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, } from './team/index.js';
-export type { AgentTeamConfig, TeamAgentConfig, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, AgentTemplate, AgentWorkshopData, WorkshopRoleDef, WorkshopToolProfile, WorkshopModelTier, WorkshopSkillDef, PlanSubmitInfo, PlanSubmitResult, PlanModeExitInfo, PlanModeCallbacks, ToolConfig as TeamToolConfig, ToolTier, ToolGroup, ProfileInfo, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, } from './team/index.js';
+export type { AgentTeamConfig, TeamAgentConfig, TeamAgentUpdate, AgentUpdateResult, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, AgentTemplate, AgentWorkshopData, WorkshopRoleDef, WorkshopToolProfile, WorkshopModelTier, WorkshopSkillDef, PlanSubmitInfo, PlanSubmitResult, PlanModeExitInfo, PlanModeCallbacks, ToolConfig as TeamToolConfig, ToolTier, ToolGroup, ProfileInfo, } from './team/index.js';
 export type { AgentRole, RoleMetadata, ToolProfile, MascotExpression, BackgroundSessionInfo, SerializedTeam, SerializedTeamAgent, TeamMetadata, TeamEvent, TeamEventType, TeamEventHandler, Artifact, ArtifactType as TeamArtifactType, ArtifactSummary as TeamArtifactSummary, CreateArtifactOptions, UpdateArtifactOptions, SerializedArtifact, SharedContext, SharedProjectInfo, SharedTeamInfo, TeamRosterEntry, TeamActivity, TeamActivityType, SharedDecision, TokenBudget, SerializedSharedContext, ParsedMention, ParsedInput, ResolvedMention, ResolveOptions, ResolutionSource, Delegation, DelegationStatus, DelegationResult, CompletionEvent, CreateDelegationOptions, DelegationStats, DelegationTrackerEvents, HandoffResult, HandoffToolConfig, HandoffIntent, HandoffValidationResult, DelegateResult, DelegateToolConfig, DelegateBackgroundResult, DelegateBackgroundToolConfig, ConsultInput, ConsultResult, ConsultToolConfig, NormalizedRole, SkillToolRequirement, } from './team/index.js';
 export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, buildAgentWorkshopData, buildSuggestedRolesMap, PLAN_MODE_BLOCKED_TOOLS, PLAN_MODE_DENIAL_MESSAGE, PLAN_MODE_PROMPT, isToolAllowedInPlanMode, getPlanModePrompt, } from './team/index.js';
 export { getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, listTemplates, getTemplate, saveTemplate, updateTemplate, deleteTemplate, createAgentFromTemplate, parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, buildContextMap, findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, suggestOwner, suggestOwners, matchesAgentExpertise, wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, resolveAgentIdCollision, setActiveSharedContext, getActiveSharedContext, recordTeamActivity, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';

package/dist/index.js

@@ -41,7 +41,7 @@ export { createCompilrAgent } from './agent.js';
 // Multi-Agent Team Orchestration
 // =============================================================================
 // Core classes
-export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, } from './team/index.js';
 // Constants
 export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, buildAgentWorkshopData, buildSuggestedRolesMap, 
 // Plan mode

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';
 /**
@@ -30,7 +31,9 @@ export interface CanvasIssue {
 }
 /** Run deterministic static checks on canvas content. No rendering. */
 export declare function runCanvasChecks(html: string, type: CanvasType, manifest?: ControlManifest): CanvasIssue[];
-export declare function createCanvasTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+export declare function createCanvasTools(config: PlatformToolsConfig, imageConfig?: {
+    resizer?: ImageResizer;
+}): (import("@compilr-dev/agents").Tool<{
     type: string;
     title: string;
     html: string;
@@ -52,4 +55,9 @@ export declare function createCanvasTools(config: PlatformToolsConfig): (import(
     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;
 }>)[];