@compilr-dev/sdk 0.15.0 → 0.17.0

package/dist/canvas/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canvas contract barrel — exposed at `@compilr-dev/sdk/canvas` (renderer-safe:
+ * pure types + validation, no node deps). Tools live in the platform module.
+ */
+export * from './types.js';
+export * from './validate.js';

package/dist/canvas/index.js

@@ -0,0 +1,6 @@
+/**
+ * Canvas contract barrel — exposed at `@compilr-dev/sdk/canvas` (renderer-safe:
+ * pure types + validation, no node deps). Tools live in the platform module.
+ */
+export * from './types.js';
+export * from './validate.js';

package/dist/canvas/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Canvas — shared contract types.
+ *
+ * A Canvas is a persisted visual artifact the agent authors as HTML/SVG, with an
+ * optional controls manifest that surfaces live parameters ("Tweaks"). These
+ * types are the host-agnostic contract: the SDK owns them + the repository + the
+ * tools; hosts (Desktop) own the renderer.
+ *
+ * Intentionally dependency-free so this module can be exposed at the renderer-safe
+ * subpath `@compilr-dev/sdk/canvas` (the Desktop renderer needs the control types
+ * + validation without pulling node-only deps — same pattern as `.../errors`).
+ */
+export type CanvasType = 'infographic' | 'carousel' | 'board';
+/** A control's runtime value. */
+export type ParamValue = string | number | boolean;
+export interface SliderControl {
+    type: 'slider';
+    param: string;
+    label: string;
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+    unit?: string;
+    group?: string;
+}
+export interface NumberControl {
+    type: 'number';
+    param: string;
+    label: string;
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    group?: string;
+}
+export interface ToggleControl {
+    type: 'toggle';
+    param: string;
+    label: string;
+    default: boolean;
+    group?: string;
+}
+export interface SelectControl {
+    type: 'select';
+    param: string;
+    label: string;
+    default: string;
+    options: string[];
+    group?: string;
+}
+export interface ColorControl {
+    type: 'color';
+    param: string;
+    label: string;
+    default: string;
+    group?: string;
+}
+export interface TextControl {
+    type: 'text';
+    param: string;
+    label: string;
+    default: string;
+    placeholder?: string;
+    group?: string;
+}
+export type Control = SliderControl | NumberControl | ToggleControl | SelectControl | ColorControl | TextControl;
+export interface ControlManifest {
+    controls: Control[];
+}
+/**
+ * Full persisted canvas. `content` is the agent's raw HTML/SVG only — the CSP +
+ * bridge are injected by the host renderer, never stored.
+ */
+export interface CanvasRecord {
+    id: number;
+    projectId: number;
+    type: CanvasType;
+    title: string;
+    content: string;
+    controls: ControlManifest;
+    /** Current tweak state; seeded from control defaults on create. */
+    values: Record<string, ParamValue>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Lightweight list entry (no content). */
+export interface CanvasSummary {
+    id: number;
+    projectId: number;
+    type: CanvasType;
+    title: string;
+    updatedAt: Date;
+}
+export interface CreateCanvasInput {
+    projectId: number;
+    type: CanvasType;
+    title: string;
+    content: string;
+    controls?: ControlManifest;
+    values?: Record<string, ParamValue>;
+}
+export type UpdateCanvasInput = Partial<Pick<CanvasRecord, 'title' | 'content' | 'controls' | 'values'>>;
+/** Seed a values map from a manifest's control defaults. */
+export declare function seedValues(manifest: ControlManifest | undefined): Record<string, ParamValue>;

package/dist/canvas/types.js

@@ -0,0 +1,21 @@
+/**
+ * Canvas — shared contract types.
+ *
+ * A Canvas is a persisted visual artifact the agent authors as HTML/SVG, with an
+ * optional controls manifest that surfaces live parameters ("Tweaks"). These
+ * types are the host-agnostic contract: the SDK owns them + the repository + the
+ * tools; hosts (Desktop) own the renderer.
+ *
+ * Intentionally dependency-free so this module can be exposed at the renderer-safe
+ * subpath `@compilr-dev/sdk/canvas` (the Desktop renderer needs the control types
+ * + validation without pulling node-only deps — same pattern as `.../errors`).
+ */
+/** Seed a values map from a manifest's control defaults. */
+export function seedValues(manifest) {
+    const values = {};
+    if (!manifest)
+        return values;
+    for (const c of manifest.controls)
+        values[c.param] = c.default;
+    return values;
+}

package/dist/canvas/validate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canvas controls-manifest validation. Dependency-free (renderer-safe subpath).
+ */
+import type { ControlManifest } from './types.js';
+export interface ManifestValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Validate a controls manifest: array shape, unique + well-formed param names,
+ * and per-type default sanity (in range / in options / correct primitive).
+ */
+export declare function validateControlManifest(manifest: ControlManifest): ManifestValidationResult;

package/dist/canvas/validate.js

@@ -0,0 +1,89 @@
+/**
+ * Canvas controls-manifest validation. Dependency-free (renderer-safe subpath).
+ */
+/** Param names must be usable as a CSS custom property suffix and a JS key. */
+const PARAM_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+/**
+ * Validate a controls manifest: array shape, unique + well-formed param names,
+ * and per-type default sanity (in range / in options / correct primitive).
+ */
+export function validateControlManifest(manifest) {
+    const errors = [];
+    // Treat the manifest as untrusted (agent JSON), not the static type.
+    const rawControls = manifest.controls;
+    if (!Array.isArray(rawControls)) {
+        return { ok: false, errors: ['manifest.controls must be an array'] };
+    }
+    const seen = new Set();
+    for (const raw of rawControls) {
+        const param = raw.param;
+        if (typeof param !== 'string' || !PARAM_RE.test(param)) {
+            errors.push(`invalid param name "${String(param)}" (must match ${PARAM_RE.source})`);
+        }
+        else if (seen.has(param)) {
+            errors.push(`duplicate param "${param}"`);
+        }
+        if (typeof param === 'string')
+            seen.add(param);
+        validateDefault(raw, errors);
+    }
+    return { ok: errors.length === 0, errors };
+}
+function validateDefault(control, errors) {
+    const c = control;
+    const p = c.param;
+    switch (c.type) {
+        case 'slider': {
+            const { min, max, default: d } = c;
+            if (typeof min === 'number' && typeof max === 'number' && min > max) {
+                errors.push(`${p}: min ${String(min)} > max ${String(max)}`);
+            }
+            if (typeof d !== 'number') {
+                errors.push(`${p}: slider default must be a number`);
+            }
+            else if (typeof min === 'number' && typeof max === 'number' && (d < min || d > max)) {
+                errors.push(`${p}: default ${String(d)} out of range [${String(min)}, ${String(max)}]`);
+            }
+            break;
+        }
+        case 'number': {
+            const { min, max, default: d } = c;
+            if (typeof d !== 'number') {
+                errors.push(`${p}: number default must be a number`);
+            }
+            else {
+                if (typeof min === 'number' && d < min)
+                    errors.push(`${p}: default < min`);
+                if (typeof max === 'number' && d > max)
+                    errors.push(`${p}: default > max`);
+            }
+            break;
+        }
+        case 'toggle':
+            if (typeof c.default !== 'boolean')
+                errors.push(`${p}: toggle default must be boolean`);
+            break;
+        case 'select': {
+            const opts = c.options;
+            if (!Array.isArray(opts) || opts.length === 0) {
+                errors.push(`${p}: select needs a non-empty options array`);
+            }
+            else if (!opts.includes(c.default)) {
+                errors.push(`${p}: default "${String(c.default)}" is not in options`);
+            }
+            break;
+        }
+        case 'color':
+            if (typeof c.default !== 'string' || !HEX_RE.test(c.default)) {
+                errors.push(`${p}: color default must be a hex color (e.g. #FF5722)`);
+            }
+            break;
+        case 'text':
+            if (typeof c.default !== 'string')
+                errors.push(`${p}: text default must be a string`);
+            break;
+        default:
+            errors.push(`${p}: unknown control type "${c.type}"`);
+    }
+}

package/dist/index.d.ts

@@ -53,7 +53,7 @@ export { CapabilityManager, CapabilityContext, createCapabilityHook, autoDetectC
 export type { CapabilityPack, CapabilityTier, LoadedCapability, CapabilityCatalogEntry, CapabilityLoadResult, CapabilityManagerConfig, CapabilityContextConfig, CapabilityHookConfig, ConditionalModule, AutoDetectResult, } from './capabilities/index.js';
 export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, VISUAL_OUTPUT_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
 export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleConditions, } from './system-prompt/index.js';
-export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, WorkItemComment, CreateCommentInput, UpdateCommentInput, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
+export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, WorkItemComment, CreateCommentInput, UpdateCommentInput, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, ICanvasRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './platform/index.js';
 export { createAskUserTool, createAskUserSimpleTool, createProposeAlternativesTool, createInteractiveFlowTool, validateFlow, INTERACTIVE_FLOW_INPUT_SCHEMA, } from './tools/index.js';
@@ -64,7 +64,7 @@ export { detectProject, suggestProjectType, detectCommon } from './detection/ind
 export type { DetectProjectOptions, DetectionResult, ContentSummary } from './detection/index.js';
 export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';
 export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './guide/index.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig, FileArtifactServiceConfig, ImageToolsConfig, ImageResizer, } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
@@ -80,6 +80,8 @@ export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate,
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
 export { classifyAgentError, isApiKeyError } from './errors/classify.js';
 export type { AgentErrorCategory, AgentErrorInfo } from './errors/classify.js';
+export { validateControlManifest, seedValues } from './canvas/index.js';
+export type { CanvasType, ParamValue, Control, ControlManifest, CanvasRecord, CanvasSummary, CreateCanvasInput, UpdateCanvasInput, SliderControl, NumberControl, ToggleControl, SelectControl, ColorControl, TextControl, ManifestValidationResult, } from './canvas/index.js';
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, PermissionHandlerResponse, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
 export { DEFAULT_PERMISSION_RULES, WRITE_TOOLS, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
 export type { PermissionRule, PermissionMode, PermissionLevel } from './permissions.js';

package/dist/index.js

@@ -147,7 +147,7 @@ export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuide
 // =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 // =============================================================================
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================
@@ -196,6 +196,9 @@ AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, Abor
 // Error classification — shared by hosts to map provider/agent failures
 // (esp. missing/invalid API key) into stable categories + host-specific copy.
 export { classifyAgentError, isApiKeyError } from './errors/classify.js';
+// Canvas contract — shared visual-canvas types + controls-manifest validation.
+// Also exposed at the renderer-safe subpath `@compilr-dev/sdk/canvas`.
+export { validateControlManifest, seedValues } from './canvas/index.js';
 // =============================================================================
 // Shared Permission Defaults & Utilities
 // =============================================================================

package/dist/platform/context.d.ts

@@ -4,7 +4,7 @@
  * Provides a single entry point for data access, abstracting over the
  * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
  */
-import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository } from './repositories.js';
+import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, ICanvasRepository } from './repositories.js';
 import type { IAnchorService, IArtifactService, IEpisodeService } from './services.js';
 export interface PlatformContext {
     readonly projects: IProjectRepository;
@@ -15,6 +15,7 @@ export interface PlatformContext {
     readonly anchors?: IAnchorService;
     readonly artifacts?: IArtifactService;
     readonly episodes?: IEpisodeService;
+    readonly canvases?: ICanvasRepository;
     readonly comments?: ICommentRepository;
 }
 export interface PlatformHooks {

package/dist/platform/index.d.ts

@@ -2,10 +2,10 @@
  * Platform — Repository interfaces, data models, tools, and workflow.
  */
 export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, WorkItemComment, CreateCommentInput, UpdateCommentInput, } from './types.js';
-export type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, } from './repositories.js';
+export type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, ICanvasRepository, } from './repositories.js';
 export type { IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, } from './services.js';
 export type { PlatformContext, PlatformToolsConfig, PlatformHooks } from './context.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, } from './tools/index.js';
 export type { ImageToolsConfig, ImageResizer } from './tools/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './sqlite/index.js';

package/dist/platform/index.js

@@ -2,7 +2,7 @@
  * Platform — Repository interfaces, data models, tools, and workflow.
  */
 // Platform tools (runtime)
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, } from './tools/index.js';
 // SQLite implementations (concrete repositories)
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
 // File-based anchor service (shared by CLI and Desktop)

package/dist/platform/repositories.d.ts

@@ -6,6 +6,7 @@
  * backends (PostgreSQL, HTTP APIs).
  */
 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';
 export interface IProjectRepository {
     create(input: CreateProjectInput): Promise<Project>;
     getById(id: number): Promise<Project | null>;
@@ -46,6 +47,13 @@ export interface IDocumentRepository {
     deleteByType(projectId: number, docType: DocumentType): Promise<boolean>;
     getTypeCounts(projectId: number): Promise<Record<string, number>>;
 }
+export interface ICanvasRepository {
+    create(input: CreateCanvasInput): Promise<CanvasRecord>;
+    getById(id: number): Promise<CanvasRecord | null>;
+    listByProject(projectId: number): Promise<CanvasSummary[]>;
+    update(id: number, input: UpdateCanvasInput): Promise<CanvasRecord | null>;
+    delete(id: number): Promise<boolean>;
+}
 export interface IPlanRepository {
     create(input: CreatePlanInput): Promise<Plan>;
     getById(id: number): Promise<Plan | null>;

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

@@ -0,0 +1,18 @@
+/**
+ * SQLite Canvas Repository — concrete implementation of ICanvasRepository.
+ *
+ * `controls` and `values` are stored as JSON text columns. Note `values` is a
+ * SQL reserved word, so it is always quoted as "values" in statements.
+ */
+import type Database from 'better-sqlite3';
+import type { ICanvasRepository } from '../repositories.js';
+import type { CanvasRecord, CanvasSummary, CreateCanvasInput, UpdateCanvasInput } from '../../canvas/types.js';
+export declare class SQLiteCanvasRepository implements ICanvasRepository {
+    private readonly db;
+    constructor(db: Database.Database);
+    create(input: CreateCanvasInput): Promise<CanvasRecord>;
+    getById(id: number): Promise<CanvasRecord | null>;
+    listByProject(projectId: number): Promise<CanvasSummary[]>;
+    update(id: number, input: UpdateCanvasInput): Promise<CanvasRecord | null>;
+    delete(id: number): Promise<boolean>;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * SQLite Canvas Repository — concrete implementation of ICanvasRepository.
+ *
+ * `controls` and `values` are stored as JSON text columns. Note `values` is a
+ * SQL reserved word, so it is always quoted as "values" in statements.
+ */
+function parseControls(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed.controls) ? { controls: parsed.controls } : { controls: [] };
+    }
+    catch {
+        return { controls: [] };
+    }
+}
+function parseValues(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}
+function toCanvas(r) {
+    return {
+        id: r.id,
+        projectId: r.project_id,
+        type: r.type,
+        title: r.title,
+        content: r.content,
+        controls: parseControls(r.controls),
+        values: parseValues(r.values),
+        createdAt: new Date(r.created_at),
+        updatedAt: new Date(r.updated_at),
+    };
+}
+function toSummary(r) {
+    return {
+        id: r.id,
+        projectId: r.project_id,
+        type: r.type,
+        title: r.title,
+        updatedAt: new Date(r.updated_at),
+    };
+}
+export class SQLiteCanvasRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(input) {
+        const now = new Date().toISOString();
+        const controls = JSON.stringify(input.controls ?? { controls: [] });
+        const values = JSON.stringify(input.values ?? {});
+        const result = this.db
+            .prepare(`INSERT INTO canvases (project_id, type, title, content, controls, "values", created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.projectId, input.type, input.title, input.content, controls, values, now, now);
+        const record = this.db
+            .prepare('SELECT * FROM canvases WHERE id = ?')
+            .get(Number(result.lastInsertRowid));
+        return Promise.resolve(toCanvas(record));
+    }
+    getById(id) {
+        const record = this.db.prepare('SELECT * FROM canvases WHERE id = ?').get(id);
+        return Promise.resolve(record ? toCanvas(record) : null);
+    }
+    listByProject(projectId) {
+        const rows = this.db
+            .prepare('SELECT * FROM canvases WHERE project_id = ? ORDER BY updated_at DESC')
+            .all(projectId);
+        return Promise.resolve(rows.map(toSummary));
+    }
+    update(id, input) {
+        const existing = this.db.prepare('SELECT * FROM canvases WHERE id = ?').get(id);
+        if (!existing)
+            return Promise.resolve(null);
+        const now = new Date().toISOString();
+        const title = input.title ?? existing.title;
+        const content = input.content ?? existing.content;
+        const controls = input.controls ? JSON.stringify(input.controls) : existing.controls;
+        const values = input.values ? JSON.stringify(input.values) : existing.values;
+        this.db
+            .prepare(`UPDATE canvases SET title = ?, content = ?, controls = ?, "values" = ?, updated_at = ? WHERE id = ?`)
+            .run(title, content, controls, values, now, id);
+        const record = this.db.prepare('SELECT * FROM canvases WHERE id = ?').get(id);
+        return Promise.resolve(toCanvas(record));
+    }
+    delete(id) {
+        const result = this.db.prepare('DELETE FROM canvases WHERE id = ?').run(id);
+        return Promise.resolve(result.changes > 0);
+    }
+}

package/dist/platform/sqlite/db.js

@@ -157,4 +157,22 @@ function runMigrations(db, fromVersion, toVersion) {
     `);
         db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(7);
     }
+    if (fromVersion < 8 && toVersion >= 8) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS canvases (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        project_id INTEGER NOT NULL,
+        type TEXT NOT NULL,
+        title TEXT NOT NULL,
+        content TEXT NOT NULL,
+        controls TEXT NOT NULL DEFAULT '{"controls":[]}',
+        values TEXT NOT NULL DEFAULT '{}',
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+      );
+      CREATE INDEX IF NOT EXISTS idx_canvases_project ON canvases(project_id);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(8);
+    }
 }

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

@@ -17,13 +17,14 @@
  */
 import type Database from 'better-sqlite3';
 import { type ProjectDeleteHooks } from './project-repository.js';
-import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository } from '../repositories.js';
+import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, ICanvasRepository } from '../repositories.js';
 export interface SQLiteRepositories {
     projects: IProjectRepository;
     workItems: IWorkItemRepository;
     documents: IDocumentRepository;
     plans: IPlanRepository;
     comments: ICommentRepository;
+    canvases: ICanvasRepository;
 }
 export interface CreateSQLiteRepositoriesOptions {
     projectDeleteHooks?: ProjectDeleteHooks;
@@ -37,6 +38,7 @@ export { SQLiteWorkItemRepository } from './work-item-repository.js';
 export { SQLiteDocumentRepository } from './document-repository.js';
 export { SQLitePlanRepository } from './plan-repository.js';
 export { SQLiteCommentRepository } from './comment-repository.js';
+export { SQLiteCanvasRepository } from './canvas-repository.js';
 export { getDatabase, closeDatabase, closeAllDatabases, databaseExists } from './db.js';
 export { SCHEMA_VERSION, SCHEMA_SQL } from './schema.js';
 export type { ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './schema.js';

package/dist/platform/sqlite/index.js

@@ -20,6 +20,7 @@ import { SQLiteWorkItemRepository } from './work-item-repository.js';
 import { SQLiteDocumentRepository } from './document-repository.js';
 import { SQLitePlanRepository } from './plan-repository.js';
 import { SQLiteCommentRepository } from './comment-repository.js';
+import { SQLiteCanvasRepository } from './canvas-repository.js';
 /**
  * Create all 4 platform repositories backed by a single SQLite database.
  */
@@ -30,6 +31,7 @@ export function createSQLiteRepositories(db, options) {
         documents: new SQLiteDocumentRepository(db),
         plans: new SQLitePlanRepository(db),
         comments: new SQLiteCommentRepository(db),
+        canvases: new SQLiteCanvasRepository(db),
     };
 }
 // Re-export classes for advanced usage
@@ -38,6 +40,7 @@ export { SQLiteWorkItemRepository } from './work-item-repository.js';
 export { SQLiteDocumentRepository } from './document-repository.js';
 export { SQLitePlanRepository } from './plan-repository.js';
 export { SQLiteCommentRepository } from './comment-repository.js';
+export { SQLiteCanvasRepository } from './canvas-repository.js';
 // Re-export database utilities
 export { getDatabase, closeDatabase, closeAllDatabases, databaseExists } from './db.js';
 // Re-export schema (for consumers that need direct access)

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

@@ -4,8 +4,8 @@
  * 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 = 7;
-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";
+export declare const SCHEMA_VERSION = 8;
+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  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;
     name: string;
@@ -63,6 +63,17 @@ export interface ProjectDocumentRecord {
     created_at: string;
     updated_at: string;
 }
+export interface CanvasDbRecord {
+    id: number;
+    project_id: number;
+    type: string;
+    title: string;
+    content: string;
+    controls: string;
+    values: string;
+    created_at: string;
+    updated_at: string;
+}
 export interface WorkItemCommentRecord {
     id: number;
     work_item_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 = 7;
+export const SCHEMA_VERSION = 8;
 export const SCHEMA_SQL = `
 -- Schema version tracking
 CREATE TABLE IF NOT EXISTS schema_version (
@@ -171,4 +171,19 @@ CREATE TABLE IF NOT EXISTS work_item_comments (
 );
 CREATE INDEX IF NOT EXISTS idx_work_item_comments_work_item ON work_item_comments(work_item_id);
 CREATE INDEX IF NOT EXISTS idx_work_item_comments_project ON work_item_comments(project_id);
+
+-- Canvases (visual reasoning surfaces: infographic / carousel / board)
+CREATE TABLE IF NOT EXISTS canvases (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  controls TEXT NOT NULL DEFAULT '{"controls":[]}',
+  values TEXT NOT NULL DEFAULT '{}',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_canvases_project ON canvases(project_id);
 `;

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

@@ -0,0 +1,22 @@
+/**
+ * Canvas Tools — agent authoring + management of visual canvases.
+ *
+ * 4 tools: canvas_write (create/update), canvas_list, canvas_get, canvas_delete.
+ *
+ * `content` is the agent's raw HTML/SVG; the host renderer injects the CSP +
+ * bridge and renders it in a sandboxed iframe. `controls` is the optional Tweaks
+ * manifest (validated here). Persistence is delegated to ctx.canvases
+ * (ICanvasRepository); the current project is resolved like the document tools.
+ */
+import type { PlatformToolsConfig } from '../context.js';
+import type { ControlManifest } from '../../canvas/types.js';
+export declare function createCanvasTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    type: string;
+    title: string;
+    html: string;
+    controls?: ControlManifest;
+    canvas_id?: number;
+    project_id?: number;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+}>)[];

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

@@ -0,0 +1,194 @@
+/**
+ * Canvas Tools — agent authoring + management of visual canvases.
+ *
+ * 4 tools: canvas_write (create/update), canvas_list, canvas_get, canvas_delete.
+ *
+ * `content` is the agent's raw HTML/SVG; the host renderer injects the CSP +
+ * bridge and renders it in a sandboxed iframe. `controls` is the optional Tweaks
+ * manifest (validated here). Persistence is delegated to ctx.canvases
+ * (ICanvasRepository); the current project is resolved like the document tools.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { truncateContent } from './truncate.js';
+import { seedValues } from '../../canvas/types.js';
+import { validateControlManifest } from '../../canvas/validate.js';
+const CANVAS_TYPES = ['infographic', 'carousel', 'board'];
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createCanvasTools(config) {
+    const ctx = config.context;
+    const canvases = ctx.canvases;
+    if (!canvases)
+        throw new Error('canvases repository required');
+    // ---------------------------------------------------------------------------
+    // canvas_write — create (no canvas_id) or update (canvas_id given)
+    // ---------------------------------------------------------------------------
+    const canvasWriteTool = defineTool({
+        name: 'canvas_write',
+        description: 'Create or update a visual canvas (infographic, carousel, or board) rendered from HTML/SVG. ' +
+            'Optionally declare a controls manifest ("Tweaks") of live parameters the user can adjust: ' +
+            'each control is { type: slider|number|toggle|select|color|text, param, label, default, ...type config }. ' +
+            'Bind params in your HTML via CSS custom properties var(--param), [data-bind="param"] text, and ' +
+            '[data-show="param"] visibility; for computed updates define window.applyParams(values) in a <script>. ' +
+            'Pass canvas_id to update an existing canvas; omit it to create a new one.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: CANVAS_TYPES,
+                    description: 'Canvas kind: infographic (single composition), carousel (slide sheets), board (infinite 2D).',
+                },
+                title: { type: 'string', description: 'Canvas title (shown in the library and tab).' },
+                html: {
+                    type: 'string',
+                    description: 'The canvas content as HTML/SVG. Raw content only — the app injects the sandbox/CSP. ' +
+                        'May include a <script> defining window.applyParams(values) for live recompute.',
+                },
+                controls: {
+                    type: 'object',
+                    description: 'Optional Tweaks manifest: { "controls": [ { "type": "slider", "param": "headline", "label": "Headline", "default": 40, "min": 24, "max": 72 }, ... ] }.',
+                    properties: {
+                        controls: { type: 'array', items: { type: 'object' } },
+                    },
+                },
+                canvas_id: {
+                    type: 'number',
+                    description: 'Existing canvas id to update. Omit to create a new canvas.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional project id. Defaults to the current project.',
+                },
+            },
+            required: ['type', 'title', 'html'],
+        },
+        execute: async (input) => {
+            try {
+                if (input.controls) {
+                    const check = validateControlManifest(input.controls);
+                    if (!check.ok) {
+                        return createErrorResult(`Invalid controls manifest:\n- ${check.errors.join('\n- ')}`);
+                    }
+                }
+                if (input.canvas_id !== undefined) {
+                    const updated = await canvases.update(input.canvas_id, {
+                        title: input.title,
+                        content: input.html,
+                        // Re-seed values from the new manifest when controls are (re)declared.
+                        // Phase 1 keeps this simple; a later phase can preserve prior tweaks.
+                        ...(input.controls
+                            ? { controls: input.controls, values: seedValues(input.controls) }
+                            : {}),
+                    });
+                    if (!updated)
+                        return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                    return createSuccessResult(`Updated canvas "${updated.title}" (${updated.type})\nID: ${String(updated.id)}`);
+                }
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No active project. Provide project_id or select a project.');
+                }
+                const controls = input.controls ?? { controls: [] };
+                const created = await canvases.create({
+                    projectId,
+                    type: input.type,
+                    title: input.title,
+                    content: input.html,
+                    controls,
+                    values: seedValues(controls),
+                });
+                return createSuccessResult(`Created canvas "${created.title}" (${created.type})\nID: ${String(created.id)}`);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to write canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // canvas_list
+    // ---------------------------------------------------------------------------
+    const canvasListTool = defineTool({
+        name: 'canvas_list',
+        description: 'List the canvases in the current (or given) project.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'number', description: 'Optional project id. Defaults to current.' },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No active project. Provide project_id or select a project.');
+                }
+                const items = await canvases.listByProject(projectId);
+                if (items.length === 0)
+                    return createSuccessResult('No canvases yet.');
+                const lines = items.map((c) => `- [${c.type}] ${c.title}  (id: ${String(c.id)})`);
+                return createSuccessResult([`${String(items.length)} canvas(es):`, ...lines].join('\n'));
+            }
+            catch (error) {
+                return createErrorResult(`Failed to list canvases: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // canvas_get
+    // ---------------------------------------------------------------------------
+    const canvasGetTool = defineTool({
+        name: 'canvas_get',
+        description: 'Get a canvas by id, including its content, controls manifest, and current values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'Canvas id.' },
+            },
+            required: ['canvas_id'],
+        },
+        execute: async (input) => {
+            try {
+                const c = await canvases.getById(input.canvas_id);
+                if (!c)
+                    return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                const tc = truncateContent(c.content);
+                const output = `Canvas "${c.title}" (${c.type})\n` +
+                    `ID: ${String(c.id)}\n` +
+                    `Controls: ${String(c.controls.controls.length)}\n\n` +
+                    `--- content ---\n` +
+                    tc.content;
+                return createSuccessResult(output);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to get canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // canvas_delete
+    // ---------------------------------------------------------------------------
+    const canvasDeleteTool = defineTool({
+        name: 'canvas_delete',
+        description: 'Delete a canvas by id.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'Canvas id.' },
+            },
+            required: ['canvas_id'],
+        },
+        execute: async (input) => {
+            try {
+                const ok = await canvases.delete(input.canvas_id);
+                if (!ok)
+                    return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                return createSuccessResult(`Deleted canvas ${String(input.canvas_id)}`);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to delete canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    return [canvasWriteTool, canvasListTool, canvasGetTool, canvasDeleteTool];
+}

package/dist/platform/tools/index.d.ts

@@ -31,5 +31,6 @@ export { createBacklogTools } from './backlog-tools.js';
 export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
+export { createCanvasTools } from './canvas-tools.js';
 export { createImageTools } from './image-tools.js';
 export type { ImageToolsConfig, ImageResizer } from './image-tools.js';

package/dist/platform/tools/index.js

@@ -16,6 +16,7 @@ import { createBacklogTools } from './backlog-tools.js';
 import { createAnchorTools } from './anchor-tools.js';
 import { createArtifactTools } from './artifact-tools.js';
 import { createEpisodeTools } from './episode-tools.js';
+import { createCanvasTools } from './canvas-tools.js';
 import { createImageTools } from './image-tools.js';
 /**
  * Create all platform tools operating against the given context.
@@ -54,6 +55,9 @@ export function createPlatformTools(config, options) {
     if (config.context.episodes) {
         tools.push(...createEpisodeTools(config));
     }
+    if (config.context.canvases) {
+        tools.push(...createCanvasTools(config));
+    }
     return tools;
 }
 // Re-export individual factory functions for selective use
@@ -65,4 +69,5 @@ export { createBacklogTools } from './backlog-tools.js';
 export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
+export { createCanvasTools } from './canvas-tools.js';
 export { createImageTools } from './image-tools.js';

package/package.json

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