@neta-art/cohub 3.1.0 → 4.0.0

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

@@ -0,0 +1,138 @@
+import { drawFarPlate } from "./far-plate.js";
+import { positionShell } from "./base-card-renderer.js";
+import { Container, Graphics, Sprite, Texture } from "pixi.js";
+//#region src/board/render/renderers/image-card-renderer.ts
+const partsByContainer = /* @__PURE__ */ new WeakMap();
+const RADIUS = 2;
+/**
+* Lay the sprite out inside the frame.
+*
+* The frame normally already matches the image's pixel aspect (see the editor's
+* media size adoption), so this fills it exactly. Until that correction lands
+* for a freshly dropped file, `contain` keeps the whole image visible rather
+* than cropping it — the brief letterbox is self-correcting.
+*/
+function layoutContain(sprite, width, height) {
+	const texture = sprite.texture;
+	const tw = texture.width;
+	const th = texture.height;
+	if (!tw || !th) return;
+	const scale = Math.min(width / tw, height / th);
+	sprite.width = tw * scale;
+	sprite.height = th * scale;
+	sprite.x = (width - sprite.width) / 2;
+	sprite.y = (height - sprite.height) / 2;
+}
+function sync(container, item, context) {
+	const parts = partsByContainer.get(container);
+	if (!parts) return;
+	positionShell(parts.root, item);
+	const { width, height } = item.frame;
+	const selected = context.selectedIds.has(item.id);
+	const hovered = context.hoveredId === item.id;
+	const key = context.assetKey(item);
+	const texture = key ? context.getTexture(key) : null;
+	const failed = Boolean(key && !texture && context.hasError(key));
+	const texId = texture ? `${texture.width}x${texture.height}` : "none";
+	const sig = [
+		key ?? "",
+		width,
+		height,
+		selected,
+		hovered,
+		texId,
+		failed,
+		context.colorScheme
+	].join("|");
+	if (sig === parts.sig) return;
+	parts.sig = sig;
+	if (texture && parts.sprite.texture !== texture) parts.sprite.texture = texture;
+	parts.sprite.visible = Boolean(texture);
+	if (texture) layoutContain(parts.sprite, width, height);
+	parts.placeholder.clear();
+	if (!texture) {
+		parts.placeholder.roundRect(0, 0, width, height, RADIUS).fill({
+			color: context.palette.surface,
+			alpha: .85
+		}).roundRect(0, 0, width, height, RADIUS).stroke({
+			color: failed ? context.palette.border : context.palette.hover,
+			width: 1,
+			alpha: .9
+		});
+		const cx = width / 2;
+		const cy = height / 2;
+		if (failed) parts.placeholder.moveTo(cx - 10, cy - 10).lineTo(cx + 10, cy + 10).moveTo(cx + 10, cy - 10).lineTo(cx - 10, cy + 10).stroke({
+			color: context.palette.muted,
+			width: 1.5,
+			alpha: .8
+		});
+		else parts.placeholder.circle(cx, cy, 6).stroke({
+			color: context.palette.muted,
+			width: 1.25,
+			alpha: .55
+		});
+	}
+	parts.placeholder.visible = !texture;
+	if (selected || hovered) {
+		const hasPixels = Boolean(texture) && parts.sprite.width > 0;
+		const ox = hasPixels ? parts.sprite.x : 0;
+		const oy = hasPixels ? parts.sprite.y : 0;
+		const ow = hasPixels ? parts.sprite.width : width;
+		const oh = hasPixels ? parts.sprite.height : height;
+		parts.placeholder.visible = true;
+		parts.placeholder.roundRect(ox, oy, ow, oh, RADIUS).stroke({
+			color: selected ? context.palette.brand : context.palette.muted,
+			width: selected ? 2 : 1,
+			alpha: selected ? .95 : .7
+		});
+	}
+}
+const imageCardRenderer = {
+	id: "image-card",
+	canRender: (item) => item.type === "image",
+	create: (item, context) => {
+		const root = new Container();
+		const sprite = new Sprite(Texture.EMPTY);
+		const placeholder = new Graphics();
+		const mask = new Graphics();
+		const maskBox = () => {
+			mask.clear();
+			if (item.type === "image") mask.roundRect(0, 0, item.frame.width, item.frame.height, RADIUS).fill({ color: 16777215 });
+		};
+		maskBox();
+		root.addChild(placeholder, sprite, mask);
+		sprite.mask = mask;
+		partsByContainer.set(root, {
+			root,
+			sprite,
+			placeholder,
+			sig: ""
+		});
+		if (item.type === "image") sync(root, item, context);
+		return root;
+	},
+	update: (container, item, context) => {
+		if (item.type !== "image") return;
+		const parts = partsByContainer.get(container);
+		if (!parts) return;
+		const mask = parts.root.children.find((child) => child !== parts.sprite && child !== parts.placeholder);
+		if (mask) mask.clear().roundRect(0, 0, item.frame.width, item.frame.height, RADIUS).fill({ color: 16777215 });
+		sync(container, item, context);
+	},
+	renderFar: (graphics, item, context) => {
+		drawFarPlate(graphics, item.frame, {
+			fill: context.palette.hover,
+			fillAlpha: .9
+		});
+	},
+	destroy: (container) => {
+		partsByContainer.get(container)?.root.destroy({ children: true });
+		partsByContainer.delete(container);
+	}
+};
+/** Helper kept for type narrowing in tests. */
+function isImageItem(item) {
+	return item.type === "image";
+}
+//#endregion
+export { imageCardRenderer, isImageItem };

package/dist/board/render/renderers/text-card-renderer.d.ts

@@ -0,0 +1,7 @@
+import { BoardItem, BoardTextItem } from "../../../protocol/dist/board-document.js";
+import { BoardCardRenderer } from "./board-renderer-registry.js";
+//#region src/board/render/renderers/text-card-renderer.d.ts
+declare const textCardRenderer: BoardCardRenderer;
+declare function isTextItem(item: BoardItem): item is BoardTextItem;
+//#endregion
+export { isTextItem, textCardRenderer };

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

@@ -0,0 +1,94 @@
+import { BOARD_FONT_STACK } from "../../../protocol/dist/board-constants.js";
+import { TEXT_FONT_SIZE, boardTextLineHeight, clampBoardTextFontSize, measureBoardText } from "../../core/text-metrics.js";
+import { pickBoardColor } from "../../core/palette.js";
+import { syncTextResolution, textResolutionForZoom } from "../text-resolution.js";
+import { drawFarPlate } from "./far-plate.js";
+import { positionShell } from "./base-card-renderer.js";
+import { Container, Text } from "pixi.js";
+//#region src/board/render/renderers/text-card-renderer.ts
+const partsByContainer = /* @__PURE__ */ new WeakMap();
+function sync(container, item, context) {
+	const parts = partsByContainer.get(container);
+	if (!parts) return;
+	positionShell(parts.root, item);
+	const fontSize = clampBoardTextFontSize(item.fontSize);
+	const measured = measureBoardText(item.text, fontSize);
+	const previewScale = Math.max(1e-4, item.frame.width / Math.max(1e-4, measured.width));
+	parts.body.scale.set(previewScale);
+	parts.body.position.set(item.frame.width / 2, item.frame.height / 2);
+	syncTextResolution(parts.body, parts, context.zoom * Math.max(1, previewScale));
+	const color = pickBoardColor(context.colors, item.color || "neutral", context.colorScheme);
+	const ink = item.color === "neutral" || !item.color ? context.palette.text : color.stroke;
+	const contentSig = [
+		item.text,
+		item.color,
+		fontSize,
+		context.colorScheme,
+		context.colors.brand.stroke,
+		context.palette.text
+	].join("|");
+	if (contentSig === parts.contentSig) return;
+	parts.contentSig = contentSig;
+	if (parts.body.text !== item.text) parts.body.text = item.text || "";
+	parts.body.style.fill = ink;
+	parts.body.style.fontSize = fontSize;
+	parts.body.style.lineHeight = boardTextLineHeight(fontSize);
+}
+const textCardRenderer = {
+	id: "text-card",
+	canRender: (item) => item.type === "text",
+	create: (item, context) => {
+		const root = new Container();
+		const resolution = textResolutionForZoom(context.zoom);
+		const color = pickBoardColor(context.colors, item.type === "text" ? item.color || "neutral" : "neutral", context.colorScheme);
+		const body = new Text({
+			text: "",
+			style: {
+				fill: item.type === "text" && (item.color === "neutral" || !item.color) ? context.palette.text : color.stroke,
+				fontFamily: BOARD_FONT_STACK,
+				fontSize: TEXT_FONT_SIZE,
+				fontWeight: "500",
+				lineHeight: boardTextLineHeight(TEXT_FONT_SIZE),
+				wordWrap: false
+			},
+			resolution,
+			roundPixels: true
+		});
+		body.anchor.set(.5);
+		root.addChild(body);
+		partsByContainer.set(root, {
+			root,
+			body,
+			resolution,
+			contentSig: ""
+		});
+		if (item.type === "text") sync(root, item, context);
+		return root;
+	},
+	update: (container, item, context) => {
+		if (item.type === "text") sync(container, item, context);
+	},
+	/**
+	* Far LOD: a low-alpha ink bar. Body text is well under a pixel tall at these
+	* zooms, so a rasterised glyph texture would only ever resolve to a smudge —
+	* this approximates that smudge for free and skips the texture entirely.
+	*/
+	renderFar: (graphics, item, context) => {
+		if (item.type !== "text") return;
+		const color = pickBoardColor(context.colors, item.color || "neutral", context.colorScheme);
+		const ink = item.color === "neutral" || !item.color ? context.palette.text : color.stroke;
+		drawFarPlate(graphics, item.frame, {
+			fill: ink,
+			fillAlpha: .35
+		});
+	},
+	destroy: (container) => {
+		partsByContainer.get(container)?.root.destroy({ children: true });
+		partsByContainer.delete(container);
+	}
+};
+function isTextItem(item) {
+	return item.type === "text";
+}
+//#endregion
+export { isTextItem, textCardRenderer };

package/dist/board/render/renderers/unknown-card-renderer.d.ts

@@ -0,0 +1,5 @@
+import { BoardCardRenderer } from "./board-renderer-registry.js";
+//#region src/board/render/renderers/unknown-card-renderer.d.ts
+declare const unknownCardRenderer: BoardCardRenderer;
+//#endregion
+export { unknownCardRenderer };

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

@@ -0,0 +1,102 @@
+import { BOARD_MONO_FONT_STACK } from "../../../protocol/dist/board-constants.js";
+import { unknownRealType } from "../../../protocol/dist/board-document.js";
+import { syncTextResolution, textResolutionForZoom } from "../text-resolution.js";
+import { drawFarPlate } from "./far-plate.js";
+import { positionShell } from "./base-card-renderer.js";
+import { Container, Graphics, Text } from "pixi.js";
+//#region src/board/render/renderers/unknown-card-renderer.ts
+const RADIUS = 10;
+const partsByContainer = /* @__PURE__ */ new WeakMap();
+/**
+* Neutral placeholder for shape types this client does not recognise. The shape
+* stays fully interactive (select/move/resize via the generic box definition) and
+* its data is preserved elsewhere — this is only its display.
+*/
+function sync(container, item, context) {
+	const parts = partsByContainer.get(container);
+	if (!parts) return;
+	positionShell(parts.root, item);
+	const { width, height } = item.frame;
+	const selected = context.selectedIds.has(item.id);
+	const realType = unknownRealType(item);
+	syncTextResolution(parts.label, parts, context.zoom);
+	const visualSig = [
+		width,
+		height,
+		selected,
+		context.palette.surface,
+		context.palette.brand,
+		context.palette.border,
+		context.palette.muted
+	].join("|");
+	if (visualSig !== parts.visualSig) {
+		parts.visualSig = visualSig;
+		parts.box.clear();
+		parts.box.roundRect(0, 0, width, height, RADIUS).fill({
+			color: context.palette.surface,
+			alpha: .7
+		}).roundRect(0, 0, width, height, RADIUS).stroke({
+			color: selected ? context.palette.brand : context.palette.border,
+			width: selected ? 2 : 1,
+			alpha: .8
+		});
+		parts.box.roundRect(6, 6, width - 12, height - 12, RADIUS - 4).stroke({
+			color: context.palette.muted,
+			width: 1,
+			alpha: .4
+		});
+	}
+	const textSig = [realType, context.palette.muted].join("|");
+	if (textSig !== parts.textSig) {
+		parts.textSig = textSig;
+		parts.label.text = realType;
+		parts.label.style.fill = context.palette.muted;
+	}
+	parts.label.position.set(width / 2, height / 2);
+}
+const unknownCardRenderer = {
+	id: "unknown-card",
+	canRender: (item) => "raw" in item,
+	create: (item, context) => {
+		const root = new Container();
+		const box = new Graphics();
+		const resolution = textResolutionForZoom(context.zoom);
+		const label = new Text({
+			text: "",
+			style: {
+				fontFamily: BOARD_MONO_FONT_STACK,
+				fontSize: 11,
+				fontWeight: "600"
+			},
+			resolution,
+			roundPixels: true
+		});
+		label.anchor.set(.5);
+		root.addChild(box, label);
+		partsByContainer.set(root, {
+			root,
+			box,
+			label,
+			visualSig: "",
+			textSig: "",
+			resolution
+		});
+		if ("raw" in item) sync(root, item, context);
+		return root;
+	},
+	update: (container, item, context) => {
+		if ("raw" in item) sync(container, item, context);
+	},
+	renderFar: (graphics, item, context) => {
+		drawFarPlate(graphics, item.frame, {
+			fill: context.palette.muted,
+			fillAlpha: .2
+		});
+	},
+	destroy: (container) => {
+		partsByContainer.get(container)?.root.destroy({ children: true });
+		partsByContainer.delete(container);
+	}
+};
+//#endregion
+export { unknownCardRenderer };

package/dist/board/render/renderers/video-card-renderer.d.ts

@@ -0,0 +1,7 @@
+import { BoardItem, BoardVideoItem } from "../../../protocol/dist/board-document.js";
+import { BoardCardRenderer } from "./board-renderer-registry.js";
+//#region src/board/render/renderers/video-card-renderer.d.ts
+declare const videoCardRenderer: BoardCardRenderer;
+declare function isVideoItem(item: BoardItem): item is BoardVideoItem;
+//#endregion
+export { isVideoItem, videoCardRenderer };

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

@@ -0,0 +1,146 @@
+import { BOARD_FONT_STACK } from "../../../protocol/dist/board-constants.js";
+import { syncTextResolution, syncTextWrapWidth, textResolutionForZoom } from "../text-resolution.js";
+import { drawFarPlate } from "./far-plate.js";
+import { positionShell } from "./base-card-renderer.js";
+import { Container, Graphics, Sprite, Text, Texture } from "pixi.js";
+//#region src/board/render/renderers/video-card-renderer.ts
+const partsByContainer = /* @__PURE__ */ new WeakMap();
+const RADIUS = 4;
+function layoutContain(sprite, width, height) {
+	const texture = sprite.texture;
+	if (!texture.width || !texture.height) return;
+	const scale = Math.min(width / texture.width, height / texture.height);
+	sprite.width = texture.width * scale;
+	sprite.height = texture.height * scale;
+	sprite.x = (width - sprite.width) / 2;
+	sprite.y = (height - sprite.height) / 2;
+}
+function sync(container, item, context) {
+	const parts = partsByContainer.get(container);
+	if (!parts) return;
+	positionShell(parts.root, item);
+	const { width, height } = item.frame;
+	const selected = context.selectedIds.has(item.id);
+	const hovered = context.hoveredId === item.id;
+	const resizing = context.resizingIds.has(item.id);
+	const title = item.snapshot?.title ?? item.ref.path.split("/").pop() ?? "Video";
+	const key = context.assetKey(item);
+	const texture = key ? context.getTexture(key) : null;
+	const failed = Boolean(key && !texture && context.hasError(key));
+	syncTextResolution(parts.label, parts, context.zoom);
+	if (parts.label.text !== title) parts.label.text = title;
+	syncTextWrapWidth(parts.label, parts, Math.max(1, width - 16), resizing);
+	parts.label.position.set(8, Math.max(8, height - parts.label.height - 8));
+	const sig = [
+		key ?? "",
+		texture ? `${texture.width}x${texture.height}` : "none",
+		width,
+		height,
+		selected,
+		hovered,
+		failed,
+		title,
+		parts.label.height,
+		context.palette.surface,
+		context.palette.brand,
+		context.palette.muted,
+		context.palette.border,
+		context.palette.hover,
+		context.palette.text
+	].join("|");
+	if (sig === parts.sig) return;
+	parts.sig = sig;
+	if (texture && parts.sprite.texture !== texture) parts.sprite.texture = texture;
+	parts.sprite.visible = Boolean(texture);
+	if (texture) layoutContain(parts.sprite, width, height);
+	parts.mask.clear().roundRect(0, 0, width, height, RADIUS).fill({ color: 16777215 });
+	parts.plate.clear().roundRect(0, 0, width, height, RADIUS).fill({
+		color: context.palette.surface,
+		alpha: .96
+	});
+	parts.chrome.clear();
+	if (texture) {
+		const bandHeight = Math.min(height, parts.label.height + 16);
+		parts.chrome.rect(0, height - bandHeight, width, bandHeight).fill({
+			color: context.palette.surface,
+			alpha: .78
+		});
+	}
+	const cx = width / 2;
+	const cy = height / 2;
+	const radius = Math.min(22, Math.min(width, height) * .18);
+	parts.chrome.circle(cx, cy, radius).fill({
+		color: selected ? context.palette.brand : context.palette.surface,
+		alpha: texture ? .88 : .96
+	});
+	const triangle = radius * .55;
+	parts.chrome.moveTo(cx - triangle * .35, cy - triangle * .6).lineTo(cx - triangle * .35, cy + triangle * .6).lineTo(cx + triangle * .7, cy).closePath().fill({
+		color: context.palette.text,
+		alpha: .94
+	});
+	parts.chrome.roundRect(0, 0, width, height, RADIUS).stroke({
+		color: selected ? context.palette.brand : hovered ? context.palette.muted : context.palette.border,
+		width: selected ? 2 : 1,
+		alpha: selected ? .95 : .85
+	});
+	parts.label.style.fill = texture ? context.palette.text : context.palette.muted;
+}
+const videoCardRenderer = {
+	id: "video-card",
+	canRender: (item) => item.type === "video",
+	create: (item, context) => {
+		const root = new Container();
+		const plate = new Graphics();
+		const sprite = new Sprite(Texture.EMPTY);
+		const mask = new Graphics();
+		const chrome = new Graphics();
+		const resolution = textResolutionForZoom(context.zoom);
+		const label = new Text({
+			text: "",
+			style: {
+				fill: context.palette.muted,
+				fontFamily: BOARD_FONT_STACK,
+				fontSize: 12,
+				fontWeight: "500",
+				wordWrap: true
+			},
+			resolution,
+			roundPixels: true
+		});
+		root.addChild(plate, sprite, mask, chrome, label);
+		sprite.mask = mask;
+		partsByContainer.set(root, {
+			root,
+			plate,
+			sprite,
+			mask,
+			chrome,
+			label,
+			sig: "",
+			wrapWidth: 0,
+			resolution
+		});
+		if (item.type === "video") sync(root, item, context);
+		return root;
+	},
+	update: (container, item, context) => {
+		if (item.type === "video") sync(container, item, context);
+	},
+	renderFar: (graphics, item, context) => {
+		drawFarPlate(graphics, item.frame, {
+			fill: context.palette.surface,
+			fillAlpha: .96,
+			accent: context.palette.brand,
+			accentAlpha: .75
+		});
+	},
+	destroy: (container) => {
+		partsByContainer.get(container)?.root.destroy({ children: true });
+		partsByContainer.delete(container);
+	}
+};
+function isVideoItem(item) {
+	return item.type === "video";
+}
+//#endregion
+export { isVideoItem, videoCardRenderer };

package/dist/board/render/text-measurement.d.ts

@@ -0,0 +1,30 @@
+//#region src/board/render/text-measurement.d.ts
+/**
+ * Canvas-backed text measurement.
+ *
+ * Measurement goes through Pixi's `DOMAdapter` rather than `document`, so the
+ * browser and a headless export produce the same numbers. The core metrics
+ * module owns the layout maths and only borrows this measurer, which is what
+ * lets `@neta-art/cohub/board` lay text out with no PixiJS installed.
+ */
+/**
+ * Route board text measurement through the active Pixi DOM adapter.
+ *
+ * Call this after swapping the adapter (see `../headless`), which drops the
+ * cached measuring context. Anything that goes through `getBoardCardRenderer`
+ * is already covered by `ensureBoardTextMeasurement`.
+ */
+declare function installBoardTextMeasurement(): void;
+/**
+ * Install the canvas measurer once, unless it already is.
+ *
+ * The core metrics module falls back to a per-character estimate when no
+ * measurer is set, which is off by ~90% for real text — wrong enough to
+ * misplace every label. Rather than make that a step consumers can forget, the
+ * renderer registry calls this before handing a renderer out. It cannot be an
+ * import-time side effect: the package is marked side-effect free, so a bundler
+ * is entitled to drop a module whose only job happens at load time.
+ */
+declare function ensureBoardTextMeasurement(): void;
+//#endregion
+export { ensureBoardTextMeasurement, installBoardTextMeasurement };

package/dist/board/render/text-measurement.js

@@ -0,0 +1,57 @@
+import { BOARD_FONT_STACK } from "../../protocol/dist/board-constants.js";
+import { setBoardTextMeasurer } from "../core/text-metrics.js";
+import { DOMAdapter } from "pixi.js";
+//#region src/board/render/text-measurement.ts
+/**
+* Canvas-backed text measurement.
+*
+* Measurement goes through Pixi's `DOMAdapter` rather than `document`, so the
+* browser and a headless export produce the same numbers. The core metrics
+* module owns the layout maths and only borrows this measurer, which is what
+* lets `@neta-art/cohub/board` lay text out with no PixiJS installed.
+*/
+let measureContext;
+let installed = false;
+function getMeasureContext() {
+	if (measureContext !== void 0) return measureContext;
+	try {
+		measureContext = DOMAdapter.get().createCanvas(1, 1).getContext("2d") ?? null;
+	} catch {
+		measureContext = null;
+	}
+	return measureContext;
+}
+function measureText(text, fontSize) {
+	const context = getMeasureContext();
+	if (!context) return null;
+	context.font = `500 ${fontSize}px ${BOARD_FONT_STACK}`;
+	return context.measureText(text).width;
+}
+/**
+* Route board text measurement through the active Pixi DOM adapter.
+*
+* Call this after swapping the adapter (see `../headless`), which drops the
+* cached measuring context. Anything that goes through `getBoardCardRenderer`
+* is already covered by `ensureBoardTextMeasurement`.
+*/
+function installBoardTextMeasurement() {
+	measureContext = void 0;
+	installed = true;
+	setBoardTextMeasurer(measureText);
+}
+/**
+* Install the canvas measurer once, unless it already is.
+*
+* The core metrics module falls back to a per-character estimate when no
+* measurer is set, which is off by ~90% for real text — wrong enough to
+* misplace every label. Rather than make that a step consumers can forget, the
+* renderer registry calls this before handing a renderer out. It cannot be an
+* import-time side effect: the package is marked side-effect free, so a bundler
+* is entitled to drop a module whose only job happens at load time.
+*/
+function ensureBoardTextMeasurement() {
+	if (installed) return;
+	installBoardTextMeasurement();
+}
+//#endregion
+export { ensureBoardTextMeasurement, installBoardTextMeasurement };

package/dist/board/render/text-resolution.d.ts

@@ -0,0 +1,16 @@
+import { Text } from "pixi.js";
+//#region src/board/render/text-resolution.d.ts
+declare function getBoardResolution(): number;
+declare function textZoomBucket(zoom: number): number;
+/** Effective text resolution for a given camera zoom. */
+declare function textResolutionForZoom(zoom: number): number;
+/** Update a Pixi text texture only when zoom crosses a resolution bucket. */
+declare function syncTextResolution(text: Text, state: {
+  resolution: number;
+}, zoom: number): void;
+/** Defer expensive Pixi word-wrap rasterisation during a live resize. */
+declare function syncTextWrapWidth(text: Text, state: {
+  wrapWidth: number;
+}, width: number, defer: boolean): void;
+//#endregion
+export { getBoardResolution, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket };

package/dist/board/render/text-resolution.js

@@ -0,0 +1,43 @@
+//#region src/board/render/text-resolution.ts
+const MAX_BOARD_RESOLUTION = 2;
+function getBoardResolution() {
+	return Math.min(globalThis.devicePixelRatio || 1, MAX_BOARD_RESOLUTION);
+}
+/**
+* Zoom buckets for text re-rasterisation. Pixi Text is a bitmap: at high zoom it
+* looks soft unless we raise its resolution. We quantise zoom into a few
+* buckets so small zoom changes don't thrash texture regeneration.
+*/
+const TEXT_ZOOM_BUCKETS = [
+	.5,
+	1,
+	1.5,
+	2,
+	3,
+	4
+];
+function textZoomBucket(zoom) {
+	const clamped = Math.max(.1, Math.min(4, zoom));
+	for (const bucket of TEXT_ZOOM_BUCKETS) if (clamped <= bucket) return bucket;
+	return TEXT_ZOOM_BUCKETS[TEXT_ZOOM_BUCKETS.length - 1] ?? 4;
+}
+/** Effective text resolution for a given camera zoom. */
+function textResolutionForZoom(zoom) {
+	const bucket = textZoomBucket(zoom);
+	return Math.min(getBoardResolution() * Math.max(1, bucket), MAX_BOARD_RESOLUTION * 3);
+}
+/** Update a Pixi text texture only when zoom crosses a resolution bucket. */
+function syncTextResolution(text, state, zoom) {
+	const resolution = textResolutionForZoom(zoom);
+	if (resolution === state.resolution) return;
+	text.resolution = resolution;
+	state.resolution = resolution;
+}
+/** Defer expensive Pixi word-wrap rasterisation during a live resize. */
+function syncTextWrapWidth(text, state, width, defer) {
+	if (defer || width === state.wrapWidth) return;
+	text.style.wordWrapWidth = width;
+	state.wrapWidth = width;
+}
+//#endregion
+export { getBoardResolution, syncTextResolution, syncTextWrapWidth, textResolutionForZoom, textZoomBucket };

package/dist/board/render/themes/board-theme-registry.d.ts

@@ -0,0 +1,22 @@
+import { BoardDocument, BoardViewport } from "../../../protocol/dist/board-document.js";
+import { BoardRenderPalette } from "../renderers/board-renderer-registry.js";
+import { Application, Container } from "pixi.js";
+//#region src/board/render/themes/board-theme-registry.d.ts
+type BoardThemeContext = {
+  app: Application;
+  document: BoardDocument;
+  viewport: BoardViewport;
+  palette: BoardRenderPalette;
+  /** The host renders an image backdrop below the transparent Pixi canvas. */
+  hasImageBackground?: boolean;
+};
+type BoardThemeRenderer = {
+  id: string;
+  canRender: (document: BoardDocument) => boolean;
+  createBackground: (context: BoardThemeContext) => Container;
+  updateBackground?: (container: Container, context: BoardThemeContext) => void;
+};
+declare function getBoardThemeRenderer(document: BoardDocument): BoardThemeRenderer;
+declare function registerBoardThemeRenderer(renderer: BoardThemeRenderer): void;
+//#endregion
+export { BoardThemeContext, BoardThemeRenderer, getBoardThemeRenderer, registerBoardThemeRenderer };