@compilr-dev/sdk 0.29.8 → 0.30.0

package/dist/canvas/types.d.ts

@@ -10,7 +10,15 @@
  * 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';
+/**
+ * `scene` is a 3D scene (3d-canvas-spec §3): its `content` is scene JSON (see `scene.ts`), not
+ * HTML — it is edited only through the scene writer / `scene_*` tools and drawn by the host's
+ * 3D viewer, never the HTML iframe.
+ */
+export type CanvasType = 'infographic' | 'carousel' | 'board' | 'scene';
+/** The canvas types whose content is HTML/SVG (everything but `scene`). */
+export type HtmlCanvasType = Exclude<CanvasType, 'scene'>;
+export declare const HTML_CANVAS_TYPES: readonly HtmlCanvasType[];
 /** A control's runtime value. */
 export type ParamValue = string | number | boolean;
 export interface SliderControl {

package/dist/canvas/types.js

@@ -10,6 +10,7 @@
  * subpath `@compilr-dev/sdk/canvas` (the Desktop renderer needs the control types
  * + validation without pulling node-only deps — same pattern as `.../errors`).
  */
+export const HTML_CANVAS_TYPES = ['infographic', 'carousel', 'board'];
 export const DEFAULT_PAGE_SIZE = '16:9';
 /** Pixel dimensions per page size (used for render aspect + export sizing). */
 export const PAGE_SIZE_DIMENSIONS = {

package/dist/capabilities/packs.d.ts

@@ -4,7 +4,7 @@
  * Maps each tool group (from tool-config.ts) to a capability pack with
  * associated prompt modules and usage guidance.
  *
- * 24 packs total, matching 1:1 with TOOL_GROUPS keys.
+ * 33 packs total, matching 1:1 with TOOL_GROUPS keys.
  */
 import type { CapabilityPack } from './types.js';
 /**

package/dist/capabilities/packs.js

@@ -4,7 +4,7 @@
  * Maps each tool group (from tool-config.ts) to a capability pack with
  * associated prompt modules and usage guidance.
  *
- * 24 packs total, matching 1:1 with TOOL_GROUPS keys.
+ * 33 packs total, matching 1:1 with TOOL_GROUPS keys.
  */
 /**
  * All capability pack definitions.
@@ -261,10 +261,36 @@ export const CAPABILITY_PACKS = {
             // ⚠️ 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,
+            '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. ' +
+            // Last, so the guide-first order above is untouched (canvas-guide.test).
+            '3D scenes are JSON, not HTML — they use the scene tools (scene_create, scene_add_object…), never these.',
+        estimatedPromptTokens: 215,
         estimatedToolTokens: 1500,
     },
+    // A separate pack, not folded into `canvas`: that pack is ~1.5k tokens of HTML guidance a
+    // scene agent never needs, and packs load lazily (3d-canvas-spec §6.3).
+    scene: {
+        id: 'scene',
+        label: '3D Scene',
+        tools: [
+            'scene_create',
+            'scene_get',
+            'scene_add_object',
+            'scene_update_object',
+            'scene_remove_object',
+            'scene_set_camera',
+            'scene_screenshot',
+        ],
+        readOnly: false,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: "3D scenes are JSON, not code. Units metres; position.y is the object's BOTTOM (0 = on the floor); " +
+            'rotation in degrees (rotate about Y). Types: box(size w,h,d), sphere(radius), cylinder/cone(radius, ' +
+            'height), torus(radius, tube; flat), extrude(points [[x,z],…], height) for walls and floors. Read with ' +
+            'scene_get before editing — the user edits too. Add up to 50 objects per scene_add_object call ' +
+            '(objects: [...]). Keep neutral colours unless asked. After building, scene_screenshot to check.',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 1400,
+    },
     plans: {
         id: 'plans',
         label: 'Planning',
@@ -476,6 +502,7 @@ export const FORBIDDEN_PACK_SUGGESTIONS = {
     backlog_read: '$pm',
     documents: '$pm',
     canvas: '$default',
+    scene: '$default',
     plans: '$pm',
     search: '$arch',
     dependencies: '$arch',

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, ICanvasRepository, 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, ICanvasRenderer, RenderedCanvasImage, 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, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createSceneTools, SCENE_TOOL_NAMES, createSceneWriter, SCENE_JOURNAL_SIZE, 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, InstalledFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
@@ -96,6 +96,9 @@ export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createL
 export { classifyAgentError, isApiKeyError } from './errors/classify.js';
 export type { AgentErrorCategory, AgentErrorInfo } from './errors/classify.js';
 export { validateControlManifest, seedValues } from './canvas/index.js';
+export { validateScene, normalizeScene, serializeScene, emptyScene, sceneBounds, fitCamera, liftFor, describeScene, applySceneOp, applySceneOps, formatUserEditNotice, SCENE_MAX_OBJECTS, SCENE_MAX_BYTES, SCENE_MAX_BATCH, HTML_CANVAS_TYPES, } from './canvas/index.js';
+export type { HtmlCanvasType, SceneFile, SceneObject, SceneObjectType, SceneCamera, SceneLight, SceneMaterial, SceneOp, SceneChange, SceneEditSource, } from './canvas/index.js';
+export type { ISceneWriter, SceneReadResult, SceneApplyResult, SceneCreateResult, SceneLastEdit, } from './platform/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';

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, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createSceneTools, SCENE_TOOL_NAMES, createSceneWriter, SCENE_JOURNAL_SIZE, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 // =============================================================================
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================
@@ -207,6 +207,8 @@ 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';
+// 3D scenes (the `scene` canvas type) — contract + pure ops. Also at `@compilr-dev/sdk/canvas`.
+export { validateScene, normalizeScene, serializeScene, emptyScene, sceneBounds, fitCamera, liftFor, describeScene, applySceneOp, applySceneOps, formatUserEditNotice, SCENE_MAX_OBJECTS, SCENE_MAX_BYTES, SCENE_MAX_BATCH, HTML_CANVAS_TYPES, } from './canvas/index.js';
 // =============================================================================
 // Shared Permission Defaults & Utilities
 // =============================================================================

package/dist/platform/context.d.ts

@@ -6,6 +6,7 @@
  */
 import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, ICanvasRepository } from './repositories.js';
 import type { IAnchorService, IArtifactService, IEpisodeService, ICanvasRenderer } from './services.js';
+import type { ISceneWriter } from './scene-writer.js';
 export interface PlatformContext {
     readonly projects: IProjectRepository;
     readonly workItems: IWorkItemRepository;
@@ -17,8 +18,15 @@ export interface PlatformContext {
     readonly episodes?: IEpisodeService;
     readonly canvases?: ICanvasRepository;
     readonly comments?: ICommentRepository;
-    /** Host-provided canvas → image renderer (for canvas_screenshot). */
+    /** Host-provided canvas → image renderer (for canvas_screenshot / scene_screenshot). */
     readonly canvasRenderer?: ICanvasRenderer;
+    /**
+     * The scene writer (3d-canvas-spec §4.2). ⚠️ Hosts that edit scenes themselves (Desktop's
+     * inspector) MUST pass the same instance they use, or the two paths hold separate locks and
+     * journals — edits interleave and the agent is never told about the user's changes. When
+     * absent, `createPlatformTools` builds one from `canvases`.
+     */
+    readonly sceneWriter?: ISceneWriter;
 }
 export interface PlatformHooks {
     /** Called when a project is resolved/selected as the current project */
@@ -53,6 +61,15 @@ export interface PlatformToolsConfig {
     cwd?: string | (() => string | undefined | null);
     /** Optional hooks for CLI-specific side effects */
     hooks?: PlatformHooks;
+    /**
+     * Which canvas surfaces get tools when `context.canvases` is present (both default true).
+     * The CLI passes `{ html: false, scene: true }`: HTML canvases have no terminal surface,
+     * but scene tools are data edits, useful without a viewer (3d-canvas-spec §7).
+     */
+    canvasSurfaces?: {
+        html?: boolean;
+        scene?: boolean;
+    };
 }
 /**
  * Resolve a `cwd` that may be a value or a getter.

package/dist/platform/index.d.ts

@@ -3,9 +3,11 @@
  */
 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, ICanvasRepository, } from './repositories.js';
-export type { IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, } from './services.js';
+export type { IAnchorService, IArtifactService, IEpisodeService, ICanvasRenderer, RenderedCanvasImage, 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, createCanvasTools, createImageTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createSceneTools, SCENE_TOOL_NAMES, sceneOutline, createImageTools, } from './tools/index.js';
+export { createSceneWriter, SCENE_JOURNAL_SIZE } from './scene-writer.js';
+export type { ISceneWriter, SceneReadResult, SceneApplyResult, SceneCreateResult, SceneLastEdit, } from './scene-writer.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,10 @@
  * Platform — Repository interfaces, data models, tools, and workflow.
  */
 // Platform tools (runtime)
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createSceneTools, SCENE_TOOL_NAMES, sceneOutline, createImageTools, } from './tools/index.js';
+// The scene writer — one per host process, shared by the scene tools and the host's own
+// edit path (Desktop's scene:apply IPC). See 3d-canvas-spec §4.2.
+export { createSceneWriter, SCENE_JOURNAL_SIZE } from './scene-writer.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/scene-writer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The scene writer — the ONE path every scene edit takes (3d-canvas-spec §4.2).
+ *
+ * Agent tools and the user's inspector (Desktop's `scene:apply` IPC) both call the same
+ * instance, so both land in the same stored record and each sees the other's changes.
+ *
+ * - Serialised per canvas: `apply` is read → ops → validate → write, and the repository's
+ *   `getById` and `update` are two awaits. Without the lock, two callers (an agent tool and an
+ *   inspector edit, both in Desktop's main process) interleave between them and one edit is
+ *   silently lost. Cross-PROCESS writers (CLI + Desktop on one projects.db) are not serialised —
+ *   the same exposure every repository has today.
+ * - Atomic batches: all ops validate against the final scene, or nothing is stored.
+ * - Revisions: an in-memory per-canvas counter (0 at process start). Not storage — it exists
+ *   for the user-edit notice and the inspector's stale-read check.
+ * - Journal: the last 50 USER changes per canvas, so an agent's next scene tool result can say
+ *   "the user moved the sofa" instead of the agent overwriting it from a stale picture.
+ *
+ * One instance per host process. Hosts create it and pass it as `PlatformContext.sceneWriter`
+ * AND use it in their own edit path; `createPlatformTools` builds one only when absent.
+ */
+import type { ICanvasRepository } from './repositories.js';
+import type { CanvasRecord } from '../canvas/types.js';
+import { type SceneFile, type SceneObject } from '../canvas/scene.js';
+import { type SceneChange, type SceneEditSource, type SceneOp } from '../canvas/scene-ops.js';
+/** How many user changes are kept per canvas. */
+export declare const SCENE_JOURNAL_SIZE = 50;
+export interface SceneLastEdit {
+    rev: number;
+    source: SceneEditSource;
+    ids: string[];
+}
+export type SceneReadResult = {
+    ok: true;
+    canvasId: number;
+    projectId: number;
+    title: string;
+    scene: SceneFile;
+    rev: number;
+    /** The most recent edit this process made (for P2's grow-in of agent-added ids). */
+    lastEdit?: SceneLastEdit;
+} | {
+    ok: false;
+    reason: 'not_found' | 'not_scene' | 'invalid';
+    error: string;
+};
+export type SceneApplyResult = {
+    ok: true;
+    canvasId: number;
+    title: string;
+    scene: SceneFile;
+    rev: number;
+    summaries: string[];
+    ids: string[];
+    warnings: string[];
+    /** Objects removed by this apply, with their former index — for an undo (Q-4). */
+    removed: {
+        index: number;
+        object: SceneObject;
+    }[];
+} | {
+    ok: false;
+    error: string;
+};
+export type SceneCreateResult = {
+    ok: true;
+    canvas: CanvasRecord;
+    scene: SceneFile;
+    rev: number;
+} | {
+    ok: false;
+    error: string;
+};
+export interface ISceneWriter {
+    /** Create a scene canvas. `scene` is optional (empty scene) and validated when given. */
+    create(input: {
+        projectId: number;
+        title: string;
+        scene?: unknown;
+    }): Promise<SceneCreateResult>;
+    /** The latest stored scene and its revision. Never cached. */
+    read(canvasId: number): Promise<SceneReadResult>;
+    /** Apply ops atomically under the canvas's lock. */
+    apply(canvasId: number, ops: SceneOp[], source: SceneEditSource): Promise<SceneApplyResult>;
+    /** User changes with rev > `rev` (oldest first). */
+    userEditsSince(canvasId: number, rev: number): SceneChange[];
+    /**
+     * User changes the agent (`agentKey`, default "") has not been told about, and marks them
+     * told. Call it only after a SUCCESSFUL scene tool call — the notice rides on successes. An
+     * agent's first contact with a canvas returns nothing: it has no stale picture to correct.
+     */
+    consumeUserEdits(canvasId: number, agentKey?: string): SceneChange[];
+    /** The current in-memory revision (0 when this process has not written it). */
+    revision(canvasId: number): number;
+}
+export declare function createSceneWriter(repo: ICanvasRepository): ISceneWriter;

package/dist/platform/scene-writer.js

@@ -0,0 +1,184 @@
+/**
+ * The scene writer — the ONE path every scene edit takes (3d-canvas-spec §4.2).
+ *
+ * Agent tools and the user's inspector (Desktop's `scene:apply` IPC) both call the same
+ * instance, so both land in the same stored record and each sees the other's changes.
+ *
+ * - Serialised per canvas: `apply` is read → ops → validate → write, and the repository's
+ *   `getById` and `update` are two awaits. Without the lock, two callers (an agent tool and an
+ *   inspector edit, both in Desktop's main process) interleave between them and one edit is
+ *   silently lost. Cross-PROCESS writers (CLI + Desktop on one projects.db) are not serialised —
+ *   the same exposure every repository has today.
+ * - Atomic batches: all ops validate against the final scene, or nothing is stored.
+ * - Revisions: an in-memory per-canvas counter (0 at process start). Not storage — it exists
+ *   for the user-edit notice and the inspector's stale-read check.
+ * - Journal: the last 50 USER changes per canvas, so an agent's next scene tool result can say
+ *   "the user moved the sofa" instead of the agent overwriting it from a stale picture.
+ *
+ * One instance per host process. Hosts create it and pass it as `PlatformContext.sceneWriter`
+ * AND use it in their own edit path; `createPlatformTools` builds one only when absent.
+ */
+import { emptyScene, normalizeScene, serializeScene, validateScene, } from '../canvas/scene.js';
+import { applySceneOps, formatValidationErrors, } from '../canvas/scene-ops.js';
+/** How many user changes are kept per canvas. */
+export const SCENE_JOURNAL_SIZE = 50;
+function htmlCanvasError(c) {
+    return (`Canvas ${String(c.id)} is an HTML canvas (${c.type}), not a 3D scene; use canvas_edit ` +
+        '(or canvas_write) for it. 3D scenes are made with scene_create.');
+}
+function notFound(canvasId) {
+    return `Canvas ${String(canvasId)} not found. List canvases with canvas_list.`;
+}
+/** Parse + validate stored content. */
+function parseStored(c) {
+    let raw;
+    try {
+        raw = JSON.parse(c.content);
+    }
+    catch (e) {
+        return {
+            error: `Canvas ${String(c.id)}'s stored scene is not valid JSON (${e instanceof Error ? e.message : String(e)}).`,
+        };
+    }
+    const v = validateScene(raw);
+    if (!v.ok) {
+        return {
+            error: `Canvas ${String(c.id)}'s stored scene is invalid:\n${v.errors
+                .slice(0, 8)
+                .map((e) => `- ${e}`)
+                .join('\n')}`,
+        };
+    }
+    return { scene: normalizeScene(v.scene) };
+}
+export function createSceneWriter(repo) {
+    const revs = new Map();
+    const journals = new Map();
+    const lastEdits = new Map();
+    /** `${canvasId}:${agentKey}` → the rev that agent was last told about. */
+    const seen = new Map();
+    /** Per-canvas promise chain — the in-process mutex. */
+    const chains = new Map();
+    function withLock(canvasId, fn) {
+        const prev = chains.get(canvasId) ?? Promise.resolve();
+        const run = prev.then(fn);
+        const tail = run.then(() => undefined, () => undefined);
+        chains.set(canvasId, tail);
+        void tail.then(() => {
+            if (chains.get(canvasId) === tail)
+                chains.delete(canvasId);
+        });
+        return run;
+    }
+    const revision = (canvasId) => revs.get(canvasId) ?? 0;
+    return {
+        revision,
+        async create(input) {
+            const title = input.title.trim();
+            if (!title)
+                return { ok: false, error: 'A scene needs a title.' };
+            let candidate;
+            if (input.scene === undefined || input.scene === null) {
+                candidate = emptyScene(title);
+            }
+            else if (typeof input.scene === 'object' && !Array.isArray(input.scene)) {
+                // Convenience: the envelope fields default from the title, so an agent can pass
+                // just { objects: [...] }. Everything else is validated as given.
+                candidate = { version: 1, units: 'm', name: title.slice(0, 80), ...input.scene };
+            }
+            else {
+                candidate = input.scene;
+            }
+            const v = validateScene(candidate);
+            if (!v.ok)
+                return { ok: false, error: formatValidationErrors(v.errors) };
+            const scene = normalizeScene(v.scene);
+            const canvas = await repo.create({
+                projectId: input.projectId,
+                type: 'scene',
+                title,
+                content: serializeScene(scene),
+                controls: { controls: [] },
+                values: {},
+            });
+            revs.set(canvas.id, 0);
+            return { ok: true, canvas, scene, rev: 0 };
+        },
+        async read(canvasId) {
+            const c = await repo.getById(canvasId);
+            if (!c)
+                return { ok: false, reason: 'not_found', error: notFound(canvasId) };
+            if (c.type !== 'scene')
+                return { ok: false, reason: 'not_scene', error: htmlCanvasError(c) };
+            const parsed = parseStored(c);
+            if ('error' in parsed)
+                return { ok: false, reason: 'invalid', error: parsed.error };
+            return {
+                ok: true,
+                canvasId: c.id,
+                projectId: c.projectId,
+                title: c.title,
+                scene: parsed.scene,
+                rev: revision(canvasId),
+                lastEdit: lastEdits.get(canvasId),
+            };
+        },
+        apply(canvasId, ops, source) {
+            return withLock(canvasId, async () => {
+                const c = await repo.getById(canvasId);
+                if (!c)
+                    return { ok: false, error: notFound(canvasId) };
+                if (c.type !== 'scene')
+                    return { ok: false, error: htmlCanvasError(c) };
+                const parsed = parseStored(c);
+                let current;
+                if ('error' in parsed) {
+                    // A broken record can still be REPLACED — that is the way out of it.
+                    if (ops[0]?.op !== 'replace')
+                        return { ok: false, error: parsed.error };
+                    current = null;
+                }
+                else
+                    current = parsed.scene;
+                const r = applySceneOps(current, ops, { source, canvasId });
+                if (!r.ok)
+                    return { ok: false, error: r.error };
+                const updated = await repo.update(canvasId, { content: serializeScene(r.scene) });
+                if (!updated)
+                    return { ok: false, error: notFound(canvasId) };
+                const rev = revision(canvasId) + 1;
+                revs.set(canvasId, rev);
+                lastEdits.set(canvasId, { rev, source, ids: r.ids });
+                if (source.kind === 'user' && r.changes.length > 0) {
+                    const journal = journals.get(canvasId) ?? [];
+                    for (const ch of r.changes)
+                        journal.push({ ...ch, rev });
+                    journals.set(canvasId, journal.slice(-SCENE_JOURNAL_SIZE));
+                }
+                return {
+                    ok: true,
+                    canvasId,
+                    title: updated.title,
+                    scene: r.scene,
+                    rev,
+                    summaries: r.summaries,
+                    ids: r.ids,
+                    warnings: r.warnings,
+                    removed: r.removed,
+                };
+            });
+        },
+        userEditsSince(canvasId, rev) {
+            return (journals.get(canvasId) ?? []).filter((c) => c.rev > rev);
+        },
+        consumeUserEdits(canvasId, agentKey = '') {
+            const key = `${String(canvasId)}:${agentKey}`;
+            const last = seen.get(key);
+            const now = revision(canvasId);
+            seen.set(key, now);
+            if (last === undefined)
+                return [];
+            return (journals.get(canvasId) ?? []).filter((c) => c.rev > last && c.rev <= now);
+        },
+    };
+}

package/dist/platform/services.d.ts

@@ -5,6 +5,8 @@
  * FileEpisodeStore) so tool definitions can live in the SDK.
  */
 import type { AnchorPriority, WorkEpisode, ProjectWorkSummary } from '@compilr-dev/agents';
+import type { HtmlCanvasType } from '../canvas/types.js';
+import type { SceneFile } from '../canvas/scene.js';
 export interface AnchorData {
     id: string;
     content: string;
@@ -115,7 +117,23 @@ export interface ICanvasRenderer {
     renderToImage(input: {
         /** Raw canvas HTML/SVG (the stored content). */
         content: string;
-        /** Canvas type — the host sizes/wraps accordingly. */
-        type: 'infographic' | 'carousel' | 'board';
+        /**
+         * Canvas type — the host sizes/wraps accordingly. Derived from `CanvasType` (it used to
+         * be a second hand-written copy of the union); scenes never reach here — they go to
+         * `renderSceneToImage`.
+         */
+        type: HtmlCanvasType;
+    }): Promise<RenderedCanvasImage>;
+    /**
+     * Render a 3D scene (3d-canvas-spec §8) for `scene_screenshot` / `canvas_screenshot`.
+     * OPTIONAL: a host without a 3D viewer omits it and the tools answer "not available in
+     * this environment". The scene is validated and normalised; the host uses its own camera
+     * when present, else `fitCamera(sceneBounds(scene))`, grid on, neutral light theme.
+     */
+    renderSceneToImage?(input: {
+        scene: SceneFile;
+        /** CSS px. Defaults chosen by the tool: 1280 × 800. */
+        width: number;
+        height: number;
     }): Promise<RenderedCanvasImage>;
 }