@neta-art/cohub 10.0.0 → 11.1.0

package/README.md

@@ -46,18 +46,39 @@ Development uses:
 - API: `https://api-dev.cohub.live`
 - WebSocket: `wss://gateway-dev.cohub.live/ws`
 
-Custom endpoints are still supported when needed:
+Override endpoints for self-hosted deployments or proxies:
 
 ```ts
 const client = createCohubClient({
   baseUrl: "https://api.example.com",
+  webBaseUrl: "https://cohub.example.com",
   getAccessToken: async () => localStorage.getItem("token"),
   websocket: {
     url: "https://gateway.example.com",
   },
+  voice: {
+    url: "https://gateway.example.com",
+  },
 });
 ```
 
+In Node.js, the SDK and CLI share these optional environment variables:
+
+| Variable | Endpoint |
+| --- | --- |
+| `COHUB_BASE_URL` | API base URL |
+| `COHUB_WS_URL` | Realtime gateway URL (`http(s)` or `ws(s)`; `/ws` is added when omitted) |
+| `COHUB_WEB_URL` | Web origin for App authorization and CLI links |
+| `COHUB_VOICE_WS_URL` | Voice input gateway URL; falls back to `COHUB_WS_URL` with `/asr/ws` |
+
+Explicit client options take precedence over environment variables. Unconfigured
+endpoints use the selected environment's defaults. API, web, and gateway addresses
+are configured separately; changing `baseUrl` does not change the gateway.
+
+```bash
+COHUB_BASE_URL=http://localhost:3000 COHUB_WS_URL=ws://localhost:8080 node app.js
+```
+
 ## Spaces and sessions
 
 A **Space** is a live, isolated working environment where users and agents create together.
@@ -101,10 +122,15 @@ const stop = board.subscribe({
 });
 ```
 
-Task Items keep a small, replaceable display snapshot beside their stable
-`taskRunId`; build it from an authoritative TaskRun with
-`taskRunToBoardTaskSnapshot(taskRun)` from `@neta-art/cohub/board`, and restore
-a Board's TaskRuns in one request with `client.tasks.getMany(ids, { spaceId })`.
+Task Items show a run by its `taskRunId`. Write only the id; the server fills
+the display snapshot from the run and rewrites it when the run finishes, on
+every Board in the Space that shows it. Lay a run's results out as media with
+`createTaskResultItems`; each result keeps an `origin` leading back to the run.
+
+```ts
+const { taskRunId } = await client.generations.create({ spaceId, model, content });
+await board.apply({ items: { hero: { type: "task", position: { x: 80, y: 80 }, size: { width: 480, height: 270 }, props: { taskRunId } } } });
+```
 
 ### Layers
 
@@ -131,7 +157,7 @@ The editor has no framework. Read state through its getters and listen with
 change, so they work directly with `useSyncExternalStore`:
 
 ```ts
-import { createBoardRegistry, defineBoardItem } from "@neta-art/cohub/board";
+import { createBoardRegistry, defineBoardItem, worldPoint } from "@neta-art/cohub/board";
 import { createBoardEditor } from "@neta-art/cohub/board/editor";
 import { createBoardReplica } from "@neta-art/cohub/board/replica";
 import { createBoardAssetManager, mountBoardStage } from "@neta-art/cohub/board/stage";
@@ -157,7 +183,16 @@ const editor = createBoardEditor({
 });
 replica.subscribe((state) => state.document && editor.loadDocument(state.document, boardId));
 
-// Where Space file paths resolve; a published copy could resolve elsewhere.
+// Prefer stable media URLs. Existing Space paths remain supported by addFile.
+editor.addMedia("https://cdn.example.com/cover.webp", worldPoint(0, 0));
+// Supply a kind for sources without a file extension.
+editor.addMedia("https://cdn.example.com/media?id=42", worldPoint(400, 0), {
+  kind: "video",
+  snapshot: { title: "Launch", naturalWidth: 1920, naturalHeight: 1080 },
+});
+
+// Media URLs load directly; these callbacks only receive Space paths.
+// A published copy can resolve paths against captured artifacts instead.
 const source = {
   resolveFileUrl: (path: string) => space.files.resolveUrl(path, { purpose: "preview" }),
   resolvePlaybackUrl: (path: string) => space.files.resolveUrl(path, { purpose: "playback" }),

package/dist/board/editor/animation.d.ts

@@ -1,3 +1,5 @@
+import { BoardChapter } from "../model/authoring.js";
+import "../model/index.js";
 import { BoardPlayhead, EditorContext } from "./context.js";
 //#region src/board/editor/animation.d.ts
 declare function createAnimationModule(ctx: EditorContext): {
@@ -8,6 +10,7 @@ declare function createAnimationModule(ctx: EditorContext): {
   removeKeyframe: (trackId: string, at: number) => void;
   setKeyframeEase: (trackId: string, at: number, ease: string | null) => void;
   createAnimation: (name: string, duration?: number) => string;
+  createSequence: (name: string, chapters: BoardChapter[]) => string | null;
 };
 type AnimationModule = ReturnType<typeof createAnimationModule>;
 //#endregion

package/dist/board/editor/animation.js

@@ -1,3 +1,4 @@
+import { boardSequence } from "../model/authoring.js";
 import { createBoardItemId } from "../model/items/id.js";
 import { readPath, sameJson } from "./document-edits.js";
 //#region src/board/editor/animation.ts
@@ -158,6 +159,19 @@ function createAnimationModule(ctx) {
 		});
 		return id;
 	}
+	function createSequence(name, chapters) {
+		if (options.readonly) return null;
+		const id = createBoardItemId();
+		commitAnimation(id, {
+			...boardSequence(state.base, chapters),
+			name
+		});
+		setPlayhead({
+			animationId: id,
+			time: 0
+		});
+		return id;
+	}
 	return {
 		setPlayhead,
 		setRecording,
@@ -165,7 +179,8 @@ function createAnimationModule(ctx) {
 		toggleKeyframe,
 		removeKeyframe,
 		setKeyframeEase,
-		createAnimation
+		createAnimation,
+		createSequence
 	};
 }
 //#endregion

package/dist/board/editor/clipboard.js

@@ -65,6 +65,13 @@ function remapItems(items, idMap, place = (item) => item, resolveEnd = () => nul
 		let item = place(source);
 		const { locked: _locked, ...unlocked } = item;
 		item = unlocked;
+		if (item.script) item = {
+			...item,
+			script: {
+				...item.script,
+				targets: Object.fromEntries(Object.entries(item.script.targets).map(([name, target]) => [name, idMap.get(target) ?? target]))
+			}
+		};
 		if (item.parent) {
 			const parent = idMap.get(item.parent);
 			if (parent) item = {

package/dist/board/editor/copy.js

@@ -7,35 +7,39 @@ function createCopyModule(ctx) {
 	const { state, options } = ctx;
 	let internalClipboard = null;
 	let pasteCount = 0;
-	function detachedSubtrees(ids) {
-		const { scene } = state;
+	function detachedSubtrees(ids, scene) {
 		const items = {};
 		for (const root of ctx.query.rootsOf(ids)) {
 			const item = scene.get(root);
-			if (!item) continue;
+			if (!item || !state.base.items[root]) continue;
 			const { id: _id, frame, ...stored } = item;
 			items[root] = ctx.document.reparent(stored, frame, void 0, scene.layout.box(root));
 			for (const child of scene.descendants(root)) {
-				const value = ctx.document.displayItem(child);
-				if (value) items[child] = value;
+				if (!state.base.items[child]) continue;
+				const shown = scene.get(child);
+				if (shown) {
+					const { id: _id, frame: _frame, ...value } = shown;
+					items[child] = value;
+				}
 			}
 		}
 		return items;
 	}
-	function arrowEndPoint(id, which) {
-		const arrow = state.scene.get(id);
+	function arrowEndPoint(scene, id, which) {
+		const arrow = scene.get(id);
 		if (arrow?.type !== "arrow") return null;
-		const resolved = resolveSceneArrow(arrow, state.scene);
-		return applyMatrix(invertMatrix(state.scene.layout.matrix(id)), (which === "start" ? resolved.start : resolved.end).point);
+		const resolved = resolveSceneArrow(arrow, scene);
+		return applyMatrix(invertMatrix(scene.layout.matrix(id)), (which === "start" ? resolved.start : resolved.end).point);
 	}
 	function duplicates(ids, offset) {
-		const { scene } = state;
-		const copied = detachedSubtrees(ids);
+		const scene = ctx.document.copyScene();
+		const copied = detachedSubtrees(ids, scene);
 		for (const id of Object.keys(copied)) for (const arrowId of scene.binders(id)) {
-			const arrow = ctx.document.displayItem(arrowId);
+			if (!state.base.items[arrowId]) continue;
 			const shown = scene.get(arrowId);
-			if (copied[arrowId] || !arrow || !shown || !arrowBindings(arrow).every((bound) => copied[bound])) continue;
-			copied[arrowId] = ctx.document.reparent(arrow, shown.frame, void 0, scene.layout.box(arrowId));
+			if (copied[arrowId] || !shown || !arrowBindings(shown).every((bound) => copied[bound])) continue;
+			const { id: _id, frame, ...arrow } = shown;
+			copied[arrowId] = ctx.document.reparent(arrow, frame, void 0, scene.layout.box(arrowId));
 		}
 		const idMap = new Map(Object.keys(copied).map((id) => [id, createBoardItemId()]));
 		const moved = remapItems(copied, idMap, (item) => item.parent && copied[item.parent] ? item : {
@@ -44,8 +48,8 @@ function createCopyModule(ctx) {
 				x: item.position.x + offset,
 				y: item.position.y + offset
 			}
-		}, arrowEndPoint);
-		let z = ctx.document.topZ(void 0);
+		}, (id, which) => arrowEndPoint(scene, id, which));
+		let z = ctx.document.topZ(void 0, scene);
 		return new Map(Object.entries(moved).map(([id, item]) => [id, item.parent ? item : {
 			...item,
 			z: z++
@@ -66,8 +70,9 @@ function createCopyModule(ctx) {
 	function copySelection() {
 		const { selection } = state;
 		if (selection.length === 0) return null;
-		const copied = detachedSubtrees(selection);
-		const origin = ctx.query.contentBounds(ctx.query.rootsOf(selection));
+		const scene = ctx.document.copyScene();
+		const copied = detachedSubtrees(selection, scene);
+		const origin = ctx.query.contentBounds(ctx.query.rootsOf(selection), scene);
 		const payload = origin ? encodeClipboard(copied, {
 			x: origin.x,
 			y: origin.y

package/dist/board/editor/creation.d.ts

@@ -3,7 +3,7 @@ import { BoardMatrix } from "../../protocol/dist/board-layout.js";
 import { WorldPoint } from "../model/geometry.js";
 import { BoardFileSnapshotFacts } from "../model/file-snapshot.js";
 import { ShapeKind } from "../model/shape-types.js";
-import { BoardItemEntry, createAppBoardItem } from "../model/items/create.js";
+import { BoardItemEntry, BoardMediaItemKind, createAppBoardItem } from "../model/items/create.js";
 import { BoardItemInput } from "../model/items/registry.js";
 import "../model/index.js";
 import { BoardInteraction } from "./interaction.js";
@@ -23,9 +23,13 @@ declare function createCreationModule(ctx: EditorContext): {
   }) => void;
   addItem: (type: string, input: BoardItemInput) => string | null;
   addApp: (app: BoardAppMetadata, at: WorldPoint) => string;
+  addMedia: (src: string, at: WorldPoint, options?: {
+    kind?: BoardMediaItemKind;
+    snapshot?: BoardMediaSnapshot;
+  }) => string;
   addFile: (path: string, at: WorldPoint, snapshot?: BoardMediaSnapshot & BoardFileSnapshotFacts) => string;
-  addTask: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, metadata?: Record<string, unknown>) => string;
-  addTaskWithSources: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, sources: BoardTaskSource[], metadata?: Record<string, unknown>) => string | null;
+  addTask: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, metadata?: Record<string, unknown>, aspect?: number) => string;
+  addTaskWithSources: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, sources: BoardTaskSource[], metadata?: Record<string, unknown>, aspect?: number) => string | null;
   addText: (text: string, at: WorldPoint) => void;
   addShape: (at: WorldPoint, geometry?: ShapeKind) => void;
   addFrame: (at: WorldPoint) => void;

package/dist/board/editor/creation.js

@@ -3,7 +3,7 @@ import { rectCenter } from "../model/geometry.js";
 import { buildBoardScene } from "../model/scene.js";
 import { isShapeKind } from "../model/shape-types.js";
 import { createBoardItemId } from "../model/items/id.js";
-import { createAppBoardItem, createArrowBoardItem, createDrawBoardItem, createFileNodeForPath, createFrameBoardItem, createShapeBoardItem, createTaskBoardItem, createTextBoardItem } from "../model/items/create.js";
+import { createAppBoardItem, createArrowBoardItem, createDrawBoardItem, createFileNodeForPath, createFrameBoardItem, createMediaBoardItem, createShapeBoardItem, createTaskBoardItem, createTextBoardItem } from "../model/items/create.js";
 import { sameJson } from "./document-edits.js";
 import { isContinuousBoardTool } from "./tool.js";
 //#region src/board/editor/creation.ts
@@ -53,10 +53,10 @@ function createCreationModule(ctx) {
 		if (options.readonly) return null;
 		return addOne(ctx.registry.create(type, input));
 	}
-	function addTaskWithSources(taskRunId, snapshot, at, sources, metadata) {
+	function addTaskWithSources(taskRunId, snapshot, at, sources, metadata, aspect) {
 		if (options.readonly) return null;
 		const { arrow } = state.toolStyles;
-		const task = createTaskBoardItem(taskRunId, snapshot, at.x, at.y, metadata);
+		const task = createTaskBoardItem(taskRunId, snapshot, at.x, at.y, metadata, void 0, aspect);
 		add([task, ...sources.filter((source) => source.itemId !== task.id && state.scene.get(source.itemId)).map((source) => {
 			const entry = createArrowBoardItem({
 				x: 0,
@@ -197,8 +197,9 @@ function createCreationModule(ctx) {
 		add,
 		addItem,
 		addApp: (app, at) => addOne(createAppBoardItem(app, at.x, at.y)),
+		addMedia: (src, at, options = {}) => addOne(createMediaBoardItem(src, at.x, at.y, options.snapshot, void 0, options.kind)),
 		addFile: (path, at, snapshot) => addOne(createFileNodeForPath(path, at.x, at.y, snapshot)),
-		addTask: (taskRunId, snapshot, at, metadata) => addOne(createTaskBoardItem(taskRunId, snapshot, at.x, at.y, metadata)),
+		addTask: (taskRunId, snapshot, at, metadata, aspect) => addOne(createTaskBoardItem(taskRunId, snapshot, at.x, at.y, metadata, void 0, aspect)),
 		addTaskWithSources,
 		addText: (text, at) => {
 			add([createTextBoardItem(text, at.x, at.y, styles().text.color)]);

package/dist/board/editor/deletion.js

@@ -8,14 +8,14 @@ function createDeletionModule(ctx) {
 		const { scene, base } = state;
 		const doomed = /* @__PURE__ */ new Set();
 		for (const id of ids) {
-			if (!scene.get(id)) continue;
+			if (!base.items[id]) continue;
 			doomed.add(id);
-			for (const child of scene.descendants(id)) doomed.add(child);
+			for (const child of scene.descendants(id)) if (base.items[child]) doomed.add(child);
 		}
 		const changes = /* @__PURE__ */ new Map();
 		for (const id of doomed) changes.set(id, null);
 		for (const id of doomed) for (const arrowId of scene.binders(id)) {
-			if (doomed.has(arrowId) || changes.has(arrowId)) continue;
+			if (!base.items[arrowId] || doomed.has(arrowId) || changes.has(arrowId)) continue;
 			const arrow = scene.get(arrowId);
 			if (!arrow) continue;
 			const resolved = resolveSceneArrow(arrow, scene);

package/dist/board/editor/document.d.ts

@@ -1,6 +1,7 @@
-import { BoardAnimation, BoardDocument, BoardItem, BoardSettings } from "../../protocol/dist/board-model.js";
+import { BoardAnimation, BoardDocument, BoardItem, BoardPatch, BoardSettings } from "../../protocol/dist/board-model.js";
 import { BoardFrame } from "../../protocol/dist/board-layout.js";
 import { Rect } from "../model/geometry.js";
+import { BoardScene } from "../model/scene.js";
 import "../model/index.js";
 import { EditorContext } from "./context.js";
 //#region src/board/editor/document.d.ts
@@ -8,8 +9,13 @@ declare function createDocumentModule(ctx: EditorContext): {
   markAdded: (ids: readonly string[]) => void;
   consumeRecentlyAdded: () => string[];
   displayItem: (id: string) => BoardItem | undefined;
+  copyScene: () => BoardScene;
   reevaluate: () => void;
   setPlayedItems: (items: ReadonlyMap<string, BoardItem>) => void;
+  readonly hasScriptItems: boolean;
+  setScriptItems: (items: ReadonlyMap<string, BoardItem>) => void;
+  animationItems: () => Map<string, BoardItem>;
+  commitPatch: (patch: BoardPatch) => Promise<void> | undefined;
   rescene: (ids?: Iterable<string>) => void;
   reset: (next: BoardDocument) => void;
   setDraftItem: (id: string, item: BoardItem | null) => void;
@@ -28,7 +34,7 @@ declare function createDocumentModule(ctx: EditorContext): {
   previewSettings: (settings: BoardSettings) => void;
   setSettings: (settings: BoardSettings) => void;
   reparent: (item: BoardItem, frame: BoardFrame, parent: string | undefined, box: Rect) => BoardItem;
-  topZ: (parent: string | undefined) => number;
+  topZ: (parent: string | undefined, scene?: BoardScene) => number;
 };
 type DocumentModule = ReturnType<typeof createDocumentModule>;
 //#endregion

package/dist/board/editor/document.js

@@ -11,6 +11,7 @@ function createDocumentModule(ctx) {
 	const recentlyAdded = /* @__PURE__ */ new Set();
 	let evaluated = /* @__PURE__ */ new Map();
 	let played = /* @__PURE__ */ new Map();
+	let scripted = /* @__PURE__ */ new Map();
 	let compiled = null;
 	function markAdded(ids) {
 		if (ids.length === 0) return;
@@ -24,14 +25,15 @@ function createDocumentModule(ctx) {
 	}
 	function displayItem(id) {
 		if (draft.has(id)) return draft.get(id) ?? void 0;
-		return evaluated.get(id) ?? played.get(id) ?? state.base.items[id];
+		return scripted.get(id) ?? evaluated.get(id) ?? played.get(id) ?? state.base.items[id];
 	}
-	function displayDocument() {
+	function displayDocument(includeScripts = true) {
 		const base = state.base;
-		if (draft.size === 0 && evaluated.size === 0 && played.size === 0) return base;
+		if (draft.size === 0 && evaluated.size === 0 && played.size === 0 && (!includeScripts || scripted.size === 0)) return base;
 		const items = { ...base.items };
 		for (const [id, item] of played) items[id] = item;
 		for (const [id, item] of evaluated) items[id] = item;
+		if (includeScripts) for (const [id, item] of scripted) items[id] = item;
 		for (const [id, item] of draft) if (item) items[id] = item;
 		else delete items[id];
 		return {
@@ -59,6 +61,17 @@ function createDocumentModule(ctx) {
 		for (const id of changed) if (draft.has(id) || evaluated.has(id) || sameJson(previous.get(id), played.get(id))) changed.delete(id);
 		if (changed.size) rescene(changed);
 	}
+	function setScriptItems(items) {
+		const previous = scripted;
+		scripted = items;
+		const changed = [.../* @__PURE__ */ new Set([...previous.keys(), ...items.keys()])].filter((id) => !sameJson(previous.get(id), items.get(id)));
+		if (!changed.length) return;
+		rescene(changed.some((id) => {
+			const before = previous.get(id) ?? state.base.items[id];
+			const after = items.get(id) ?? state.base.items[id];
+			return !before || !after || before.parent !== after.parent || before.z !== after.z || !sameJson(arrowBindings(before), arrowBindings(after));
+		}) ? void 0 : changed);
+	}
 	function rescene(ids) {
 		if (ids) {
 			const changed = [...ids];
@@ -76,6 +89,7 @@ function createDocumentModule(ctx) {
 		draft.clear();
 		draftOrigins.clear();
 		played = /* @__PURE__ */ new Map();
+		scripted = /* @__PURE__ */ new Map();
 		reevaluate();
 		state.scene = buildBoardScene(next);
 		ctx.query.invalidate();
@@ -114,12 +128,20 @@ function createDocumentModule(ctx) {
 		rescene();
 	}
 	function send(patch) {
-		if (options.readonly || isEmptyBoardPatch(patch)) return;
+		if (options.readonly || isEmptyBoardPatch(patch)) return Promise.resolve(null);
 		state.pendingCommits += 1;
-		Promise.resolve(options.onCommit(patch)).then(() => {
+		let completion;
+		try {
+			completion = Promise.resolve(options.onCommit(patch));
+		} catch (error) {
+			completion = Promise.reject(error);
+		}
+		return completion.then(() => {
 			state.saveError = null;
+			return null;
 		}).catch((error) => {
 			state.saveError = error instanceof Error ? error.message : "Failed to sync board";
+			return error instanceof Error ? error : new Error(state.saveError);
 		}).finally(() => {
 			state.pendingCommits -= 1;
 		});
@@ -183,6 +205,24 @@ function createDocumentModule(ctx) {
 		for (const [id, item] of changes) setDraftItem(id, item);
 		commit({}, record);
 	}
+	function commitPatch(patch) {
+		if (options.readonly) throw new Error("Board is read-only.");
+		const before = state.base;
+		const result = applyBoardPatchToDocument(before, patch);
+		if (!result.ok) throw new Error(result.diagnostics[0]?.message ?? "Invalid board patch.");
+		const ids = Object.keys(patch.items ?? {});
+		const redo = diffBoardEdits(before, result.document, ids);
+		if (isEmptyBoardPatch(redo)) return;
+		state.undoStack = [...state.undoStack.slice(-199), {
+			undo: diffBoardEdits(result.document, before, ids),
+			redo
+		}];
+		state.redoStack = [];
+		adopt(result.document, ids);
+		return send(redo).then((error) => {
+			if (error) throw error;
+		});
+	}
 	function applyPatch(patch) {
 		const result = applyBoardPatchToDocument(state.base, patch);
 		if (!result.ok) {
@@ -222,17 +262,24 @@ function createDocumentModule(ctx) {
 		const matrix = parent ? state.scene.layout.matrix(parent) : IDENTITY_MATRIX;
 		return placeItem(next, frame, matrix, box);
 	}
-	function topZ(parent) {
+	function topZ(parent, scene = state.scene) {
 		let z = 0;
-		for (const id of state.scene.children(parent)) z = Math.max(z, displayItem(id)?.z ?? 0);
+		for (const id of scene.children(parent)) z = Math.max(z, scene.get(id)?.z ?? 0);
 		return z + 1;
 	}
 	return {
 		markAdded,
 		consumeRecentlyAdded,
 		displayItem,
+		copyScene: () => scripted.size ? buildBoardScene(displayDocument(false)) : state.scene,
 		reevaluate,
 		setPlayedItems,
+		get hasScriptItems() {
+			return scripted.size > 0;
+		},
+		setScriptItems,
+		animationItems: () => new Map([...played, ...evaluated]),
+		commitPatch,
 		rescene,
 		reset,
 		setDraftItem,

package/dist/board/editor/editor.d.ts

@@ -1,15 +1,17 @@
-import { BoardDocument, BoardItem, BoardMediaSnapshot, BoardSettings, BoardTaskSnapshot } from "../../protocol/dist/board-model.js";
+import { BoardDocument, BoardItem, BoardMediaSnapshot, BoardPatch, BoardSettings, BoardTaskSnapshot } from "../../protocol/dist/board-model.js";
 import { BoardFrame } from "../../protocol/dist/board-layout.js";
 import { BoardViewport, Rect, ScreenPoint, WorldPoint } from "../model/geometry.js";
 import { BoardScene, BoardSceneItem } from "../model/scene.js";
+import { BoardChapter } from "../model/authoring.js";
 import { BoardFileSnapshotFacts } from "../model/file-snapshot.js";
 import { ShapeKind } from "../model/shape-types.js";
+import { BoardItemEntry, BoardMediaItemKind } from "../model/items/create.js";
 import { BoardItemInput, BoardRegistry } from "../model/items/registry.js";
 import "../model/index.js";
 import { AlignMode, DistributeAxis } from "./align.js";
 import { BoardFocusOptions } from "./camera.js";
 import { BoardSelectionTransform, BoardTransformControl } from "./selection-transform.js";
-import { BoardInteraction, BoardPointerEvent } from "./interaction.js";
+import { BoardInteraction, BoardPointerEvent, BoardTransformEnd } from "./interaction.js";
 import { BoardAppMetadata, BoardTaskSource } from "./creation.js";
 import { BoardClipboardPayload } from "./clipboard.js";
 import { BoardNaturalSize } from "./snapshots.js";
@@ -22,6 +24,7 @@ declare function createBoardEditor(options: BoardEditorOptions): {
   registry: BoardRegistry;
   readonly: boolean;
   subscribe: (channels: BoardEditorChannel | readonly BoardEditorChannel[], listener: BoardEditorListener) => () => void;
+  readonly hasScripts: boolean;
   readonly document: BoardDocument;
   readonly settings: {
     title?: string | undefined;
@@ -130,11 +133,14 @@ declare function createBoardEditor(options: BoardEditorOptions): {
   setSettings: (settings: BoardSettings) => void;
   previewSettings: (settings: BoardSettings) => void;
   setPlayedItems: (items: ReadonlyMap<string, BoardItem>) => void;
+  setScriptItems: (items: ReadonlyMap<string, BoardItem>) => void;
+  animationItems: () => Map<string, BoardItem>;
+  commitPatch: (patch: BoardPatch) => Promise<void> | undefined;
   consumeRecentlyAdded: () => string[];
-  itemAt: (point: WorldPoint, exclude?: ReadonlySet<string> | undefined) => BoardSceneItem | null;
+  itemAt: (point: WorldPoint, exclude?: ReadonlySet<string> | undefined, includeTemporary?: boolean | undefined) => BoardSceneItem | null;
   itemById: (id: string) => BoardSceneItem | null;
   labelItemAt: (point: WorldPoint) => BoardSceneItem | null;
-  idsInRect: (rect: Rect) => string[];
+  idsInRect: (rect: Rect, includeTemporary?: boolean | undefined) => string[];
   setCamera: (viewport: BoardViewport) => void;
   setCameraPolicy: (policy: BoardCameraPolicy) => void;
   takeCameraControl: () => void;
@@ -162,10 +168,18 @@ declare function createBoardEditor(options: BoardEditorOptions): {
   bringToFront: () => void;
   sendToBack: () => void;
   addItem: (type: string, input: BoardItemInput) => string | null;
+  addItems: (entries: BoardItemEntry[], { select, enter }?: {
+    select?: boolean;
+    enter?: boolean;
+  }) => void;
   addApp: (app: BoardAppMetadata, at: WorldPoint) => string;
   addFile: (path: string, at: WorldPoint, snapshot?: BoardMediaSnapshot & BoardFileSnapshotFacts) => string;
-  addTask: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, metadata?: Record<string, unknown>) => string;
-  addTaskWithSources: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, sources: BoardTaskSource[], metadata?: Record<string, unknown>) => string | null;
+  addMedia: (src: string, at: WorldPoint, options?: {
+    kind?: BoardMediaItemKind;
+    snapshot?: BoardMediaSnapshot;
+  }) => string;
+  addTask: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, metadata?: Record<string, unknown>, aspect?: number) => string;
+  addTaskWithSources: (taskRunId: string, snapshot: BoardTaskSnapshot, at: WorldPoint, sources: BoardTaskSource[], metadata?: Record<string, unknown>, aspect?: number) => string | null;
   addText: (text: string, at: WorldPoint) => void;
   addShape: (at: WorldPoint, geometry?: ShapeKind) => void;
   addFrame: (at: WorldPoint) => void;
@@ -190,7 +204,6 @@ declare function createBoardEditor(options: BoardEditorOptions): {
     snapshot: BoardFileSnapshotFacts;
     replace?: boolean;
   }>) => void;
-  applyTaskSnapshots: (snapshots: ReadonlyMap<string, BoardTaskSnapshot>) => void;
   setPlayhead: (next: BoardPlayhead | null) => void;
   setRecording: (value: boolean) => void;
   keyframeState: (property: string) => "animated" | "keyframe" | "none";
@@ -198,10 +211,12 @@ declare function createBoardEditor(options: BoardEditorOptions): {
   removeKeyframe: (trackId: string, at: number) => void;
   setKeyframeEase: (trackId: string, at: number, ease: string | null) => void;
   createAnimation: (name: string, duration?: number) => string;
+  createSequence: (name: string, chapters: BoardChapter[]) => string | null;
   pointerDown: (event: BoardPointerEvent) => void;
   pointerMove: (event: BoardPointerEvent) => void;
   pointerUp: (event: BoardPointerEvent) => void;
   pointerLeave: () => void;
+  subscribeTransforms: (listener: (event: BoardTransformEnd) => void) => () => void;
   cancelPointerInteraction: () => void;
   destroy(): void;
 };

package/dist/board/editor/editor.js

@@ -1,7 +1,8 @@
 import { clampBoardStrokeSize } from "../../protocol/dist/board-constants.js";
+import { hasBoardScripts } from "../model/script-index.js";
 import { normalizeViewport } from "../model/geometry.js";
-import { isBoardColorId } from "../model/palette.js";
 import { buildBoardScene } from "../model/scene.js";
+import { isBoardColorId } from "../model/palette.js";
 import { isShapeKind } from "../model/shape-types.js";
 import { createBoardToolStyles } from "../model/tool-styles.js";
 import { titleForBoardItem } from "../model/items/create.js";
@@ -145,6 +146,9 @@ function createBoardEditor(options) {
 		registry,
 		readonly: options.readonly === true,
 		subscribe: channels.subscribe,
+		get hasScripts() {
+			return read("document", () => hasBoardScripts(state.base));
+		},
 		get document() {
 			return read("document", () => state.base);
 		},
@@ -344,6 +348,9 @@ function createBoardEditor(options) {
 		setSettings: document.setSettings,
 		previewSettings: document.previewSettings,
 		setPlayedItems: document.setPlayedItems,
+		setScriptItems: document.setScriptItems,
+		animationItems: document.animationItems,
+		commitPatch: document.commitPatch,
 		consumeRecentlyAdded: document.consumeRecentlyAdded,
 		itemAt: tracked(["scene", "camera"], query.itemAt),
 		itemById: tracked(["scene"], query.itemById),
@@ -380,8 +387,10 @@ function createBoardEditor(options) {
 		bringToFront: selection.bringToFront,
 		sendToBack: selection.sendToBack,
 		addItem: creation.addItem,
+		addItems: creation.add,
 		addApp: creation.addApp,
 		addFile: creation.addFile,
+		addMedia: creation.addMedia,
 		addTask: creation.addTask,
 		addTaskWithSources: creation.addTaskWithSources,
 		addText: creation.addText,
@@ -400,7 +409,6 @@ function createBoardEditor(options) {
 		applyMediaFileChange: snapshots.applyMediaFileChange,
 		adoptMediaNaturalSizes: snapshots.adoptMediaNaturalSizes,
 		applyFileSnapshots: snapshots.applyFileSnapshots,
-		applyTaskSnapshots: snapshots.applyTaskSnapshots,
 		setPlayhead: animation.setPlayhead,
 		setRecording: animation.setRecording,
 		keyframeState: tracked([
@@ -413,10 +421,12 @@ function createBoardEditor(options) {
 		removeKeyframe: animation.removeKeyframe,
 		setKeyframeEase: animation.setKeyframeEase,
 		createAnimation: animation.createAnimation,
+		createSequence: animation.createSequence,
 		pointerDown: interaction.pointerDown,
 		pointerMove: interaction.pointerMove,
 		pointerUp: interaction.pointerUp,
 		pointerLeave: interaction.pointerLeave,
+		subscribeTransforms: interaction.subscribeTransforms,
 		cancelPointerInteraction: interaction.cancel,
 		destroy() {
 			stopViewState();

package/dist/board/editor/index.d.ts

@@ -2,7 +2,7 @@ import { BOARD_CLIPBOARD_MIME } from "../../protocol/dist/board.js";
 import { AlignMode, DistributeAxis, alignFrames, distributeFrames, framesBounds } from "./align.js";
 import { BoardFocusOptions } from "./camera.js";
 import { BoardSelectionTransform, BoardTransformControl, resizeCursorForHandle, resolveSelectionTransform, selectionTransformControlAt } from "./selection-transform.js";
-import { BoardInteraction, BoardPointerEvent } from "./interaction.js";
+import { BoardInteraction, BoardPointerEvent, BoardTransformEnd } from "./interaction.js";
 import { BoardAppMetadata, BoardTaskSource } from "./creation.js";
 import { BOARD_CLIPBOARD_VERSION, BoardClipboardPayload, DUPLICATE_OFFSET, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, defaultPasteOffset, encodeClipboard, materializeClipboard, parseClipboard, remapItems } from "./clipboard.js";
 import { BoardNaturalSize } from "./snapshots.js";
@@ -15,4 +15,4 @@ import { BoardEditPlayhead, diffBoardEdits, isEmptyBoardPatch, readPath, routeBo
 import { BoardEditor, createBoardEditor } from "./editor.js";
 import { SpatialEntry, SpatialIndex, createSpatialIndex } from "./spatial.js";
 import { normalizeWheelDelta, wheelZoomFactor } from "./wheel.js";
-export { AlignMode, BOARD_CLIPBOARD_MIME, BOARD_CLIPBOARD_VERSION, BOARD_HAND_TAP_SLOP, type BoardAppMetadata, type BoardCameraPolicy, BoardClipboardPayload, BoardEditPlayhead, type BoardEditor, type BoardEditorChannel, type BoardEditorListener, type BoardEditorOptions, type BoardEditorPreferences, type BoardFocusOptions, type BoardInteraction, type BoardNaturalSize, type BoardPlayhead, type BoardPointerEvent, BoardSelectionTransform, type BoardTaskSource, BoardToolId, BoardTransformControl, type BoardViewState, CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, ConnectionPort, DUPLICATE_OFFSET, DistributeAxis, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, SnapAxis, SnapGuide, SnapOptions, SnapResult, SpatialEntry, SpatialIndex, alignFrames, canTapSelectWithHand, computeSnap, connectionPortAt, connectionPorts, createBoardEditor, createSpatialIndex, defaultBoardTool, defaultPasteOffset, diffBoardEdits, distributeFrames, encodeClipboard, framesBounds, isContinuousBoardTool, isCreationBoardTool, isEmptyBoardPatch, isWithinHandTapSlop, materializeClipboard, normalizeWheelDelta, parseClipboard, portHitRadius, readPath, remapItems, resizeCursorForHandle, resolveSelectionTransform, routeBoardEdits, sameJson, selectionTransformControlAt, wheelZoomFactor, writePath };
+export { AlignMode, BOARD_CLIPBOARD_MIME, BOARD_CLIPBOARD_VERSION, BOARD_HAND_TAP_SLOP, type BoardAppMetadata, type BoardCameraPolicy, BoardClipboardPayload, BoardEditPlayhead, type BoardEditor, type BoardEditorChannel, type BoardEditorListener, type BoardEditorOptions, type BoardEditorPreferences, type BoardFocusOptions, type BoardInteraction, type BoardNaturalSize, type BoardPlayhead, type BoardPointerEvent, BoardSelectionTransform, type BoardTaskSource, BoardToolId, BoardTransformControl, type BoardTransformEnd, type BoardViewState, CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, ConnectionPort, DUPLICATE_OFFSET, DistributeAxis, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, SnapAxis, SnapGuide, SnapOptions, SnapResult, SpatialEntry, SpatialIndex, alignFrames, canTapSelectWithHand, computeSnap, connectionPortAt, connectionPorts, createBoardEditor, createSpatialIndex, defaultBoardTool, defaultPasteOffset, diffBoardEdits, distributeFrames, encodeClipboard, framesBounds, isContinuousBoardTool, isCreationBoardTool, isEmptyBoardPatch, isWithinHandTapSlop, materializeClipboard, normalizeWheelDelta, parseClipboard, portHitRadius, readPath, remapItems, resizeCursorForHandle, resolveSelectionTransform, routeBoardEdits, sameJson, selectionTransformControlAt, wheelZoomFactor, writePath };