@neta-art/cohub 3.0.0 → 3.2.0

package/dist/board/geometry.js

@@ -0,0 +1,468 @@
+//#region src/board/geometry.ts
+function screenPoint(x, y) {
+	return {
+		x,
+		y
+	};
+}
+function worldPoint(x, y) {
+	return {
+		x,
+		y
+	};
+}
+const MIN_BOARD_ZOOM = .05;
+const MAX_BOARD_ZOOM = 8;
+const DEFAULT_BOARD_VIEWPORT = {
+	x: 0,
+	y: 0,
+	zoom: 1
+};
+/** Smallest an item can be resized to, in world units. */
+const MIN_ITEM_SIZE = 24;
+/** Extra world-space padding applied when fitting content into view. */
+const FIT_PADDING = 64;
+/**
+* Fraction of the viewport's larger dimension used as an off-screen margin for
+* both card culling and texture preloading. Keeping them equal means a card's
+* texture is already requested before the card scrolls into view.
+*/
+const VIEWPORT_MARGIN_RATIO = .5;
+function clampZoom(zoom) {
+	const value = Number.isFinite(zoom) ? zoom : DEFAULT_BOARD_VIEWPORT.zoom;
+	return Math.min(8, Math.max(MIN_BOARD_ZOOM, value));
+}
+/** Keep transient camera state finite without discarding its last valid axes. */
+function normalizeViewport(viewport, fallback = DEFAULT_BOARD_VIEWPORT) {
+	const fallbackX = Number.isFinite(fallback.x) ? fallback.x : DEFAULT_BOARD_VIEWPORT.x;
+	const fallbackY = Number.isFinite(fallback.y) ? fallback.y : DEFAULT_BOARD_VIEWPORT.y;
+	const fallbackZoom = Number.isFinite(fallback.zoom) ? clampZoom(fallback.zoom) : DEFAULT_BOARD_VIEWPORT.zoom;
+	return {
+		x: Number.isFinite(viewport.x) ? viewport.x : fallbackX,
+		y: Number.isFinite(viewport.y) ? viewport.y : fallbackY,
+		zoom: Number.isFinite(viewport.zoom) ? clampZoom(viewport.zoom) : fallbackZoom
+	};
+}
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+function degToRad(degrees) {
+	return degrees * Math.PI / 180;
+}
+function radToDeg(radians) {
+	return radians * 180 / Math.PI;
+}
+function frameRect(frame) {
+	return {
+		x: frame.x,
+		y: frame.y,
+		width: frame.width,
+		height: frame.height
+	};
+}
+function rectCenter(rect) {
+	return worldPoint(rect.x + rect.width / 2, rect.y + rect.height / 2);
+}
+function rectsIntersect(a, b) {
+	return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+function rectContainsPoint(rect, point, tolerance = 0) {
+	return point.x >= rect.x - tolerance && point.x <= rect.x + rect.width + tolerance && point.y >= rect.y - tolerance && point.y <= rect.y + rect.height + tolerance;
+}
+function expandRect(rect, amount) {
+	return {
+		x: rect.x - amount,
+		y: rect.y - amount,
+		width: rect.width + amount * 2,
+		height: rect.height + amount * 2
+	};
+}
+function unionRects(rects) {
+	if (rects.length === 0) return null;
+	let minX = Number.POSITIVE_INFINITY;
+	let minY = Number.POSITIVE_INFINITY;
+	let maxX = Number.NEGATIVE_INFINITY;
+	let maxY = Number.NEGATIVE_INFINITY;
+	for (const rect of rects) {
+		minX = Math.min(minX, rect.x);
+		minY = Math.min(minY, rect.y);
+		maxX = Math.max(maxX, rect.x + rect.width);
+		maxY = Math.max(maxY, rect.y + rect.height);
+	}
+	return {
+		x: minX,
+		y: minY,
+		width: maxX - minX,
+		height: maxY - minY
+	};
+}
+function rotatePointAround(point, center, angleRad) {
+	const cos = Math.cos(angleRad);
+	const sin = Math.sin(angleRad);
+	const dx = point.x - center.x;
+	const dy = point.y - center.y;
+	return {
+		x: center.x + dx * cos - dy * sin,
+		y: center.y + dx * sin + dy * cos
+	};
+}
+/** Axis-aligned bounding box of a (possibly rotated) frame. */
+function itemBounds(frame) {
+	const rotation = frame.rotation || 0;
+	if (rotation === 0) return frameRect(frame);
+	const center = rectCenter(frameRect(frame));
+	const halfW = frame.width / 2;
+	const halfH = frame.height / 2;
+	const rad = degToRad(rotation);
+	const cos = Math.abs(Math.cos(rad));
+	const sin = Math.abs(Math.sin(rad));
+	const boundW = halfW * cos + halfH * sin;
+	const boundH = halfW * sin + halfH * cos;
+	return {
+		x: center.x - boundW,
+		y: center.y - boundH,
+		width: boundW * 2,
+		height: boundH * 2
+	};
+}
+function selectionBounds(frames) {
+	return unionRects(frames.map(itemBounds));
+}
+/** Exact point-in-frame test, accounting for rotation. */
+function frameContainsPoint(frame, point) {
+	const rect = frameRect(frame);
+	const rotation = frame.rotation || 0;
+	let local = point;
+	if (rotation !== 0) local = rotatePointAround(point, rectCenter(rect), -degToRad(rotation));
+	return rectContainsPoint(rect, local);
+}
+/** World position of a resize handle on a single (possibly rotated) frame. */
+function frameHandlePosition(frame, handle) {
+	const rect = frameRect(frame);
+	const position = handlePosition(rect, handle);
+	const rotation = frame.rotation || 0;
+	if (rotation === 0) return position;
+	return rotatePointAround(position, rectCenter(rect), degToRad(rotation));
+}
+/** Corners in clockwise order, following the frame's rotation. */
+function frameCorners(frame) {
+	return [
+		"nw",
+		"ne",
+		"se",
+		"sw"
+	].map((handle) => frameHandlePosition(frame, handle));
+}
+/** Screen-space radius (px) within which a pointer grabs a handle. */
+const HANDLE_HIT_RADIUS = 8;
+/** Screen-space offset (px) from the selection's lower-facing edge. */
+const ROTATION_HANDLE_OFFSET = 28;
+function frameRayIntersection(frame, pointer) {
+	const center = rectCenter(frame);
+	let dx = pointer.x - center.x;
+	let dy = pointer.y - center.y;
+	if (Math.hypot(dx, dy) < 1e-4) {
+		dx = 0;
+		dy = 1;
+	}
+	const rad = degToRad(frame.rotation || 0);
+	const cos = Math.cos(rad);
+	const sin = Math.sin(rad);
+	const localDx = dx * cos + dy * sin;
+	const localDy = -dx * sin + dy * cos;
+	const scaleX = Math.abs(localDx) > 1e-4 ? frame.width / 2 / Math.abs(localDx) : Number.POSITIVE_INFINITY;
+	const scaleY = Math.abs(localDy) > 1e-4 ? frame.height / 2 / Math.abs(localDy) : Number.POSITIVE_INFINITY;
+	const scale = Math.min(scaleX, scaleY);
+	return worldPoint(center.x + dx * scale, center.y + dy * scale);
+}
+function rotationHandleAnchor(frame) {
+	const center = rectCenter(frame);
+	return frameRayIntersection(frame, worldPoint(center.x, center.y + 1));
+}
+function rotationHandlePosition(frame, zoom) {
+	const center = rectCenter(frame);
+	const anchor = rotationHandleAnchor(frame);
+	const offset = 28 / Math.max(zoom, 1e-4);
+	return worldPoint(center.x, anchor.y + offset);
+}
+const CORNER_RESIZE_HANDLES = [
+	"nw",
+	"ne",
+	"se",
+	"sw"
+];
+const EDGE_RESIZE_HANDLES = [
+	"n",
+	"e",
+	"s",
+	"w"
+];
+const RESIZE_HANDLES = [
+	"nw",
+	"n",
+	"ne",
+	"e",
+	"se",
+	"s",
+	"sw",
+	"w"
+];
+/**
+* Hit-test the continuous edge zones of a rotated frame. Corners are inset so
+* their resize handles retain priority even on small nodes.
+*/
+function frameEdgeHandleAt(frame, point, zoom, screenRadius = 8) {
+	const rect = frameRect(frame);
+	const center = rectCenter(rect);
+	const local = frame.rotation ? rotatePointAround(point, center, -degToRad(frame.rotation)) : point;
+	const radius = screenRadius / Math.max(zoom, 1e-4);
+	const insetX = Math.min(rect.width / 3, radius * 1.5);
+	const insetY = Math.min(rect.height / 3, radius * 1.5);
+	let closest = null;
+	let closestDistance = Number.POSITIVE_INFINITY;
+	if (local.x >= rect.x + insetX && local.x <= rect.x + rect.width - insetX) {
+		const north = Math.abs(local.y - rect.y);
+		const south = Math.abs(local.y - (rect.y + rect.height));
+		if (north <= radius && north < closestDistance) {
+			closest = "n";
+			closestDistance = north;
+		}
+		if (south <= radius && south < closestDistance) {
+			closest = "s";
+			closestDistance = south;
+		}
+	}
+	if (local.y >= rect.y + insetY && local.y <= rect.y + rect.height - insetY) {
+		const west = Math.abs(local.x - rect.x);
+		const east = Math.abs(local.x - (rect.x + rect.width));
+		if (west <= radius && west < closestDistance) {
+			closest = "w";
+			closestDistance = west;
+		}
+		if (east <= radius && east < closestDistance) closest = "e";
+	}
+	return closest;
+}
+/** Direction of a handle from the rect center: -1, 0, or 1 per axis. */
+const HANDLE_DIRECTION = {
+	nw: {
+		x: -1,
+		y: -1
+	},
+	n: {
+		x: 0,
+		y: -1
+	},
+	ne: {
+		x: 1,
+		y: -1
+	},
+	e: {
+		x: 1,
+		y: 0
+	},
+	se: {
+		x: 1,
+		y: 1
+	},
+	s: {
+		x: 0,
+		y: 1
+	},
+	sw: {
+		x: -1,
+		y: 1
+	},
+	w: {
+		x: -1,
+		y: 0
+	}
+};
+/** Position of a handle on an unrotated rect. */
+function handlePosition(rect, handle) {
+	const direction = HANDLE_DIRECTION[handle];
+	return worldPoint(rect.x + rect.width / 2 + direction.x * rect.width / 2, rect.y + rect.height / 2 + direction.y * rect.height / 2);
+}
+/** Resize a frame to exact dimensions while keeping the opposite handle fixed. */
+function resizeFrameToSize(frame, handle, width, height) {
+	const direction = HANDLE_DIRECTION[handle];
+	const rect = frameRect(frame);
+	const center = rectCenter(rect);
+	const rad = degToRad(frame.rotation || 0);
+	const anchorLocal = {
+		x: -direction.x * rect.width / 2,
+		y: -direction.y * rect.height / 2
+	};
+	const anchor = rotatePointAround({
+		x: center.x + anchorLocal.x,
+		y: center.y + anchorLocal.y
+	}, center, rad);
+	const centerLocal = {
+		x: direction.x * width / 2,
+		y: direction.y * height / 2
+	};
+	const nextCenter = rotatePointAround({
+		x: anchor.x + centerLocal.x,
+		y: anchor.y + centerLocal.y
+	}, anchor, rad);
+	return {
+		x: nextCenter.x - width / 2,
+		y: nextCenter.y - height / 2,
+		width,
+		height,
+		rotation: frame.rotation || 0
+	};
+}
+/**
+* Resize a frame by dragging a handle to a world-space pointer position.
+* The edge/corner opposite the handle stays anchored. Works correctly for
+* rotated frames by performing the resize in the frame's local space.
+*/
+function resizeFrame(frame, handle, pointer, minSize = 24, keepAspect = false) {
+	const direction = HANDLE_DIRECTION[handle];
+	const rect = frameRect(frame);
+	const center = rectCenter(rect);
+	const rad = degToRad(frame.rotation || 0);
+	const aspect = rect.width / Math.max(rect.height, 1e-4);
+	const anchorLocal = {
+		x: -direction.x * rect.width / 2,
+		y: -direction.y * rect.height / 2
+	};
+	const anchor = rotatePointAround({
+		x: center.x + anchorLocal.x,
+		y: center.y + anchorLocal.y
+	}, center, rad);
+	const toLocal = rotatePointAround(pointer, anchor, -rad);
+	const local = {
+		x: toLocal.x - anchor.x,
+		y: toLocal.y - anchor.y
+	};
+	let width = direction.x !== 0 ? clamp(direction.x * local.x, minSize, Number.POSITIVE_INFINITY) : rect.width;
+	let height = direction.y !== 0 ? clamp(direction.y * local.y, minSize, Number.POSITIVE_INFINITY) : rect.height;
+	if (keepAspect) {
+		if (direction.x !== 0 && direction.y !== 0) if (Math.abs(width / aspect) > height) height = width / aspect;
+		else width = height * aspect;
+		else if (direction.x !== 0) height = width / aspect;
+		else if (direction.y !== 0) width = height * aspect;
+		width = Math.max(minSize, width);
+		height = Math.max(minSize, height);
+	}
+	return resizeFrameToSize(frame, handle, width, height);
+}
+/**
+* Proportionally scale a group of frames by dragging a corner handle of their
+* combined bounds. Individual rotations are preserved.
+*/
+function scaleFrames(frames, bounds, handle, pointer, minSize = 24, scaleRange) {
+	const direction = HANDLE_DIRECTION[handle];
+	if (direction.x === 0 || direction.y === 0) return frames;
+	const anchor = {
+		x: bounds.x + bounds.width / 2 - direction.x * bounds.width / 2,
+		y: bounds.y + bounds.height / 2 - direction.y * bounds.height / 2
+	};
+	const original = handlePosition(bounds, handle);
+	const originalDist = Math.hypot(original.x - anchor.x, original.y - anchor.y);
+	const nextDist = Math.hypot(pointer.x - anchor.x, pointer.y - anchor.y);
+	if (originalDist === 0) return frames;
+	const frameMinScale = frames.reduce((minimum, frame) => Math.max(minimum, minSize / Math.max(1e-4, Math.min(frame.width, frame.height))), 0);
+	const minScale = Math.max(frameMinScale, scaleRange?.min ?? 0);
+	const maxScale = Math.max(minScale, scaleRange?.max ?? Number.POSITIVE_INFINITY);
+	const scale = clamp(nextDist / originalDist, minScale, maxScale);
+	return frames.map((frame) => {
+		const center = rectCenter(frameRect(frame));
+		const nextCenter = {
+			x: anchor.x + (center.x - anchor.x) * scale,
+			y: anchor.y + (center.y - anchor.y) * scale
+		};
+		const width = frame.width * scale;
+		const height = frame.height * scale;
+		return {
+			x: nextCenter.x - width / 2,
+			y: nextCenter.y - height / 2,
+			width,
+			height,
+			rotation: frame.rotation || 0
+		};
+	});
+}
+/** Angle (degrees) from a center to a world-space pointer. */
+function angleFromCenter(center, pointer) {
+	return radToDeg(Math.atan2(pointer.y - center.y, pointer.x - center.x));
+}
+/**
+* Rotate a set of frames around a pivot by a delta (degrees). Each frame's
+* center orbits the pivot and its own rotation increases by the delta.
+*/
+function rotateFrames(frames, pivot, deltaDeg) {
+	const rad = degToRad(deltaDeg);
+	return frames.map((frame) => {
+		const nextCenter = rotatePointAround(rectCenter(frameRect(frame)), pivot, rad);
+		return {
+			x: nextCenter.x - frame.width / 2,
+			y: nextCenter.y - frame.height / 2,
+			width: frame.width,
+			height: frame.height,
+			rotation: (frame.rotation || 0) + deltaDeg
+		};
+	});
+}
+/** Normalize a rotation into the [-180, 180] range for tidy persistence. */
+function normalizeRotation(degrees) {
+	let value = degrees % 360;
+	if (value > 180) value -= 360;
+	if (value < -180) value += 360;
+	return Math.abs(value) < .01 ? 0 : value;
+}
+/** Convert a surface-relative screen point into world space. */
+function pointToWorld(point, viewport) {
+	return worldPoint((point.x - viewport.x) / viewport.zoom, (point.y - viewport.y) / viewport.zoom);
+}
+function worldToScreen(point, viewport) {
+	return screenPoint(point.x * viewport.zoom + viewport.x, point.y * viewport.zoom + viewport.y);
+}
+function screenToWorld(clientX, clientY, rect, viewport) {
+	return pointToWorld(screenPoint(clientX - rect.left, clientY - rect.top), viewport);
+}
+/** Zoom while keeping a surface-relative screen point fixed under the cursor. */
+function zoomAround(viewport, anchor, nextZoom) {
+	const current = normalizeViewport(viewport);
+	const zoom = Number.isFinite(nextZoom) ? clampZoom(nextZoom) : current.zoom;
+	const world = pointToWorld(anchor, current);
+	return {
+		x: anchor.x - world.x * zoom,
+		y: anchor.y - world.y * zoom,
+		zoom
+	};
+}
+function panBy(viewport, dx, dy) {
+	return {
+		...viewport,
+		x: viewport.x + dx,
+		y: viewport.y + dy
+	};
+}
+/** Compute a viewport that frames the given world rect within the surface. */
+function fitToContent(content, surface, padding = 64) {
+	const availableW = Math.max(1, surface.width - padding * 2);
+	const availableH = Math.max(1, surface.height - padding * 2);
+	const zoom = clampZoom(Math.min(availableW / content.width, availableH / content.height));
+	return {
+		x: surface.width / 2 - (content.x + content.width / 2) * zoom,
+		y: surface.height / 2 - (content.y + content.height / 2) * zoom,
+		zoom
+	};
+}
+/** World-space rectangle currently visible in the board stage. */
+function visibleWorldRect(viewport, surfaceWidth, surfaceHeight) {
+	const width = Math.max(0, surfaceWidth);
+	const height = Math.max(0, surfaceHeight);
+	const zoom = viewport.zoom || 1;
+	return {
+		x: -viewport.x / zoom,
+		y: -viewport.y / zoom,
+		width: width / zoom,
+		height: height / zoom
+	};
+}
+//#endregion
+export { CORNER_RESIZE_HANDLES, EDGE_RESIZE_HANDLES, FIT_PADDING, HANDLE_DIRECTION, HANDLE_HIT_RADIUS, MAX_BOARD_ZOOM, MIN_BOARD_ZOOM, MIN_ITEM_SIZE, RESIZE_HANDLES, ROTATION_HANDLE_OFFSET, VIEWPORT_MARGIN_RATIO, angleFromCenter, clamp, clampZoom, degToRad, expandRect, fitToContent, frameContainsPoint, frameCorners, frameEdgeHandleAt, frameHandlePosition, frameRayIntersection, frameRect, handlePosition, itemBounds, normalizeRotation, normalizeViewport, panBy, pointToWorld, radToDeg, rectCenter, rectContainsPoint, rectsIntersect, resizeFrame, resizeFrameToSize, rotateFrames, rotatePointAround, rotationHandleAnchor, rotationHandlePosition, scaleFrames, screenPoint, screenToWorld, selectionBounds, unionRects, visibleWorldRect, worldPoint, worldToScreen, zoomAround };

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

@@ -0,0 +1,69 @@
+import { BoardDocument } from "../../protocol/dist/board-document.js";
+import { BoardExportOptions, BoardExportResult } from "../export/index.js";
+import { Renderer } from "pixi.js";
+//#region src/board/headless/index.d.ts
+type HeadlessCanvasModule = {
+  createCanvas: (width: number, height: number) => unknown;
+  Image: new () => unknown;
+  GlobalFonts: {
+    registerFromPath: (path: string, name?: string) => unknown;
+    has: (name: string) => boolean;
+  };
+};
+type BoardHeadlessFont = {
+  /** Absolute path to a font file (woff2, ttf and otf all work). */
+  path: string;
+  /** Family name renderers should ask for. Defaults to the board text family. */
+  family?: string;
+};
+type BoardHeadlessRendererOptions = {
+  /**
+   * Fonts to register before the first measurement. Board text asks for
+   * "Geist"; without a matching family the platform substitutes one, which
+   * changes glyph shapes and text metrics.
+   */
+  fonts?: BoardHeadlessFont[];
+  /** Override the canvas module (tests, or a pre-imported instance). */
+  canvasModule?: HeadlessCanvasModule;
+};
+/**
+ * A decoded image, opaque to callers.
+ *
+ * Node consumers (the CLI) should not need PixiJS in their own type surface just
+ * to hand textures back to the exporter, so the concrete `Texture` stays inside
+ * this module.
+ */
+type BoardHeadlessTexture = {
+  readonly __boardTexture: unique symbol;
+};
+type BoardHeadlessRenderer = {
+  renderer: Renderer;
+  canvasModule: HeadlessCanvasModule;
+  /** Decode image bytes into a texture the exporter accepts. */
+  decodeImage: (bytes: Uint8Array, mimeType?: string) => Promise<BoardHeadlessTexture>;
+  destroy: () => void;
+};
+/**
+ * Create a Canvas2D renderer backed by Skia.
+ *
+ * `skipExtensionImports` is essential: it stops Pixi from auto-loading its
+ * browser environment bundle, which would pull in DOM-only pipes.
+ */
+declare function createBoardHeadlessRenderer(options?: BoardHeadlessRendererOptions): Promise<BoardHeadlessRenderer>;
+type BoardHeadlessExportFormat = "png" | "jpeg" | "webp";
+type BoardHeadlessExportOptions = Omit<BoardExportOptions, "textures"> & {
+  /** Textures from `decodeImage`, keyed by image key. */
+  textures?: Map<string, BoardHeadlessTexture>;
+  format?: BoardHeadlessExportFormat;
+  /** JPEG/WebP quality, 0–1. Ignored for PNG. */
+  quality?: number;
+};
+type BoardHeadlessExportResult = Omit<BoardExportResult, "canvas"> & {
+  bytes: Uint8Array;
+  format: BoardHeadlessExportFormat;
+};
+declare function boardHeadlessMimeType(format: BoardHeadlessExportFormat): string;
+/** Render a document to encoded image bytes. Returns null for an empty region. */
+declare function exportBoardImageBytes(headless: BoardHeadlessRenderer, document: BoardDocument, options?: BoardHeadlessExportOptions): BoardHeadlessExportResult | null;
+//#endregion
+export { BoardHeadlessExportFormat, BoardHeadlessExportOptions, BoardHeadlessExportResult, BoardHeadlessFont, BoardHeadlessRenderer, BoardHeadlessRendererOptions, BoardHeadlessTexture, HeadlessCanvasModule, boardHeadlessMimeType, createBoardHeadlessRenderer, exportBoardImageBytes };

package/dist/board/headless/index.js

@@ -0,0 +1,150 @@
+import "../../protocol/dist/board-constants.js";
+import { installBoardTextMeasurement } from "../render/text-measurement.js";
+import { renderBoardExport } from "../export/index.js";
+//#region src/board/headless/index.ts
+/**
+* A minimal WebGL stand-in.
+*
+* `ParticleContainerPipe` builds a `GlProgram` when the renderer registers its
+* pipes, and that probes shader precision through a throwaway context — even
+* though the Canvas2D backend never draws with it. Returning a stub keeps
+* registration working; nothing here is ever used to render.
+*/
+const WEBGL_PROBE_STUB = {
+	getShaderPrecisionFormat: () => ({
+		precision: 1,
+		rangeMin: 1,
+		rangeMax: 1
+	}),
+	getExtension: () => null,
+	getParameter: () => 0
+};
+function isWebGLContext(kind) {
+	return kind.startsWith("webgl") || kind === "experimental-webgl";
+}
+async function loadCanvasModule() {
+	try {
+		return await import("@napi-rs/canvas");
+	} catch (cause) {
+		throw new Error("Board image export needs the optional '@napi-rs/canvas' package. Install it with: npm i @napi-rs/canvas", { cause });
+	}
+}
+/** Node has no rAF; Pixi's scheduler only needs a callback pump. */
+function installAnimationFrameShim() {
+	const globals = globalThis;
+	if (globals.requestAnimationFrame) return () => {};
+	const timers = /* @__PURE__ */ new Set();
+	globals.requestAnimationFrame = (cb) => {
+		const timer = setTimeout(() => {
+			timers.delete(timer);
+			cb(Date.now());
+		}, 16);
+		timer.unref?.();
+		timers.add(timer);
+		return timer;
+	};
+	globals.cancelAnimationFrame = (id) => {
+		clearTimeout(id);
+		timers.delete(id);
+	};
+	return () => {
+		for (const timer of timers) clearTimeout(timer);
+		timers.clear();
+		globals.requestAnimationFrame = void 0;
+		globals.cancelAnimationFrame = void 0;
+	};
+}
+/**
+* Create a Canvas2D renderer backed by Skia.
+*
+* `skipExtensionImports` is essential: it stops Pixi from auto-loading its
+* browser environment bundle, which would pull in DOM-only pipes.
+*/
+async function createBoardHeadlessRenderer(options = {}) {
+	const canvasModule = options.canvasModule ?? await loadCanvasModule();
+	const { CanvasGraphicsContextSystem, CanvasGraphicsPipe, CanvasRenderer, CanvasRendererTextSystem, CanvasTextPipe, CanvasTextSystem, DOMAdapter, extensions, GraphicsContextSystem, GraphicsPipe, ImageSource, Texture } = await import("pixi.js");
+	extensions.add(CanvasGraphicsPipe, GraphicsPipe, CanvasGraphicsContextSystem, GraphicsContextSystem, CanvasRendererTextSystem, CanvasTextSystem, CanvasTextPipe);
+	for (const font of options.fonts ?? []) canvasModule.GlobalFonts.registerFromPath(font.path, font.family ?? "Geist");
+	function createCanvas(width = 1, height = 1) {
+		const canvas = canvasModule.createCanvas(Math.max(1, Math.ceil(width)), Math.max(1, Math.ceil(height)));
+		const nativeGetContext = canvas.getContext.bind(canvas);
+		canvas.getContext = (kind, ...rest) => isWebGLContext(String(kind)) ? WEBGL_PROBE_STUB : nativeGetContext(kind, ...rest);
+		return canvas;
+	}
+	DOMAdapter.set({
+		createCanvas: (width, height) => createCanvas(width, height),
+		createImage: () => new canvasModule.Image(),
+		getCanvasRenderingContext2D: () => createCanvas(1, 1).getContext("2d").constructor,
+		getWebGLRenderingContext: () => WEBGL_PROBE_STUB,
+		getNavigator: () => ({
+			userAgent: "cohub-board-headless",
+			gpu: null
+		}),
+		getBaseUrl: () => "file://",
+		getFontFaceSet: () => null,
+		fetch: (url, init) => fetch(url, init),
+		parseXML: () => {
+			throw new Error("XML parsing is not available in headless board export.");
+		}
+	});
+	installBoardTextMeasurement();
+	const restoreAnimationFrame = installAnimationFrameShim();
+	const renderer = new CanvasRenderer();
+	await renderer.init({
+		width: 1,
+		height: 1,
+		backgroundAlpha: 0,
+		antialias: true,
+		resolution: 1,
+		skipExtensionImports: true
+	});
+	return {
+		renderer,
+		canvasModule,
+		decodeImage: async (bytes, mimeType = "image/png") => {
+			const image = new canvasModule.Image();
+			const base64 = Buffer.from(bytes).toString("base64");
+			await new Promise((resolve, reject) => {
+				image.onload = () => resolve();
+				image.onerror = (error) => reject(error);
+				image.src = `data:${mimeType};base64,${base64}`;
+			});
+			return new Texture({ source: new ImageSource({
+				resource: image,
+				width: image.width,
+				height: image.height
+			}) });
+		},
+		destroy: () => {
+			renderer.destroy();
+			restoreAnimationFrame();
+		}
+	};
+}
+const MIME = {
+	png: "image/png",
+	jpeg: "image/jpeg",
+	webp: "image/webp"
+};
+function boardHeadlessMimeType(format) {
+	return MIME[format];
+}
+/** Render a document to encoded image bytes. Returns null for an empty region. */
+function exportBoardImageBytes(headless, document, options = {}) {
+	const { format = "png", quality = .92, textures, ...rest } = options;
+	const result = renderBoardExport(headless.renderer, document, {
+		...rest,
+		...textures ? { textures } : {}
+	});
+	if (!result) return null;
+	const canvas = result.canvas;
+	const bytes = format === "png" ? canvas.toBuffer(MIME.png) : canvas.toBuffer(MIME[format], Math.round(quality * 100));
+	return {
+		bytes: new Uint8Array(bytes),
+		plan: result.plan,
+		warnings: result.warnings,
+		format
+	};
+}
+//#endregion
+export { boardHeadlessMimeType, createBoardHeadlessRenderer, exportBoardImageBytes };

package/dist/board/image-key.d.ts

@@ -0,0 +1,19 @@
+import { BoardItem } from "../protocol/dist/board-document.js";
+//#region src/board/image-key.d.ts
+/**
+ * Stable cache key for an item's image resource, or null when it has none.
+ *
+ * Space files and remote URLs are namespaced so they can never collide, and file
+ * cards contribute their cover image — which means covers ride the exact same
+ * reference counting, LRU cooling pool and viewport preloading as image nodes,
+ * with no second loader to keep in step. The exporter resolves the same keys, so
+ * an exported card shows the same picture the editor does.
+ */
+declare function imageAssetKey(item: BoardItem): string | null;
+/** The source a key resolves from, recovered from its namespace prefix. */
+declare function boardImageKeySource(key: string): {
+  kind: "file" | "url";
+  value: string;
+} | null;
+//#endregion
+export { boardImageKeySource, imageAssetKey };