@neta-art/cohub 9.0.1 → 11.0.0

package/README.md

@@ -76,138 +76,144 @@ await session.messages.send({
 
 ## Boards
 
-Use `space.boards` for collection operations and bind an ID with
-`space.board(boardId)` for entity operations:
+A Board is one document of `board` settings, `items` and `animations`. Bind
+one with `space.board(boardId)`; every write is a JSON Merge Patch (`null`
+deletes, unmentioned fields stay):
 
 ```ts
 const created = await space.boards.create({
   path: "boards/plan.board",
   title: "Plan",
-  items: [{
-    id: "goal",
-    type: "geo",
-    frame: { x: 80, y: 80, width: 240, height: 120, rotation: 0 },
-    props: { shape: "rounded", text: "Ship" },
-    style: { color: "green" },
-  }],
+  document: {
+    items: {
+      goal: { type: "shape", position: { x: 80, y: 80 }, size: { width: 240, height: 120 }, props: { geometry: "rounded", text: "Ship" } },
+    },
+  },
 });
 
-const board = space.board(created.board.id);
-// Equivalent: space.boards.byId(created.board.id)
+const board = space.board(created.id);
+const { items, version } = await board.get({ only: ["items"] });
+await board.apply({ items: { goal: { props: { text: "Shipped" } } } }, { baseVersion: version });
 
-// Machine-readable types, enums and coordinate spaces for dynamic clients.
-const capabilities = await board.capabilities();
+const stop = board.subscribe({
+  changed: (event) => console.log("version", event.payload.version),
+  playback: (event) => console.log("playback", event.payload.playback?.status),
+});
+```
 
-const snapshot = await board.authoring({ include: ["items"] });
+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 })`.
 
-await board.mutateSemantic({
-  baseVersion: snapshot.board.version,
-  commands: [{
-    type: "item.patch",
-    itemId: "goal",
-    patch: { props: { text: "Updated plan" } },
-  }],
-});
+### Layers
 
-await board.play({
-  commandId: crypto.randomUUID(),
-  type: "play",
-  compositionId: "ambient",
-});
-```
+Board is layered by dependency, so each use pulls in only what it needs:
 
-A bound `BoardClient` injects its `boardId` into semantic mutation requests.
-Realtime subscriptions use the same semantic resource projection:
+| Import | What it is | Needs |
+|---|---|---|
+| `@neta-art/cohub/board` | Document model, geometry, item types (`defineBoardItem`, `createBoardRegistry`), export planning | — |
+| `@neta-art/cohub/board/replica` | A local copy kept in step with the server, with offline writes | — |
+| `@neta-art/cohub/board/editor` | The editor engine: selection, tools, gestures, undo, camera | — |
+| `@neta-art/cohub/board/player` | Animation playback | — |
+| `@neta-art/cohub/board/render` | Canvas renderers for each item type | `pixi.js` |
+| `@neta-art/cohub/board/stage` | An editor drawn into a DOM element, with input and DOM item views | `pixi.js` |
+| `@neta-art/cohub/board/export` | Render a document to an image | `pixi.js` |
+| `@neta-art/cohub/board/export/node` | The same in Node.js | `pixi.js`, `@napi-rs/canvas` |
 
-```ts
-const stop = board.subscribe({
-  changed(event) {
-    console.log("version", event.payload.version);
-    console.log("items", event.payload.changed.items);
-  },
-  playback(event) {
-    console.log("playback", event.payload.status);
-  },
-});
+`pixi.js` and `@napi-rs/canvas` are optional peers: HTTP-only installs, agents
+and servers never load them.
 
-stop();
-```
+### Embedding an editor
 
-Task Items keep a small, replaceable display snapshot beside their stable `taskRunId`. The SDK can build that projection from an authoritative TaskRun without copying the full payload, result or inline media into a Board:
+The editor has no framework. Read state through its getters and listen with
+`subscribe(channel, listener)`; snapshots keep their identity until they
+change, so they work directly with `useSyncExternalStore`:
 
 ```ts
-import { taskRunToBoardTaskSnapshot } from "@neta-art/cohub/board";
-
-const snapshot = taskRunToBoardTaskSnapshot(taskRun);
-```
+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";
+import { z } from "zod";
+
+// A business item type. The server stores extension props as they are; the
+// schema is checked when the editor creates or edits one.
+const order = defineBoardItem({
+  type: "acme.order",
+  props: z.object({ orderId: z.string(), status: z.enum(["open", "paid"]) }),
+  size: { width: 320, height: 200 },
+  capabilities: { canRotate: false },
+});
 
-Use `client.tasks.getMany(ids, { spaceId })` to restore the TaskRuns for a Board in one request. The server applies the same Space permissions and result sanitization as the regular task list endpoint.
+const replica = createBoardReplica({ remote: space.board(boardId) });
+await replica.start();
 
-Board is split by dependency: the model runs anywhere, drawing needs PixiJS.
-`@neta-art/cohub/board` carries the document schema, geometry, the shape layer,
-timeline compilation and export planning, with no renderer and no PixiJS — so
-agents, servers and edge workers can read, write and measure boards without a
-graphics stack:
+const editor = createBoardEditor({
+  document: replica.state.document!,
+  registry: createBoardRegistry([order]),
+  key: boardId,
+  onCommit: (patch) => replica.apply(patch),
+});
+replica.subscribe((state) => state.document && editor.loadDocument(state.document, boardId));
+
+// 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 },
+});
 
-```ts
-import {
-  BoardDocumentSchema,
-  compileComposition,
-  createBoardExtensionRegistry,
-  itemBounds,
-  planBoardExport,
-} from "@neta-art/cohub/board";
-
-const composition = compileComposition({
-  id: "ambient",
-  name: "Ambient",
-  duration: 1_000,
-  tracks: [{
-    id: "image-translation",
-    target: { type: "item", itemId: "image" },
-    channel: "transform.translation",
-    fill: "both",
-    keyframes: [
-      { time: 0, value: { x: 0, y: 0 } },
-      { time: 500, value: { x: 0, y: -8 } },
-      { time: 1_000, value: { x: 0, y: 0 } },
-    ],
+// 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" }),
+};
+const stage = mountBoardStage(element, {
+  editor,
+  source,
+  assets: createBoardAssetManager({ resolveFileUrl: source.resolveFileUrl }),
+  views: [{
+    type: "acme.order",
+    // Mount anything: a React root, a Vue app, plain DOM.
+    mount: (target, item, context) => {
+      const root = createRoot(target);
+      const render = (next = item, ctx = context) => root.render(<OrderCard item={next} selected={ctx.selected} />);
+      render();
+      return { update: render, destroy: () => root.unmount() };
+    },
   }],
-  playback: { loop: true, endBehavior: "hold", reducedMotion: { mode: "base" } },
 });
 
-await space.boards.create({
-  path: "boards/ambient.board",
-  metadata: {
-    playback: { compositionId: composition.id, delayMs: 500 },
-  },
-  compositions: [composition],
-});
+editor.addItem("acme.order", { at: editor.viewCenter(), props: { orderId: "o-1", status: "open" } });
+
+// React: const selection = useSyncExternalStore((fn) => editor.subscribe("selection", fn), () => editor.selection);
 ```
 
-Drawing pixels is where PixiJS enters. The card renderers and themes the editor
-uses live behind `@neta-art/cohub/board/render`, and turning a plan into an
-image has dedicated browser and Node.js entries:
+Items of a type the client does not know still render as a placeholder, move
+and keep every field, so documents written by newer clients are never
+rewritten by older ones. For a canvas look instead of DOM, pass renderers to
+`createBoardCardRendererResolver` from `board/render` and hand the result to
+the stage or to `renderBoardExport` as `renderers`.
+
+### Images
+
+In the browser, `renderBoardExport(renderer, document, options)` from
+`board/export` draws with the page's renderer (`stage.renderer`). In Node.js:
 
 ```ts
-import { getBoardCardRenderer } from "@neta-art/cohub/board/render";
-import { renderBoardExport } from "@neta-art/cohub/board/export";
-import {
-  createBoardHeadlessRenderer,
-  exportBoardImageBytes,
-} from "@neta-art/cohub/board/headless";
-```
+import { createNodeBoardRenderer, exportBoardImageBytes } from "@neta-art/cohub/board/export/node";
 
-Install `pixi.js` to use `board/render` or `board/export`, and add
-`@napi-rs/canvas` as well for `board/headless`. Both are optional peers, and
-`@neta-art/cohub/board` never reaches for either, so HTTP-only installations
-stay lightweight.
+const renderer = await createNodeBoardRenderer();
+const result = exportBoardImageBytes(renderer, document, { format: "png", scale: 2 });
+```
 
 Text metrics follow the same split. The renderers measure through a real canvas
-and set that up themselves, so nothing extra is needed to draw or export. Called
-straight off `@neta-art/cohub/board` with no renderer in play,
-`measureBoardText` returns a per-character estimate instead — fine for laying
-out a board on a server, but call `installBoardTextMeasurement` from
+and set that up themselves. Called straight off `@neta-art/cohub/board` with no
+renderer in play, `measureBoardText` returns a per-character estimate — fine
+for laying out a board on a server; call `installBoardTextMeasurement` from
 `board/render` first if the numbers have to match what the editor draws.
 
 ## Session subscriptions

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

@@ -0,0 +1,11 @@
+import { BoardFrame } from "../../protocol/dist/board-layout.js";
+import { Rect } from "../model/geometry.js";
+import "../model/index.js";
+//#region src/board/editor/align.d.ts
+type AlignMode = "left" | "center-x" | "right" | "top" | "center-y" | "bottom";
+type DistributeAxis = "horizontal" | "vertical";
+declare function alignFrames(frames: Map<string, BoardFrame>, mode: AlignMode): Map<string, BoardFrame>;
+declare function distributeFrames(frames: Map<string, BoardFrame>, axis: DistributeAxis): Map<string, BoardFrame>;
+declare function framesBounds(frames: Iterable<BoardFrame>): Rect | null;
+//#endregion
+export { AlignMode, DistributeAxis, alignFrames, distributeFrames, framesBounds };

package/dist/board/editor/align.js

@@ -0,0 +1,72 @@
+import { itemBounds, selectionBounds } from "../model/geometry.js";
+//#region src/board/editor/align.ts
+function alignFrames(frames, mode) {
+	if (frames.size < 2) return /* @__PURE__ */ new Map();
+	const bounds = selectionBounds([...frames.values()]);
+	if (!bounds) return /* @__PURE__ */ new Map();
+	const next = /* @__PURE__ */ new Map();
+	for (const [id, frame] of frames) {
+		const box = itemBounds(frame);
+		let x = frame.x;
+		let y = frame.y;
+		switch (mode) {
+			case "left":
+				x = frame.x + (bounds.x - box.x);
+				break;
+			case "center-x":
+				x = frame.x + (bounds.x + bounds.width / 2 - (box.x + box.width / 2));
+				break;
+			case "right":
+				x = frame.x + (bounds.x + bounds.width - (box.x + box.width));
+				break;
+			case "top":
+				y = frame.y + (bounds.y - box.y);
+				break;
+			case "center-y":
+				y = frame.y + (bounds.y + bounds.height / 2 - (box.y + box.height / 2));
+				break;
+			case "bottom": y = frame.y + (bounds.y + bounds.height - (box.y + box.height));
+		}
+		if (x !== frame.x || y !== frame.y) next.set(id, {
+			...frame,
+			x,
+			y
+		});
+	}
+	return next;
+}
+function distributeFrames(frames, axis) {
+	if (frames.size < 3) return /* @__PURE__ */ new Map();
+	const entries = [...frames.entries()].map(([id, frame]) => ({
+		id,
+		frame,
+		box: itemBounds(frame)
+	}));
+	const horizontal = axis === "horizontal";
+	entries.sort((a, b) => horizontal ? a.box.x - b.box.x : a.box.y - b.box.y);
+	const first = entries[0];
+	const last = entries[entries.length - 1];
+	if (!first || !last) return /* @__PURE__ */ new Map();
+	const start = horizontal ? first.box.x : first.box.y;
+	const end = horizontal ? last.box.x + last.box.width : last.box.y + last.box.height;
+	const totalSize = entries.reduce((sum, entry) => sum + (horizontal ? entry.box.width : entry.box.height), 0);
+	const gap = (end - start - totalSize) / (entries.length - 1);
+	const next = /* @__PURE__ */ new Map();
+	let cursor = start;
+	for (const entry of entries) {
+		const size = horizontal ? entry.box.width : entry.box.height;
+		const delta = cursor - (horizontal ? entry.box.x : entry.box.y);
+		if (delta !== 0) next.set(entry.id, {
+			...entry.frame,
+			x: horizontal ? entry.frame.x + delta : entry.frame.x,
+			y: horizontal ? entry.frame.y : entry.frame.y + delta
+		});
+		cursor += size + gap;
+	}
+	return next;
+}
+function framesBounds(frames) {
+	return selectionBounds([...frames]);
+}
+//#endregion
+export { alignFrames, distributeFrames, framesBounds };

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

@@ -0,0 +1,17 @@
+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): {
+  setPlayhead: (next: BoardPlayhead | null) => void;
+  setRecording: (value: boolean) => void;
+  keyframeState: (property: string) => "none" | "animated" | "keyframe";
+  toggleKeyframe: (property: string) => void;
+  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
+export { AnimationModule, createAnimationModule };

package/dist/board/editor/animation.js

@@ -0,0 +1,187 @@
+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
+function createAnimationModule(ctx) {
+	const { state, options } = ctx;
+	function setPlayhead(next) {
+		if (next && !state.base.animations[next.animationId]) next = null;
+		if (sameJson(next, state.playhead)) return;
+		state.playhead = next;
+		if (!next) state.recording = false;
+		ctx.document.discardDraft();
+	}
+	function setRecording(value) {
+		state.recording = value && state.playhead !== null && !options.readonly;
+	}
+	function current() {
+		const { playhead, base } = state;
+		const animation = playhead ? base.animations[playhead.animationId] : void 0;
+		return playhead && animation ? {
+			playhead,
+			animation
+		} : null;
+	}
+	function tracksFor(itemId) {
+		const result = /* @__PURE__ */ new Map();
+		const animation = current()?.animation;
+		if (!animation) return result;
+		for (const [trackId, track] of Object.entries(animation.tracks)) if (track.target === itemId) result.set(track.property, [trackId, track]);
+		return result;
+	}
+	function keyframeState(property) {
+		const selected = ctx.selection.items();
+		if (!state.playhead || selected.length === 0) return "none";
+		const time = Math.round(state.playhead.time);
+		let animated = true;
+		let keyed = true;
+		for (const item of selected) {
+			const track = tracksFor(item.id).get(property)?.[1];
+			if (!track) animated = false;
+			if (!track?.keyframes.some((keyframe) => keyframe.at === time)) keyed = false;
+		}
+		return keyed ? "keyframe" : animated ? "animated" : "none";
+	}
+	function commitAnimation(animationId, animation) {
+		ctx.document.commit({ animations: {
+			...state.base.animations,
+			[animationId]: animation
+		} });
+	}
+	function toggleKeyframe(property) {
+		const found = options.readonly ? null : current();
+		if (!found) return;
+		const { playhead, animation } = found;
+		const time = Math.round(playhead.time);
+		const tracks = { ...animation.tracks };
+		const remove = keyframeState(property) === "keyframe";
+		for (const item of ctx.selection.items()) {
+			const existing = tracksFor(item.id).get(property);
+			const shown = readPath(ctx.document.displayItem(item.id), property.split("."));
+			if (remove && existing) {
+				const keyframes = existing[1].keyframes.filter((keyframe) => keyframe.at !== time);
+				if (keyframes.length) tracks[existing[0]] = {
+					...existing[1],
+					keyframes
+				};
+				else delete tracks[existing[0]];
+			} else if (!remove) {
+				const [trackId, track] = existing ?? [`${item.id}-${property.replaceAll(".", "-")}`, {
+					target: item.id,
+					property,
+					keyframes: [],
+					composite: "replace",
+					interpolation: "auto"
+				}];
+				const keyframes = [...track.keyframes.filter((keyframe) => keyframe.at !== time), {
+					at: time,
+					value: shown
+				}].sort((a, b) => a.at - b.at);
+				tracks[trackId] = {
+					...track,
+					keyframes
+				};
+			}
+		}
+		commitAnimation(playhead.animationId, {
+			...animation,
+			duration: Math.max(animation.duration, time),
+			tracks
+		});
+	}
+	function trackAt(trackId) {
+		const found = options.readonly ? null : current();
+		const track = found?.animation.tracks[trackId];
+		return found && track ? {
+			...found,
+			track
+		} : null;
+	}
+	function removeKeyframe(trackId, at) {
+		const found = trackAt(trackId);
+		if (!found) return;
+		const { playhead, animation, track } = found;
+		const time = Math.round(at);
+		const keyframes = track.keyframes.filter((keyframe) => keyframe.at !== time);
+		const tracks = { ...animation.tracks };
+		if (keyframes.length) tracks[trackId] = {
+			...track,
+			keyframes
+		};
+		else delete tracks[trackId];
+		commitAnimation(playhead.animationId, {
+			...animation,
+			tracks
+		});
+	}
+	function setKeyframeEase(trackId, at, ease) {
+		const found = trackAt(trackId);
+		if (!found) return;
+		const { playhead, animation, track } = found;
+		const time = Math.round(at);
+		const keyframes = track.keyframes.map((keyframe) => {
+			if (keyframe.at !== time) return keyframe;
+			if (!ease || ease === "linear") {
+				const { ease: _removed, ...rest } = keyframe;
+				return rest;
+			}
+			return {
+				...keyframe,
+				ease
+			};
+		});
+		commitAnimation(playhead.animationId, {
+			...animation,
+			tracks: {
+				...animation.tracks,
+				[trackId]: {
+					...track,
+					keyframes
+				}
+			}
+		});
+	}
+	function createAnimation(name, duration = 5e3) {
+		const id = createBoardItemId();
+		commitAnimation(id, {
+			name,
+			duration,
+			play: "manual",
+			delay: 0,
+			loop: false,
+			end: "hold",
+			markers: [],
+			tracks: {}
+		});
+		setPlayhead({
+			animationId: id,
+			time: 0
+		});
+		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,
+		keyframeState,
+		toggleKeyframe,
+		removeKeyframe,
+		setKeyframeEase,
+		createAnimation,
+		createSequence
+	};
+}
+//#endregion
+export { createAnimationModule };

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

@@ -0,0 +1,32 @@
+import { BoardViewport, Rect, ScreenPoint, WorldPoint } from "../model/geometry.js";
+import "../model/index.js";
+import { BoardCameraPolicy, EditorContext } from "./context.js";
+//#region src/board/editor/camera.d.ts
+type BoardFocusOptions = {
+  fit?: "contain" | "cover";
+  padding?: number;
+  minZoom?: number;
+  maxZoom?: number;
+  animate?: boolean;
+};
+declare function createCameraModule(ctx: EditorContext): {
+  setCamera: (viewport: BoardViewport) => void;
+  setCameraPolicy: (policy: BoardCameraPolicy) => void;
+  takeCameraControl: () => void;
+  cancelAnimation: () => void;
+  viewCenter: () => WorldPoint;
+  visibleRect: () => Rect | null;
+  zoomAt: (point: ScreenPoint, factor: number, animate?: boolean) => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+  resetZoom: () => void;
+  focusRect: (rect: Rect, focus?: BoardFocusOptions) => void;
+  fitView: (focus?: BoardFocusOptions) => void;
+  focusItems: (ids: Iterable<string>, focus?: BoardFocusOptions) => void;
+  focusNode: (id: string, focus?: BoardFocusOptions) => void;
+  focusSelection: (focus?: BoardFocusOptions) => void;
+  wheel: (point: ScreenPoint, deltaX: number, deltaY: number, zoomKey: boolean, deltaMode?: number) => void;
+};
+type CameraModule = ReturnType<typeof createCameraModule>;
+//#endregion
+export { BoardFocusOptions, CameraModule, createCameraModule };