@compilr-dev/sdk 0.17.17 → 0.18.0

package/dist/canvas/types.d.ts

@@ -81,6 +81,8 @@ export interface CanvasRecord {
     controls: ControlManifest;
     /** Current tweak state; seeded from control defaults on create. */
     values: Record<string, ParamValue>;
+    /** Page size / aspect (carousel slide aspect). Undefined = default 16:9. */
+    pageSize?: PageSize;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -92,6 +94,24 @@ export interface CanvasSummary {
     title: string;
     updatedAt: Date;
 }
+/**
+ * Page size / aspect for a canvas — mainly the carousel slide aspect (16:9
+ * widescreen, 4:3 standard, 1:1 square, 4:5 portrait, 9:16 story). The agent may
+ * set it and the user may change it live. Infographic/board ignore it (sized by
+ * content / declared bounds). Default `16:9`.
+ */
+export type PageSize = '16:9' | '4:3' | '1:1' | '4:5' | '9:16';
+export declare const DEFAULT_PAGE_SIZE: PageSize;
+/** Pixel dimensions per page size (used for render aspect + export sizing). */
+export declare const PAGE_SIZE_DIMENSIONS: Record<PageSize, {
+    w: number;
+    h: number;
+}>;
+/** Resolve a page size (or undefined) to pixel dimensions, defaulting to 16:9. */
+export declare function pageSizeDimensions(pageSize: PageSize | undefined): {
+    w: number;
+    h: number;
+};
 export interface CreateCanvasInput {
     projectId: number;
     type: CanvasType;
@@ -99,7 +119,8 @@ export interface CreateCanvasInput {
     content: string;
     controls?: ControlManifest;
     values?: Record<string, ParamValue>;
+    pageSize?: PageSize;
 }
-export type UpdateCanvasInput = Partial<Pick<CanvasRecord, 'title' | 'content' | 'controls' | 'values'>>;
+export type UpdateCanvasInput = Partial<Pick<CanvasRecord, 'title' | 'content' | 'controls' | 'values' | 'pageSize'>>;
 /** 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

@@ -10,6 +10,19 @@
  * subpath `@compilr-dev/sdk/canvas` (the Desktop renderer needs the control types
  * + validation without pulling node-only deps — same pattern as `.../errors`).
  */
+export const DEFAULT_PAGE_SIZE = '16:9';
+/** Pixel dimensions per page size (used for render aspect + export sizing). */
+export const PAGE_SIZE_DIMENSIONS = {
+    '16:9': { w: 1280, h: 720 },
+    '4:3': { w: 1024, h: 768 },
+    '1:1': { w: 1080, h: 1080 },
+    '4:5': { w: 1080, h: 1350 },
+    '9:16': { w: 1080, h: 1920 },
+};
+/** Resolve a page size (or undefined) to pixel dimensions, defaulting to 16:9. */
+export function pageSizeDimensions(pageSize) {
+    return PAGE_SIZE_DIMENSIONS[pageSize ?? DEFAULT_PAGE_SIZE];
+}
 /** Seed a values map from a manifest's control defaults. */
 export function seedValues(manifest) {
     const values = {};

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

@@ -30,6 +30,7 @@ function toCanvas(r) {
         content: r.content,
         controls: parseControls(r.controls),
         values: parseValues(r.values),
+        pageSize: r.page_size ? r.page_size : undefined,
         createdAt: new Date(r.created_at),
         updatedAt: new Date(r.updated_at),
     };
@@ -53,9 +54,9 @@ export class SQLiteCanvasRepository {
         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);
+            .prepare(`INSERT INTO canvases (project_id, type, title, content, controls, "values", page_size, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.projectId, input.type, input.title, input.content, controls, values, input.pageSize ?? null, now, now);
         const record = this.db
             .prepare('SELECT * FROM canvases WHERE id = ?')
             .get(Number(result.lastInsertRowid));
@@ -80,9 +81,10 @@ export class SQLiteCanvasRepository {
         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;
+        const pageSize = input.pageSize !== undefined ? input.pageSize : existing.page_size;
         this.db
-            .prepare(`UPDATE canvases SET title = ?, content = ?, controls = ?, "values" = ?, updated_at = ? WHERE id = ?`)
-            .run(title, content, controls, values, now, id);
+            .prepare(`UPDATE canvases SET title = ?, content = ?, controls = ?, "values" = ?, page_size = ?, updated_at = ? WHERE id = ?`)
+            .run(title, content, controls, values, pageSize, now, id);
         const record = this.db.prepare('SELECT * FROM canvases WHERE id = ?').get(id);
         return Promise.resolve(toCanvas(record));
     }

package/dist/platform/sqlite/db.js

@@ -175,4 +175,9 @@ function runMigrations(db, fromVersion, toVersion) {
     `);
         db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(8);
     }
+    if (fromVersion < 9 && toVersion >= 9) {
+        // Canvas page size / aspect (carousel slide aspect). NULL = default 16:9.
+        db.exec(`ALTER TABLE canvases ADD COLUMN page_size TEXT;`);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(9);
+    }
 }

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 = 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 declare const SCHEMA_VERSION = 9;
+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;
     name: string;
@@ -71,6 +71,7 @@ export interface CanvasDbRecord {
     content: string;
     controls: string;
     values: string;
+    page_size: string | null;
     created_at: string;
     updated_at: string;
 }

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 = 8;
+export const SCHEMA_VERSION = 9;
 export const SCHEMA_SQL = `
 -- Schema version tracking
 CREATE TABLE IF NOT EXISTS schema_version (
@@ -181,6 +181,7 @@ CREATE TABLE IF NOT EXISTS canvases (
   content TEXT NOT NULL,
   controls TEXT NOT NULL DEFAULT '{"controls":[]}',
   "values" TEXT NOT NULL DEFAULT '{}',
+  page_size TEXT,
   created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
   updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
   FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE

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

@@ -17,6 +17,7 @@ export declare function createCanvasTools(config: PlatformToolsConfig): (import(
     title: string;
     html: string;
     controls?: ControlManifest;
+    page_size?: string;
     canvas_id?: number;
     project_id?: number;
 }> | import("@compilr-dev/agents").Tool<{

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

@@ -12,6 +12,7 @@
  */
 import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
 import { truncateContent } from './truncate.js';
+const PAGE_SIZES = ['16:9', '4:3', '1:1', '4:5', '9:16'];
 import { seedValues } from '../../canvas/types.js';
 import { validateControlManifest } from '../../canvas/validate.js';
 const CANVAS_TYPES = ['infographic', 'carousel', 'board'];
@@ -91,6 +92,13 @@ export function createCanvasTools(config) {
                         controls: { type: 'array', items: { type: 'object' } },
                     },
                 },
+                page_size: {
+                    type: 'string',
+                    enum: PAGE_SIZES,
+                    description: 'Optional page size / aspect — mainly the CAROUSEL slide aspect: 16:9 (widescreen, default), ' +
+                        '4:3 (standard), 1:1 (square/Instagram), 4:5 (portrait), 9:16 (story/reel). Ignored for ' +
+                        'infographic/board. Set 1:1 or 4:5 for social carousels.',
+                },
                 canvas_id: {
                     type: 'number',
                     description: 'Existing canvas id to update. Omit to create a new canvas.',
@@ -119,6 +127,7 @@ export function createCanvasTools(config) {
                         ...(input.controls
                             ? { controls: input.controls, values: seedValues(input.controls) }
                             : {}),
+                        ...(input.page_size ? { pageSize: input.page_size } : {}),
                     });
                     if (!updated)
                         return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
@@ -136,6 +145,7 @@ export function createCanvasTools(config) {
                     content: input.html,
                     controls,
                     values: seedValues(controls),
+                    pageSize: input.page_size,
                 });
                 return createSuccessResult(`Created canvas "${created.title}" (${created.type})\nID: ${String(created.id)}`);
             }

package/dist/team/consult-tool.d.ts

@@ -40,31 +40,57 @@ export interface ConsultResult {
      *  (target run exceeded max iterations, transport error, etc.). */
     error?: string;
 }
+/** Default wall-clock cap for a whole consult sub-run (ms). */
+export declare const DEFAULT_CONSULT_TIMEOUT_MS = 180000;
+/**
+ * Options passed to `onConsult` alongside the question. Additive — hosts
+ * that predate the timeout work can ignore `signal` and keep compiling,
+ * but they will NOT get the hang protection until they forward it into
+ * their target `agent.run(..., { signal })`.
+ */
+export interface ConsultRunOptions {
+    /**
+     * Aborts when the wall-clock timeout fires (or the host links its own
+     * borrower signal to it). Implementations MUST forward this into the
+     * target agent's run so an expired consult actually stops the sub-run
+     * instead of orphaning it.
+     */
+    signal: AbortSignal;
+}
 /**
  * Configuration for `createConsultTool`.
  *
  * `onConsult` is intentionally platform-shaped — each host runs sub-agents
  * differently (CLI's REPL sub-context, Desktop's agent-manager, in-process
- * Agent.run). The SDK owns validation and message format; the platform
- * owns the actual run.
+ * Agent.run). The SDK owns validation, message format, and the wall-clock
+ * timeout; the platform owns the actual run.
  */
 export interface ConsultToolConfig {
     /** The team instance — used to validate target agent membership. */
     team: AgentTeam;
     /** The borrowing agent's ID. */
     currentAgentId: string;
+    /**
+     * Wall-clock cap for the whole consult sub-run, in ms. The SDK arms a
+     * timer, aborts `signal` on expiry, and returns a recoverable timeout
+     * error to the borrower's LLM. Defaults to {@link DEFAULT_CONSULT_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
     /**
      * Platform-specific consult handler. Called after validation passes.
      * Should:
      *   1. Synthesise the question message (use `buildConsultQuestionMessage`).
-     *   2. Run the target agent against that message (sub-run, not a turn
-     *      in the borrower's conversation).
+     *   2. Run the target agent against that message, **history-aware** (the
+     *      target's real agent/history — NOT a throwaway or snapshot-restored
+     *      run), forwarding `opts.signal` into the run so the timeout can
+     *      abort it.
      *   3. Return the target's final response text.
      *
-     * The target's conversation history is NOT mutated by a consult — the
-     * call is transient.
+     * As of consult v2 the target DOES remember the exchange — the historical
+     * "transient / history not mutated" contract is removed. See
+     * `consult-persistent-conversation-spec.md`.
      */
-    onConsult: (targetAgentId: string, question: string, context: string | undefined) => Promise<{
+    onConsult: (targetAgentId: string, question: string, context: string | undefined, opts: ConsultRunOptions) => Promise<{
         answer: string;
         error?: string;
     }>;

package/dist/team/consult-tool.js

@@ -21,6 +21,8 @@
  *   /workspace/project-docs/00-requirements/compilr-dev-sdk/consult-tool-spec.md
  */
 import { defineTool } from '@compilr-dev/agents';
+/** Default wall-clock cap for a whole consult sub-run (ms). */
+export const DEFAULT_CONSULT_TIMEOUT_MS = 180_000;
 // =============================================================================
 // Canonical question-message format
 // =============================================================================
@@ -63,10 +65,12 @@ export function buildConsultQuestionMessage(input) {
  */
 export function createConsultTool(config) {
     const { team, currentAgentId, onConsult } = config;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_CONSULT_TIMEOUT_MS;
     return defineTool({
         name: 'consult',
-        description: 'Ask another specialist a focused question and continue the conversation yourself. ' +
-            'Use this when you need a quick opinion or expertise input from a teammate without giving up the conversation. ' +
+        description: 'Ask a teammate a focused question and continue your own work. ' +
+            'They answer using their own context and remember the exchange, so a consult is a real interaction in their conversation — not a throwaway. ' +
+            'Use this when you need a quick opinion or expertise from a teammate without giving up the conversation. ' +
             'Unlike handoff, you keep ownership — the target answers and control returns to you. ' +
             'Example: $arch can consult $pm on scope, get an answer, and continue designing.',
         inputSchema: {
@@ -123,8 +127,19 @@ export function createConsultTool(config) {
                     error: `Agent "${targetId}" not found in team. Available specialists: ${available || '(none)'}`,
                 };
             }
+            // Wall-clock cap for the whole sub-run. The SDK owns this so BOTH
+            // hosts inherit the hang fix without duplicating timeout logic. On
+            // expiry we abort the signal (the host forwards it into the target
+            // run) and hand the borrower's LLM a recoverable error rather than
+            // hanging "running" forever — the failure mode observed in testing.
+            const ac = new AbortController();
+            const timer = setTimeout(() => {
+                ac.abort(new Error('consult-timeout'));
+            }, timeoutMs);
             try {
-                const { answer, error } = await onConsult(targetId, question, context);
+                const { answer, error } = await onConsult(targetId, question, context, {
+                    signal: ac.signal,
+                });
                 if (error) {
                     return { success: false, error };
                 }
@@ -132,11 +147,23 @@ export function createConsultTool(config) {
                 return { success: true, result };
             }
             catch (err) {
+                if (ac.signal.aborted) {
+                    const seconds = String(Math.round(timeoutMs / 1000));
+                    return {
+                        success: false,
+                        error: `$${targetId} didn't respond in time (${seconds}s). ` +
+                            'It may have a pending question — the request was surfaced in your chat. ' +
+                            'You can try consulting again, ask the user, or proceed without it.',
+                    };
+                }
                 return {
                     success: false,
                     error: `Consult failed: ${err instanceof Error ? err.message : String(err)}`,
                 };
             }
+            finally {
+                clearTimeout(timer);
+            }
         },
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.17.17",
+  "version": "0.18.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",