@neta-art/cohub 10.0.0 → 11.1.0

package/dist/board/export/node/scripts.js

@@ -0,0 +1,258 @@
+import { boardScriptScope, composeBoardScriptItems } from "../../model/script-scene.js";
+import { buildBoardScene } from "../../model/scene.js";
+import { createBoardScriptModuleReader, loadBoardScriptSources } from "../../../protocol/dist/board-script-modules.js";
+import { createScriptRuntime } from "../../render/script-runtime.js";
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+//#region src/board/export/node/scripts.ts
+const WORKER = `
+const {parentPort, workerData} = require('node:worker_threads');
+const {createContext, Script, SourceTextModule} = require('node:vm');
+const {createCanvas} = require(workerData.canvasModule);
+const instances = new Map();
+const graphs = new Map();
+const update = new Script('__runtime.update(JSON.parse(__inputJson)); __runtime.step(__time)');
+const draw = new Script('__runtime.draw(__drawing)');
+const output = new Script('JSON.stringify(__runtime.output())');
+const dispose = new Script('__runtime.destroy()');
+function release(id) {
+ const entry=instances.get(id);instances.delete(id);
+ if(entry) {try {dispose.runInContext(entry.context,{timeout:workerData.timeout});} catch {}}
+}
+async function create(data) {
+ const context = createContext({console:{log(){},warn(){},error(){}},structuredClone},{codeGeneration:{strings:false,wasm:false}});
+ new Script("const __name=(value,name)=>Object.defineProperty(value,'name',{value:name,configurable:true})").runInContext(context);
+ const sources = graphs.get(data.src);
+ if(!sources) throw new Error('Module graph is unavailable.');
+ const modules = new Map();
+ const resolve = (from,name) => {
+  const parts=from.split('/').slice(0,-1);
+  for(const part of name.split('/')) { if(part==='..') parts.pop(); else if(part!=='.') parts.push(part); }
+  return parts.join('/');
+ };
+ const link = (name,ref) => load(resolve(ref.identifier,name));
+ function load(path) {
+  if(modules.has(path)) return modules.get(path);
+  const source=sources[path];
+  if(!source) throw new Error('Module is unavailable: '+path);
+  const module=new SourceTextModule(source.code,{context,identifier:path,importModuleDynamically:async name=>{
+   const child=load(resolve(path,name));
+   if(child.status==='unlinked') await child.link(link);
+   if(child.status==='linked') await child.evaluate({timeout:workerData.timeout});
+   return child;
+  }});
+  modules.set(path,module);return module;
+ }
+ const root=load(data.src);
+ await root.link(link);await root.evaluate({timeout:workerData.timeout});
+ context.__module=root.namespace;
+ context.__inputJson=JSON.stringify(data.input);
+ new Script('globalThis.__runtime=('+workerData.runtime+')(__module,JSON.parse(__inputJson),{call:async()=>{throw new Error("Capabilities are unavailable during export.")},invalidate(){}})').runInContext(context,{timeout:workerData.timeout});
+ return {context,signature:data.signature,time:-1,draw:!!root.namespace.draw,canvas:null};
+}
+parentPort.on('message',async data=>{
+ try {
+  if(data.release) {for(const id of data.release) release(id);return;}
+  if(data.sources) graphs.set(data.src,data.sources);
+  let entry=instances.get(data.input.id);
+  if(!entry || entry.signature!==data.signature || data.time<entry.time) {
+   release(data.input.id);
+   entry=await create(data);instances.set(data.input.id,entry);
+  }
+  const context=entry.context;
+  context.__inputJson=JSON.stringify(data.input);context.__time=data.time;
+  update.runInContext(context,{timeout:workerData.timeout});entry.time=data.time;
+  let png;
+  if(entry.draw) {
+   const width=Math.max(1,Math.round(data.input.width*data.scale));
+   const height=Math.max(1,Math.round(data.input.height*data.scale));
+   const canvas=entry.canvas??=createCanvas(width,height);
+   canvas.width=width;canvas.height=height;
+   const drawing=canvas.getContext('2d');drawing.scale(data.scale,data.scale);
+   context.__drawing=drawing;draw.runInContext(context,{timeout:workerData.timeout});
+   png=canvas.toBuffer('image/png');delete context.__drawing;
+  }
+  parentPort.postMessage({png,output:JSON.parse(output.runInContext(context,{timeout:workerData.timeout}))});
+ } catch(error) { instances.delete(data.input?.id);parentPort.postMessage({error:String(error.stack||error)}); }
+});
+`;
+function createNodeBoardScriptHost(renderer, options) {
+	const textures = /* @__PURE__ */ new Map();
+	const outputs = /* @__PURE__ */ new Map();
+	const errors = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	const modules = createBoardScriptModuleReader(options.readModule, options.readTimeoutMs);
+	const lanes = Array.from({ length: 4 }, () => ({
+		worker: null,
+		tail: Promise.resolve(),
+		graphs: /* @__PURE__ */ new Set()
+	}));
+	const assignments = /* @__PURE__ */ new Map();
+	let disposed = false;
+	let nextLane = 0;
+	const timeout = options.timeoutMs ?? 2e3;
+	const key = (id, time) => `${id}|${time}`;
+	function stop(lane) {
+		const worker = lane.worker;
+		lane.worker = null;
+		lane.graphs.clear();
+		worker?.terminate();
+	}
+	function sample(input, graph, time, scale) {
+		let lane = assignments.get(input.id);
+		if (!lane) {
+			lane = lanes[nextLane++ % lanes.length];
+			assignments.set(input.id, lane);
+		}
+		const selected = lane;
+		const task = selected.tail.then(() => new Promise((resolve, reject) => {
+			if (disposed) {
+				reject(/* @__PURE__ */ new Error("Script host is disposed."));
+				return;
+			}
+			if (!Number.isFinite(time) || time < 0 || time > 6e5) {
+				reject(/* @__PURE__ */ new Error("Script export time must be between 0 and 600000 ms."));
+				return;
+			}
+			const freshWorker = !selected.worker;
+			selected.worker ??= new Worker(WORKER, {
+				eval: true,
+				execArgv: ["--experimental-vm-modules", "--disable-warning=ExperimentalWarning"],
+				env: {},
+				resourceLimits: { maxOldGenerationSizeMb: 128 },
+				workerData: {
+					runtime: createScriptRuntime.toString(),
+					timeout,
+					canvasModule: fileURLToPath(import.meta.resolve("@napi-rs/canvas"))
+				}
+			});
+			const worker = selected.worker;
+			if (freshWorker) {
+				const stopped = (error) => {
+					if (selected.worker !== worker) return;
+					if (selected.reject) selected.reject(error);
+					else stop(selected);
+				};
+				worker.on("error", stopped);
+				worker.on("exit", () => stopped(/* @__PURE__ */ new Error("Script worker stopped.")));
+			}
+			const cleanup = () => {
+				clearTimeout(timer);
+				worker.off("message", message);
+				selected.reject = void 0;
+			};
+			const failure = (error) => {
+				cleanup();
+				stop(selected);
+				reject(error);
+			};
+			const message = (value) => {
+				cleanup();
+				if (value.error) reject(new Error(value.error));
+				else resolve(value);
+			};
+			const timer = setTimeout(() => failure(/* @__PURE__ */ new Error("Script export timed out.")), Math.max(timeout, 15e3));
+			selected.reject = failure;
+			worker.once("message", message);
+			const src = input.item.script?.src ?? "";
+			worker.postMessage({
+				input,
+				src,
+				signature: JSON.stringify(input.item.script),
+				sources: selected.graphs.has(src) ? void 0 : graph,
+				time,
+				scale
+			});
+			selected.graphs.add(src);
+		}));
+		selected.tail = task.catch(() => void 0);
+		return task;
+	}
+	return {
+		ready: (id) => [...outputs.values()].some((at) => at.has(id)),
+		frame: (item, time) => textures.get(key(item.id, time)) ?? null,
+		error: (id) => errors.get(id) ?? null,
+		release() {},
+		document(document, time) {
+			const at = outputs.get(time);
+			if (!at?.size) return document;
+			const items = { ...document.items };
+			for (const [id, item] of composeBoardScriptItems(document, buildBoardScene(document), at)) items[id] = item;
+			return {
+				...document,
+				items
+			};
+		},
+		clearFrames() {
+			for (const texture of textures.values()) texture.destroy(true);
+			textures.clear();
+			outputs.clear();
+			errors.clear();
+		},
+		async prepare(items, times, zoom) {
+			const scripted = items.filter((item) => item.script?.enabled);
+			const alive = new Set(scripted.map((item) => item.id));
+			for (const [id, lane] of assignments) if (!alive.has(id)) {
+				lane.worker?.postMessage({ release: [id] });
+				assignments.delete(id);
+			}
+			if (!scripted.length) return;
+			const all = Object.fromEntries(items.map(({ id, frame: _frame, ...item }) => [id, item]));
+			await Promise.all(scripted.map(async (item) => {
+				const base = all[item.id];
+				const src = item.script?.src;
+				if (!base || !src) return;
+				try {
+					let graph = sources.get(src);
+					if (!graph) {
+						graph = loadBoardScriptSources(src, modules.read, options.readTimeoutMs);
+						sources.set(src, graph);
+					}
+					const resolved = await graph;
+					const width = "size" in item ? item.size.width : item.frame.width;
+					const height = "size" in item ? item.size.height : item.frame.height;
+					const scale = Math.min(4, Math.max(.25, zoom), 2048 / Math.max(1, width, height));
+					const scoped = Object.fromEntries([...boardScriptScope({ items: all }, item.id)].flatMap((id) => all[id] ? [[id, all[id]]] : []));
+					for (const time of times) {
+						const result = await sample({
+							id: item.id,
+							item: base,
+							items: scoped,
+							width,
+							height
+						}, resolved, time, scale);
+						if (disposed) return;
+						if (result.png) {
+							const frameKey = key(item.id, time);
+							textures.get(frameKey)?.destroy(true);
+							textures.set(frameKey, await renderer.decodeImage(result.png));
+						}
+						let at = outputs.get(time);
+						if (!at) {
+							at = /* @__PURE__ */ new Map();
+							outputs.set(time, at);
+						}
+						at.set(item.id, result.output);
+					}
+				} catch (error) {
+					errors.set(item.id, error instanceof Error ? error.message : String(error));
+				}
+			}));
+		},
+		destroy() {
+			disposed = true;
+			for (const lane of lanes) {
+				lane.reject?.(/* @__PURE__ */ new Error("Script host is disposed."));
+				stop(lane);
+			}
+			for (const texture of textures.values()) texture.destroy(true);
+			textures.clear();
+			outputs.clear();
+			sources.clear();
+			modules.destroy();
+			assignments.clear();
+		}
+	};
+}
+//#endregion
+export { createNodeBoardScriptHost };

package/dist/board/export/scene.d.ts

@@ -12,13 +12,14 @@ type BoardExportSceneInput = {
   scene: BoardScene;
   items: readonly BoardSceneItem[];
   time?: number;
+  frameAt?: BoardRenderContext["frameAt"];
   world: Rect;
   scale: number;
   colorScheme: "dark" | "light";
   palette?: Partial<BoardRenderPalette>;
   colors?: BoardShapeColors;
   textures?: Map<string, Texture>;
-  sketches?: BoardRenderContext["sketches"];
+  scripts?: BoardRenderContext["scripts"];
   assetKey?: (item: BoardSceneItem) => string | null;
   /** Renderers for item types beyond the built-ins. */
   renderers?: BoardCardRendererResolver;

package/dist/board/export/scene.js

@@ -1,8 +1,8 @@
 import { buildFallbackShapeColors } from "../model/palette.js";
 import { imageAssetKey } from "../model/image-key.js";
-import { clippingAncestor, isClippingFrame, syncClipGroup } from "../render/clip.js";
 import { defaultBoardPalette } from "../render/palette.js";
-import { getBoardCardRenderer } from "../render/renderers/board-renderer-registry.js";
+import { clippingAncestor, isClippingFrame, syncClipGroup } from "../render/clip.js";
+import { DEFAULT_BOARD_RENDER_LABELS, getBoardCardRenderer } from "../render/renderers/board-renderer-registry.js";
 import { Container, Graphics, Sprite, TilingSprite } from "pixi.js";
 //#region src/board/export/scene.ts
 function buildContext(input) {
@@ -13,6 +13,7 @@ function buildContext(input) {
 			settings: input.settings,
 			scene: input.scene,
 			time: input.time ?? 0,
+			frameAt: input.frameAt,
 			selectedIds: /* @__PURE__ */ new Set(),
 			hoveredId: null,
 			resizingIds: /* @__PURE__ */ new Set(),
@@ -24,7 +25,10 @@ function buildContext(input) {
 			colorScheme: input.colorScheme,
 			rendererType: "canvas",
 			zoom: input.scale,
-			sketches: input.sketches,
+			reducedMotion: true,
+			labels: DEFAULT_BOARD_RENDER_LABELS,
+			taskRun: () => null,
+			scripts: input.scripts,
 			assetKey: input.assetKey ?? imageAssetKey,
 			getTexture: (key) => textures.get(key) ?? null,
 			hasError: (key) => {
@@ -77,13 +81,26 @@ function createBoardExportScene(input) {
 	world.position.set(-input.world.x * input.scale, -input.world.y * input.scale);
 	const resolve = input.renderers ?? getBoardCardRenderer;
 	const groups = /* @__PURE__ */ new Map();
-	for (const item of input.items) {
+	function hostFor(item) {
 		const clip = clippingAncestor(input.scene, item);
-		const host = clip && groups.get(clip) || world;
+		const ancestor = clip ? input.scene.get(clip) : void 0;
+		if (!ancestor) return world;
+		let group = groups.get(ancestor.id);
+		if (!group) {
+			group = syncClipGroup(void 0, ancestor).group;
+			hostFor(ancestor).addChild(group);
+			groups.set(ancestor.id, group);
+		}
+		return group;
+	}
+	for (const item of input.items) {
+		const opacity = input.scene.opacity(item.id);
+		if (opacity <= 0) continue;
+		const host = hostFor(item);
 		const container = resolve(item, context).create(item, context);
-		container.alpha = input.scene.opacity(item.id);
+		container.alpha = opacity;
 		host.addChild(container);
-		if (isClippingFrame(item)) {
+		if (isClippingFrame(item) && !groups.has(item.id)) {
 			const { group } = syncClipGroup(void 0, item);
 			host.addChild(group);
 			groups.set(item.id, group);

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

@@ -35,7 +35,10 @@ type CompiledBoardAnimations = {
   readonly document: BoardDocument;
 };
 declare function compileBoardAnimations(document: BoardDocument): CompiledBoardAnimations;
-type BoardColorResolver = (color: BoardColor) => number | null;
+type BoardColorResolver = (color: BoardColor) => number | {
+  color: number;
+  alpha: number;
+} | null;
 declare function parseHexColor(color: BoardColor): number | null;
 declare function sampleBoardTrack(track: CompiledTrack, time: number, resolveColor?: BoardColorResolver): unknown;
 type BoardCameraOverride = {

package/dist/board/model/animation.js

@@ -183,11 +183,21 @@ function hex(color) {
 	return `#${Math.max(0, Math.min(16777215, Math.round(color))).toString(16).padStart(6, "0")}`;
 }
 function mixColor(a, b, t, resolve) {
-	const from = resolve(a);
-	const to = resolve(b);
-	if (from === null || to === null) return t < 1 ? a : b;
-	const channel = (shift) => Math.round(lerp(from >> shift & 255, to >> shift & 255, t));
-	return hex(channel(16) << 16 | channel(8) << 8 | channel(0));
+	const left = resolve(a);
+	const right = resolve(b);
+	if (left === null || right === null) return t < 1 ? a : b;
+	const from = typeof left === "number" ? {
+		color: left,
+		alpha: 1
+	} : left;
+	const to = typeof right === "number" ? {
+		color: right,
+		alpha: 1
+	} : right;
+	const alpha = lerp(from.alpha, to.alpha, t);
+	const channel = (shift) => alpha > 0 ? Math.round(lerp((from.color >> shift & 255) * from.alpha, (to.color >> shift & 255) * to.alpha, t) / alpha) : 0;
+	const rgb = hex(channel(16) << 16 | channel(8) << 8 | channel(0));
+	return alpha >= 1 ? rgb : `${rgb}${Math.round(Math.max(0, alpha) * 255).toString(16).padStart(2, "0")}`;
 }
 function parseHexColor(color) {
 	if (typeof color !== "string") return null;
@@ -196,6 +206,23 @@ function parseHexColor(color) {
 	const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
 	return Number.parseInt(digits, 16);
 }
+function parseAnimationColor(color) {
+	if (typeof color === "string") {
+		if (color.trim().toLowerCase() === "transparent") return {
+			color: 0,
+			alpha: 0
+		};
+		const match = /^#([0-9a-f]{4}|[0-9a-f]{8})$/i.exec(color.trim());
+		if (match?.[1]) {
+			const digits = match[1].length === 4 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
+			return {
+				color: Number.parseInt(digits.slice(0, 6), 16),
+				alpha: Number.parseInt(digits.slice(6), 16) / 255
+			};
+		}
+	}
+	return parseHexColor(color);
+}
 function blend(track, index, time, resolveColor) {
 	const { times, values } = track;
 	const from = values[index];
@@ -229,7 +256,7 @@ function blend(track, index, time, resolveColor) {
 		default: return progress >= 1 ? to : from;
 	}
 }
-function sampleBoardTrack(track, time, resolveColor = parseHexColor) {
+function sampleBoardTrack(track, time, resolveColor = parseAnimationColor) {
 	const index = keyframeIndex(track.times, time);
 	if (index < 0) return track.values[0];
 	return blend(track, index, time, resolveColor);
@@ -302,7 +329,7 @@ function outranks(track, time, other, otherTime) {
 	return track.id > other.id;
 }
 function evaluateBoardAnimations(compiled, times, options = {}) {
-	const resolveColor = options.resolveColor ?? parseHexColor;
+	const resolveColor = options.resolveColor ?? parseAnimationColor;
 	const local = new Map(times instanceof Map ? times : Object.entries(times));
 	for (const id of compiled.order) {
 		const animation = compiled.animations.get(id);

package/dist/board/model/authoring.d.ts

@@ -0,0 +1,20 @@
+import { BoardAnimation, BoardDocument, BoardPatch, BoardTrack, BoardVec2 } from "../../protocol/dist/board-model.js";
+import "../../protocol/dist/index.js";
+//#region src/board/model/authoring.d.ts
+type BoardChapter = {
+  animation: string;
+  frame?: string;
+  label?: string;
+  gap?: number;
+  pause?: boolean;
+};
+declare function boardSequence(document: BoardDocument, chapters: readonly BoardChapter[]): BoardAnimation;
+declare function boardSequencePatch(document: BoardDocument, id: string, chapters: readonly BoardChapter[]): BoardPatch;
+declare function boardPathTrack(target: string, points: readonly BoardVec2[], options: {
+  duration: number;
+  at?: number;
+  samples?: number;
+  orient?: boolean;
+}): BoardTrack;
+//#endregion
+export { BoardChapter, boardPathTrack, boardSequence, boardSequencePatch };

package/dist/board/model/authoring.js

@@ -0,0 +1,185 @@
+import { BoardIdSchema } from "../../protocol/dist/board-model.js";
+import { applyBoardPatchToDocument } from "../../protocol/dist/board-patch.js";
+//#region src/board/model/authoring.ts
+function validateChapterComposition(document, chapters) {
+	const uses = /* @__PURE__ */ new Map();
+	for (const [index, chapter] of chapters.entries()) for (const track of Object.values(document.animations[chapter.animation]?.tracks ?? {})) {
+		let properties = uses.get(track.target);
+		if (!properties) {
+			properties = /* @__PURE__ */ new Map();
+			uses.set(track.target, properties);
+		}
+		for (const [property, usage] of properties) if ((property === track.property || property.startsWith(`${track.property}.`) || track.property.startsWith(`${property}.`)) && (usage.additive || track.composite === "add") && [...usage.chapters].some((other) => other !== index)) throw new Error(`Chapters share additive tracks on ${track.target}.${track.property}; use distinct items or combine the tracks before sequencing.`);
+		const usage = properties.get(track.property) ?? {
+			chapters: /* @__PURE__ */ new Set(),
+			additive: false
+		};
+		usage.chapters.add(index);
+		usage.additive ||= track.composite === "add";
+		properties.set(track.property, usage);
+	}
+}
+function boardSequence(document, chapters) {
+	if (!chapters.length) throw new Error("A sequence needs at least one chapter.");
+	validateChapterComposition(document, chapters);
+	const tracks = {};
+	const markers = [];
+	let cursor = 0;
+	const seen = /* @__PURE__ */ new Set();
+	const seenFrames = /* @__PURE__ */ new Set();
+	for (const [index, chapter] of chapters.entries()) {
+		const animation = document.animations[chapter.animation];
+		if (!animation) throw new Error(`Animation ${chapter.animation} does not exist.`);
+		if (animation.play !== "manual") throw new Error(`Chapter ${chapter.animation} must use manual playback.`);
+		if (!Number.isFinite(animation.duration) || animation.duration <= 0) throw new Error("Chapter duration must be positive and finite.");
+		if (seen.has(chapter.animation)) throw new Error(`Animation ${chapter.animation} appears more than once; use separate animation IDs.`);
+		seen.add(chapter.animation);
+		if (chapter.frame && document.items[chapter.frame]?.type !== "frame") throw new Error(`Chapter ${chapter.animation} needs a valid frame.`);
+		if (chapter.frame && seenFrames.has(chapter.frame)) throw new Error("Each chapter needs a separate frame, or omit frame visibility control.");
+		if (chapter.frame) seenFrames.add(chapter.frame);
+		const gap = chapter.gap ?? 0;
+		if (!Number.isFinite(gap) || gap < 0) throw new Error("Chapter gap must be finite and non-negative.");
+		cursor += gap;
+		const start = cursor;
+		const end = start + animation.duration;
+		const rankWidth = String(Object.keys(animation.tracks).length).length;
+		const ranks = new Map(Object.keys(animation.tracks).sort().map((id, rank) => [id, String(rank).padStart(rankWidth, "0")]));
+		const chapterIndex = String(index).padStart(String(chapters.length).length, "0");
+		for (const [id, track] of Object.entries(animation.tracks)) {
+			if (document.animations[track.target]) throw new Error(`Chapter ${chapter.animation} contains nested clocks; compose its leaf animations instead.`);
+			if (chapter.frame && track.target === "camera" && track.property === "focus") continue;
+			tracks[`chapter-${chapterIndex}-${ranks.get(id)}`] = {
+				...track,
+				keyframes: track.keyframes.map((keyframe) => ({
+					...keyframe,
+					at: start + keyframe.at
+				}))
+			};
+		}
+		const boundary = end + (chapter.pause && index < chapters.length - 1 ? 1 : 0);
+		if (chapter.frame) {
+			tracks[`visibility-${index}`] = {
+				target: chapter.frame,
+				property: "opacity",
+				composite: "add",
+				interpolation: "step",
+				keyframes: [
+					...start > 0 ? [{
+						at: 0,
+						value: 0
+					}] : [],
+					{
+						at: start,
+						value: 1
+					},
+					...index < chapters.length - 1 ? [{
+						at: boundary + (chapters[index + 1]?.gap ?? 0),
+						value: 0
+					}] : []
+				]
+			};
+			tracks[`camera-${index}`] = {
+				target: "camera",
+				property: "focus",
+				composite: "replace",
+				interpolation: "step",
+				keyframes: [{
+					at: start,
+					value: chapter.frame
+				}]
+			};
+		}
+		markers.push({
+			at: start,
+			label: chapter.label ?? animation.name ?? chapter.animation
+		});
+		for (const marker of animation.markers) markers.push({
+			...marker,
+			at: start + marker.at
+		});
+		if (chapter.pause) markers.push({
+			at: end,
+			pause: true
+		});
+		cursor = boundary;
+	}
+	const byTime = /* @__PURE__ */ new Map();
+	for (const marker of markers) {
+		const previous = byTime.get(marker.at);
+		byTime.set(marker.at, {
+			...previous,
+			...marker,
+			pause: Boolean(previous?.pause || marker.pause)
+		});
+	}
+	return {
+		duration: cursor,
+		play: "manual",
+		end: "hold",
+		delay: 0,
+		loop: false,
+		tracks,
+		markers: [...byTime.values()].sort((a, b) => a.at - b.at)
+	};
+}
+function boardSequencePatch(document, id, chapters) {
+	BoardIdSchema.parse(id);
+	if (chapters.some((chapter) => chapter.animation === id)) throw new Error("A sequence cannot overwrite one of its source chapters.");
+	const animation = boardSequence(document, chapters);
+	const tracks = { ...animation.tracks };
+	for (const key of Object.keys(document.animations[id]?.tracks ?? {})) if (!(key in tracks)) tracks[key] = null;
+	const patch = { animations: { [id]: {
+		...animation,
+		tracks
+	} } };
+	const result = applyBoardPatchToDocument(document, patch);
+	if (!result.ok) throw new Error(result.diagnostics.map((entry) => `${entry.path}: ${entry.message}`).join("; "));
+	return patch;
+}
+function boardPathTrack(target, points, options) {
+	const { duration, at = 0, samples = 64, orient = false } = options;
+	if (points.length < 2 || points.length > 1e4 || points.some((p) => !Number.isFinite(p.x) || !Number.isFinite(p.y))) throw new Error("A path needs 2 to 10000 finite points.");
+	if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(at) || at < 0) throw new Error("Path duration must be positive and start time non-negative.");
+	if (!Number.isInteger(samples) || samples < 2 || samples > 1e4) throw new Error("Path samples must be an integer from 2 to 10000.");
+	const segments = [];
+	let total = 0;
+	let previous = points[0];
+	for (const point of points.slice(1)) {
+		if (!previous) break;
+		const start = total;
+		total += Math.hypot(point.x - previous.x, point.y - previous.y);
+		segments.push({
+			a: previous,
+			b: point,
+			start,
+			end: total
+		});
+		previous = point;
+	}
+	const distances = [.../* @__PURE__ */ new Set([...segments.map((segment) => segment.end), ...Array.from({ length: samples }, (_, index) => total * index / (samples - 1))])].sort((a, b) => a - b);
+	let segmentIndex = 0;
+	return {
+		target,
+		property: "position",
+		composite: "replace",
+		interpolation: "auto",
+		orient,
+		keyframes: distances.map((distance) => {
+			const progress = total > 0 ? distance / total : 0;
+			while (segmentIndex < segments.length - 1 && (segments[segmentIndex]?.end ?? 0) < distance) segmentIndex++;
+			const segment = segments[segmentIndex];
+			if (!segment) throw new Error("Path has no segments.");
+			const { a, b, start, end } = segment;
+			const fraction = end > start ? (distance - start) / (end - start) : 0;
+			return {
+				at: at + duration * progress,
+				value: {
+					x: a.x + (b.x - a.x) * fraction,
+					y: a.y + (b.y - a.y) * fraction
+				}
+			};
+		})
+	};
+}
+//#endregion
+export { boardPathTrack, boardSequence, boardSequencePatch };

package/dist/board/model/export-plan.js

@@ -43,6 +43,7 @@ function resolveRegion(scene, region) {
 		return boundsOf.get(item.id) ?? null;
 	};
 	const visible = (item, rect) => {
+		if (item.type === "effect" && item.props.kind === "trail" && item.props.follow) return true;
 		const box = bounds(item);
 		return box !== null && rectsIntersect(box, rect);
 	};

package/dist/board/model/file-preview.js

@@ -13,7 +13,7 @@ function filePreviewKind(snapshot) {
 }
 /** Short uppercase type label for a file card (`MD`, `JSON`, `FILE`). */
 function fileTypeLabel(path) {
-	const name = path.split("/").filter(Boolean).pop() ?? path;
+	const name = fileBaseName(path);
 	const dot = name.lastIndexOf(".");
 	if (dot <= 0) return (name.replace(/^\./, "") || "file").toUpperCase();
 	return name.slice(dot + 1).toUpperCase();

package/dist/board/model/file-snapshot.js

@@ -1,3 +1,4 @@
+import { getMediaResourceTitle } from "./media.js";
 //#region src/board/model/file-snapshot.ts
 /**
 * File-card snapshot derivation — pure, renderer-agnostic, dependency-free.
@@ -134,7 +135,7 @@ const MEDIA_EXTENSIONS = /* @__PURE__ */ new Set([
 ]);
 const IMAGE_REF_RE = /\.(png|jpe?g|gif|webp|avif|svg|bmp|ico)(\?|#|$)/i;
 function extensionOf(path) {
-	const name = path.split("/").filter(Boolean).pop() ?? path;
+	const name = fileBaseName(path);
 	const dot = name.lastIndexOf(".");
 	if (dot <= 0) return "";
 	return name.slice(dot + 1).toLowerCase();
@@ -162,7 +163,7 @@ function fileCategory(path, mimeType) {
 }
 /** Basename of a path, used as a last-resort card title. */
 function fileBaseName(path) {
-	return path.split("/").filter(Boolean).pop() ?? path;
+	return getMediaResourceTitle(path);
 }
 /** Basename with a trailing extension stripped. Dotfiles keep their full name. */
 function fileStem(path) {