@pauloricca/spagbol 0.0.0-stage → 0.1.0

package/src/core/groups.ts

@@ -0,0 +1,125 @@
+import { clone, createId, spagbolGroupKinds, type GraphDocument, type GraphNode, type NodeRegistry, type PortDefinition, type NodeData, type PortEndpoint, type LinkTarget } from './model.js';
+import { pruneInvalidPorts } from './graph.js';
+
+export function isGroupBoundary(node: GraphNode): boolean {
+  return node.kind === spagbolGroupKinds.inputs || node.kind === spagbolGroupKinds.outputs;
+}
+export function normalizeGroupPortLabel(label: string): string {
+  const normalized = label.trim().toLowerCase().replace(/\s+/g, ' ');
+  if (!/^[a-z0-9]+(?: [a-z0-9]+)*$/.test(normalized)) throw new Error('Use a lowercase, human-readable port name with spaces.');
+  return normalized;
+}
+export function createGroupPort(node: GraphNode, label: string, defaultValue = 0): PortDefinition {
+  if (!isGroupBoundary(node)) throw new Error('Ports can be added to Ins or Outs nodes.');
+  const port: PortDefinition = { id: createId('port'), label: normalizeGroupPortLabel(label), direction: node.kind === spagbolGroupKinds.inputs ? 'output' : 'input', defaultValue };
+  node.ports ??= [];
+  if (node.ports.some(item => item.label === port.label)) throw new Error('That port name already exists.');
+  node.ports.push(port);
+  if (node.kind === spagbolGroupKinds.inputs) node.values[port.id] = defaultValue;
+  return port;
+}
+
+export function createEditablePort(node: GraphNode, registry: NodeRegistry, label: string, defaultValue = 0): PortDefinition {
+  if (isGroupBoundary(node)) return createGroupPort(node, label, defaultValue);
+  const definition = registry.get(node.kind);
+  if (!definition?.editablePorts || !definition.createPort) throw new Error('This node does not expose editable ports.');
+  const normalized = normalizeGroupPortLabel(label);
+  if (node.ports?.some(port => port.label === normalized)) throw new Error('That port name already exists.');
+  const port = definition.createPort(node, normalized);
+  node.ports ??= []; node.ports.push(port); node.values[port.id] = port.defaultValue ?? defaultValue;
+  return port;
+}
+
+/** Apply a boundary change to every linked group instance and prune dependent cables atomically. */
+export function synchronizeGroupBoundaries(document: GraphDocument, registry: NodeRegistry): void {
+  for (const node of document.nodes) if (node.graph) {
+    synchronizeGroupBoundaries(node.graph, registry);
+    if (node.kind !== spagbolGroupKinds.group) continue;
+    node.ports = [...new Map(node.graph.nodes.filter(isGroupBoundary).flatMap(boundary => (boundary.ports ?? []).map(port => ({ ...port, direction: boundary.kind === spagbolGroupKinds.inputs ? 'input' as const : 'output' as const }))).map(port => [`${port.direction}:${port.id}`, port])).values()];
+    const inputs = new Set(node.ports.filter(port => port.direction === 'input').map(port => port.id));
+    for (const id of Object.keys(node.values)) if (!inputs.has(id)) delete node.values[id];
+    for (const port of node.ports) if (port.direction === 'input' && node.values[port.id] === undefined) node.values[port.id] = port.defaultValue ?? 0;
+    pruneInvalidPorts(document, registry, node.id);
+    const ids = new Set(node.graph.nodes.map(item => item.id));
+    for (const overrides of [node.overrides, node.dataOverrides])
+      if (overrides) for (const id of Object.keys(overrides)) if (!ids.has(groupControlPath(id)[0]!)) delete overrides[id];
+  }
+}
+
+export function groupControlKey(path: string | readonly string[]): string {
+  return typeof path === 'string' ? path : path.length === 1 ? path[0]! : JSON.stringify(path);
+}
+export function groupControlPath(key: string): string[] {
+  if (key.startsWith('[')) try { const path: unknown = JSON.parse(key); if (Array.isArray(path) && path.every(id => typeof id === 'string')) return path; } catch { /* A literal node id. */ }
+  return [key];
+}
+export function findGroupControl(group: GraphNode, path: string | readonly string[]): GraphNode | undefined {
+  const ids = typeof path === 'string' ? groupControlPath(path) : path;
+  let graph = group.graph;
+  let node: GraphNode | undefined;
+  for (const id of ids) { node = graph?.nodes.find(item => item.id === id); if (!node) return; graph = node.graph; }
+  return node;
+}
+export function effectiveGroupGraph(group: GraphNode): GraphDocument | undefined {
+  if (!group.graph) return;
+  const result: GraphNode = { ...group, graph: clone(group.graph) };
+  for (const node of result.graph!.nodes) if (node.graph) {
+    node.graph = effectiveGroupGraph(node)!;
+    delete node.overrides; delete node.dataOverrides;
+  }
+  for (const [id, values] of Object.entries(group.overrides ?? {})) {
+    const node = findGroupControl(result, id);
+    if (node) Object.assign(node.values, values);
+  }
+  for (const [id, data] of Object.entries(group.dataOverrides ?? {})) {
+    const node = findGroupControl(result, id);
+    if (node) Object.assign(node.data, data);
+  }
+  return result.graph;
+}
+
+/** Teia's UI/Controls area projection, with explicit exposure also supported. */
+const panelCache = new WeakMap<GraphNode, ReturnType<typeof computeGroupPanelLayout>>();
+export function groupPanelLayout(group: GraphNode) {
+  if (!Object.isFrozen(group)) return computeGroupPanelLayout(group);
+  if (!panelCache.has(group)) panelCache.set(group, computeGroupPanelLayout(group));
+  return panelCache.get(group);
+}
+function computeGroupPanelLayout(group: GraphNode) {
+  const graph = effectiveGroupGraph(group);
+  if (!graph) return;
+  const areas = graph.areas.filter(area => area.data?.role === 'controls' || (!area.ownerNodeId && ['ui', 'controls'].includes(area.title.trim().toLowerCase())));
+  const exposed = graph.data?.exposedNodeIds;
+  const ids = new Set<string>([...(group.panelNodeIds ?? []), ...(Array.isArray(exposed) ? exposed.filter((id): id is string => typeof id === 'string') : [])]);
+  for (const area of areas) for (const node of graph.nodes) {
+    if (area.locked ? area.nodeIds?.includes(node.id) : node.position.x >= area.position.x && node.position.x < area.position.x + area.size.width && node.position.y >= area.position.y && node.position.y < area.position.y + area.size.height) ids.add(node.id);
+  }
+  const nodes = graph.nodes.filter(node => ids.has(node.id) && !isGroupBoundary(node));
+  if (!areas.length && !nodes.length) return;
+  const left = areas.length ? Math.min(...areas.map(area => area.position.x)) : Math.min(...nodes.map(node => node.position.x));
+  const top = Math.min(...areas.map(area => area.position.y + 32), ...nodes.map(node => node.position.y));
+  const right = areas.length ? Math.max(...areas.map(area => area.position.x + area.size.width)) : Math.max(...nodes.map(node => node.position.x + ((node.size?.width ?? 220) * (node.scale ?? 1))));
+  const bottom = areas.length ? Math.max(...areas.map(area => area.position.y + area.size.height)) : Math.max(...nodes.map(node => node.position.y + ((node.size?.height ?? 120) * (node.scale ?? 1))));
+  return { position: { x: left, y: top }, size: { width: right - left, height: bottom - top }, nodes };
+}
+
+/** Transient handle ID; it is resolved to a persistent boundary port in one edit. */
+export const spagbolNewPortId = 'spagbol.new-port';
+export function resolveNewBoundaryPorts(graph: GraphDocument, source: PortEndpoint, target: LinkTarget, registry: NodeRegistry) {
+  const from = { ...source }, to = { ...target };
+  const label = (nodeId: string, portId: string) => {
+    const node = graph.nodes.find(node => node.id === nodeId);
+    return node && (node.ports ?? registry.get(node.kind)?.ports(node) ?? []).find(port => port.id === portId)?.label;
+  };
+  const create = (nodeId: string, direction: 'input' | 'output', preferred?: string) => {
+    const node = graph.nodes.find(node => node.id === nodeId && (node.kind === (direction === 'output' ? spagbolGroupKinds.inputs : spagbolGroupKinds.outputs) || registry.get(node.kind)?.editablePorts === direction));
+    if (!node) return spagbolNewPortId;
+    const base = preferred?.toLowerCase().replace(/[^a-z0-9 ]/g, ' ').replace(/\s+/g, ' ').trim() || 'value';
+    let name = base, suffix = 2;
+    while (node.ports?.some(port => port.label === name)) name = `${base} ${suffix++}`;
+    return createEditablePort(node, registry, name).id;
+  };
+  if (from.portId === spagbolNewPortId) from.portId = create(from.nodeId, "output", to.type === 'port' ? label(to.nodeId, to.portId) : 'strength');
+  if (to.type === 'port' && to.portId === spagbolNewPortId) to.portId = create(to.nodeId, "input", label(from.nodeId, from.portId));
+  return { source: from, target: to };
+}

package/src/core/index.ts

@@ -0,0 +1,7 @@
+export * from "./model.js";
+export * from "./graph.js";
+export * from "./controller.js";
+export * from "./serialization.js";
+export * from "./observations.js";
+export * from "./grouping.js";
+export * from "./groups.js";

package/src/core/model.ts

@@ -0,0 +1,304 @@
+/** Saved data is JSON only. Functions, observers and UI state never enter documents. */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+export type NodeData = { [key: string]: JsonValue };
+export interface Point {
+  x: number;
+  y: number;
+}
+export interface Size {
+  width: number;
+  height: number;
+}
+export interface PortDefinition {
+  id: string;
+  label: string;
+  direction: "input" | "output";
+  dataType?: string;
+  connectable?: boolean;
+  valueEditor?: boolean;
+  defaultValue?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  integer?: boolean;
+}
+export interface GraphNode<D extends NodeData = NodeData> {
+  id: string;
+  kind: string;
+  label?: string;
+  position: Point;
+  size?: Size;
+  compact?: boolean;
+  compactLabel?: string;
+  scale?: number;
+  enabled?: boolean;
+  data: D;
+  values: Record<string, number>;
+  /** Explicit/dynamic instance ports; a definition may derive ports instead. */
+  ports?: PortDefinition[];
+  graph?: GraphDocument;
+  /** Equal IDs opt into shared nested structure; instance values stay local. */
+  sharedGraphId?: string;
+  /** Explicit nested nodes to show on this parent. No title conventions in core. */
+  panelNodeIds?: string[];
+  overrides?: Record<string, Record<string, number>>;
+  dataOverrides?: Record<string, NodeData>;
+}
+export interface PortEndpoint {
+  nodeId: string;
+  portId: string;
+}
+export type LinkTarget =
+  | ({ type: "port" } & PortEndpoint)
+  | { type: "link"; linkId: string; property: string };
+export interface GraphLink {
+  id: string;
+  source: PortEndpoint;
+  target: LinkTarget;
+  mode: string;
+  weight: number;
+  enabled?: boolean;
+  data?: NodeData;
+}
+export interface GraphArea {
+  id: string;
+  /** A domain node whose UI/layout is owned by this area. */
+  ownerNodeId?: string;
+  title: string;
+  position: Point;
+  size: Size;
+  collapsed?: boolean;
+  locked?: boolean;
+  nodeIds?: string[];
+  areaIds?: string[];
+  /** The top portion remains operable while the rest is collapsed. */
+  controlHeight?: number;
+  data?: NodeData;
+}
+export interface GraphDocument {
+  format: "spagbol";
+  version: 1;
+  nodes: GraphNode[];
+  links: GraphLink[];
+  areas: GraphArea[];
+  data?: NodeData;
+}
+export interface Selection {
+  port?: { nodeId: string; portId: string; direction: "input" | "output" };
+  nodeIds: string[];
+  linkIds: string[];
+  areaIds: string[];
+}
+export interface Diagnostic {
+  severity: "info" | "warning" | "error";
+  code: string;
+  message: string;
+  path: readonly string[];
+  nodeId?: string;
+  linkId?: string;
+  portId?: string;
+}
+export interface LinkModeDefinition {
+  id: string;
+  label: string;
+  color: string;
+  shortcut?: string;
+  description: string;
+}
+export interface NodeDefinition<D extends NodeData = NodeData> {
+  kind: string;
+  label: string;
+  category?: string;
+  description?: string;
+  keywords?: string[];
+  createData(): D;
+  createGraph?(): GraphDocument;
+  editablePorts?: "input" | "output";
+  newPortLabel?: string;
+  createPort?(node: GraphNode<D>, label: string): PortDefinition;
+  ports(node: GraphNode<D>): readonly PortDefinition[];
+  defaultSize?: Size;
+  validate?(node: GraphNode<D>): readonly string[];
+  /** App code can remap asset or domain references when duplicating. */
+  cloneData?(data: D, ids: ReadonlyMap<string, string>): D;
+}
+export interface GraphPolicy {
+  /** All registered modes are allowed unless the consumer supplies a subset. */
+  modes?: readonly string[];
+  linkProperties?: readonly string[];
+  allowSelfLinks?: boolean;
+  allowDuplicateLinks?: boolean;
+  /** Host metadata update when deleting a selected editable domain port. */
+  deletePort?(node: GraphNode, port: PortDefinition): void;
+  canConnect?(
+    source: PortEndpoint,
+    target: LinkTarget,
+    graph: GraphDocument,
+  ): string | undefined;
+}
+export interface ChangeEvent {
+  label: string;
+  kinds: readonly ChangeKind[];
+  document: GraphDocument;
+  path: readonly string[];
+  origin: "edit" | "undo" | "redo" | "replace";
+}
+export type ChangeKind = "structure" | "values" | "layout" | "metadata";
+export function emptyGraph(): GraphDocument {
+  return { format: "spagbol", version: 1, nodes: [], links: [], areas: [] };
+}
+export function emptySelection(): Selection {
+  return { nodeIds: [], linkIds: [], areaIds: [] };
+}
+export function clone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+export function createId(prefix = "item"): string {
+  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function graphAt(
+  document: GraphDocument,
+  path: readonly string[],
+): GraphDocument {
+  let graph = document;
+  for (const id of path) {
+    const nested = graph.nodes.find((node) => node.id === id)?.graph;
+    if (!nested) throw new Error(`Nested graph ${id} does not exist.`);
+    graph = nested;
+  }
+  return graph;
+}
+export function validPath(
+  document: GraphDocument,
+  path: readonly string[],
+): string[] {
+  const result: string[] = [];
+  let graph = document;
+  for (const id of path) {
+    const nested = graph.nodes.find((node) => node.id === id)?.graph;
+    if (!nested) break;
+    result.push(id);
+    graph = nested;
+  }
+  return result;
+}
+const immutablePortCache = new WeakMap<GraphNode, WeakMap<NodeRegistry, readonly PortDefinition[]>>();
+export function portsFor(
+  node: GraphNode,
+  definitions: NodeRegistry,
+): readonly PortDefinition[] {
+  if (!Object.isFrozen(node)) return definitions.get(node.kind)?.ports(node) ?? node.ports ?? [];
+  let registries = immutablePortCache.get(node);
+  if (!registries) { registries = new WeakMap(); immutablePortCache.set(node, registries); }
+  let ports = registries.get(definitions);
+  if (!ports) { ports = definitions.get(node.kind)?.ports(node) ?? node.ports ?? []; registries.set(definitions, ports); }
+  return ports;
+}
+export const spagbolGroupKinds = { group: "spagbol.group", inputs: "spagbol.group.inputs", outputs: "spagbol.group.outputs" } as const;
+const groupDefinitions: readonly NodeDefinition[] = [
+  { kind: spagbolGroupKinds.group, label: 'Group', category: 'graph', createData: () => ({}), ports: node => node.ports ?? [], createGraph: () => ({ ...emptyGraph(), nodes: [
+    { id: createId('node'), kind: spagbolGroupKinds.inputs, position: { x: 0, y: 0 }, data: {}, values: {}, ports: [] },
+    { id: createId('node'), kind: spagbolGroupKinds.outputs, position: { x: 500, y: 0 }, data: {}, values: {}, ports: [] },
+  ] }) },
+  { kind: spagbolGroupKinds.inputs, label: 'Ins', category: 'graph', createData: () => ({}), ports: node => node.ports ?? [] },
+  { kind: spagbolGroupKinds.outputs, label: 'Outs', category: 'graph', createData: () => ({}), ports: node => node.ports ?? [] },
+];
+
+export class NodeRegistry {
+  readonly #definitions = new Map<string, NodeDefinition>();
+  constructor(definitions: readonly NodeDefinition[] = []) {
+    for (const definition of [...groupDefinitions, ...definitions]) {
+      if (this.#definitions.has(definition.kind))
+        throw new Error(`Duplicate node kind ${definition.kind}.`);
+      this.#definitions.set(definition.kind, definition);
+    }
+  }
+  get(kind: string): NodeDefinition | undefined {
+    return this.#definitions.get(kind);
+  }
+  list(): readonly NodeDefinition[] {
+    return [...this.#definitions.values()];
+  }
+  create(kind: string, position: Point, id = createId("node")): GraphNode {
+    const definition = this.get(kind);
+    if (!definition) throw new Error(`Unknown node kind ${kind}.`);
+    const node: GraphNode = {
+      id,
+      kind,
+      position: { ...position },
+      data: definition.createData(),
+      values: {},
+    };
+    if (definition.createGraph) {
+      node.graph = definition.createGraph();
+      node.sharedGraphId = createId('shared');
+      node.ports = [];
+    }
+    if (definition.defaultSize) node.size = { ...definition.defaultSize };
+    node.values = Object.fromEntries(
+      definition
+        .ports(node)
+        .filter((port) => port.direction === "input")
+        .map((port) => [port.id, port.defaultValue ?? 0]),
+    );
+    return node;
+  }
+}
+export function defineNode<D extends NodeData>(
+  definition: NodeDefinition<D>,
+): NodeDefinition<D> {
+  return definition;
+}
+export const standardLinkModes: readonly LinkModeDefinition[] = Object.freeze([
+  {
+    id: "set",
+    label: "set",
+    color: "#fff",
+    shortcut: "s",
+    description:
+      "Average weighted set sources, replacing the local base value.",
+  },
+  {
+    id: "add",
+    label: "add",
+    color: "#ffe45c",
+    shortcut: "a",
+    description: "Add weighted sources after set values or the local base.",
+  },
+  {
+    id: "multiply",
+    label: "multiply",
+    color: "#8fdcff",
+    shortcut: "m",
+    description: "Multiply by each weighted source after addition.",
+  },
+  {
+    id: "bend",
+    label: "bend",
+    color: "#c084fc",
+    shortcut: "b",
+    description: "Scale by 2^(source × weight) after multiplication.",
+  },
+]);
+export class LinkModeRegistry {
+  readonly #definitions = new Map<string, LinkModeDefinition>();
+  constructor(definitions: readonly LinkModeDefinition[] = standardLinkModes) {
+    for (const definition of definitions) {
+      if (this.#definitions.has(definition.id))
+        throw new Error(`Duplicate link mode ${definition.id}.`);
+      this.#definitions.set(definition.id, Object.freeze({ ...definition }));
+    }
+  }
+  get(id: string): LinkModeDefinition | undefined {
+    return this.#definitions.get(id);
+  }
+  list(): readonly LinkModeDefinition[] {
+    return [...this.#definitions.values()];
+  }
+}

package/src/core/observations.ts

@@ -0,0 +1,31 @@
+/** Runtime data is instance-scoped, externally supplied and absent from history. */
+export class ObservationStore<T = unknown> {
+  readonly #values = new Map<string, T>();
+  readonly #listeners = new Map<string, Set<() => void>>();
+  key(path: readonly string[], nodeId: string, instance = ""): string {
+    return JSON.stringify([path, nodeId, instance]);
+  }
+  get(key: string): T | undefined {
+    return this.#values.get(key);
+  }
+  set(key: string, value: T): void {
+    if (Object.is(this.#values.get(key), value)) return;
+    this.#values.set(key, value);
+    for (const listener of this.#listeners.get(key) ?? []) listener();
+  }
+  subscribe(key: string, listener: () => void): () => void {
+    const listeners = this.#listeners.get(key) ?? new Set();
+    listeners.add(listener);
+    this.#listeners.set(key, listeners);
+    return () => {
+      listeners.delete(listener);
+      if (!listeners.size) this.#listeners.delete(key);
+    };
+  }
+  clear(): void {
+    const keys = [...this.#values.keys()];
+    this.#values.clear();
+    for (const key of keys)
+      for (const listener of this.#listeners.get(key) ?? []) listener();
+  }
+}

package/src/core/serialization.ts

@@ -0,0 +1,184 @@
+import { clone, type GraphDocument, type JsonValue } from "./model.js";
+import type { GraphFragment } from "./graph.js";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function finite(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function string(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+function point(value: unknown): boolean {
+  return record(value) && finite(value.x) && finite(value.y);
+}
+function size(value: unknown): boolean {
+  return (
+    record(value) &&
+    finite(value.width) &&
+    value.width > 0 &&
+    finite(value.height) &&
+    value.height > 0
+  );
+}
+function endpoint(value: unknown): boolean {
+  return record(value) && string(value.nodeId) && string(value.portId);
+}
+function optional(
+  value: unknown,
+  predicate: (value: unknown) => boolean,
+): boolean {
+  return value === undefined || predicate(value);
+}
+function numberRecord(value: unknown): boolean {
+  return record(value) && Object.values(value).every(finite);
+}
+export function isJsonValue(
+  value: unknown,
+  ancestors = new Set<object>(),
+): value is JsonValue {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    finite(value)
+  )
+    return true;
+  if (!Array.isArray(value) && !record(value)) return false;
+  if (ancestors.has(value)) return false;
+  const next = new Set([...ancestors, value]);
+  return (
+    Object.getPrototypeOf(value) ===
+      (Array.isArray(value) ? Array.prototype : Object.prototype) &&
+    Object.values(value).every((child) => isJsonValue(child, next))
+  );
+}
+function boolean(value: unknown): boolean {
+  return typeof value === "boolean";
+}
+function strings(value: unknown): boolean {
+  return Array.isArray(value) && value.every(string);
+}
+function node(value: unknown, depth: number): boolean {
+  return (
+    record(value) &&
+    string(value.id) &&
+    string(value.kind) &&
+    point(value.position) &&
+    record(value.data) &&
+    isJsonValue(value.data) &&
+    numberRecord(value.values) &&
+    optional(value.label, (text) => typeof text === "string") &&
+    optional(value.size, size) &&
+    optional(value.enabled, boolean) &&
+    optional(value.compact, boolean) &&
+    optional(value.compactLabel, text => typeof text === "string") &&
+    optional(value.scale, scale => finite(scale) && scale > 0) &&
+    optional(value.sharedGraphId, string) &&
+    optional(value.panelNodeIds, strings) &&
+    optional(value.dataOverrides, values => record(values) && Object.values(values).every(item => record(item) && isJsonValue(item))) &&
+    optional(
+      value.overrides,
+      (overrides) =>
+        record(overrides) && Object.values(overrides).every(numberRecord),
+    ) &&
+    optional(
+      value.ports,
+      (ports) =>
+        Array.isArray(ports) &&
+        ports.every(
+          (port) =>
+            record(port) &&
+            string(port.id) &&
+            string(port.label) &&
+            (port.direction === "input" || port.direction === "output") &&
+            optional(port.dataType, string) &&
+            optional(port.connectable, boolean) &&
+            optional(port.valueEditor, boolean) &&
+            optional(port.integer, boolean) &&
+            ["defaultValue", "min", "max", "step"].every((key) =>
+              optional(port[key], finite),
+            ) &&
+            !(finite(port.min) && finite(port.max) && port.min > port.max),
+        ),
+    ) &&
+    optional(value.graph, (graph) => document(graph, depth + 1))
+  );
+}
+function link(value: unknown): boolean {
+  return (
+    record(value) &&
+    string(value.id) &&
+    endpoint(value.source) &&
+    record(value.target) &&
+    ((value.target.type === "port" && endpoint(value.target)) ||
+      (value.target.type === "link" &&
+        string(value.target.linkId) &&
+        string(value.target.property))) &&
+    string(value.mode) &&
+    finite(value.weight) &&
+    optional(value.enabled, boolean) &&
+    optional(value.data, (data) => record(data) && isJsonValue(data))
+  );
+}
+function area(value: unknown): boolean {
+  return (
+    record(value) &&
+    optional(value.ownerNodeId, string) &&
+    string(value.id) &&
+    typeof value.title === "string" &&
+    point(value.position) &&
+    size(value.size) &&
+    optional(value.locked, boolean) &&
+    optional(value.collapsed, boolean) &&
+    optional(value.nodeIds, strings) &&
+    optional(value.areaIds, strings) &&
+    optional(value.controlHeight, (height) => finite(height) && height >= 0) &&
+    optional(value.data, (data) => record(data) && isJsonValue(data))
+  );
+}
+function document(value: unknown, depth: number): boolean {
+  return (
+    depth <= 32 &&
+    record(value) &&
+    value.format === "spagbol" &&
+    value.version === 1 &&
+    Array.isArray(value.nodes) &&
+    value.nodes.every((candidate) => node(candidate, depth)) &&
+    Array.isArray(value.links) &&
+    value.links.every(link) &&
+    Array.isArray(value.areas) &&
+    value.areas.every(area) &&
+    optional(value.data, (data) => record(data) && isJsonValue(data))
+  );
+}
+export function assertDocument(value: unknown): asserts value is GraphDocument {
+  if (!isJsonValue(value) || !document(value, 0))
+    throw new Error(
+      "Invalid Spagbol document. Expected format spagbol/version 1, finite JSON data and valid node/link/area shapes (maximum nesting 32).",
+    );
+}
+/** Preserve array order. Never sort links as a side effect of serialization. */
+export function writeDocument(value: GraphDocument): string {
+  assertDocument(value);
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function readDocument(input: string | unknown): GraphDocument {
+  const parsed: unknown = typeof input === "string" ? JSON.parse(input) : input;
+  assertDocument(parsed);
+  return clone(parsed);
+}
+export function readFragment(input: string | unknown): GraphFragment {
+  const parsed: unknown = typeof input === "string" ? JSON.parse(input) : input;
+  if (
+    !record(parsed) ||
+    parsed.format !== "spagbol-fragment" ||
+    parsed.version !== 1 ||
+    !Array.isArray(parsed.boundaryLinks) ||
+    !parsed.boundaryLinks.every(link)
+  )
+    throw new Error("Invalid Spagbol clipboard fragment.");
+  assertDocument({ ...parsed, format: "spagbol" });
+  return clone(parsed) as unknown as GraphFragment;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./core/index.js";
+export * from "./react/index.js";
+export {
+  SpagbolControlSlider,
+  SpagbolControlButton,
+  type SpagbolControlSliderProps,
+  type SpagbolControlButtonProps,
+  type SpagbolControlButtonMode,
+} from "./react/Controls.js";