@neta-art/cohub 5.3.2 → 5.4.0

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

@@ -0,0 +1,215 @@
+import { BOARD_CONNECTION_STROKE_SIZE, clampBoardStrokeSize } from "./board-constants.js";
+import { z } from "zod";
+//#region ../protocol/dist/board-connection.js
+/**
+* Board connections — the first-class relation between two Board nodes.
+*
+* A connection is *not* a shape. It has no frame of its own: its geometry is
+* derived entirely from the two nodes it joins, which is exactly why it belongs
+* in its own entity rather than in the item list. Storing it as a node would
+* force a bounding box to be persisted and kept in sync with both endpoints —
+* a second source of truth that is stale the moment either node moves.
+*
+* The stored form is therefore purely semantic: which nodes, in which direction,
+* anchored where, routed how. Every world coordinate is resolved at read time
+* from the live node frames (see the SDK's connection geometry), so a connection
+* can never drift from the nodes it describes.
+*
+* Agents read this model directly: `source`, `target`, `relation` and `label`
+* carry the meaning, while `routing` and `style` carry only presentation. A
+* reader that wants the graph never has to interpret pixels.
+*/
+/** Sides of a node frame a connection can attach to. */
+const BOARD_CONNECTION_SIDES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+/**
+* Where a connection meets its node.
+*
+* - `auto` — the side is chosen from the live geometry of both endpoints, so the
+*   connection stays sensible through any move or resize. This is the default and
+*   what almost every connection should use.
+* - `side` — the user pinned a side; `offset` (0..1) positions it along that edge.
+* - `fixed` — the user pinned an exact normalized point on the frame.
+*
+* `auto` is a *declaration of intent*, not a computed value: the resolved side is
+* never written back, so the connection keeps adapting instead of freezing the
+* first layout it happened to have.
+*/
+const BoardConnectionAnchorSchema = z.union([
+	z.object({ kind: z.literal("auto") }),
+	z.object({
+		kind: z.literal("side"),
+		side: z.enum(BOARD_CONNECTION_SIDES),
+		offset: z.number().finite().min(0).max(1).default(.5)
+	}),
+	z.object({
+		kind: z.literal("fixed"),
+		nx: z.number().finite().min(0).max(1),
+		ny: z.number().finite().min(0).max(1)
+	})
+]);
+const AUTO_BOARD_CONNECTION_ANCHOR = { kind: "auto" };
+const BoardConnectionEndpointSchema = z.object({
+	nodeId: z.string().min(1).max(160),
+	anchor: BoardConnectionAnchorSchema.default(AUTO_BOARD_CONNECTION_ANCHOR)
+});
+/**
+* Which ends carry an arrowhead.
+*
+* This is the *semantic* direction, not a style flag: `forward` means the
+* relation reads source → target, `backward` means target → source, and `none`
+* means the relation is symmetric. Renderers derive arrowheads from it, so the
+* drawing can never disagree with the meaning.
+*/
+const BOARD_CONNECTION_DIRECTIONS = [
+	"none",
+	"forward",
+	"backward",
+	"both"
+];
+/** How the line travels between its two resolved endpoints. */
+const BOARD_CONNECTION_ROUTINGS = [
+	"straight",
+	"curve",
+	"orthogonal"
+];
+const BOARD_CONNECTION_LINES = ["solid", "dashed"];
+/**
+* The default relation kind.
+*
+* "related" is deliberately unopinionated: drawing a line between two nodes
+* states that they are connected, not *how*. A stronger claim (depends-on,
+* blocks, ...) is something the user or an agent asserts explicitly.
+*/
+const DEFAULT_BOARD_RELATION = "related";
+/**
+* Relation kind — a free-form slug, not an enum.
+*
+* Boards are used for domains we do not control, so a closed vocabulary would
+* force unrelated meanings into the wrong bucket. The format is constrained
+* (lowercase, dash/dot separated) so relations stay comparable and queryable
+* across clients instead of accumulating near-duplicate spellings.
+*/
+const BoardRelationSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/, "relation must be a lowercase slug").default(DEFAULT_BOARD_RELATION);
+/**
+* Waypoints a user dragged the line through, in world space.
+*
+* Stored because they are *input*, not output: the resolved path is recomputed
+* from them on every read, but the intent behind a hand-routed line cannot be
+* recovered once discarded.
+*/
+const BoardConnectionWaypointSchema = z.object({
+	x: z.number().finite(),
+	y: z.number().finite()
+});
+const BoardConnectionRoutingSchema = z.object({
+	kind: z.enum(BOARD_CONNECTION_ROUTINGS).default("curve"),
+	/** Curve bow as a fraction of endpoint distance (-0.85..0.85). */
+	bend: z.number().finite().min(-.85).max(.85).default(0),
+	waypoints: z.array(BoardConnectionWaypointSchema).max(64).default([])
+});
+const BoardConnectionStyleSchema = z.object({
+	/** Palette color id, resolved to a theme token at render time. */
+	color: z.string().min(1).max(40).default("brand"),
+	size: z.number().finite().positive().default(BOARD_CONNECTION_STROKE_SIZE),
+	line: z.enum(BOARD_CONNECTION_LINES).default("solid")
+});
+const DEFAULT_BOARD_CONNECTION_ROUTING = {
+	kind: "curve",
+	bend: 0,
+	waypoints: []
+};
+const DEFAULT_BOARD_CONNECTION_STYLE = {
+	color: "brand",
+	size: BOARD_CONNECTION_STROKE_SIZE,
+	line: "solid"
+};
+const BoardConnectionSchema = z.object({
+	id: z.string().min(1).max(160),
+	source: BoardConnectionEndpointSchema,
+	target: BoardConnectionEndpointSchema,
+	relation: BoardRelationSchema,
+	direction: z.enum(BOARD_CONNECTION_DIRECTIONS).default("forward"),
+	label: z.string().max(280).default(""),
+	routing: BoardConnectionRoutingSchema.default(DEFAULT_BOARD_CONNECTION_ROUTING),
+	style: BoardConnectionStyleSchema.default(DEFAULT_BOARD_CONNECTION_STYLE),
+	metadata: z.record(z.string(), z.unknown()).default({})
+});
+/**
+* A patch to an existing connection.
+*
+* `id` is excluded: a connection's identity never changes, and re-pointing both
+* endpoints is an edit of the same relation, not a new one.
+*/
+const BoardConnectionPatchSchema = BoardConnectionSchema.omit({ id: true }).partial();
+/** Both node ids a connection touches, deduped for a self-loop. */
+function connectionNodeIds(connection) {
+	return connection.source.nodeId === connection.target.nodeId ? [connection.source.nodeId] : [connection.source.nodeId, connection.target.nodeId];
+}
+/** Whether a connection touches the given node. */
+function connectionTouchesNode(connection, nodeId) {
+	return connection.source.nodeId === nodeId || connection.target.nodeId === nodeId;
+}
+/** The node at the far end of a connection from `nodeId`, or null. */
+function connectionOtherNodeId(connection, nodeId) {
+	if (connection.source.nodeId === nodeId) return connection.target.nodeId;
+	if (connection.target.nodeId === nodeId) return connection.source.nodeId;
+	return null;
+}
+function normalizeBoardConnectionStyle(style) {
+	return {
+		color: style?.color?.trim() || DEFAULT_BOARD_CONNECTION_STYLE.color,
+		size: clampBoardStrokeSize(typeof style?.size === "number" && Number.isFinite(style.size) ? style.size : DEFAULT_BOARD_CONNECTION_STYLE.size),
+		line: style?.line ?? DEFAULT_BOARD_CONNECTION_STYLE.line
+	};
+}
+/**
+* Build a connection with every default filled in.
+*
+* Callers only state what they mean (which nodes, and optionally the relation),
+* so a connection created by the editor, an agent or the CLI is byte-identical
+* for the same intent.
+*/
+function createBoardConnection(input) {
+	return {
+		id: input.id,
+		source: {
+			nodeId: input.sourceNodeId,
+			anchor: input.sourceAnchor ?? AUTO_BOARD_CONNECTION_ANCHOR
+		},
+		target: {
+			nodeId: input.targetNodeId,
+			anchor: input.targetAnchor ?? AUTO_BOARD_CONNECTION_ANCHOR
+		},
+		relation: input.relation ?? "related",
+		direction: input.direction ?? "forward",
+		label: input.label ?? "",
+		routing: {
+			...DEFAULT_BOARD_CONNECTION_ROUTING,
+			...input.routing
+		},
+		style: normalizeBoardConnectionStyle(input.style),
+		metadata: input.metadata ?? {}
+	};
+}
+/** Reverse a connection's endpoints, preserving the relation's reading order. */
+function flipBoardConnection(connection) {
+	const direction = connection.direction === "forward" ? "backward" : connection.direction === "backward" ? "forward" : connection.direction;
+	return {
+		...connection,
+		source: connection.target,
+		target: connection.source,
+		direction,
+		routing: {
+			...connection.routing,
+			bend: -connection.routing.bend,
+			waypoints: [...connection.routing.waypoints].reverse()
+		}
+	};
+}
+//#endregion
+export { AUTO_BOARD_CONNECTION_ANCHOR, BOARD_CONNECTION_DIRECTIONS, BOARD_CONNECTION_LINES, BOARD_CONNECTION_ROUTINGS, BOARD_CONNECTION_SIDES, BoardConnectionAnchorSchema, BoardConnectionEndpointSchema, BoardConnectionPatchSchema, BoardConnectionRoutingSchema, BoardConnectionSchema, BoardConnectionStyleSchema, BoardConnectionWaypointSchema, BoardRelationSchema, DEFAULT_BOARD_CONNECTION_ROUTING, DEFAULT_BOARD_CONNECTION_STYLE, DEFAULT_BOARD_RELATION, connectionNodeIds, connectionOtherNodeId, connectionTouchesNode, createBoardConnection, flipBoardConnection, normalizeBoardConnectionStyle };

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

@@ -19,5 +19,15 @@ type BoardCapability = {
   fallbackId?: string;
   schema?: Record<string, unknown>;
 };
+/**
+ * Stroke width bounds, shared by every stroked board entity.
+ *
+ * Defined here (not beside the editor) because the persisted schemas clamp with
+ * them: a single range is what keeps a width authored by the editor, an agent or
+ * the CLI from being silently re-clamped to something else on read.
+ */
+declare const BOARD_STROKE_MIN_SIZE = 1;
+declare const BOARD_STROKE_MAX_SIZE = 64;
+declare function clampBoardStrokeSize(size: number): number;
 //#endregion
-export { BoardCapability, BoardRenderCost };
+export { BOARD_STROKE_MAX_SIZE, BOARD_STROKE_MIN_SIZE, BoardCapability, BoardRenderCost, clampBoardStrokeSize };

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

@@ -35,6 +35,20 @@ const BOARD_BUILTIN_EFFECT_KINDS = ["effects.pulse", "effects.float"];
 */
 const BOARD_TEXT_FONT_FAMILY = "Geist";
 const BOARD_ARROW_STROKE_SIZE = 2.5;
+const BOARD_CONNECTION_STROKE_SIZE = 2.5;
+/**
+* Stroke width bounds, shared by every stroked board entity.
+*
+* Defined here (not beside the editor) because the persisted schemas clamp with
+* them: a single range is what keeps a width authored by the editor, an agent or
+* the CLI from being silently re-clamped to something else on read.
+*/
+const BOARD_STROKE_MIN_SIZE = 1;
+const BOARD_STROKE_MAX_SIZE = 64;
+function clampBoardStrokeSize(size) {
+	if (!Number.isFinite(size)) return BOARD_CONNECTION_STROKE_SIZE;
+	return Math.min(64, Math.max(1, size));
+}
 /**
 * Font stacks used by every board renderer.
 *
@@ -58,4 +72,4 @@ const BOARD_BUILTIN_CAPABILITIES = [...BOARD_BUILTIN_CLIP_KINDS.map((id) => ({
 	renderers: ["webgpu", "webgl"]
 }))];
 //#endregion
-export { BOARD_ARROW_STROKE_SIZE, BOARD_BUILTIN_CAPABILITIES, BOARD_BUILTIN_CLIP_KINDS, BOARD_BUILTIN_EFFECT_KINDS, BOARD_FONT_STACK, BOARD_MONO_FONT_STACK, BOARD_TEXT_FONT_FAMILY, DEFAULT_BOARD_RENDER_LIMITS };
+export { BOARD_ARROW_STROKE_SIZE, BOARD_BUILTIN_CAPABILITIES, BOARD_BUILTIN_CLIP_KINDS, BOARD_BUILTIN_EFFECT_KINDS, BOARD_CONNECTION_STROKE_SIZE, BOARD_FONT_STACK, BOARD_MONO_FONT_STACK, BOARD_STROKE_MAX_SIZE, BOARD_STROKE_MIN_SIZE, BOARD_TEXT_FONT_FAMILY, DEFAULT_BOARD_RENDER_LIMITS, clampBoardStrokeSize };

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

@@ -150,6 +150,11 @@ declare const DrawPointSchema: z.ZodObject<{
   y: z.ZodNumber;
   p: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
+/** A world-space point. */
+declare const BoardPointSchema: z.ZodObject<{
+  x: z.ZodNumber;
+  y: z.ZodNumber;
+}, z.core.$strip>;
 declare const BoardDrawItemSchema: z.ZodObject<{
   id: z.ZodString;
   frame: z.ZodObject<{
@@ -187,18 +192,15 @@ declare const BoardDrawItemSchema: z.ZodObject<{
   color: z.ZodDefault<z.ZodString>;
   size: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
-/** An arrow endpoint: a free point or a binding to another shape. */
-declare const ArrowEndpointSchema: z.ZodUnion<readonly [z.ZodObject<{
-  kind: z.ZodLiteral<"point">;
-  x: z.ZodNumber;
-  y: z.ZodNumber;
-}, z.core.$strip>, z.ZodObject<{
-  kind: z.ZodLiteral<"binding">;
-  target: z.ZodString;
-  nx: z.ZodDefault<z.ZodNumber>;
-  ny: z.ZodDefault<z.ZodNumber>;
-  precise: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>]>;
+/**
+ * A free arrow — a standalone annotation stroke between two world points.
+ *
+ * Arrows do not relate nodes. A relation between two nodes is a
+ * `BoardConnection`, which is stored separately and resolves its geometry from
+ * the live node frames. Keeping the two apart is what lets an arrow be a plain
+ * shape (its own frame, freely movable) while a connection stays purely
+ * semantic — neither has to pretend to be the other.
+ */
 declare const BoardArrowItemSchema: z.ZodObject<{
   id: z.ZodString;
   frame: z.ZodObject<{
@@ -228,28 +230,14 @@ declare const BoardArrowItemSchema: z.ZodObject<{
   }, z.core.$strip>>;
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   type: z.ZodLiteral<"arrow">;
-  start: z.ZodUnion<readonly [z.ZodObject<{
-    kind: z.ZodLiteral<"point">;
+  start: z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;
-  }, z.core.$strip>, z.ZodObject<{
-    kind: z.ZodLiteral<"binding">;
-    target: z.ZodString;
-    nx: z.ZodDefault<z.ZodNumber>;
-    ny: z.ZodDefault<z.ZodNumber>;
-    precise: z.ZodDefault<z.ZodBoolean>;
-  }, z.core.$strip>]>;
-  end: z.ZodUnion<readonly [z.ZodObject<{
-    kind: z.ZodLiteral<"point">;
+  }, z.core.$strip>;
+  end: z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;
-  }, z.core.$strip>, z.ZodObject<{
-    kind: z.ZodLiteral<"binding">;
-    target: z.ZodString;
-    nx: z.ZodDefault<z.ZodNumber>;
-    ny: z.ZodDefault<z.ZodNumber>;
-    precise: z.ZodDefault<z.ZodBoolean>;
-  }, z.core.$strip>]>;
+  }, z.core.$strip>;
   bend: z.ZodDefault<z.ZodNumber>;
   color: z.ZodDefault<z.ZodString>;
   size: z.ZodDefault<z.ZodNumber>;
@@ -677,26 +665,12 @@ declare const BoardItemSchema: z.ZodPipe<z.ZodAny, z.ZodTransform<BoardUnknownIt
   metadata?: Record<string, unknown> | undefined;
   type: "arrow";
   start: {
-    kind: "point";
     x: number;
     y: number;
-  } | {
-    kind: "binding";
-    target: string;
-    nx: number;
-    ny: number;
-    precise: boolean;
   };
   end: {
-    kind: "point";
     x: number;
     y: number;
-  } | {
-    kind: "binding";
-    target: string;
-    nx: number;
-    ny: number;
-    precise: boolean;
   };
   bend: number;
   color: string;
@@ -966,26 +940,12 @@ declare const BoardDocumentSchema: z.ZodObject<{
     metadata?: Record<string, unknown> | undefined;
     type: "arrow";
     start: {
-      kind: "point";
       x: number;
       y: number;
-    } | {
-      kind: "binding";
-      target: string;
-      nx: number;
-      ny: number;
-      precise: boolean;
     };
     end: {
-      kind: "point";
       x: number;
       y: number;
-    } | {
-      kind: "binding";
-      target: string;
-      nx: number;
-      ny: number;
-      precise: boolean;
     };
     bend: number;
     color: string;
@@ -1016,6 +976,76 @@ declare const BoardDocumentSchema: z.ZodObject<{
     label: string;
     color: string;
   }, any>>>;
+  connections: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodObject<{
+      nodeId: z.ZodString;
+      anchor: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"auto">;
+      }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"side">;
+        side: z.ZodEnum<{
+          bottom: "bottom";
+          left: "left";
+          right: "right";
+          top: "top";
+        }>;
+        offset: z.ZodDefault<z.ZodNumber>;
+      }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"fixed">;
+        nx: z.ZodNumber;
+        ny: z.ZodNumber;
+      }, z.core.$strip>]>>;
+    }, z.core.$strip>;
+    target: z.ZodObject<{
+      nodeId: z.ZodString;
+      anchor: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"auto">;
+      }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"side">;
+        side: z.ZodEnum<{
+          bottom: "bottom";
+          left: "left";
+          right: "right";
+          top: "top";
+        }>;
+        offset: z.ZodDefault<z.ZodNumber>;
+      }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"fixed">;
+        nx: z.ZodNumber;
+        ny: z.ZodNumber;
+      }, z.core.$strip>]>>;
+    }, z.core.$strip>;
+    relation: z.ZodDefault<z.ZodString>;
+    direction: z.ZodDefault<z.ZodEnum<{
+      backward: "backward";
+      both: "both";
+      forward: "forward";
+      none: "none";
+    }>>;
+    label: z.ZodDefault<z.ZodString>;
+    routing: z.ZodDefault<z.ZodObject<{
+      kind: z.ZodDefault<z.ZodEnum<{
+        curve: "curve";
+        orthogonal: "orthogonal";
+        straight: "straight";
+      }>>;
+      bend: z.ZodDefault<z.ZodNumber>;
+      waypoints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    style: z.ZodDefault<z.ZodObject<{
+      color: z.ZodDefault<z.ZodString>;
+      size: z.ZodDefault<z.ZodNumber>;
+      line: z.ZodDefault<z.ZodEnum<{
+        dashed: "dashed";
+        solid: "solid";
+      }>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>>;
 }, z.core.$strip>;
 type BoardFrame = z.infer<typeof BoardFrameSchema>;
 type BoardViewport = z.infer<typeof BoardViewportSchema>;
@@ -1026,8 +1056,8 @@ type BoardMediaSnapshot = z.infer<typeof BoardMediaSnapshotSchema>;
 type BoardTextItem = z.infer<typeof BoardTextItemSchema>;
 type BoardGeoItem = z.infer<typeof BoardGeoItemSchema>;
 type DrawPoint = z.infer<typeof DrawPointSchema>;
+type BoardPoint = z.infer<typeof BoardPointSchema>;
 type BoardDrawItem = z.infer<typeof BoardDrawItemSchema>;
-type ArrowEndpoint = z.infer<typeof ArrowEndpointSchema>;
 type BoardArrowItem = z.infer<typeof BoardArrowItemSchema>;
 type BoardFrameItem = z.infer<typeof BoardFrameItemSchema>;
 type BoardImageItem = z.infer<typeof BoardImageItemSchema>;
@@ -1039,9 +1069,25 @@ type BoardKnownItem = BoardImageItem | BoardVideoItem | BoardFileItem | BoardTex
 /** Any item, including forward-compatible unknown types. */
 type BoardItem = BoardKnownItem | BoardUnknownItem;
 type BoardDocument = z.infer<typeof BoardDocumentSchema>;
+/**
+ * Parse a board document and drop connections whose endpoints are missing.
+ *
+ * The schema alone cannot express "every endpoint must name an existing item",
+ * so referential integrity is enforced here, at the single place a document
+ * enters the system. A dangling connection is dropped rather than repaired:
+ * there is no correct node to invent, and keeping it would render nothing while
+ * still counting as data.
+ *
+ * Item parsing stays lenient (see parseBoardItemLoose) — nodes carry content and
+ * are never discarded — while connections are pure references and are only
+ * meaningful with both ends present.
+ */
+declare function parseBoardDocument(input: unknown): BoardDocument;
+/** Keep only the connections whose endpoints both exist in `items`. */
+declare function withResolvedConnections(document: BoardDocument): BoardDocument;
 declare function isUnknownItem(item: BoardItem): item is BoardUnknownItem;
 declare function isMediaItem(item: BoardItem): item is BoardImageItem | BoardVideoItem;
 /** Whether an item references a workspace file (image, video or file card). */
 declare function isFileBackedItem(item: BoardItem): item is BoardImageItem | BoardVideoItem | BoardFileItem;
 //#endregion
-export { ArrowEndpoint, ArrowEndpointSchema, BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BoardAppearance, BoardAppearanceSchema, BoardArrowItem, BoardArrowItemSchema, BoardDocument, BoardDocumentSchema, BoardDrawItem, BoardDrawItemSchema, BoardFileItem, BoardFileItemSchema, BoardFileSnapshot, BoardFileSnapshotSchema, BoardFrame, BoardFrameItem, BoardFrameItemSchema, BoardFrameSchema, BoardGeoItem, BoardGeoItemSchema, BoardImageItem, BoardImageItemSchema, BoardItem, BoardItemSchema, BoardItemStyle, BoardItemStyleSchema, BoardKnownItem, BoardMediaSnapshot, BoardMediaSnapshotSchema, BoardTextItem, BoardTextItemSchema, BoardUnknownItem, BoardVideoItem, BoardVideoItemSchema, BoardViewport, BoardViewportSchema, DrawPoint, DrawPointSchema, KNOWN_BOARD_ITEM_TYPES, KnownBoardItemType, SpaceFileRef, SpaceFileRefSchema, UNKNOWN_BOARD_ITEM_TYPE, isFileBackedItem, isMediaItem, isUnknownItem, parseBoardItemLoose, unknownRealType };
+export { BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BoardAppearance, BoardAppearanceSchema, BoardArrowItem, BoardArrowItemSchema, BoardDocument, BoardDocumentSchema, BoardDrawItem, BoardDrawItemSchema, BoardFileItem, BoardFileItemSchema, BoardFileSnapshot, BoardFileSnapshotSchema, BoardFrame, BoardFrameItem, BoardFrameItemSchema, BoardFrameSchema, BoardGeoItem, BoardGeoItemSchema, BoardImageItem, BoardImageItemSchema, BoardItem, BoardItemSchema, BoardItemStyle, BoardItemStyleSchema, BoardKnownItem, BoardMediaSnapshot, BoardMediaSnapshotSchema, BoardPoint, BoardPointSchema, BoardTextItem, BoardTextItemSchema, BoardUnknownItem, BoardVideoItem, BoardVideoItemSchema, BoardViewport, BoardViewportSchema, DrawPoint, DrawPointSchema, KNOWN_BOARD_ITEM_TYPES, KnownBoardItemType, SpaceFileRef, SpaceFileRefSchema, UNKNOWN_BOARD_ITEM_TYPE, isFileBackedItem, isMediaItem, isUnknownItem, parseBoardDocument, parseBoardItemLoose, unknownRealType, withResolvedConnections };

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

@@ -1,4 +1,5 @@
 import { BOARD_ARROW_STROKE_SIZE } from "./board-constants.js";
+import { BoardConnectionSchema } from "./board-connection.js";
 import { BOARD_DOCUMENT_KIND, BOARD_EXTENSION } from "./board.js";
 import { z } from "zod";
 //#region ../protocol/dist/board-document.js
@@ -110,29 +111,31 @@ const DrawPointSchema = z.object({
 	y: z.number().finite(),
 	p: z.number().finite().min(0).max(1).default(.5)
 });
+/** A world-space point. */
+const BoardPointSchema = z.object({
+	x: z.number().finite(),
+	y: z.number().finite()
+});
 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)
-})]);
+/**
+* A free arrow — a standalone annotation stroke between two world points.
+*
+* Arrows do not relate nodes. A relation between two nodes is a
+* `BoardConnection`, which is stored separately and resolves its geometry from
+* the live node frames. Keeping the two apart is what lets an arrow be a plain
+* shape (its own frame, freely movable) while a connection stays purely
+* semantic — neither has to pretend to be the other.
+*/
 const BoardArrowItemSchema = BoardItemBaseSchema.extend({
 	type: z.literal("arrow"),
-	start: ArrowEndpointSchema,
-	end: ArrowEndpointSchema,
-	bend: z.number().finite().default(0),
+	start: BoardPointSchema,
+	end: BoardPointSchema,
+	bend: z.number().finite().min(-.85).max(.85).default(0),
 	color: z.string().min(1).default("brand"),
 	size: z.number().finite().positive().default(BOARD_ARROW_STROKE_SIZE),
 	arrowStart: z.boolean().default(false),
@@ -305,8 +308,45 @@ const BoardDocumentSchema = z.object({
 		mood: "clean"
 	}),
 	viewport: BoardViewportSchema,
-	items: z.array(BoardItemSchema)
+	items: z.array(BoardItemSchema),
+	/**
+	* Node relations. Separate from `items` because a connection has no frame of
+	* its own — its geometry is derived from the nodes it joins, so it is a
+	* relation over the item set rather than a member of it.
+	*
+	* Connections referencing a missing node are dropped on parse: a relation to
+	* nothing is not a relation, and keeping one would let an invisible dangling
+	* edge accumulate silently. Callers that need to know write through the
+	* transaction API, which reports the reference error instead.
+	*/
+	connections: z.array(BoardConnectionSchema).default([])
 });
+/**
+* Parse a board document and drop connections whose endpoints are missing.
+*
+* The schema alone cannot express "every endpoint must name an existing item",
+* so referential integrity is enforced here, at the single place a document
+* enters the system. A dangling connection is dropped rather than repaired:
+* there is no correct node to invent, and keeping it would render nothing while
+* still counting as data.
+*
+* Item parsing stays lenient (see parseBoardItemLoose) — nodes carry content and
+* are never discarded — while connections are pure references and are only
+* meaningful with both ends present.
+*/
+function parseBoardDocument(input) {
+	return withResolvedConnections(BoardDocumentSchema.parse(input));
+}
+/** Keep only the connections whose endpoints both exist in `items`. */
+function withResolvedConnections(document) {
+	if (document.connections.length === 0) return document;
+	const ids = new Set(document.items.map((item) => item.id));
+	const connections = document.connections.filter((connection) => ids.has(connection.source.nodeId) && ids.has(connection.target.nodeId));
+	return connections.length === document.connections.length ? document : {
+		...document,
+		connections
+	};
+}
 function isUnknownItem(item) {
 	return item.type === UNKNOWN_BOARD_ITEM_TYPE;
 }
@@ -318,4 +358,4 @@ 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, BoardTextItemSchema, BoardVideoItemSchema, BoardViewportSchema, DrawPointSchema, KNOWN_BOARD_ITEM_TYPES, SpaceFileRefSchema, UNKNOWN_BOARD_ITEM_TYPE, isFileBackedItem, isMediaItem, isUnknownItem, parseBoardItemLoose, unknownRealType };
+export { BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BoardAppearanceSchema, BoardArrowItemSchema, BoardDocumentSchema, BoardDrawItemSchema, BoardFileItemSchema, BoardFileSnapshotSchema, BoardFrameItemSchema, BoardFrameSchema, BoardGeoItemSchema, BoardImageItemSchema, BoardItemSchema, BoardItemStyleSchema, BoardMediaSnapshotSchema, BoardPointSchema, BoardTextItemSchema, BoardVideoItemSchema, BoardViewportSchema, DrawPointSchema, KNOWN_BOARD_ITEM_TYPES, SpaceFileRefSchema, UNKNOWN_BOARD_ITEM_TYPE, isFileBackedItem, isMediaItem, isUnknownItem, parseBoardDocument, parseBoardItemLoose, unknownRealType, withResolvedConnections };

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

@@ -1,4 +1,5 @@
 import { BoardCapability, BoardRenderCost } from "./board-constants.js";
+import "./board-connection.js";
 import { z } from "zod";
 //#region ../protocol/dist/board.d.ts
 declare const BOARD_EXTENSION: ".board";

package/dist/protocol/dist/board.js

@@ -1,4 +1,5 @@
 import "./board-constants.js";
+import { BoardConnectionSchema } from "./board-connection.js";
 import { z } from "zod";
 //#region ../protocol/dist/board.js
 const BOARD_EXTENSION = ".board";
@@ -149,6 +150,7 @@ z.object({
 	title: z.string().min(1).max(255).optional(),
 	metadata: jsonObjectSchema.optional(),
 	nodes: z.array(BoardNodeInputSchema).max(5e4).optional(),
+	connections: z.array(BoardConnectionSchema).max(5e4).optional(),
 	effects: z.array(BoardEffectSchema.omit({
 		boardId: true,
 		revision: true
@@ -164,6 +166,7 @@ z.object({
 z.object({
 	include: z.array(z.enum([
 		"nodes",
+		"connections",
 		"effects",
 		"sequences",
 		"clips",

package/dist/protocol/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { BoardCapability, BoardRenderCost } from "./board-constants.js";
+import { AUTO_BOARD_CONNECTION_ANCHOR, BOARD_CONNECTION_DIRECTIONS, BOARD_CONNECTION_LINES, BOARD_CONNECTION_ROUTINGS, BOARD_CONNECTION_SIDES, BoardConnection, BoardConnectionAnchor, BoardConnectionAnchorSchema, BoardConnectionDirection, BoardConnectionEndpoint, BoardConnectionEndpointSchema, BoardConnectionInput, BoardConnectionLine, BoardConnectionPatch, BoardConnectionPatchSchema, BoardConnectionRecord, BoardConnectionRouting, BoardConnectionRoutingConfig, BoardConnectionRoutingSchema, BoardConnectionSchema, BoardConnectionSide, BoardConnectionStyle, BoardConnectionStyleSchema, BoardConnectionWaypointSchema, BoardRelationSchema, DEFAULT_BOARD_CONNECTION_ROUTING, DEFAULT_BOARD_CONNECTION_STYLE, DEFAULT_BOARD_RELATION, connectionNodeIds, connectionOtherNodeId, connectionTouchesNode, createBoardConnection, flipBoardConnection, normalizeBoardConnectionStyle } from "./board-connection.js";
 import { 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 } from "./board.js";
 import "./realtime/board-awareness.js";
 import "./work.js";
 import "./realtime/types.js";
-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 };
+export { AUTO_BOARD_CONNECTION_ANCHOR, BOARD_CONNECTION_DIRECTIONS, BOARD_CONNECTION_LINES, BOARD_CONNECTION_ROUTINGS, BOARD_CONNECTION_SIDES, BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BoardAssetRef, BoardAssetRefSchema, BoardClip, BoardClipSchema, BoardConnection, BoardConnectionAnchor, BoardConnectionAnchorSchema, BoardConnectionDirection, BoardConnectionEndpoint, BoardConnectionEndpointSchema, BoardConnectionInput, BoardConnectionLine, BoardConnectionPatch, BoardConnectionPatchSchema, BoardConnectionRecord, BoardConnectionRouting, BoardConnectionRoutingConfig, BoardConnectionRoutingSchema, BoardConnectionSchema, BoardConnectionSide, BoardConnectionStyle, BoardConnectionStyleSchema, BoardConnectionWaypointSchema, BoardDiagnostic, BoardEffect, BoardEffectSchema, BoardManifest, BoardManifestSchema, BoardNodeInput, BoardNodeRecord, BoardRecord, BoardRelationSchema, BoardSequence, BoardSequenceSchema, BoardTarget, BoardTargetSchema, BoardValidationResult, DEFAULT_BOARD_CONNECTION_ROUTING, DEFAULT_BOARD_CONNECTION_STYLE, DEFAULT_BOARD_RELATION, InvalidBoardFileError, connectionNodeIds, connectionOtherNodeId, connectionTouchesNode, createBoardConnection, flipBoardConnection, isBoardPath, normalizeBoardConnectionStyle, parseBoardManifest, serializeBoardManifest };

package/dist/protocol/dist/index.js

@@ -1,7 +1,8 @@
 import "./board-constants.js";
+import { AUTO_BOARD_CONNECTION_ANCHOR, BOARD_CONNECTION_DIRECTIONS, BOARD_CONNECTION_LINES, BOARD_CONNECTION_ROUTINGS, BOARD_CONNECTION_SIDES, BoardConnectionAnchorSchema, BoardConnectionEndpointSchema, BoardConnectionPatchSchema, BoardConnectionRoutingSchema, BoardConnectionSchema, BoardConnectionStyleSchema, BoardConnectionWaypointSchema, BoardRelationSchema, DEFAULT_BOARD_CONNECTION_ROUTING, DEFAULT_BOARD_CONNECTION_STYLE, DEFAULT_BOARD_RELATION, connectionNodeIds, connectionOtherNodeId, connectionTouchesNode, createBoardConnection, flipBoardConnection, normalizeBoardConnectionStyle } from "./board-connection.js";
 import { BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BOARD_MANIFEST_KIND, BoardAssetRefSchema, BoardClipSchema, BoardEffectSchema, BoardKeyframeSchema, BoardManifestSchema, BoardNodeInputSchema, BoardSequenceSchema, BoardTargetSchema, InvalidBoardFileError, isBoardPath, parseBoardManifest, serializeBoardManifest } from "./board.js";
 import { BoardAwarenessDrawPointSchema, BoardAwarenessFrameSchema, BoardAwarenessGestureSchema, BoardAwarenessNodePreviewSchema, BoardAwarenessPointSchema, BoardAwarenessStateUpdateSchema, BoardAwarenessUpdateSchema } from "./realtime/board-awareness.js";
 import { COHUB_SOURCE_HEADER } from "./provenance.js";
 import { RESERVED_PLATFORM_PATH_SEGMENTS } from "./public-identifiers.js";
 import "./work-view-stats.js";
-export { BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BOARD_MANIFEST_KIND, BoardAssetRefSchema, BoardAwarenessDrawPointSchema, BoardAwarenessFrameSchema, BoardAwarenessGestureSchema, BoardAwarenessNodePreviewSchema, BoardAwarenessPointSchema, BoardAwarenessStateUpdateSchema, BoardAwarenessUpdateSchema, BoardClipSchema, BoardEffectSchema, BoardKeyframeSchema, BoardManifestSchema, BoardNodeInputSchema, BoardSequenceSchema, BoardTargetSchema, COHUB_SOURCE_HEADER, InvalidBoardFileError, RESERVED_PLATFORM_PATH_SEGMENTS, isBoardPath, parseBoardManifest, serializeBoardManifest };
+export { AUTO_BOARD_CONNECTION_ANCHOR, BOARD_CONNECTION_DIRECTIONS, BOARD_CONNECTION_LINES, BOARD_CONNECTION_ROUTINGS, BOARD_CONNECTION_SIDES, BOARD_DOCUMENT_KIND, BOARD_EXTENSION, BOARD_MANIFEST_KIND, BoardAssetRefSchema, BoardAwarenessDrawPointSchema, BoardAwarenessFrameSchema, BoardAwarenessGestureSchema, BoardAwarenessNodePreviewSchema, BoardAwarenessPointSchema, BoardAwarenessStateUpdateSchema, BoardAwarenessUpdateSchema, BoardClipSchema, BoardConnectionAnchorSchema, BoardConnectionEndpointSchema, BoardConnectionPatchSchema, BoardConnectionRoutingSchema, BoardConnectionSchema, BoardConnectionStyleSchema, BoardConnectionWaypointSchema, BoardEffectSchema, BoardKeyframeSchema, BoardManifestSchema, BoardNodeInputSchema, BoardRelationSchema, BoardSequenceSchema, BoardTargetSchema, COHUB_SOURCE_HEADER, DEFAULT_BOARD_CONNECTION_ROUTING, DEFAULT_BOARD_CONNECTION_STYLE, DEFAULT_BOARD_RELATION, InvalidBoardFileError, RESERVED_PLATFORM_PATH_SEGMENTS, connectionNodeIds, connectionOtherNodeId, connectionTouchesNode, createBoardConnection, flipBoardConnection, isBoardPath, normalizeBoardConnectionStyle, parseBoardManifest, serializeBoardManifest };