@neta-art/cohub 5.3.3 → 5.4.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as parseAssistantMessageCommit, B as ModelsApi, C as SpaceClient, D as buildSpacePath, E as buildSpaceInvitePath, F as ReferencesApi, H as CronJobsApi, I as SearchApi, L as PublicAssetsApi, M as createSessionPatchReducer, N as ensureRealtimeConnected, O as SessionGenerationStreamClient, P as SessionAccessApi, R as SkillsApi, S as BoardTransactionError, T as PublicInviteApi, U as ChannelsApi, V as GenerationsApi, _ as isUiSurfaceMethod, a as ReferralsApi, b as TasksApi, c as UiCommandsApi, d as UI_COMMAND_PAYLOAD_MAX_BYTES, f as UI_COMMAND_PENDING_TTL_SECONDS, g as isTerminalUiCommandStatus, h as UI_COMMAND_VERSION, i as WorksApi, j as SessionPatchReducer, k as createSessionGenerationStreamClient, l as UI_COMMAND_DEFAULT_TIMEOUT_MS, m as UI_COMMAND_TERMINAL_TTL_SECONDS, n as createHttpClient, o as UsersApi, p as UI_COMMAND_SETTLEMENT_GRACE_SECONDS, r as WorkCommerceApi, s as UserApi, t as CohubHttpClient, u as UI_COMMAND_MAX_TIMEOUT_MS, v as parseUiCommand, w as SpacesApi, x as BoardClient, y as parseUiCommandId, z as PromptsApi } from "./chunks/http.js";
+import { A as parseAssistantMessageCommit, B as ReferencesApi, C as SpaceClient, D as buildSpacePath, E as buildSpaceInvitePath, F as BOARD_ARROW_STROKE_SIZE, G as ModelsApi, H as PublicAssetsApi, I as BOARD_BUILTIN_CAPABILITIES, J as ChannelsApi, K as GenerationsApi, L as BOARD_CONNECTION_STROKE_SIZE, M as createSessionPatchReducer, N as ensureRealtimeConnected, O as SessionGenerationStreamClient, P as BoardConnectionSchema, R as DEFAULT_BOARD_RENDER_LIMITS, S as BoardTransactionError, T as PublicInviteApi, U as SkillsApi, V as SearchApi, W as PromptsApi, _ as isUiSurfaceMethod, a as ReferralsApi, b as TasksApi, c as UiCommandsApi, d as UI_COMMAND_PAYLOAD_MAX_BYTES, f as UI_COMMAND_PENDING_TTL_SECONDS, g as isTerminalUiCommandStatus, h as UI_COMMAND_VERSION, i as WorksApi, j as SessionPatchReducer, k as createSessionGenerationStreamClient, l as UI_COMMAND_DEFAULT_TIMEOUT_MS, m as UI_COMMAND_TERMINAL_TTL_SECONDS, n as createHttpClient, o as UsersApi, p as UI_COMMAND_SETTLEMENT_GRACE_SECONDS, q as CronJobsApi, r as WorkCommerceApi, s as UserApi, t as CohubHttpClient, u as UI_COMMAND_MAX_TIMEOUT_MS, v as parseUiCommand, w as SpacesApi, x as BoardClient, y as parseUiCommandId, z as SessionAccessApi } from "./chunks/http.js";
 import { _ as requestSourceToHeaders, a as sanitizeAccessToken, b as REALTIME_ROOM_EVENT_NAME_PATTERN, c as REQUEST_SOURCE_VIA_MAX_LENGTH, d as isRequestSourceEmpty, f as isRequestSourceUuid, g as readRequestSourceFromEnv, h as parseRequestSourceFromHeaders, i as matchesUnauthorizedErrorToken, l as hasRequestSourceIdentity, m as normalizeRequestSource, n as HttpTransport, o as COHUB_SOURCE_HEADER, p as mergeRequestSourceIntoMeta, r as joinApiUrl, s as COHUB_SOURCE_HEADER_NAMES, t as HttpError, u as isRequestSourceClientId, v as resolveRequestSourceChannel, y as REALTIME_DOMAINS } from "./chunks/transport.js";
 import { a as resolveApiBaseUrl, c as resolveWebsocketUrl, i as normalizeWebsocketUrl, n as normalizeBaseUrl, o as resolveCohubEnvironment, r as normalizeVoiceInputWebsocketUrl, s as resolveVoiceInputWebsocketUrl, t as COHUB_ENVIRONMENTS } from "./chunks/environment.js";
 import { a as extractBillingPayload, c as isFeatureNotEntitledError, i as FEATURE_NOT_ENTITLED_ERROR_CODE, l as isHttpErrorCode, n as createWebsocketClient, o as isBillingAccessBlockedCode, r as BILLING_ACCESS_BLOCKED_ERROR_CODE, s as isBillingAccessBlockedError, t as WebsocketClient } from "./chunks/websocket.js";
@@ -70,47 +70,6 @@ var BillingApi = class {
 	}
 };
 //#endregion
-//#region ../protocol/dist/board-constants.js
-const DEFAULT_BOARD_RENDER_LIMITS = {
-	particles: 2e4,
-	vertices: 5e5,
-	dynamicVertices: 15e4,
-	drawCalls: 400,
-	filterPasses: 24,
-	renderTexturePixels: 16777216,
-	textureBytes: 512 * 1024 * 1024,
-	bufferBytes: 256 * 1024 * 1024,
-	simulationSteps: 1e5
-};
-const BOARD_BUILTIN_CLIP_KINDS = [
-	"motion.keyframes",
-	"motion.path",
-	"draw.reveal",
-	"draw.handwrite",
-	"text.reveal",
-	"effects.particles",
-	"effects.trail",
-	"effects.impact",
-	"effects.flash",
-	"effects.color",
-	"camera.pan",
-	"camera.zoom",
-	"camera.shake"
-];
-const BOARD_BUILTIN_EFFECT_KINDS = ["effects.pulse", "effects.float"];
-const BOARD_ARROW_STROKE_SIZE = 2.5;
-const BOARD_BUILTIN_CAPABILITIES = [...BOARD_BUILTIN_CLIP_KINDS.map((id) => ({
-	kind: "clip",
-	id,
-	version: 1,
-	renderers: ["webgpu", "webgl"]
-})), ...BOARD_BUILTIN_EFFECT_KINDS.map((id) => ({
-	kind: "effect",
-	id,
-	version: 1,
-	renderers: ["webgpu", "webgl"]
-}))];
-//#endregion
 //#region ../protocol/dist/realtime/board-awareness.js
 const idSchema$1 = z.string().min(1).max(160);
 const finiteSchema$1 = z.number().finite();
@@ -126,23 +85,13 @@ const BoardAwarenessFrameSchema = z.object({
 	height: finiteSchema$1.positive(),
 	rotation: finiteSchema$1
 });
-const arrowEndpointSchema = z.union([z.object({
-	kind: z.literal("point"),
-	x: finiteSchema$1,
-	y: finiteSchema$1
-}), z.object({
-	kind: z.literal("binding"),
-	target: idSchema$1,
-	nx: finiteSchema$1,
-	ny: finiteSchema$1,
-	precise: z.boolean()
-})]);
 const BoardAwarenessNodePreviewSchema = z.object({
 	nodeId: idSchema$1,
 	frame: BoardAwarenessFrameSchema,
+	/** Live endpoints of a free arrow being dragged. */
 	arrow: z.object({
-		start: arrowEndpointSchema,
-		end: arrowEndpointSchema,
+		start: BoardAwarenessPointSchema,
+		end: BoardAwarenessPointSchema,
 		bend: finiteSchema$1
 	}).optional()
 });
@@ -191,6 +140,15 @@ const BoardAwarenessGestureSchema = z.discriminatedUnion("kind", [
 		color: z.string().min(1).max(64),
 		geo: z.string().min(1).max(40)
 	}),
+	z.object({
+		kind: z.literal("connection"),
+		id: idSchema$1,
+		sourceNodeId: idSchema$1,
+		targetNodeId: idSchema$1.nullable(),
+		current: BoardAwarenessPointSchema,
+		color: z.string().min(1).max(64),
+		size: finiteSchema$1.positive().max(256).default(BOARD_CONNECTION_STROKE_SIZE)
+	}),
 	z.object({
 		kind: z.literal("transform"),
 		id: idSchema$1,
@@ -198,7 +156,8 @@ const BoardAwarenessGestureSchema = z.discriminatedUnion("kind", [
 			"translate",
 			"resize",
 			"rotate",
-			"arrow"
+			"arrow",
+			"connection"
 		]),
 		nodes: z.array(BoardAwarenessNodePreviewSchema).max(64),
 		bounds: BoardAwarenessFrameSchema.nullable()
@@ -2572,6 +2531,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
@@ -2587,6 +2547,7 @@ z.object({
 z.object({
 	include: z.array(z.enum([
 		"nodes",
+		"connections",
 		"effects",
 		"sequences",
 		"clips",

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

@@ -0,0 +1,310 @@
+import { z } from "zod";
+//#region ../protocol/dist/board-connection.d.ts
+/** Sides of a node frame a connection can attach to. */
+declare const BOARD_CONNECTION_SIDES: readonly ["top", "right", "bottom", "left"];
+type BoardConnectionSide = (typeof BOARD_CONNECTION_SIDES)[number];
+/**
+ * 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.
+ */
+declare const BoardConnectionAnchorSchema: 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>]>;
+type BoardConnectionAnchor = z.infer<typeof BoardConnectionAnchorSchema>;
+declare const AUTO_BOARD_CONNECTION_ANCHOR: BoardConnectionAnchor;
+declare const BoardConnectionEndpointSchema: 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>;
+type BoardConnectionEndpoint = z.infer<typeof BoardConnectionEndpointSchema>;
+/**
+ * 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.
+ */
+declare const BOARD_CONNECTION_DIRECTIONS: readonly ["none", "forward", "backward", "both"];
+type BoardConnectionDirection = (typeof BOARD_CONNECTION_DIRECTIONS)[number];
+/** How the line travels between its two resolved endpoints. */
+declare const BOARD_CONNECTION_ROUTINGS: readonly ["straight", "curve", "orthogonal"];
+type BoardConnectionRouting = (typeof BOARD_CONNECTION_ROUTINGS)[number];
+declare const BOARD_CONNECTION_LINES: readonly ["solid", "dashed"];
+type BoardConnectionLine = (typeof BOARD_CONNECTION_LINES)[number];
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare const BoardRelationSchema: z.ZodDefault<z.ZodString>;
+/**
+ * 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.
+ */
+declare const BoardConnectionWaypointSchema: z.ZodObject<{
+  x: z.ZodNumber;
+  y: z.ZodNumber;
+}, z.core.$strip>;
+declare const BoardConnectionRoutingSchema: 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>;
+type BoardConnectionRoutingConfig = z.infer<typeof BoardConnectionRoutingSchema>;
+declare const BoardConnectionStyleSchema: z.ZodObject<{
+  color: z.ZodDefault<z.ZodString>;
+  size: z.ZodDefault<z.ZodNumber>;
+  line: z.ZodDefault<z.ZodEnum<{
+    dashed: "dashed";
+    solid: "solid";
+  }>>;
+}, z.core.$strip>;
+type BoardConnectionStyle = z.infer<typeof BoardConnectionStyleSchema>;
+declare const DEFAULT_BOARD_CONNECTION_ROUTING: BoardConnectionRoutingConfig;
+declare const DEFAULT_BOARD_CONNECTION_STYLE: BoardConnectionStyle;
+declare const BoardConnectionSchema: 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>;
+type BoardConnection = z.infer<typeof BoardConnectionSchema>;
+/** Server-owned fields, mirroring how nodes carry a board id and revision. */
+type BoardConnectionRecord = BoardConnection & {
+  boardId: string;
+  revision: number;
+  createdAt: string | null;
+  updatedAt: string | null;
+};
+/** The client-authored form of a connection (no server-owned fields). */
+type BoardConnectionInput = BoardConnection;
+/**
+ * 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.
+ */
+declare const BoardConnectionPatchSchema: z.ZodObject<{
+  source: z.ZodOptional<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.ZodOptional<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.ZodOptional<z.ZodDefault<z.ZodString>>;
+  direction: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+    backward: "backward";
+    both: "both";
+    forward: "forward";
+    none: "none";
+  }>>>;
+  label: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+  routing: z.ZodOptional<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.ZodOptional<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.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+type BoardConnectionPatch = z.infer<typeof BoardConnectionPatchSchema>;
+/** Both node ids a connection touches, deduped for a self-loop. */
+declare function connectionNodeIds(connection: BoardConnection): string[];
+/** Whether a connection touches the given node. */
+declare function connectionTouchesNode(connection: BoardConnection, nodeId: string): boolean;
+/** The node at the far end of a connection from `nodeId`, or null. */
+declare function connectionOtherNodeId(connection: BoardConnection, nodeId: string): string | null;
+declare function normalizeBoardConnectionStyle(style: Partial<BoardConnectionStyle> | undefined): BoardConnectionStyle;
+/**
+ * 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.
+ */
+declare function createBoardConnection(input: {
+  id: string;
+  sourceNodeId: string;
+  targetNodeId: string;
+  relation?: string;
+  direction?: BoardConnectionDirection;
+  label?: string;
+  sourceAnchor?: BoardConnectionAnchor;
+  targetAnchor?: BoardConnectionAnchor;
+  routing?: Partial<BoardConnectionRoutingConfig>;
+  style?: Partial<BoardConnectionStyle>;
+  metadata?: Record<string, unknown>;
+}): BoardConnection;
+/** Reverse a connection's endpoints, preserving the relation's reading order. */
+declare function flipBoardConnection(connection: BoardConnection): BoardConnection;
+//#endregion
+export { 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 };

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 };