@neta-art/cohub 3.1.0 → 3.2.0

package/dist/protocol/dist/board-document.js

@@ -0,0 +1,331 @@
+import "./board-constants.js";
+import { BOARD_DOCUMENT_KIND, BOARD_EXTENSION } from "./board.js";
+import { z } from "zod";
+//#region ../protocol/dist/board-document.js
+const BoardFrameSchema = z.object({
+	x: z.number().finite(),
+	y: z.number().finite(),
+	width: z.number().finite().positive(),
+	height: z.number().finite().positive(),
+	rotation: z.number().finite().default(0)
+});
+/**
+* The board camera. This is local UI state, not synced content: semantic ops
+* (see diffBoardDocuments) never describe the viewport, and the editor holds
+* the live camera separately from the persisted document. Here it only serves
+* as an initial camera hint when a document is first loaded.
+*/
+const BoardViewportSchema = z.object({
+	x: z.number().finite(),
+	y: z.number().finite(),
+	zoom: z.number().finite().min(.05).max(8)
+});
+const BoardAppearanceSchema = z.object({
+	theme: z.string().min(1).default("clean"),
+	background: z.object({
+		kind: z.enum([
+			"solid",
+			"dots",
+			"grid",
+			"image",
+			"shader",
+			"custom"
+		]).default("dots"),
+		color: z.string().optional(),
+		imageUrl: z.string().url().optional()
+	}).default({ kind: "solid" }),
+	grid: z.object({
+		visible: z.boolean().default(false),
+		size: z.number().finite().min(4).default(24),
+		opacity: z.number().finite().min(0).max(1).default(.12)
+	}).default({
+		visible: false,
+		size: 24,
+		opacity: .12
+	}),
+	mood: z.enum([
+		"clean",
+		"playful",
+		"arcane",
+		"cyber",
+		"natural"
+	]).default("clean")
+});
+/** Optional visual chrome still carried by a few older shapes. */
+const BoardItemStyleSchema = z.object({
+	variant: z.string().min(1).default("default"),
+	theme: z.string().min(1).optional(),
+	accentColor: z.string().optional(),
+	size: z.enum([
+		"sm",
+		"md",
+		"lg"
+	]).default("md"),
+	emphasis: z.enum([
+		"normal",
+		"rare",
+		"epic",
+		"legendary"
+	]).default("normal"),
+	effects: z.array(z.string().min(1)).default([])
+});
+const SpaceFileRefSchema = z.object({
+	kind: z.literal("space-file"),
+	path: z.string().min(1)
+});
+const BoardMediaSnapshotSchema = z.object({
+	title: z.string().optional(),
+	mimeType: z.string().optional(),
+	size: z.number().finite().nonnegative().optional(),
+	mtimeMs: z.number().finite().nonnegative().optional(),
+	/** Intrinsic pixel size once known. */
+	naturalWidth: z.number().finite().positive().optional(),
+	naturalHeight: z.number().finite().positive().optional()
+});
+const BoardItemBaseSchema = z.object({
+	id: z.string().min(1),
+	frame: BoardFrameSchema,
+	/** When true the shape cannot be moved, resized, or deleted. */
+	locked: z.boolean().optional(),
+	style: BoardItemStyleSchema.optional(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+/** Freestanding text — no card chrome; its frame always follows the glyphs. */
+const BoardTextItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("text"),
+	text: z.string().default(""),
+	color: z.string().min(1).default("neutral"),
+	fontSize: z.number().finite().min(2).max(512).default(18)
+});
+const BoardNoteItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("note"),
+	text: z.string().default(""),
+	color: z.string().min(1).default("amber")
+});
+const BoardGeoItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("geo"),
+	geo: z.string().min(1).default("rectangle"),
+	text: z.string().default(""),
+	color: z.string().min(1).default("brand"),
+	fillOpacity: z.number().finite().min(0).max(1).default(0)
+});
+/** A raw freehand sample. Pressure defaults to 0.5 (mouse) when absent. */
+const DrawPointSchema = z.object({
+	x: z.number().finite(),
+	y: z.number().finite(),
+	p: z.number().finite().min(0).max(1).default(.5)
+});
+const BoardDrawItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("draw"),
+	points: z.array(DrawPointSchema).default([]),
+	color: z.string().min(1).default("brand"),
+	size: z.number().finite().positive().default(4)
+});
+/** An arrow endpoint: a free point or a binding to another shape. */
+const ArrowEndpointSchema = z.union([z.object({
+	kind: z.literal("point"),
+	x: z.number().finite(),
+	y: z.number().finite()
+}), z.object({
+	kind: z.literal("binding"),
+	target: z.string().min(1),
+	nx: z.number().finite().default(.5),
+	ny: z.number().finite().default(.5),
+	precise: z.boolean().default(true)
+})]);
+const BoardArrowItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("arrow"),
+	start: ArrowEndpointSchema,
+	end: ArrowEndpointSchema,
+	bend: z.number().finite().default(0),
+	color: z.string().min(1).default("brand"),
+	size: z.number().finite().positive().default(2.5),
+	arrowStart: z.boolean().default(false),
+	arrowEnd: z.boolean().default(true),
+	label: z.string().default("")
+});
+/** A frame container for organising shapes. */
+const BoardFrameItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("frame"),
+	label: z.string().default("Frame"),
+	color: z.string().min(1).default("neutral")
+});
+/** Image node — space file only, natural aspect, no chrome. */
+const BoardImageItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("image"),
+	ref: SpaceFileRefSchema,
+	snapshot: BoardMediaSnapshotSchema.optional(),
+	/** Optional normalized crop in source image space (0..1). */
+	crop: z.object({
+		x: z.number().finite().min(0).max(1).default(0),
+		y: z.number().finite().min(0).max(1).default(0),
+		w: z.number().finite().min(0).max(1).default(1),
+		h: z.number().finite().min(0).max(1).default(1)
+	}).optional()
+});
+/** Video node — space file only. Playback state is local UI, never synced. */
+const BoardVideoItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("video"),
+	ref: SpaceFileRefSchema,
+	snapshot: BoardMediaSnapshotSchema.optional()
+});
+/**
+* Cached display facts for a file card.
+*
+* Purely derived from the referenced file and versioned by `mtimeMs`, so it is a
+* cache and never a second source of truth: the workspace file remains
+* authoritative, and a stale snapshot is detectable rather than silently wrong.
+* It is stored so that opening a board renders complete cards immediately, with
+* no per-node file read on the first paint.
+*/
+const BoardFileSnapshotSchema = z.object({
+	title: z.string().optional(),
+	mimeType: z.string().optional(),
+	size: z.number().finite().nonnegative().optional(),
+	mtimeMs: z.number().finite().nonnegative().optional(),
+	/** Cleaned leading prose. Capped when written (see FILE_EXCERPT_MAX_CHARS). */
+	excerpt: z.string().optional(),
+	/** Cover image inside the space, already resolved to a workspace path. */
+	coverPath: z.string().optional(),
+	/** Cover image at an absolute https URL, as declared by the file itself. */
+	coverUrl: z.string().optional()
+});
+/**
+* File node — a thumbnail entry point to any workspace file.
+*
+* This is the fallback for every dropped file that is not natively an image or
+* video, including binaries and unknown extensions: a board should never refuse
+* a file, only present it with less detail. Presentation tiers are derived from
+* the snapshot (see filePreviewKind), not stored, so there is no display state
+* to drift from the facts.
+*/
+const BoardFileItemSchema = BoardItemBaseSchema.extend({
+	type: z.literal("file"),
+	ref: SpaceFileRefSchema,
+	snapshot: BoardFileSnapshotSchema.optional()
+});
+/**
+* The set of shape types this client understands natively. Anything else is
+* preserved verbatim as an unknown item (see BoardUnknownItem) so documents
+* authored by newer clients round-trip losslessly — data is never dropped or
+* silently downgraded just because this client predates a shape type.
+*/
+const KNOWN_BOARD_ITEM_TYPES = [
+	"image",
+	"video",
+	"file",
+	"text",
+	"note",
+	"geo",
+	"draw",
+	"arrow",
+	"frame"
+];
+/**
+* A forward-compatible carrier for shape types this client does not recognise.
+* Its discriminant is the literal `"unknown"` so the item union still narrows
+* cleanly on `type`. The real type string and every original field are preserved
+* verbatim in `raw`.
+*/
+const UNKNOWN_BOARD_ITEM_TYPE = "unknown";
+/** The real (preserved) type string of an unknown item. */
+function unknownRealType(item) {
+	const real = item.raw.type;
+	return typeof real === "string" && real ? real : "unknown";
+}
+const BoardItemSchema = z.any().transform((raw) => parseBoardItemLoose(raw));
+/**
+* Parse a single item leniently: known types are validated and normalised;
+* anything else becomes a lossless unknown item. Never throws on shape data —
+* a malformed known item degrades to unknown rather than failing the document.
+*/
+function parseBoardItemLoose(raw) {
+	if (!raw || typeof raw !== "object") return makeUnknownItem(raw);
+	switch (raw.type) {
+		case "image": {
+			const parsed = BoardImageItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "video": {
+			const parsed = BoardVideoItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "file": {
+			const parsed = BoardFileItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "text": {
+			const parsed = BoardTextItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "note": {
+			const parsed = BoardNoteItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "geo": {
+			const parsed = BoardGeoItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "draw": {
+			const parsed = BoardDrawItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "arrow": {
+			const parsed = BoardArrowItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		case "frame": {
+			const parsed = BoardFrameItemSchema.safeParse(raw);
+			return parsed.success ? parsed.data : makeUnknownItem(raw);
+		}
+		default: return makeUnknownItem(raw);
+	}
+}
+function makeUnknownItem(raw) {
+	const record = raw && typeof raw === "object" ? raw : {};
+	const frameParsed = BoardFrameSchema.safeParse(record.frame);
+	const styleParsed = BoardItemStyleSchema.safeParse(record.style);
+	return {
+		id: typeof record.id === "string" && record.id ? record.id : "unknown",
+		type: UNKNOWN_BOARD_ITEM_TYPE,
+		frame: frameParsed.success ? frameParsed.data : {
+			x: 0,
+			y: 0,
+			width: 120,
+			height: 80,
+			rotation: 0
+		},
+		...record.locked === true ? { locked: true } : {},
+		...styleParsed.success && record.style ? { style: styleParsed.data } : {},
+		...record.metadata && typeof record.metadata === "object" ? { metadata: record.metadata } : {},
+		raw: record
+	};
+}
+const BoardDocumentSchema = z.object({
+	kind: z.literal(BOARD_DOCUMENT_KIND),
+	version: z.literal(1),
+	appearance: BoardAppearanceSchema.default({
+		theme: "clean",
+		background: { kind: "solid" },
+		grid: {
+			visible: false,
+			size: 24,
+			opacity: .12
+		},
+		mood: "clean"
+	}),
+	viewport: BoardViewportSchema,
+	items: z.array(BoardItemSchema)
+});
+function isUnknownItem(item) {
+	return item.type === UNKNOWN_BOARD_ITEM_TYPE;
+}
+function isMediaItem(item) {
+	return item.type === "image" || item.type === "video";
+}
+/** Whether an item references a workspace file (image, video or file card). */
+function isFileBackedItem(item) {
+	return item.type === "image" || item.type === "video" || item.type === "file";
+}
+//#endregion
+export { ArrowEndpointSchema, BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BoardAppearanceSchema, BoardArrowItemSchema, BoardDocumentSchema, BoardDrawItemSchema, BoardFileItemSchema, BoardFileSnapshotSchema, BoardFrameItemSchema, BoardFrameSchema, BoardGeoItemSchema, BoardImageItemSchema, BoardItemSchema, BoardItemStyleSchema, BoardMediaSnapshotSchema, BoardNoteItemSchema, BoardTextItemSchema, BoardVideoItemSchema, BoardViewportSchema, DrawPointSchema, KNOWN_BOARD_ITEM_TYPES, SpaceFileRefSchema, UNKNOWN_BOARD_ITEM_TYPE, isFileBackedItem, isMediaItem, isUnknownItem, parseBoardItemLoose, unknownRealType };

package/dist/protocol/dist/board.d.ts

@@ -0,0 +1,186 @@
+import { BoardCapability, BoardRenderCost } from "./board-constants.js";
+import { z } from "zod";
+//#region ../protocol/dist/board.d.ts
+declare const BOARD_EXTENSION: ".board";
+declare const BOARD_DOCUMENT_KIND: "cohub.board";
+declare const BoardManifestSchema: z.ZodObject<{
+  kind: z.ZodLiteral<"cohub.board.manifest">;
+  version: z.ZodLiteral<1>;
+  boardId: z.ZodString;
+  title: z.ZodString;
+}, z.core.$strip>;
+type BoardManifest = z.infer<typeof BoardManifestSchema>;
+declare class InvalidBoardFileError extends Error {
+  readonly code = "INVALID_BOARD_FILE";
+  constructor(message?: string);
+}
+declare function parseBoardManifest(input: string | unknown): BoardManifest;
+declare function serializeBoardManifest(manifest: BoardManifest): string;
+declare const BoardTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<"node">;
+  nodeId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"effect">;
+  effectId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"board">;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"camera">;
+}, z.core.$strip>], "type">;
+declare const BoardAssetRefSchema: z.ZodObject<{
+  type: z.ZodEnum<{
+    extension: "extension";
+    "space-file": "space-file";
+  }>;
+  ref: z.ZodString;
+  digest: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const BoardClipSchema: z.ZodObject<{
+  id: z.ZodString;
+  sequenceId: z.ZodString;
+  kind: z.ZodString;
+  kindVersion: z.ZodNumber;
+  target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"node">;
+    nodeId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"effect">;
+    effectId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"board">;
+  }, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"camera">;
+  }, z.core.$strip>], "type">;
+  start: z.ZodNumber;
+  duration: z.ZodNumber;
+  layer: z.ZodDefault<z.ZodEnum<{
+    behind: "behind";
+    content: "content";
+    front: "front";
+    screen: "screen";
+  }>>;
+  fill: z.ZodDefault<z.ZodEnum<{
+    backwards: "backwards";
+    both: "both";
+    forwards: "forwards";
+    none: "none";
+  }>>;
+  easing: z.ZodDefault<z.ZodString>;
+  params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  keyframes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    at: z.ZodNumber;
+    value: z.ZodUnknown;
+    easing: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  assetRefs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    type: z.ZodEnum<{
+      extension: "extension";
+      "space-file": "space-file";
+    }>;
+    ref: z.ZodString;
+    digest: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  seed: z.ZodString;
+  metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const BoardEffectSchema: z.ZodObject<{
+  id: z.ZodString;
+  boardId: z.ZodString;
+  target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"node">;
+    nodeId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"board">;
+  }, z.core.$strip>], "type">;
+  kind: z.ZodString;
+  kindVersion: z.ZodNumber;
+  enabled: z.ZodDefault<z.ZodBoolean>;
+  lifecycle: z.ZodEnum<{
+    manual: "manual";
+    persistent: "persistent";
+    "when-visible": "when-visible";
+  }>;
+  timeOrigin: z.ZodEnum<{
+    activation: "activation";
+    board: "board";
+    visible: "visible";
+  }>;
+  layer: z.ZodDefault<z.ZodEnum<{
+    behind: "behind";
+    front: "front";
+    screen: "screen";
+  }>>;
+  seed: z.ZodString;
+  params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  assetRefs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    type: z.ZodEnum<{
+      extension: "extension";
+      "space-file": "space-file";
+    }>;
+    ref: z.ZodString;
+    digest: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  revision: z.ZodNumber;
+}, z.core.$strip>;
+declare const BoardSequenceSchema: z.ZodObject<{
+  id: z.ZodString;
+  boardId: z.ZodString;
+  name: z.ZodString;
+  duration: z.ZodNumber;
+  seed: z.ZodString;
+  restPose: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  revision: z.ZodNumber;
+}, z.core.$strip>;
+type BoardTarget = z.infer<typeof BoardTargetSchema>;
+type BoardAssetRef = z.infer<typeof BoardAssetRefSchema>;
+type BoardClip = z.infer<typeof BoardClipSchema>;
+type BoardEffect = z.infer<typeof BoardEffectSchema>;
+type BoardSequence = z.infer<typeof BoardSequenceSchema>;
+type BoardRecord = {
+  id: string;
+  spaceId: string;
+  title: string;
+  version: number;
+  metadata: Record<string, unknown>;
+  createdAt: string | null;
+  updatedAt: string | null;
+};
+type BoardNodeRecord = {
+  boardId: string;
+  nodeId: string;
+  type: string;
+  parentId: string | null;
+  orderKey: string | null;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rotation: number;
+  refKind: string | null;
+  refPath: string | null;
+  refUrl: string | null;
+  view: Record<string, unknown>;
+  style: Record<string, unknown>;
+  data: Record<string, unknown>;
+  version: number;
+  createdAt: string | null;
+  updatedAt: string | null;
+};
+type BoardNodeInput = Omit<BoardNodeRecord, "boardId" | "version" | "createdAt" | "updatedAt">;
+type BoardDiagnostic = {
+  severity: "info" | "warning" | "error";
+  code: string;
+  message: string;
+  path?: string;
+  adaptation?: Record<string, unknown>;
+};
+type BoardValidationResult = {
+  valid: boolean;
+  diagnostics: BoardDiagnostic[];
+  peakCost: BoardRenderCost;
+};
+declare function isBoardPath(path: string): boolean;
+//#endregion
+export { BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BoardAssetRef, BoardAssetRefSchema, BoardClip, BoardClipSchema, BoardDiagnostic, BoardEffect, BoardEffectSchema, BoardManifest, BoardManifestSchema, BoardNodeInput, BoardNodeRecord, BoardRecord, BoardSequence, BoardSequenceSchema, BoardTarget, BoardTargetSchema, BoardValidationResult, InvalidBoardFileError, isBoardPath, parseBoardManifest, serializeBoardManifest };