@neta-art/cohub 8.10.2 → 8.12.0

package/dist/board/render/{themes/clean-theme.js → board-background.js}

@@ -1,12 +1,11 @@
-import { parseBoardCssColor } from "../css-color.js";
+import { parseBoardCssColor } from "./css-color.js";
 import { Container, Graphics, RenderTexture, TilingSprite } from "pixi.js";
-//#region src/board/render/themes/clean-theme.ts
+//#region src/board/render/board-background.ts
 const partsByContainer = /* @__PURE__ */ new WeakMap();
-/** Positive modulo so tile offsets stay valid for negative viewport offsets. */
 function wrap(value, period) {
 	return (value % period + period) % period;
 }
-function buildGridTexture(context, size, color, opacity, kind = "dots") {
+function buildGridTexture(context, size, color, opacity, kind) {
 	const graphics = new Graphics();
 	if (kind === "grid") graphics.moveTo(0, .5).lineTo(size, .5).moveTo(.5, 0).lineTo(.5, size).stroke({
 		color,
@@ -46,11 +45,10 @@ function sync(parts, context) {
 		parts.lastBg = bgColor;
 		parts.lastBgAlpha = bgAlpha;
 	}
-	const appearance = document.appearance;
-	const visible = appearance.grid?.visible === true;
-	const size = Math.max(4, appearance.grid?.size ?? 24);
-	const opacity = appearance.grid?.opacity ?? .12;
-	const kind = appearance.background?.kind === "grid" ? "grid" : "dots";
+	const visible = document.appearance.grid?.visible === true;
+	const size = Math.max(4, document.appearance.grid?.size ?? 24);
+	const opacity = document.appearance.grid?.opacity ?? .12;
+	const kind = document.appearance.background?.kind === "grid" ? "grid" : "dots";
 	const key = `${kind}|${size}|${palette.border}|${opacity}`;
 	if (!visible) {
 		if (parts.sprite) parts.sprite.visible = false;
@@ -80,30 +78,25 @@ function sync(parts, context) {
 	sprite.tileScale.set(viewport.zoom);
 	sprite.tilePosition.set(wrap(viewport.x, step), wrap(viewport.y, step));
 }
-const cleanBoardTheme = {
-	id: "clean",
-	canRender: () => true,
-	createBackground: (context) => {
-		const container = new Container();
-		const fill = new Graphics();
-		container.addChild(fill);
-		const parts = {
-			fill,
-			sprite: null,
-			textureKey: "",
-			lastWidth: -1,
-			lastHeight: -1,
-			lastBg: NaN,
-			lastBgAlpha: NaN
-		};
-		partsByContainer.set(container, parts);
-		sync(parts, context);
-		return container;
-	},
-	updateBackground: (container, context) => {
-		const parts = partsByContainer.get(container);
-		if (parts) sync(parts, context);
-	}
-};
+function createBoardBackground(context) {
+	const container = new Container({ label: "board-background" });
+	const fill = new Graphics();
+	container.addChild(fill);
+	partsByContainer.set(container, {
+		fill,
+		sprite: null,
+		textureKey: "",
+		lastWidth: -1,
+		lastHeight: -1,
+		lastBg: NaN,
+		lastBgAlpha: NaN
+	});
+	sync(partsByContainer.get(container), context);
+	return container;
+}
+function updateBoardBackground(container, context) {
+	const parts = partsByContainer.get(container);
+	if (parts) sync(parts, context);
+}
 //#endregion
-export { cleanBoardTheme };
+export { createBoardBackground, updateBoardBackground };

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

@@ -1,11 +1,11 @@
+import { BoardCardRenderer, BoardRenderContext, BoardRenderPalette, boardCardRenderersForTest, getBoardCardRenderer, registerBoardCardRenderer } from "./renderers/board-renderer-registry.js";
+import { BoardBackgroundContext, createBoardBackground, updateBoardBackground } from "./board-background.js";
 import { ConnectionLayer, ConnectionRenderInput, createConnectionLayer, framesFromItems } from "./connection-layer.js";
 import { parseBoardCssColor } from "./css-color.js";
 import { BoardMediaAction, boardMediaActionAt, mediaPlayBadgeHit, mediaPlayBadgeVisible } from "./media-interaction.js";
-import { BoardCardRenderer, BoardRenderContext, BoardRenderPalette, boardCardRenderersForTest, getBoardCardRenderer, registerBoardCardRenderer } from "./renderers/board-renderer-registry.js";
 import { defaultBoardPalette } from "./palette.js";
 import { TASK_CARD_FULL_DETAIL_ZOOM } from "./renderers/task-card-renderer.js";
 import { ensureBoardTextMeasurement, installBoardTextMeasurement } from "./text-measurement.js";
 import { getBoardResolution, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket } from "./text-resolution.js";
-import { BoardThemeContext, BoardThemeRenderer, getBoardThemeRenderer, registerBoardThemeRenderer } from "./themes/board-theme-registry.js";
 import { VIDEO_THUMBNAIL_MAX_EDGE, VideoNaturalSize, loadVideoThumbnailTexture, videoTextureNaturalSize, videoThumbnailSize } from "./video-thumbnail.js";
-export { BoardCardRenderer, BoardMediaAction, BoardRenderContext, BoardRenderPalette, BoardThemeContext, BoardThemeRenderer, ConnectionLayer, ConnectionRenderInput, TASK_CARD_FULL_DETAIL_ZOOM, VIDEO_THUMBNAIL_MAX_EDGE, VideoNaturalSize, boardCardRenderersForTest, boardMediaActionAt, createConnectionLayer, defaultBoardPalette, ensureBoardTextMeasurement, framesFromItems, getBoardCardRenderer, getBoardResolution, getBoardThemeRenderer, installBoardTextMeasurement, loadVideoThumbnailTexture, mediaPlayBadgeHit, mediaPlayBadgeVisible, parseBoardCssColor, registerBoardCardRenderer, registerBoardThemeRenderer, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket, videoTextureNaturalSize, videoThumbnailSize };
+export { BoardBackgroundContext, BoardCardRenderer, BoardMediaAction, BoardRenderContext, BoardRenderPalette, ConnectionLayer, ConnectionRenderInput, TASK_CARD_FULL_DETAIL_ZOOM, VIDEO_THUMBNAIL_MAX_EDGE, VideoNaturalSize, boardCardRenderersForTest, boardMediaActionAt, createBoardBackground, createConnectionLayer, defaultBoardPalette, ensureBoardTextMeasurement, framesFromItems, getBoardCardRenderer, getBoardResolution, installBoardTextMeasurement, loadVideoThumbnailTexture, mediaPlayBadgeHit, mediaPlayBadgeVisible, parseBoardCssColor, registerBoardCardRenderer, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket, updateBoardBackground, videoTextureNaturalSize, videoThumbnailSize };

package/dist/board/render/index.js

@@ -1,4 +1,5 @@
 import { parseBoardCssColor } from "./css-color.js";
+import { createBoardBackground, updateBoardBackground } from "./board-background.js";
 import { getBoardResolution, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket } from "./text-resolution.js";
 import { createConnectionLayer, framesFromItems } from "./connection-layer.js";
 import { TASK_CARD_FULL_DETAIL_ZOOM } from "./renderers/task-card-renderer.js";
@@ -6,6 +7,5 @@ import { boardMediaActionAt, mediaPlayBadgeHit, mediaPlayBadgeVisible } from "./
 import { defaultBoardPalette } from "./palette.js";
 import { ensureBoardTextMeasurement, installBoardTextMeasurement } from "./text-measurement.js";
 import { boardCardRenderersForTest, getBoardCardRenderer, registerBoardCardRenderer } from "./renderers/board-renderer-registry.js";
-import { getBoardThemeRenderer, registerBoardThemeRenderer } from "./themes/board-theme-registry.js";
 import { VIDEO_THUMBNAIL_MAX_EDGE, loadVideoThumbnailTexture, videoTextureNaturalSize, videoThumbnailSize } from "./video-thumbnail.js";
-export { TASK_CARD_FULL_DETAIL_ZOOM, VIDEO_THUMBNAIL_MAX_EDGE, boardCardRenderersForTest, boardMediaActionAt, createConnectionLayer, defaultBoardPalette, ensureBoardTextMeasurement, framesFromItems, getBoardCardRenderer, getBoardResolution, getBoardThemeRenderer, installBoardTextMeasurement, loadVideoThumbnailTexture, mediaPlayBadgeHit, mediaPlayBadgeVisible, parseBoardCssColor, registerBoardCardRenderer, registerBoardThemeRenderer, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket, videoTextureNaturalSize, videoThumbnailSize };
+export { TASK_CARD_FULL_DETAIL_ZOOM, VIDEO_THUMBNAIL_MAX_EDGE, boardCardRenderersForTest, boardMediaActionAt, createBoardBackground, createConnectionLayer, defaultBoardPalette, ensureBoardTextMeasurement, framesFromItems, getBoardCardRenderer, getBoardResolution, installBoardTextMeasurement, loadVideoThumbnailTexture, mediaPlayBadgeHit, mediaPlayBadgeVisible, parseBoardCssColor, registerBoardCardRenderer, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket, updateBoardBackground, videoTextureNaturalSize, videoThumbnailSize };

package/dist/board/render/renderers/file-card-renderer.js

@@ -1,5 +1,6 @@
-import { BOARD_FONT_STACK } from "../../../protocol/dist/board-constants.js";
-import { fileBaseName, filePreviewKind } from "../../core/file-preview.js";
+import { BOARD_FONT_STACK, BOARD_MONO_FONT_STACK } from "../../../protocol/dist/board-constants.js";
+import { fileCategory, fileStem } from "../../core/file-snapshot.js";
+import { fileCategoryAccent, filePreviewKind, fileTypeLabel } from "../../core/file-preview.js";
 import { syncTextResolution } from "../text-resolution.js";
 import { positionShell } from "./base-card-renderer.js";
 import { drawFarPlate } from "./far-plate.js";
@@ -31,8 +32,10 @@ const TITLE_LINE = TITLE_SIZE * 1.35;
 const TITLE_MAX_LINES = 2;
 const EXCERPT_SIZE = 11;
 const EXCERPT_LINE = EXCERPT_SIZE * 1.45;
-const EXCERPT_MAX_LINES = 4;
+const EXCERPT_MAX_LINES = 3;
+const TYPE_MARK_SIZE = 28;
 const GAP = 4;
+const STRIPE = 2;
 /** Zoom below which the title is dropped (glyphs are sub-pixel). */
 const LOD_TITLE_ZOOM = .35;
 /** Zoom below which the excerpt is dropped. */
@@ -168,8 +171,12 @@ function sync(container, item, context) {
 	const coverFailed = Boolean(key && !texture && context.hasError(key));
 	const fileState = context.fileState(item.ref.path);
 	const band = coverHeight(item, height);
+	const kind = filePreviewKind(item.snapshot);
+	const category = fileCategory(item.ref.path, item.snapshot?.mimeType);
+	const accent = fileCategoryAccent(category, context.palette);
 	syncTextResolution(parts.title, parts.titleRes, context.zoom);
 	syncTextResolution(parts.excerpt, parts.excerptRes, context.zoom);
+	syncTextResolution(parts.typeMark, parts.typeMarkRes, context.zoom);
 	const visualSig = [
 		key ?? "",
 		width,
@@ -180,9 +187,12 @@ function sync(container, item, context) {
 		texture ? `${texture.width}x${texture.height}` : "none",
 		coverFailed,
 		fileState,
+		kind,
+		category,
 		context.colorScheme,
 		context.palette.surface,
-		context.palette.hover
+		context.palette.hover,
+		accent
 	].join("|");
 	if (visualSig !== parts.visualSig) {
 		parts.visualSig = visualSig;
@@ -218,41 +228,61 @@ function sync(container, item, context) {
 		}
 		parts.cover.visible = showCover;
 		parts.coverMask.visible = showCover;
-		if (!band) parts.plate.rect(1, 1, 2, height - 2).fill({
-			color: context.palette.muted,
-			alpha: .35
+		if (!band) parts.plate.rect(1, 1, STRIPE, height - 2).fill({
+			color: accent,
+			alpha: .55
 		});
 		parts.title.visible = detail !== "plate";
 		parts.excerpt.visible = detail === "full";
+		parts.typeMark.visible = kind === "blank" && detail !== "plate";
 	}
-	if (detail === "plate") return;
-	const title = item.snapshot?.title || fileBaseName(item.ref.path);
+	if (detail === "plate") {
+		parts.typeMark.visible = false;
+		return;
+	}
+	const title = item.snapshot?.title || fileStem(item.ref.path);
 	const excerpt = item.snapshot?.excerpt ?? "";
+	const mark = fileTypeLabel(item.ref.path);
 	const innerWidth = Math.max(1, width - 20);
+	const showTypeMark = kind === "blank";
 	const textSig = [
 		title,
 		excerpt,
+		mark,
 		detail,
 		innerWidth,
 		band,
 		height,
+		kind,
 		context.palette.text,
-		context.palette.muted
+		context.palette.muted,
+		accent
 	].join("|");
 	if (textSig === parts.textSig) return;
 	parts.textSig = textSig;
 	const top = band > 0 ? band + PADDING * .8 : PADDING;
 	const contentBottom = height - PADDING;
-	const titleLines = linesInRoom(Math.max(0, contentBottom - top), TITLE_LINE, TITLE_MAX_LINES);
+	let cursor = top;
+	if (showTypeMark) {
+		const markSize = Math.max(18, Math.min(TYPE_MARK_SIZE, Math.round(height * .22)));
+		parts.typeMark.style.fill = accent;
+		parts.typeMark.style.fontSize = markSize;
+		parts.typeMark.style.lineHeight = markSize * 1.1;
+		if (parts.typeMark.text !== mark) parts.typeMark.text = mark;
+		parts.typeMark.position.set(PADDING, cursor);
+		parts.typeMark.visible = true;
+		cursor += parts.typeMark.height + GAP;
+	} else parts.typeMark.visible = false;
+	const titleLines = linesInRoom(Math.max(0, contentBottom - cursor), TITLE_LINE, TITLE_MAX_LINES);
 	parts.title.style.fill = context.palette.text;
 	fitTextToLines(parts.title, title, titleLines, innerWidth);
-	parts.title.position.set(PADDING, top);
+	parts.title.position.set(PADDING, cursor);
 	parts.title.visible = titleLines > 0;
 	if (detail !== "full") {
 		parts.excerpt.visible = false;
 		return;
 	}
-	const excerptTop = top + (titleLines > 0 ? parts.title.height + GAP : 0);
+	const excerptTop = cursor + (titleLines > 0 ? parts.title.height + GAP : 0);
 	const excerptLines = linesInRoom(contentBottom - excerptTop, EXCERPT_LINE, EXCERPT_MAX_LINES);
 	const showExcerpt = Boolean(excerpt) && excerptLines > 0;
 	if (showExcerpt) {
@@ -302,8 +332,20 @@ const fileCardRenderer = {
 			resolution,
 			roundPixels: true
 		});
+		const typeMark = new Text({
+			text: "",
+			style: {
+				fill: context.palette.muted,
+				fontFamily: BOARD_MONO_FONT_STACK,
+				fontSize: TYPE_MARK_SIZE,
+				fontWeight: "700",
+				lineHeight: TYPE_MARK_SIZE * 1.1
+			},
+			resolution,
+			roundPixels: true
+		});
 		body.mask = clip;
-		body.addChild(cover, coverMask, title, excerpt);
+		body.addChild(cover, coverMask, typeMark, title, excerpt);
 		root.addChild(plate, body, clip);
 		partsByContainer.set(root, {
 			root,
@@ -312,12 +354,14 @@ const fileCardRenderer = {
 			clip,
 			cover,
 			coverMask,
+			typeMark,
 			title,
 			excerpt,
 			visualSig: "",
 			textSig: "",
 			titleRes: { resolution },
-			excerptRes: { resolution }
+			excerptRes: { resolution },
+			typeMarkRes: { resolution }
 		});
 		if (item.type === "file") sync(root, item, context);
 		return root;
@@ -330,11 +374,12 @@ const fileCardRenderer = {
 	* would mean one draw call per distinct image and defeat the batch.
 	*/
 	renderFar: (graphics, item, context) => {
+		const category = fileCategory(item.type === "file" ? item.ref.path : "", item.type === "file" ? item.snapshot?.mimeType : void 0);
 		drawFarPlate(graphics, item.frame, {
 			fill: context.palette.surface,
 			fillAlpha: .96,
-			accent: context.palette.muted,
-			accentAlpha: .4
+			accent: fileCategoryAccent(category, context.palette),
+			accentAlpha: .45
 		});
 	},
 	destroy: (container) => {

package/dist/board/replay.d.ts

@@ -0,0 +1,52 @@
+import { RequestSource } from "../protocol/dist/provenance.js";
+import { BoardTransactionsPage } from "../protocol/dist/board.js";
+import { BoardDocument } from "../protocol/dist/board-document.js";
+import "../protocol/dist/index.js";
+//#region src/board/replay.d.ts
+type BoardReplayActorKind = "human" | "cli" | "agent";
+/** One step on the replay timeline. */
+type BoardReplayEntry = {
+  version: number;
+  actorId: string;
+  kind: BoardReplayActorKind;
+  /** Epoch milliseconds. */
+  at: number;
+  /** Whether the step changed anything visible in the render document. */
+  visual: boolean;
+};
+type BoardReplayPlayer = ReturnType<typeof createBoardReplayPlayer>;
+declare function boardReplayActorKind(source: RequestSource | null): BoardReplayActorKind;
+/**
+ * Create a player positioned at the live version described by the first page.
+ *
+ * `transactions` are newest-first as served; the player keeps them oldest-first.
+ * Older pages can be added with `prepend`, and newer transactions that arrive
+ * live can be added with `append`, so the timeline grows in both directions
+ * without a reset.
+ */
+declare function createBoardReplayPlayer(page: BoardTransactionsPage): {
+  /** Oldest version the loaded transactions can rewind to. */
+  readonly floor: number;
+  /** Newest version known to the player. */
+  readonly head: number;
+  readonly entries: readonly BoardReplayEntry[];
+  /** Current position. */
+  readonly version: number;
+  seek: (version: number) => number;
+  documentAt: (version: number) => BoardDocument;
+  /** Item ids touched by the transaction that produced `version`, for camera follow. */
+  changedItemIds(version: number): string[];
+  /** Add an older page (as served, newest-first). */
+  prepend(older: BoardTransactionsPage): void;
+  /**
+   * Add transactions that landed after the current head. Forward payloads are
+   * enough to extend the timeline; the scrub position is untouched.
+   *
+   * Returns false when the page does not reach back to the head: the chain
+   * would have a hole, so nothing is appended and the caller must fetch an
+   * older page (`before` = the page's oldest version) and try again.
+   */
+  append(latest: BoardTransactionsPage): boolean;
+};
+//#endregion
+export { BoardReplayActorKind, BoardReplayEntry, BoardReplayPlayer, boardReplayActorKind, createBoardReplayPlayer };

package/dist/board/replay.js

@@ -0,0 +1,261 @@
+import { BOARD_DOCUMENT_KIND } from "../protocol/dist/board.js";
+import { BoardAppearanceSchema, parseBoardDocument } from "../protocol/dist/board-document.js";
+import { boardNodeToAuthoringItem } from "../protocol/dist/board-codec.js";
+import { DEFAULT_BOARD_APPEARANCE, boardAuthoringItemToDocumentItem } from "./semantic-document.js";
+//#region src/board/replay.ts
+function boardReplayActorKind(source) {
+	if (!source) return "human";
+	if (source.toolCallId) return "agent";
+	return source.via === "cli" ? "cli" : "human";
+}
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+/** Apply one stored operation (forward payload or inverse) to the mutable state. */
+function applyOperation(state, type, payload) {
+	switch (type) {
+		case "board.patch": {
+			const patch = isRecord(payload.patch) ? payload.patch : {};
+			if (isRecord(patch.metadata)) state.metadata = patch.metadata;
+			if (isRecord(patch.metadataPatch)) state.metadata = {
+				...state.metadata,
+				...patch.metadataPatch
+			};
+			return;
+		}
+		case "node.create": {
+			const node = payload.node;
+			if (node) state.nodes.set(node.nodeId, node);
+			return;
+		}
+		case "node.patch": {
+			const nodeId = payload.nodeId;
+			const current = state.nodes.get(nodeId);
+			if (current && isRecord(payload.patch)) state.nodes.set(nodeId, {
+				...current,
+				...payload.patch,
+				nodeId
+			});
+			return;
+		}
+		case "node.delete":
+			state.nodes.delete(payload.nodeId);
+			return;
+		case "connection.create": {
+			const connection = payload.connection;
+			if (connection) state.connections.set(connection.id, connection);
+			return;
+		}
+		case "connection.patch": {
+			const connectionId = payload.connectionId;
+			const current = state.connections.get(connectionId);
+			if (current && isRecord(payload.patch)) state.connections.set(connectionId, {
+				...current,
+				...payload.patch,
+				id: connectionId
+			});
+			return;
+		}
+		case "connection.delete":
+			state.connections.delete(payload.connectionId);
+			return;
+		default: return;
+	}
+}
+/**
+* Inverses are stored either as a full operation (`{ type, payload }`) or, for
+* `board.patch`, as a bare `{ patch }`. Normalise both to `(type, payload)`.
+*/
+function inverseOf(operation) {
+	const inverse = operation.inverse;
+	if (!inverse) return null;
+	if (typeof inverse.type === "string" && isRecord(inverse.payload)) return {
+		type: inverse.type,
+		payload: inverse.payload
+	};
+	if (operation.type === "board.patch" && isRecord(inverse.patch)) return {
+		type: "board.patch",
+		payload: { patch: inverse.patch }
+	};
+	return null;
+}
+function operationItemIds(operation) {
+	const payload = operation.payload;
+	switch (operation.type) {
+		case "node.create": return isRecord(payload.node) && typeof payload.node.nodeId === "string" ? [payload.node.nodeId] : [];
+		case "node.patch":
+		case "node.delete": return typeof payload.nodeId === "string" ? [payload.nodeId] : [];
+		default: return [];
+	}
+}
+const VISUAL_OPERATION_TYPES = /* @__PURE__ */ new Set([
+	"board.patch",
+	"node.create",
+	"node.patch",
+	"node.delete",
+	"connection.create",
+	"connection.patch",
+	"connection.delete"
+]);
+function entryOf(transaction) {
+	return {
+		version: transaction.version,
+		actorId: transaction.actorId,
+		kind: boardReplayActorKind(transaction.source),
+		at: Date.parse(transaction.createdAt),
+		visual: transaction.operations.some((operation) => VISUAL_OPERATION_TYPES.has(operation.type))
+	};
+}
+function appearanceOf(metadata) {
+	const parsed = BoardAppearanceSchema.safeParse(metadata.appearance);
+	return parsed.success ? parsed.data : DEFAULT_BOARD_APPEARANCE;
+}
+function project(state) {
+	const nodes = [...state.nodes.values()].sort((a, b) => (a.orderKey ?? "").localeCompare(b.orderKey ?? ""));
+	return parseBoardDocument({
+		kind: BOARD_DOCUMENT_KIND,
+		version: 1,
+		appearance: appearanceOf(state.metadata),
+		viewport: {
+			x: 0,
+			y: 0,
+			zoom: 1
+		},
+		items: nodes.map((node) => boardAuthoringItemToDocumentItem(boardNodeToAuthoringItem(node))),
+		connections: [...state.connections.values()]
+	});
+}
+function stateFromSnapshot(snapshot) {
+	return {
+		nodes: new Map(snapshot.nodes.map(({ boardId: _boardId, version: _version, createdAt: _c, updatedAt: _u, ...node }) => [node.nodeId, node])),
+		connections: new Map(snapshot.connections.map(({ boardId: _boardId, revision: _revision, createdAt: _c, updatedAt: _u, ...connection }) => [connection.id, connection])),
+		metadata: snapshot.board.metadata
+	};
+}
+/**
+* Create a player positioned at the live version described by the first page.
+*
+* `transactions` are newest-first as served; the player keeps them oldest-first.
+* Older pages can be added with `prepend`, and newer transactions that arrive
+* live can be added with `append`, so the timeline grows in both directions
+* without a reset.
+*/
+function createBoardReplayPlayer(page) {
+	if (!page.snapshot) throw new Error("Board replay needs the first transactions page (with snapshot).");
+	const liveVersion = page.board.version;
+	const newest = page.transactions.reduce((max, transaction) => Math.max(max, transaction.version), 0);
+	if (page.transactions.length > 0 && newest !== liveVersion) throw new Error(`Board replay page is inconsistent: board is at v${liveVersion}, newest transaction is v${newest}.`);
+	let transactions = [...page.transactions].sort((a, b) => a.version - b.version);
+	let entries = transactions.map(entryOf);
+	const state = stateFromSnapshot(page.snapshot);
+	let cursor = liveVersion;
+	const documents = /* @__PURE__ */ new Map();
+	/** Oldest version reachable with the transactions loaded so far. */
+	let floor = transactions[0]?.baseVersion ?? liveVersion;
+	/**
+	* Index of the first transaction whose version is `>= version`. Versions are
+	* strictly increasing but not dense (a no-op mutation leaves a gap), so
+	* binary-search by value rather than indexing by offset.
+	*/
+	function lowerBound(version) {
+		let low = 0;
+		let high = transactions.length;
+		while (low < high) {
+			const mid = low + high >> 1;
+			if (transactions[mid].version < version) low = mid + 1;
+			else high = mid;
+		}
+		return low;
+	}
+	function transactionProducing(version) {
+		const candidate = transactions[lowerBound(version)];
+		return candidate?.version === version ? candidate : void 0;
+	}
+	/** Undo the transaction that produced `cursor`. */
+	function stepBackward() {
+		const transaction = transactionProducing(cursor);
+		if (!transaction) return false;
+		for (let index = transaction.operations.length - 1; index >= 0; index -= 1) {
+			const inverse = inverseOf(transaction.operations[index]);
+			if (inverse) applyOperation(state, inverse.type, inverse.payload);
+		}
+		cursor = transaction.baseVersion;
+		return true;
+	}
+	function stepForward(next) {
+		for (const operation of next.operations) applyOperation(state, operation.type, operation.payload);
+		cursor = next.version;
+	}
+	function head() {
+		return transactions.at(-1)?.version ?? liveVersion;
+	}
+	/**
+	* Move to `version`, clamped to the loaded range. Returns the version reached,
+	* which is the nearest loaded version at or below the request.
+	*/
+	function seek(version) {
+		const target = Math.max(floor, Math.min(head(), version));
+		while (cursor > target && stepBackward());
+		for (let next = transactions[lowerBound(cursor + 1)]; next && next.version <= target; next = transactions[lowerBound(cursor + 1)]) stepForward(next);
+		return cursor;
+	}
+	function documentAt(version) {
+		const reached = seek(version);
+		const cached = documents.get(reached);
+		if (cached) return cached;
+		const document = project(state);
+		documents.set(reached, document);
+		return document;
+	}
+	return {
+		/** Oldest version the loaded transactions can rewind to. */
+		get floor() {
+			return floor;
+		},
+		/** Newest version known to the player. */
+		get head() {
+			return head();
+		},
+		get entries() {
+			return entries;
+		},
+		/** Current position. */
+		get version() {
+			return cursor;
+		},
+		seek,
+		documentAt,
+		/** Item ids touched by the transaction that produced `version`, for camera follow. */
+		changedItemIds(version) {
+			return [...new Set(transactionProducing(version)?.operations.flatMap(operationItemIds))];
+		},
+		/** Add an older page (as served, newest-first). */
+		prepend(older) {
+			const current = floor;
+			const fresh = older.transactions.filter((transaction) => transaction.version <= current).sort((a, b) => a.version - b.version);
+			if (fresh.length === 0) return;
+			transactions = [...fresh, ...transactions];
+			entries = [...fresh.map(entryOf), ...entries];
+			floor = fresh[0].baseVersion;
+		},
+		/**
+		* Add transactions that landed after the current head. Forward payloads are
+		* enough to extend the timeline; the scrub position is untouched.
+		*
+		* Returns false when the page does not reach back to the head: the chain
+		* would have a hole, so nothing is appended and the caller must fetch an
+		* older page (`before` = the page's oldest version) and try again.
+		*/
+		append(latest) {
+			const current = head();
+			const fresh = latest.transactions.filter((transaction) => transaction.version > current).sort((a, b) => a.version - b.version);
+			if (fresh.length === 0) return true;
+			if (fresh[0].baseVersion > current) return false;
+			transactions = [...transactions, ...fresh];
+			entries = [...entries, ...fresh.map(entryOf)];
+			return true;
+		}
+	};
+}
+//#endregion
+export { boardReplayActorKind, createBoardReplayPlayer };

package/dist/board/semantic-document.d.ts

@@ -4,7 +4,15 @@ import { BoardDocument, BoardItem } from "../protocol/dist/board-document.js";
 import "../protocol/dist/index.js";
 //#region src/board/semantic-document.d.ts
 declare const DEFAULT_BOARD_APPEARANCE: {
-  theme: string;
+  theme?: string | undefined;
+  motion?: {
+    enter?: {
+      kind: string;
+      kindVersion: number;
+      params: Record<string, unknown>;
+    } | undefined;
+  } | undefined;
+  mood?: "arcane" | "clean" | "cyber" | "natural" | "playful" | undefined;
   background: {
     kind: "custom" | "dots" | "grid" | "image" | "shader" | "solid";
     color?: string | undefined;
@@ -18,7 +26,6 @@ declare const DEFAULT_BOARD_APPEARANCE: {
     size: number;
     opacity: number;
   };
-  mood: "arcane" | "clean" | "cyber" | "natural" | "playful";
 };
 /** Convert a public authoring Item to the renderer/editor document shape. */
 declare function boardAuthoringItemToDocumentItem(item: BoardAuthoringItem): BoardItem;

package/dist/board/semantic-document.js

@@ -5,14 +5,12 @@ import { boardDrawPointsToWorld } from "../protocol/dist/board-geometry.js";
 import { boardAuthoringItemToNode } from "../protocol/dist/board-codec.js";
 //#region src/board/semantic-document.ts
 const DEFAULT_BOARD_APPEARANCE = BoardAppearanceSchema.parse({
-	theme: "clean",
 	background: { kind: "solid" },
 	grid: {
 		visible: false,
 		size: 24,
 		opacity: .12
-	},
-	mood: "clean"
+	}
 });
 /** Convert a public authoring Item to the renderer/editor document shape. */
 function boardAuthoringItemToDocumentItem(item) {