@neta-art/cohub 3.1.0 → 4.0.0

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

@@ -0,0 +1,282 @@
+//#region src/board/core/file-preview.ts
+/**
+* File-card preview derivation — pure, renderer-agnostic, dependency-free.
+*
+* A board file card is a *thumbnail entry point* to a workspace file, never a
+* second copy of it. So everything here derives display facts from file content
+* that the caller already has, and the resulting snapshot is treated strictly as
+* a cache keyed by the file's mtime: the file on disk stays the single source of
+* truth, and nothing in this module ever writes back to it.
+*
+* Three presentation tiers fall out of which facts are available, so an
+* unrecognised file degrades instead of being rejected:
+*
+* - `cover` — a cover image was declared in markdown frontmatter;
+* - `text`  — text-like content yielded a readable excerpt;
+* - `blank` — anything else (binary, empty, oversized): icon, name and type.
+*/
+/** Hard cap on a stored excerpt. Board cards show a few lines at most, and the
+* snapshot rides along in every board transaction — so this stays small. */
+const FILE_EXCERPT_MAX_CHARS = 480;
+/** Files above this size are shown as `blank`; we never pull them for a preview. */
+const FILE_EXCERPT_MAX_BYTES = 256 * 1024;
+/** Frontmatter keys checked for a cover image, in precedence order. */
+const COVER_KEYS = [
+	"cover",
+	"coverImage",
+	"cover_image",
+	"image",
+	"banner",
+	"thumbnail",
+	"ogImage",
+	"og:image"
+];
+/**
+* Which tier a card renders at. Derived rather than stored: presentation follows
+* from the facts present, so there is no second piece of state to fall out of
+* sync with them.
+*/
+function filePreviewKind(snapshot) {
+	if (!snapshot) return "blank";
+	if (snapshot.coverPath || snapshot.coverUrl) return "cover";
+	if (snapshot.excerpt) return "text";
+	return "blank";
+}
+/** Short uppercase type label for the card's meta line (`MD`, `JSON`, `FILE`). */
+function fileTypeLabel(path) {
+	const name = path.split("/").filter(Boolean).pop() ?? path;
+	const dot = name.lastIndexOf(".");
+	if (dot <= 0) return (name.replace(/^\./, "") || "file").toUpperCase();
+	return name.slice(dot + 1).toUpperCase();
+}
+/** Human-readable byte size for the meta line. */
+function formatFileSize(bytes) {
+	if (bytes === void 0 || !Number.isFinite(bytes) || bytes < 0) return "";
+	if (bytes < 1024) return `${bytes} B`;
+	const units = [
+		"KB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	let value = bytes / 1024;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit += 1;
+	}
+	return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+/** Normalise a space-relative path: resolve `.`/`..` against the file's dir. */
+function resolveSpacePath(fromFilePath, ref) {
+	const base = ref.startsWith("/") ? [] : fromFilePath.split("/").slice(0, -1).filter(Boolean);
+	const segments = ref.replace(/^\//, "").split("/");
+	const out = [...base];
+	for (const segment of segments) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") {
+			out.pop();
+			continue;
+		}
+		out.push(segment);
+	}
+	return out.join("/");
+}
+/**
+* Classify a raw cover reference from frontmatter.
+*
+* Remote covers are allowed on purpose — a lot of real markdown points at a CDN.
+* The trade-off is that opening such a board issues a request to that third
+* party; the renderer degrades silently if it fails, and nothing is retried in a
+* loop.
+*/
+function resolveCoverRef(fromFilePath, raw) {
+	const value = (raw ?? "").trim();
+	if (!value) return null;
+	if (value.startsWith("//")) return {
+		kind: "url",
+		url: `https:${value}`
+	};
+	const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
+	if (scheme) {
+		if (scheme === "https") return {
+			kind: "url",
+			url: value
+		};
+		return null;
+	}
+	const path = resolveSpacePath(fromFilePath, value);
+	return path ? {
+		kind: "path",
+		path
+	} : null;
+}
+/**
+* Split leading YAML frontmatter from a markdown source. Deliberately minimal:
+* this only needs the raw block so a handful of scalar keys can be read, not a
+* YAML parser.
+*/
+function splitFrontmatter(source) {
+	if (!/^---[ \t]*\r?\n/.test(source)) return {
+		frontmatter: null,
+		body: source
+	};
+	const lines = source.split(/\r?\n/);
+	for (let index = 1; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		if (line === "---" || line === "...") return {
+			frontmatter: lines.slice(1, index).join("\n"),
+			body: lines.slice(index + 1).join("\n")
+		};
+	}
+	return {
+		frontmatter: null,
+		body: source
+	};
+}
+function unquote(value) {
+	const trimmed = value.trim();
+	if (trimmed.length < 2) return trimmed;
+	const first = trimmed[0];
+	const last = trimmed[trimmed.length - 1];
+	if (first === "\"" && last === "\"" || first === "'" && last === "'") return trimmed.slice(1, -1);
+	return trimmed;
+}
+/** Read non-empty top-level scalar values from a frontmatter block. */
+function readFrontmatterScalars(frontmatter) {
+	const found = /* @__PURE__ */ new Map();
+	if (!frontmatter) return found;
+	for (const line of frontmatter.split(/\r?\n/)) {
+		if (!line.trim() || /^\s/.test(line) || line.trimStart().startsWith("#")) continue;
+		const match = /^([A-Za-z0-9_:.-]+):(.*)$/.exec(line);
+		if (!match) continue;
+		const key = match[1];
+		const value = unquote(match[2] ?? "");
+		if (key && value && !found.has(key)) found.set(key, value);
+	}
+	return found;
+}
+/** Read the document title declared by top-level frontmatter. */
+function readTitleFromFrontmatter(frontmatter) {
+	return readFrontmatterScalars(frontmatter).get("title") ?? null;
+}
+/**
+* Read the first cover-ish scalar from a frontmatter block.
+*
+* Only top-level keys are considered (a leading-space line is nested and skipped)
+* so `cover:` under some other mapping cannot be mistaken for the file's own.
+*/
+function readCoverFromFrontmatter(frontmatter) {
+	const found = readFrontmatterScalars(frontmatter);
+	for (const key of COVER_KEYS) {
+		const value = found.get(key);
+		if (value) return value;
+	}
+	return null;
+}
+/**
+* Reduce source text to a short, readable excerpt.
+*
+* The goal is a card-sized hint of what the file is about, so markdown
+* decoration is flattened rather than rendered: fenced code is dropped whole
+* (it reads as noise at thumbnail size), headings and emphasis lose their
+* markers, links keep their text, and blank runs collapse.
+*/
+function buildFileExcerpt(source, limit = 480) {
+	if (!source) return "";
+	const cleaned = source.replace(/```[\s\S]*?(?:```|$)/g, " ").replace(/<!--[\s\S]*?-->/g, " ").replace(/<\/?[a-z][^>]*>/gi, " ").replace(/!\[[^\]]*\]\([^)]*\)/g, " ").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/^[ \t]*#{1,6}[ \t]+/gm, "").replace(/^[ \t]*>[ \t]?/gm, "").replace(/^[ \t]*[-*+][ \t]+/gm, "").replace(/^[ \t]*\d+\.[ \t]+/gm, "").replace(/^[ \t]*([-*_])(?:[ \t]*\1){2,}[ \t]*$/gm, " ").replace(/\|/g, " ").replace(/[*_`~]/g, "").replace(/\r\n?/g, "\n").replace(/[ \t]+/g, " ").replace(/\n{2,}/g, "\n").replace(/[ \t]*\n[ \t]*/g, "\n").trim();
+	if (cleaned.length <= limit) return cleaned;
+	const slice = cleaned.slice(0, limit);
+	const lastSpace = slice.lastIndexOf(" ");
+	return `${(lastSpace > limit * .6 ? slice.slice(0, lastSpace) : slice).trimEnd()}…`;
+}
+/** Basename of a path, used as the default card title. */
+function fileBaseName(path) {
+	return path.split("/").filter(Boolean).pop() ?? path;
+}
+/**
+* Build the cached display facts for a file node.
+*
+* Content is optional by design: a snapshot built without it still produces a
+* usable `blank` card, so a node can be created the instant a file is dropped
+* and enriched later without blocking on a read.
+*/
+function buildFileSnapshot(input) {
+	const snapshot = { title: input.title?.trim() || fileBaseName(input.path) };
+	if (input.mimeType) snapshot.mimeType = input.mimeType;
+	if (typeof input.size === "number" && Number.isFinite(input.size)) snapshot.size = input.size;
+	if (typeof input.mtimeMs === "number" && Number.isFinite(input.mtimeMs)) snapshot.mtimeMs = input.mtimeMs;
+	const content = input.content;
+	if (typeof content !== "string" || content.length === 0) return snapshot;
+	const { frontmatter, body } = splitFrontmatter(content);
+	const frontmatterTitle = readTitleFromFrontmatter(frontmatter);
+	if (frontmatterTitle) snapshot.title = frontmatterTitle;
+	const cover = resolveCoverRef(input.path, readCoverFromFrontmatter(frontmatter));
+	if (cover?.kind === "url") snapshot.coverUrl = cover.url;
+	else if (cover?.kind === "path") snapshot.coverPath = cover.path;
+	const excerpt = buildFileExcerpt(body);
+	if (excerpt) snapshot.excerpt = excerpt;
+	return snapshot;
+}
+/** Whether a snapshot's cached facts still describe the file on disk. */
+function isFileSnapshotFresh(snapshot, file) {
+	if (!snapshot) return false;
+	if (snapshot.mtimeMs === void 0 || file.mtimeMs === void 0) return false;
+	if (snapshot.mtimeMs !== file.mtimeMs) return false;
+	if (snapshot.size !== void 0 && file.size !== void 0 && snapshot.size !== file.size) return false;
+	return true;
+}
+/** Whether a file is small enough that fetching a text preview is worthwhile. */
+function shouldFetchFileExcerpt(input) {
+	if (input.size !== void 0 && input.size > 262144) return false;
+	return true;
+}
+/**
+* Classify a failed read.
+*
+* Only a 404 (or 410 Gone) is treated as the file being absent. Everything else
+* — offline, 5xx, timeout, 401/403 — is `unavailable`: the file may well exist and
+* simply not be reachable by this client right now.
+*/
+function availabilityFromError(error) {
+	const status = typeof error === "object" && error !== null ? error.status : void 0;
+	if (typeof status !== "number") return "unavailable";
+	if (status === 404 || status === 410) return "missing";
+	return "unavailable";
+}
+/**
+* Cache key for a file within a space.
+*
+* A path only means anything relative to its space, and identical paths across
+* spaces are the norm ("README.md"), so every preview cache is keyed by both. The
+* separator is NUL because it cannot appear in a space id or a path, so no path can
+* be crafted to collide with another space's entry.
+*/
+function filePreviewScope(spaceId, path) {
+	return `${spaceId}\u0000${path}`;
+}
+/**
+* Cache key for one *version* of a file. The mtime is part of the key so a changed
+* file misses the cache instead of serving a stale excerpt or cover.
+*/
+function filePreviewMemoKey(spaceId, path, mtimeMs) {
+	return `${filePreviewScope(spaceId, path)}@${mtimeMs ?? 0}`;
+}
+/**
+* Fold a freshly read snapshot into the cached one.
+*
+* `complete` decides whether the incoming facts supersede the cached ones or are
+* merged over them, and the difference is not cosmetic. A snapshot omits fields the
+* file does not have, so merging a complete read would resurrect a cover or an
+* excerpt the file no longer contains — permanently, since the stale value is then
+* committed back. Merging is right only for an incomplete read, where an absent
+* field means "could not establish", not "not there".
+*/
+function mergeFileSnapshot(cached, incoming, complete) {
+	return complete ? incoming : {
+		...cached,
+		...incoming
+	};
+}
+//#endregion
+export { FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, availabilityFromError, buildFileExcerpt, buildFileSnapshot, fileBaseName, filePreviewKind, filePreviewMemoKey, filePreviewScope, fileTypeLabel, formatFileSize, isFileSnapshotFresh, mergeFileSnapshot, readCoverFromFrontmatter, readTitleFromFrontmatter, resolveCoverRef, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter };

package/dist/board/core/palette.d.ts

@@ -0,0 +1,42 @@
+//#region src/board/core/palette.d.ts
+/**
+ * Board color palette — a small, named set of shape colors shared by text,
+ * geo, draw and arrow shapes. Colors are stored by id in shape props (never
+ * raw hex), so themes and space `.cohub/theme.css` can remap them via CSS
+ * tokens while persisted data stays compact and forward-compatible.
+ *
+ * Concrete values are resolved from CSS variables at render time:
+ *   --board-color-{id}-stroke | -fill | -label
+ * with hard-coded light/dark tables as offline / export fallbacks.
+ */
+type BoardColorId = "brand" | "neutral" | "black" | "white" | "blue" | "green" | "amber" | "violet" | "rose";
+type BoardColorValue = {
+  /** Stroke / accent color (sRGB hex). */
+  stroke: number;
+  /** Translucent fill used behind shapes (sRGB hex). */
+  fill: number;
+  /** Readable label color on top of the fill. */
+  label: number;
+};
+type BoardColorEntry = {
+  id: BoardColorId;
+  label: string;
+  dark: BoardColorValue;
+  light: BoardColorValue;
+};
+declare const BOARD_COLORS: readonly BoardColorEntry[];
+declare const DEFAULT_BOARD_COLOR: BoardColorId;
+declare function isBoardColorId(value: unknown): value is BoardColorId;
+declare function boardColorCssVar(id: BoardColorId, part: keyof BoardColorValue): string;
+/** Resolve a color id to concrete values for a color mode. Unknown → brand. */
+declare function resolveBoardColor(id: unknown, mode: "dark" | "light"): BoardColorValue;
+type BoardShapeColors = Record<BoardColorId, BoardColorValue>;
+/** Build a full shape-color table from hard-coded fallbacks (export / SSR). */
+declare function buildFallbackShapeColors(mode: "dark" | "light"): BoardShapeColors;
+/**
+ * Pick a concrete color from a live shape-color table, falling back to the
+ * default brand entry when the id is unknown.
+ */
+declare function pickBoardColor(colors: BoardShapeColors | null | undefined, id: unknown, mode?: "dark" | "light"): BoardColorValue;
+//#endregion
+export { BOARD_COLORS, BoardColorEntry, BoardColorId, BoardColorValue, BoardShapeColors, DEFAULT_BOARD_COLOR, boardColorCssVar, buildFallbackShapeColors, isBoardColorId, pickBoardColor, resolveBoardColor };

package/dist/board/core/palette.js

@@ -0,0 +1,166 @@
+//#region src/board/core/palette.ts
+/**
+* Label color fallbacks mirror `--board-color-*-label`, which every theme maps
+* to `--text-primary`: labels sit on a *translucent* fill over the page, not on
+* a saturated swatch, so a tinted label would be dark-on-dark. Keeping these in
+* step with `theme.css` is what makes a headless export match the screen.
+*/
+const LABEL_DARK = 16053492;
+const LABEL_LIGHT = 1579035;
+const BOARD_COLORS = [
+	{
+		id: "brand",
+		label: "Brand",
+		dark: {
+			stroke: 16734751,
+			fill: 16734751,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 15222030,
+			fill: 15222030,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "neutral",
+		label: "Neutral",
+		dark: {
+			stroke: 10133670,
+			fill: 10133670,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 6251368,
+			fill: 6251368,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "black",
+		label: "Black",
+		dark: {
+			stroke: 0,
+			fill: 0,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 0,
+			fill: 0,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "white",
+		label: "White",
+		dark: {
+			stroke: 16777215,
+			fill: 16777215,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 16777215,
+			fill: 16777215,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "blue",
+		label: "Blue",
+		dark: {
+			stroke: 3718648,
+			fill: 3718648,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 2450411,
+			fill: 2450411,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "green",
+		label: "Green",
+		dark: {
+			stroke: 3462041,
+			fill: 3462041,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 1483594,
+			fill: 1483594,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "amber",
+		label: "Amber",
+		dark: {
+			stroke: 16096779,
+			fill: 16096779,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 14251782,
+			fill: 14251782,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "violet",
+		label: "Violet",
+		dark: {
+			stroke: 10980346,
+			fill: 10980346,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 8141549,
+			fill: 8141549,
+			label: LABEL_LIGHT
+		}
+	},
+	{
+		id: "rose",
+		label: "Rose",
+		dark: {
+			stroke: 16478597,
+			fill: 16478597,
+			label: LABEL_DARK
+		},
+		light: {
+			stroke: 14753096,
+			fill: 14753096,
+			label: LABEL_LIGHT
+		}
+	}
+];
+const DEFAULT_BOARD_COLOR = "brand";
+const COLOR_INDEX = new Map(BOARD_COLORS.map((entry) => [entry.id, entry]));
+function isBoardColorId(value) {
+	return typeof value === "string" && COLOR_INDEX.has(value);
+}
+function boardColorCssVar(id, part) {
+	return `--board-color-${id}-${part}`;
+}
+/** Resolve a color id to concrete values for a color mode. Unknown → brand. */
+function resolveBoardColor(id, mode) {
+	return ((isBoardColorId(id) ? COLOR_INDEX.get(id) : void 0) ?? COLOR_INDEX.get("brand"))[mode];
+}
+/** Build a full shape-color table from hard-coded fallbacks (export / SSR). */
+function buildFallbackShapeColors(mode) {
+	const out = {};
+	for (const entry of BOARD_COLORS) out[entry.id] = entry[mode];
+	return out;
+}
+/**
+* Pick a concrete color from a live shape-color table, falling back to the
+* default brand entry when the id is unknown.
+*/
+function pickBoardColor(colors, id, mode = "dark") {
+	if (colors && isBoardColorId(id) && colors[id]) return colors[id];
+	if (colors) return colors[DEFAULT_BOARD_COLOR];
+	return resolveBoardColor(id, mode);
+}
+//#endregion
+export { BOARD_COLORS, DEFAULT_BOARD_COLOR, boardColorCssVar, buildFallbackShapeColors, isBoardColorId, pickBoardColor, resolveBoardColor };

package/dist/board/core/shape-definition.d.ts

@@ -0,0 +1,35 @@
+import { BoardFrame, BoardItem } from "../../protocol/dist/board-document.js";
+import { Rect, WorldPoint } from "../geometry.js";
+import { ShapeCapabilities, ShapeGeometry, ShapeHandle, ShapeResizeMode } from "./shape-types.js";
+//#region src/board/core/shape-definition.d.ts
+type ShapeDefinition = {
+  /** The item type this definition handles. */
+  type: string;
+  capabilities: ShapeCapabilities;
+  /** Rotation-aware world bounds (culling, marquee). Defaults to itemBounds. */
+  getBounds?: (item: BoardItem) => Rect;
+  /** Exact world-space containment (hit testing). Defaults to rotated rect. */
+  hitTest?: (item: BoardItem, point: WorldPoint) => boolean;
+  /** Interaction handles in the shape's local space. Defaults to none. */
+  getHandles?: (item: BoardItem) => ShapeHandle[];
+  /**
+   * Local-space geometry outline, used for precise hit tests and snapping.
+   * Optional; box shapes rely on the frame directly.
+   */
+  getGeometry?: (item: BoardItem) => ShapeGeometry;
+};
+declare function registerShapeDefinition(definition: ShapeDefinition): void;
+declare function getShapeDefinition(type: string): ShapeDefinition | undefined;
+/**
+ * The generic fallback for unknown shape types: a plain movable/resizable box.
+ * This guarantees a shape authored by a newer client is still interactive here.
+ */
+declare const unknownShapeDefinition: ShapeDefinition;
+declare function definitionForItem(item: BoardItem): ShapeDefinition;
+declare function shapeBounds(item: BoardItem): Rect;
+declare function shapeHitTest(item: BoardItem, point: WorldPoint): boolean;
+declare function shapeHandles(item: BoardItem): ShapeHandle[];
+declare function shapeCapabilities(item: BoardItem): ShapeCapabilities;
+declare function shapeResizeMode(item: BoardItem): ShapeResizeMode;
+//#endregion
+export { type BoardFrame, ShapeDefinition, definitionForItem, getShapeDefinition, registerShapeDefinition, shapeBounds, shapeCapabilities, shapeHandles, shapeHitTest, shapeResizeMode, unknownShapeDefinition };

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

@@ -0,0 +1,64 @@
+import { isUnknownItem } from "../../protocol/dist/board-document.js";
+import { frameContainsPoint, itemBounds } from "../geometry.js";
+import { resizeModeForCapabilities } from "./shape-types.js";
+//#region src/board/core/shape-definition.ts
+/**
+* ShapeDefinition protocol + registry.
+*
+* A ShapeDefinition describes everything the editor needs to *behave* correctly
+* around a shape — bounds, hit testing, handles, capabilities, snap targets —
+* with no knowledge of how the shape is drawn. The Pixi renderers are a separate
+* concern (board-renderer-registry). This separation is what lets us add a shape
+* by writing one definition + one renderer, and keeps geometry fully unit-testable
+* without a GPU.
+*
+* Definitions are looked up by `item.type`. Unknown types fall back to a generic
+* box definition so unrecognised shapes still select, move and resize.
+*/
+const definitions = /* @__PURE__ */ new Map();
+function registerShapeDefinition(definition) {
+	definitions.set(definition.type, definition);
+}
+function getShapeDefinition(type) {
+	return definitions.get(type);
+}
+/**
+* The generic fallback for unknown shape types: a plain movable/resizable box.
+* This guarantees a shape authored by a newer client is still interactive here.
+*/
+const unknownShapeDefinition = {
+	type: "__unknown__",
+	capabilities: {
+		canMove: true,
+		canResize: true,
+		aspectLocked: false,
+		canRotate: true,
+		canEdit: false,
+		canBind: true,
+		canSnap: true,
+		canLock: true
+	}
+};
+function definitionForItem(item) {
+	if (isUnknownItem(item)) return unknownShapeDefinition;
+	return definitions.get(item.type) ?? unknownShapeDefinition;
+}
+function shapeBounds(item) {
+	return definitionForItem(item).getBounds?.(item) ?? itemBounds(item.frame);
+}
+function shapeHitTest(item, point) {
+	const definition = definitionForItem(item);
+	if (definition.hitTest) return definition.hitTest(item, point);
+	return frameContainsPoint(item.frame, point);
+}
+function shapeHandles(item) {
+	return definitionForItem(item).getHandles?.(item) ?? [];
+}
+function shapeCapabilities(item) {
+	return definitionForItem(item).capabilities;
+}
+function shapeResizeMode(item) {
+	return resizeModeForCapabilities(shapeCapabilities(item));
+}
+//#endregion
+export { definitionForItem, getShapeDefinition, registerShapeDefinition, shapeBounds, shapeCapabilities, shapeHandles, shapeHitTest, shapeResizeMode, unknownShapeDefinition };