@neta-art/cohub 3.0.0 → 3.2.0

package/dist/board/core/shape-types.js

@@ -0,0 +1,27 @@
+//#region src/board/core/shape-types.ts
+function resizeModeForCapabilities(capabilities) {
+	if (!capabilities.canResize) return "none";
+	return capabilities.aspectLocked ? "uniform" : "free";
+}
+const FULL_CAPABILITIES = {
+	canMove: true,
+	canResize: true,
+	aspectLocked: false,
+	canRotate: true,
+	canEdit: false,
+	canBind: true,
+	canSnap: true,
+	canLock: true
+};
+const GEO_KINDS = [
+	"rectangle",
+	"rounded",
+	"ellipse",
+	"diamond",
+	"triangle"
+];
+function isGeoKind(value) {
+	return typeof value === "string" && GEO_KINDS.includes(value);
+}
+//#endregion
+export { FULL_CAPABILITIES, GEO_KINDS, isGeoKind, resizeModeForCapabilities };

package/dist/board/core/text-metrics.d.ts

@@ -0,0 +1,18 @@
+//#region src/board/core/text-metrics.d.ts
+declare const TEXT_FONT_FAMILY = "Geist";
+declare const TEXT_FONT_SIZE = 18;
+declare const TEXT_LINE_HEIGHT = 24;
+declare const TEXT_MIN_FONT_SIZE = 2;
+declare const TEXT_MAX_FONT_SIZE = 512;
+type BoardTextMeasurer = (text: string, fontSize: number) => number | null;
+/** Install the renderer's text measurer, or clear it for environment-free fallback metrics. */
+declare function setBoardTextMeasurer(measurer?: BoardTextMeasurer): void;
+declare function clampBoardTextFontSize(fontSize: number): number;
+declare function boardTextLineHeight(fontSize: number): number;
+/** Measure unwrapped plain text into scalable world-space bounds. */
+declare function measureBoardText(text: string, fontSize?: number): {
+  width: number;
+  height: number;
+};
+//#endregion
+export { TEXT_FONT_FAMILY, TEXT_FONT_SIZE, TEXT_LINE_HEIGHT, TEXT_MAX_FONT_SIZE, TEXT_MIN_FONT_SIZE, boardTextLineHeight, clampBoardTextFontSize, measureBoardText, setBoardTextMeasurer };

package/dist/board/core/text-metrics.js

@@ -0,0 +1,43 @@
+import { BOARD_TEXT_FONT_FAMILY } from "../../protocol/dist/board-constants.js";
+//#region src/board/core/text-metrics.ts
+const TEXT_FONT_FAMILY = BOARD_TEXT_FONT_FAMILY;
+const TEXT_FONT_SIZE = 18;
+const TEXT_LINE_HEIGHT = 24;
+const TEXT_MIN_FONT_SIZE = 2;
+const TEXT_MAX_FONT_SIZE = 512;
+const TEXT_LINE_HEIGHT_RATIO = TEXT_LINE_HEIGHT / TEXT_FONT_SIZE;
+const TEXT_MIN_WIDTH_RATIO = 16 / TEXT_FONT_SIZE;
+const TEXT_HORIZONTAL_PADDING_RATIO = 2 / TEXT_FONT_SIZE;
+const FALLBACK_CHARACTER_RATIO = .52;
+let textMeasurer;
+/** Install the renderer's text measurer, or clear it for environment-free fallback metrics. */
+function setBoardTextMeasurer(measurer) {
+	textMeasurer = measurer;
+}
+function clampBoardTextFontSize(fontSize) {
+	return Math.min(TEXT_MAX_FONT_SIZE, Math.max(TEXT_MIN_FONT_SIZE, fontSize));
+}
+function boardTextLineHeight(fontSize) {
+	return clampBoardTextFontSize(fontSize) * TEXT_LINE_HEIGHT_RATIO;
+}
+/** Measure unwrapped plain text into scalable world-space bounds. */
+function measureBoardText(text, fontSize = TEXT_FONT_SIZE) {
+	const size = clampBoardTextFontSize(fontSize);
+	const lines = (text || " ").split("\n");
+	const minWidth = size * TEXT_MIN_WIDTH_RATIO;
+	const horizontalPadding = size * TEXT_HORIZONTAL_PADDING_RATIO;
+	const lineHeight = boardTextLineHeight(size);
+	const characterWidth = size * FALLBACK_CHARACTER_RATIO;
+	let width = minWidth;
+	for (const line of lines) {
+		const value = line || " ";
+		const measured = textMeasurer?.(value, size);
+		width = Math.max(width, (measured ?? Math.max(1, value.length) * characterWidth) + horizontalPadding);
+	}
+	return {
+		width,
+		height: Math.max(lineHeight, lines.length * lineHeight)
+	};
+}
+//#endregion
+export { TEXT_FONT_FAMILY, TEXT_FONT_SIZE, TEXT_LINE_HEIGHT, TEXT_MAX_FONT_SIZE, TEXT_MIN_FONT_SIZE, boardTextLineHeight, clampBoardTextFontSize, measureBoardText, setBoardTextMeasurer };

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

@@ -0,0 +1,56 @@
+import { BoardDocument, BoardItem } from "../../protocol/dist/board-document.js";
+import { BoardExportPlan, BoardExportPlanInput, BoardExportRegion } from "../core/export-plan.js";
+import { BoardShapeColors } from "../core/palette.js";
+import { BoardRenderPalette } from "../render/renderers/board-renderer-registry.js";
+import "../render/index.js";
+import { BoardExportScene, BoardExportSceneInput, createBoardExportScene } from "./scene.js";
+import { ICanvas, Renderer, Texture } from "pixi.js";
+//#region src/board/export/index.d.ts
+/** Paper behind the content: the theme's page color, or none at all. */
+type BoardExportBackground = "paper" | "transparent" | number;
+type BoardExportOptions = {
+  region?: BoardExportRegion;
+  /** Output pixels per world unit. Defaults to 2. */
+  scale?: number;
+  /** World-space padding. Frame and rect regions default to 0, others to 32. */
+  padding?: number;
+  colorScheme?: "dark" | "light";
+  /** Defaults to "paper" — a transparent PNG surprises people who paste it. */
+  background?: BoardExportBackground;
+  palette?: Partial<BoardRenderPalette>;
+  colors?: BoardShapeColors;
+  /** Resolved textures by preview key; unresolved keys become placeholders. */
+  textures?: Map<string, Texture>;
+  /** Preview-key strategy supplied by the host; defaults to still images only. */
+  assetKey?: (item: BoardItem) => string | null;
+  maxEdge?: number;
+  maxPixels?: number;
+};
+type BoardExportWarning = {
+  kind: "scale-clamped";
+  requested: number;
+  applied: number;
+} | {
+  kind: "images-missing";
+  keys: string[];
+} | {
+  kind: "many-items";
+  count: number;
+};
+type BoardExportResult = {
+  canvas: ICanvas;
+  plan: BoardExportPlan;
+  warnings: BoardExportWarning[];
+};
+/**
+ * Capture a board region as a canvas.
+ *
+ * Returns null when the region is empty — an empty selection is a no-op, not a
+ * failure. The scene is always destroyed, so a throwing renderer cannot leak
+ * GPU resources.
+ */
+declare function renderBoardExport(renderer: Renderer, input: BoardDocument, options?: BoardExportOptions): BoardExportResult | null;
+/** Human-readable form of a warning, shared by the CLI and the web UI. */
+declare function describeBoardExportWarning(warning: BoardExportWarning): string;
+//#endregion
+export { BoardExportBackground, BoardExportOptions, type BoardExportPlan, type BoardExportPlanInput, type BoardExportRegion, BoardExportResult, type BoardExportScene, type BoardExportSceneInput, BoardExportWarning, createBoardExportScene, describeBoardExportWarning, renderBoardExport };

package/dist/board/export/index.js

@@ -0,0 +1,86 @@
+import { normalizeBoardDocument, planBoardExport } from "../core/export-plan.js";
+import { defaultBoardPalette } from "../render/palette.js";
+import { createBoardExportScene } from "./scene.js";
+import { Rectangle } from "pixi.js";
+//#region src/board/export/index.ts
+function resolveBackground(background, palette) {
+	if (background === "transparent") return null;
+	if (typeof background === "number") return background;
+	return palette.bg;
+}
+/**
+* Capture a board region as a canvas.
+*
+* Returns null when the region is empty — an empty selection is a no-op, not a
+* failure. The scene is always destroyed, so a throwing renderer cannot leak
+* GPU resources.
+*/
+function renderBoardExport(renderer, input, options = {}) {
+	const document = normalizeBoardDocument(input);
+	const plan = planBoardExport({
+		document,
+		region: options.region ?? { kind: "all" },
+		scale: options.scale,
+		padding: options.padding,
+		maxEdge: options.maxEdge,
+		maxPixels: options.maxPixels
+	});
+	if (!plan) return null;
+	const colorScheme = options.colorScheme ?? "dark";
+	const palette = {
+		...defaultBoardPalette(colorScheme),
+		...options.palette
+	};
+	const scene = createBoardExportScene({
+		document,
+		items: plan.items,
+		world: plan.world,
+		scale: plan.scale,
+		colorScheme,
+		palette,
+		colors: options.colors,
+		textures: options.textures,
+		assetKey: options.assetKey,
+		background: resolveBackground(options.background, palette)
+	});
+	try {
+		const canvas = renderer.extract.canvas({
+			target: scene.root,
+			frame: new Rectangle(0, 0, plan.width, plan.height),
+			resolution: 1,
+			antialias: true,
+			clearColor: options.background === "transparent" ? void 0 : palette.bg
+		});
+		const warnings = [];
+		if (plan.clamped) warnings.push({
+			kind: "scale-clamped",
+			requested: plan.requestedScale,
+			applied: plan.scale
+		});
+		if (scene.missingImageKeys.length > 0) warnings.push({
+			kind: "images-missing",
+			keys: scene.missingImageKeys
+		});
+		if (plan.items.length > 2e3) warnings.push({
+			kind: "many-items",
+			count: plan.items.length
+		});
+		return {
+			canvas,
+			plan,
+			warnings
+		};
+	} finally {
+		scene.destroy();
+	}
+}
+/** Human-readable form of a warning, shared by the CLI and the web UI. */
+function describeBoardExportWarning(warning) {
+	switch (warning.kind) {
+		case "scale-clamped": return `Scale reduced from ${warning.requested}x to ${warning.applied.toFixed(2)}x to stay within the size limit.`;
+		case "images-missing": return warning.keys.length === 1 ? "1 image could not be loaded and was drawn as a placeholder." : `${warning.keys.length} images could not be loaded and were drawn as placeholders.`;
+		case "many-items": return `${warning.count} items exported; this may take a moment.`;
+	}
+}
+//#endregion
+export { createBoardExportScene, describeBoardExportWarning, renderBoardExport };

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

@@ -0,0 +1,35 @@
+import { BoardDocument, BoardItem } from "../../protocol/dist/board-document.js";
+import { Rect } from "../geometry.js";
+import { BoardShapeColors } from "../core/palette.js";
+import { BoardRenderPalette } from "../render/renderers/board-renderer-registry.js";
+import "../render/index.js";
+import { Container, Texture } from "pixi.js";
+//#region src/board/export/scene.d.ts
+type BoardExportSceneInput = {
+  document: BoardDocument;
+  /** Items to draw, in document (z) order. */
+  items: BoardItem[];
+  /** World rect being captured; content is translated so it starts at 0,0. */
+  world: Rect;
+  /** Output pixels per world unit. Drives text rasterisation resolution. */
+  scale: number;
+  colorScheme: "dark" | "light";
+  palette?: Partial<BoardRenderPalette>;
+  colors?: BoardShapeColors;
+  /** Resolved textures by preview key. Missing keys render as placeholders. */
+  textures?: Map<string, Texture>;
+  /** Preview-key strategy supplied by the host; defaults to still images only. */
+  assetKey?: (item: BoardItem) => string | null;
+  /** Opaque paper behind the content, or null for transparency. */
+  background?: number | null;
+};
+type BoardExportScene = {
+  /** Root to hand to the renderer; already positioned and scaled. */
+  root: Container;
+  /** Image keys the scene wanted but could not resolve. */
+  missingImageKeys: string[];
+  destroy: () => void;
+};
+declare function createBoardExportScene(input: BoardExportSceneInput): BoardExportScene;
+//#endregion
+export { BoardExportScene, BoardExportSceneInput, createBoardExportScene };

package/dist/board/export/scene.js

@@ -0,0 +1,69 @@
+import { imageAssetKey } from "../image-key.js";
+import { buildFallbackShapeColors } from "../core/palette.js";
+import { defaultBoardPalette } from "../render/palette.js";
+import { getBoardCardRenderer } from "../render/renderers/board-renderer-registry.js";
+import { Container, Graphics } from "pixi.js";
+//#region src/board/export/scene.ts
+/**
+* Render context for an export.
+*
+* Interaction state is empty by construction: nothing is selected, hovered or
+* resizing, so no editor chrome (outlines, handles) can leak into the image.
+*/
+function buildContext(input) {
+	const missing = /* @__PURE__ */ new Set();
+	const byId = new Map(input.document.items.map((item) => [item.id, item]));
+	const textures = input.textures ?? /* @__PURE__ */ new Map();
+	return {
+		context: {
+			document: input.document,
+			getItem: (id) => byId.get(id) ?? null,
+			selectedIds: /* @__PURE__ */ new Set(),
+			hoveredId: null,
+			resizingIds: /* @__PURE__ */ new Set(),
+			palette: {
+				...defaultBoardPalette(input.colorScheme),
+				...input.palette
+			},
+			colors: input.colors ?? buildFallbackShapeColors(input.colorScheme),
+			colorScheme: input.colorScheme,
+			zoom: input.scale,
+			assetKey: input.assetKey ?? imageAssetKey,
+			getTexture: (key) => textures.get(key) ?? null,
+			hasError: (key) => {
+				if (!textures.has(key)) missing.add(key);
+				return false;
+			},
+			fileState: () => "ok",
+			acquireTexture: () => {},
+			releaseTexture: () => {}
+		},
+		missing
+	};
+}
+function createBoardExportScene(input) {
+	const { context, missing } = buildContext(input);
+	const root = new Container({ label: "board-export-root" });
+	if (input.background != null) root.addChild(new Graphics().rect(0, 0, input.world.width * input.scale, input.world.height * input.scale).fill({
+		color: input.background,
+		alpha: 1
+	}));
+	const world = new Container({
+		isRenderGroup: true,
+		label: "board-export-world"
+	});
+	world.scale.set(input.scale);
+	world.position.set(-input.world.x * input.scale, -input.world.y * input.scale);
+	for (const item of input.items) {
+		const renderer = getBoardCardRenderer(item, context);
+		world.addChild(renderer.create(item, context));
+	}
+	root.addChild(world);
+	return {
+		root,
+		missingImageKeys: [...missing],
+		destroy: () => root.destroy({ children: true })
+	};
+}
+//#endregion
+export { createBoardExportScene };

package/dist/board/geometry.d.ts

@@ -0,0 +1,131 @@
+import { BoardFrame, BoardViewport } from "../protocol/dist/board-document.js";
+//#region src/board/geometry.d.ts
+type Point = {
+  x: number;
+  y: number;
+};
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type Size = {
+  width: number;
+  height: number;
+};
+declare const coordBrand: unique symbol;
+/** Surface-relative screen coordinate, in CSS pixels. */
+type ScreenPoint = {
+  x: number;
+  y: number;
+  readonly [coordBrand]: "screen";
+};
+/** Board world coordinate, in board units. */
+type WorldPoint = {
+  x: number;
+  y: number;
+  readonly [coordBrand]: "world";
+};
+declare function screenPoint(x: number, y: number): ScreenPoint;
+declare function worldPoint(x: number, y: number): WorldPoint;
+declare const MIN_BOARD_ZOOM = 0.05;
+declare const MAX_BOARD_ZOOM = 8;
+/** Smallest an item can be resized to, in world units. */
+declare const MIN_ITEM_SIZE = 24;
+/** Extra world-space padding applied when fitting content into view. */
+declare 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.
+ */
+declare const VIEWPORT_MARGIN_RATIO = 0.5;
+declare function clampZoom(zoom: number): number;
+/** Keep transient camera state finite without discarding its last valid axes. */
+declare function normalizeViewport(viewport: BoardViewport, fallback?: BoardViewport): BoardViewport;
+declare function clamp(value: number, min: number, max: number): number;
+declare function degToRad(degrees: number): number;
+declare function radToDeg(radians: number): number;
+declare function frameRect(frame: BoardFrame): Rect;
+declare function rectCenter(rect: Rect): WorldPoint;
+declare function rectsIntersect(a: Rect, b: Rect): boolean;
+declare function rectContainsPoint(rect: Rect, point: Point, tolerance?: number): boolean;
+declare function expandRect(rect: Rect, amount: number): Rect;
+declare function unionRects(rects: Rect[]): Rect | null;
+declare function rotatePointAround<P extends Point>(point: P, center: Point, angleRad: number): P;
+/** Axis-aligned bounding box of a (possibly rotated) frame. */
+declare function itemBounds(frame: BoardFrame): Rect;
+declare function selectionBounds(frames: BoardFrame[]): Rect | null;
+/** Exact point-in-frame test, accounting for rotation. */
+declare function frameContainsPoint(frame: BoardFrame, point: WorldPoint): boolean;
+/** World position of a resize handle on a single (possibly rotated) frame. */
+declare function frameHandlePosition(frame: BoardFrame, handle: ResizeHandle): WorldPoint;
+/** Corners in clockwise order, following the frame's rotation. */
+declare function frameCorners(frame: BoardFrame): readonly WorldPoint[];
+/** Screen-space radius (px) within which a pointer grabs a handle. */
+declare const HANDLE_HIT_RADIUS = 8;
+/** Screen-space offset (px) from the selection's lower-facing edge. */
+declare const ROTATION_HANDLE_OFFSET = 28;
+declare function frameRayIntersection(frame: Rect & {
+  rotation?: number;
+}, pointer: WorldPoint): WorldPoint;
+declare function rotationHandleAnchor(frame: Rect & {
+  rotation?: number;
+}): WorldPoint;
+declare function rotationHandlePosition(frame: Rect & {
+  rotation?: number;
+}, zoom: number): WorldPoint;
+type ResizeHandle = "nw" | "n" | "ne" | "e" | "se" | "s" | "sw" | "w";
+declare const CORNER_RESIZE_HANDLES: readonly ["nw", "ne", "se", "sw"];
+declare const EDGE_RESIZE_HANDLES: readonly ["n", "e", "s", "w"];
+declare const RESIZE_HANDLES: ResizeHandle[];
+/**
+ * Hit-test the continuous edge zones of a rotated frame. Corners are inset so
+ * their resize handles retain priority even on small nodes.
+ */
+declare function frameEdgeHandleAt(frame: BoardFrame, point: WorldPoint, zoom: number, screenRadius?: number): Extract<ResizeHandle, "n" | "e" | "s" | "w"> | null;
+/** Direction of a handle from the rect center: -1, 0, or 1 per axis. */
+declare const HANDLE_DIRECTION: Record<ResizeHandle, Point>;
+/** Position of a handle on an unrotated rect. */
+declare function handlePosition(rect: Rect, handle: ResizeHandle): WorldPoint;
+/** Resize a frame to exact dimensions while keeping the opposite handle fixed. */
+declare function resizeFrameToSize(frame: BoardFrame, handle: ResizeHandle, width: number, height: number): BoardFrame;
+/**
+ * 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.
+ */
+declare function resizeFrame(frame: BoardFrame, handle: ResizeHandle, pointer: WorldPoint, minSize?: number,
+/** Keep the original aspect ratio (Shift). */
+keepAspect?: boolean): BoardFrame;
+/**
+ * Proportionally scale a group of frames by dragging a corner handle of their
+ * combined bounds. Individual rotations are preserved.
+ */
+declare function scaleFrames(frames: BoardFrame[], bounds: Rect, handle: ResizeHandle, pointer: WorldPoint, minSize?: number, scaleRange?: {
+  min?: number;
+  max?: number;
+}): BoardFrame[];
+/** Angle (degrees) from a center to a world-space pointer. */
+declare function angleFromCenter(center: WorldPoint, pointer: WorldPoint): number;
+/**
+ * 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.
+ */
+declare function rotateFrames(frames: BoardFrame[], pivot: WorldPoint, deltaDeg: number): BoardFrame[];
+/** Normalize a rotation into the [-180, 180] range for tidy persistence. */
+declare function normalizeRotation(degrees: number): number;
+/** Convert a surface-relative screen point into world space. */
+declare function pointToWorld(point: ScreenPoint, viewport: BoardViewport): WorldPoint;
+declare function worldToScreen(point: WorldPoint, viewport: BoardViewport): ScreenPoint;
+declare function screenToWorld(clientX: number, clientY: number, rect: DOMRect, viewport: BoardViewport): WorldPoint;
+/** Zoom while keeping a surface-relative screen point fixed under the cursor. */
+declare function zoomAround(viewport: BoardViewport, anchor: ScreenPoint, nextZoom: number): BoardViewport;
+declare function panBy(viewport: BoardViewport, dx: number, dy: number): BoardViewport;
+/** Compute a viewport that frames the given world rect within the surface. */
+declare function fitToContent(content: Rect, surface: Size, padding?: number): BoardViewport;
+/** World-space rectangle currently visible in the board stage. */
+declare function visibleWorldRect(viewport: BoardViewport, surfaceWidth: number, surfaceHeight: number): Rect;
+//#endregion
+export { CORNER_RESIZE_HANDLES, EDGE_RESIZE_HANDLES, FIT_PADDING, HANDLE_DIRECTION, HANDLE_HIT_RADIUS, MAX_BOARD_ZOOM, MIN_BOARD_ZOOM, MIN_ITEM_SIZE, Point, RESIZE_HANDLES, ROTATION_HANDLE_OFFSET, Rect, ResizeHandle, ScreenPoint, Size, VIEWPORT_MARGIN_RATIO, WorldPoint, 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 };