@tuongaz/seeflow 0.1.31 → 0.1.39

package/src/layout.ts

@@ -0,0 +1,217 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { runInThisContext } from 'node:vm';
+import ELK from 'elkjs/lib/elk-api.js';
+import type { FlowNode } from './schema.ts';
+
+// elkjs Bun-compat shim. The `elk-worker.min.js` file inspects `self` at the
+// bottom to decide between its browser-worker branch and its CJS-export
+// branch. Bun exposes `self` globally, which makes it take the
+// browser-worker branch — and skip the export — so we'd get an empty
+// module otherwise. We load the vendored worker source via vm and run it
+// inside a wrapper that shadows `self`, then pluck the Worker class out of
+// the resulting module.exports. One-time cost at module load.
+const requireFromHere = createRequire(import.meta.url);
+const workerSource = readFileSync(requireFromHere.resolve('elkjs/lib/elk-worker.min.js'), 'utf8');
+type WorkerCtor = new () => { postMessage: (msg: unknown) => unknown };
+const workerModule: { exports: { Worker?: WorkerCtor } } = { exports: {} };
+const wrappedSource = `(function (module, exports) { var self; ${workerSource} })`;
+const wrapped = runInThisContext(wrappedSource, {
+  filename: 'elkjs/lib/elk-worker.min.js',
+}) as (m: typeof workerModule, e: typeof workerModule.exports) => void;
+wrapped(workerModule, workerModule.exports);
+const ElkWorker = workerModule.exports.Worker;
+if (!ElkWorker) throw new Error('elkjs worker class not found after Bun shim');
+
+// ELK's type expects a full DOM Worker; our shim provides the minimal duck
+// (postMessage / addEventListener). ELK only checks `typeof postMessage ===
+// 'function'` at runtime, so the cast is safe.
+const elk = new ELK({
+  workerFactory: () => new ElkWorker() as unknown as Worker,
+});
+
+export type LayoutDirection = 'RIGHT' | 'DOWN' | 'LEFT' | 'UP';
+export type SourceHandle = 'r' | 'b';
+export type TargetHandle = 't' | 'l';
+
+export interface LayoutOptions {
+  direction?: LayoutDirection;
+  spacing?: { layer?: number; node?: number };
+}
+
+export interface LayoutResult {
+  nodes: Record<string, { position: { x: number; y: number } }>;
+  connectors: Record<string, { sourceHandle: SourceHandle; targetHandle: TargetHandle }>;
+}
+
+// Structural shape computeLayout cares about. Decoupled from the strict
+// FlowSchema so callers like assembleDemo (which carries pre-validation
+// passthrough data) can feed in their loose nodes without round-tripping
+// through Zod.
+export interface LayoutNode {
+  id: string;
+  type: FlowNode['type'];
+  data?: { width?: number; height?: number; shape?: string };
+}
+
+export interface LayoutEdge {
+  id: string;
+  source: string;
+  target: string;
+}
+
+const DEFAULT_DIMENSIONS: Record<FlowNode['type'], { width: number; height: number }> = {
+  playNode: { width: 220, height: 100 },
+  stateNode: { width: 220, height: 100 },
+  shapeNode: { width: 160, height: 80 },
+  iconNode: { width: 80, height: 80 },
+  htmlNode: { width: 320, height: 200 },
+  imageNode: { width: 200, height: 150 },
+};
+
+const SHAPE_OVERRIDES: Record<string, { width: number; height: number }> = {
+  text: { width: 160, height: 40 },
+  sticky: { width: 160, height: 180 },
+};
+
+const FLOATING_SHAPES = new Set(['sticky', 'text']);
+
+const nodeDimensions = (node: LayoutNode): { width: number; height: number } => {
+  const data = node.data ?? {};
+  if (typeof data.width === 'number' && typeof data.height === 'number') {
+    return { width: data.width, height: data.height };
+  }
+  if (node.type === 'shapeNode' && data.shape) {
+    const override = SHAPE_OVERRIDES[data.shape];
+    if (override) return override;
+  }
+  return DEFAULT_DIMENSIONS[node.type];
+};
+
+// Sticky / text shapes are floating annotations. They never participate in
+// layered layout — they sit in a side column so the orthogonal flow stays
+// clean.
+const isFloatingAnnotation = (node: LayoutNode): boolean => {
+  if (node.type !== 'shapeNode') return false;
+  const shape = node.data?.shape;
+  return shape !== undefined && FLOATING_SHAPES.has(shape);
+};
+
+// Schema vocabulary: SourceHandle ∈ {r, b}, TargetHandle ∈ {t, l}. After
+// ELK lays out positions we pick handles geometrically — the layered LR
+// algorithm puts most edges going east, so the default is source.r →
+// target.l. Back-edges (target to the left or directly below) route via
+// source.b → target.t so they don't try to enter from a side that has no
+// target handle.
+const pickHandles = (
+  src: { x: number; y: number; w: number; h: number },
+  tgt: { x: number; y: number; w: number; h: number },
+): { sourceHandle: SourceHandle; targetHandle: TargetHandle } => {
+  const sCenter = { x: src.x + src.w / 2, y: src.y + src.h / 2 };
+  const tCenter = { x: tgt.x + tgt.w / 2, y: tgt.y + tgt.h / 2 };
+  const dx = tCenter.x - sCenter.x;
+  const dy = tCenter.y - sCenter.y;
+
+  if (dx > 0 && Math.abs(dx) >= Math.abs(dy)) {
+    return { sourceHandle: 'r', targetHandle: 'l' };
+  }
+  return { sourceHandle: 'b', targetHandle: 't' };
+};
+
+export const computeLayout = async (
+  nodes: readonly LayoutNode[],
+  edges: readonly LayoutEdge[],
+  options?: LayoutOptions,
+): Promise<LayoutResult> => {
+  // Stable input ordering keeps ELK output deterministic across runs.
+  const allNodes = [...nodes].sort((a, b) => a.id.localeCompare(b.id));
+  const connectors = [...edges].sort((a, b) => a.id.localeCompare(b.id));
+
+  const result: LayoutResult = { nodes: {}, connectors: {} };
+
+  if (allNodes.length === 0) return result;
+
+  const dims = new Map<string, { width: number; height: number }>();
+  for (const n of allNodes) dims.set(n.id, nodeDimensions(n));
+
+  const referenced = new Set<string>();
+  for (const c of connectors) {
+    referenced.add(c.source);
+    referenced.add(c.target);
+  }
+  const laidOut = allNodes.filter((n) => referenced.has(n.id) && !isFloatingAnnotation(n));
+  const floatingNodes = allNodes.filter((n) => !laidOut.includes(n));
+
+  const layerSpacing = options?.spacing?.layer ?? 220;
+  const nodeSpacing = options?.spacing?.node ?? 140;
+  const direction = options?.direction ?? 'RIGHT';
+
+  if (laidOut.length > 0) {
+    const elkGraph = {
+      id: 'root',
+      layoutOptions: {
+        'elk.algorithm': 'layered',
+        'elk.direction': direction,
+        'elk.layered.spacing.nodeNodeBetweenLayers': String(layerSpacing),
+        'elk.spacing.nodeNode': String(nodeSpacing),
+        'elk.spacing.edgeNode': '60',
+        'elk.spacing.edgeEdge': '30',
+        'elk.spacing.edgeLabel': '12',
+        'elk.layered.edgeLabels.sideSelection': 'SMART_DOWN',
+        'elk.edgeRouting': 'ORTHOGONAL',
+        'elk.separateConnectedComponents': 'true',
+      },
+      children: laidOut.map((n) => {
+        const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.playNode;
+        return { id: n.id, width: d.width, height: d.height };
+      }),
+      edges: connectors
+        .filter((c) => referenced.has(c.source) && referenced.has(c.target))
+        .map((c) => ({ id: c.id, sources: [c.source], targets: [c.target] })),
+    };
+
+    const out = await elk.layout(elkGraph);
+    for (const child of out.children ?? []) {
+      if (typeof child.x !== 'number' || typeof child.y !== 'number') continue;
+      result.nodes[child.id] = {
+        position: { x: Math.round(child.x), y: Math.round(child.y) },
+      };
+    }
+  }
+
+  // Floating nodes get a right-side column at x = maxLaidOutX + gap. Avoids
+  // the (0,0) pile-up that the old hand-authored positions had whenever a
+  // sticky note slipped through without an explicit position.
+  if (floatingNodes.length > 0) {
+    let maxRight = 0;
+    for (const id of Object.keys(result.nodes)) {
+      const pos = result.nodes[id]?.position;
+      const d = dims.get(id);
+      if (!pos || !d) continue;
+      maxRight = Math.max(maxRight, pos.x + d.width);
+    }
+    const columnX = laidOut.length > 0 ? maxRight + 200 : 0;
+    let cursorY = 0;
+    for (const n of floatingNodes) {
+      const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.shapeNode;
+      result.nodes[n.id] = { position: { x: columnX, y: cursorY } };
+      cursorY += d.height + nodeSpacing;
+    }
+  }
+
+  // Geometric handle assignment runs after positions are known so it can
+  // see whether each edge ended up going east, south, or backwards.
+  for (const c of connectors) {
+    const sPos = result.nodes[c.source]?.position;
+    const tPos = result.nodes[c.target]?.position;
+    const sDim = dims.get(c.source);
+    const tDim = dims.get(c.target);
+    if (!sPos || !tPos || !sDim || !tDim) continue;
+    result.connectors[c.id] = pickHandles(
+      { x: sPos.x, y: sPos.y, w: sDim.width, h: sDim.height },
+      { x: tPos.x, y: tPos.y, w: tDim.width, h: tDim.height },
+    );
+  }
+
+  return result;
+};

package/src/mcp.ts

@@ -98,7 +98,7 @@ const DemoNodeIdBaseSchema = z.object({
 });
 
 // add_node input: { flowId, node: <node payload> }. The inner `node` object is
-// loose here (additionalProperties=true via passthrough) because FlowSchema
+// loose here (additionalProperties=true via passthrough) because ResolvedFlowSchema
 // runs the full validation server-side after the new node is merged in.
 const AddNodeInputSchema = z.object({
   flowId: z.string().min(1),
@@ -139,7 +139,7 @@ const PatchNodeInputSchema = NodePatchBodySchema.extend({
 
 // add_connector input: { flowId, connector: <connector payload> }. The inner
 // `connector` object is loose (additionalProperties=true via z.record) because
-// FlowSchema runs the full validation server-side after the new connector is
+// ResolvedFlowSchema runs the full validation server-side after the new connector is
 // merged in (post-mutation parse catches dangling source/target refs and
 // kind-discriminator violations).
 const AddConnectorInputSchema = z.object({
@@ -174,25 +174,25 @@ const buildTools = (deps: OperationsDeps): McpTool[] => [
   {
     name: 'validate_seeflow',
     description:
-      'Validate an architecture.json (and optional style.json) against the ' +
-      'SeeFlow schemas. Stateless: no flow id, no file:// resolution, no ' +
-      'registry side-effects. Returns { ok: true } or { ok: false, issues }.',
+      'Validate a flow.json (and optional style.json) against the SeeFlow ' +
+      'schemas. Stateless: no flow id, no file:// resolution, no registry ' +
+      'side-effects. Returns { ok: true } or { ok: false, issues }.',
     inputSchema: {
       type: 'object',
       properties: {
-        architecture: { type: 'object' },
+        flow: { type: 'object' },
         style: { type: 'object' },
       },
-      required: ['architecture'],
+      required: ['flow'],
       additionalProperties: false,
     },
     handler: async (args) => {
       const body = args as Record<string, unknown> | undefined;
-      if (!body || !('architecture' in body)) {
-        return errorResult('Body must include `architecture`');
+      if (!body || !('flow' in body)) {
+        return errorResult('Body must include `flow`');
       }
       const result = validateImpl({
-        architecture: body.architecture,
+        flow: body.flow,
         style: body.style as unknown,
       });
       return okResult(result);

package/src/merge.ts

@@ -1,19 +1,19 @@
-import type { Architecture, Flow, Style } from './schema.ts';
+import type { Flow, ResolvedFlow, Style } from './schema.ts';
 
 /**
- * Merge architecture.json (semantic data) and the optional style.json
- * (presentation overrides) into the merged Flow shape consumed by the API,
- * the canvas, and the rest of the studio.
+ * Merge flow.json (semantic data) and the optional style.json (presentation
+ * overrides) into the merged ResolvedFlow shape consumed by the API, the
+ * canvas, and the rest of the studio.
  *
- * Style entries with no matching architecture id are silently dropped — the
- * write path strips dangling entries after delete, but a stale file on disk
+ * Style entries with no matching flow id are silently dropped — the write
+ * path strips dangling entries after delete, but a stale file on disk
  * shouldn't break the read path.
  */
-export function mergeArchitectureAndStyle(arch: Architecture, style: Style): Flow {
+export function mergeFlowAndStyle(flow: Flow, style: Style): ResolvedFlow {
   const nodeStyles = style.nodes ?? {};
   const connectorStyles = style.connectors ?? {};
 
-  const mergedNodes = arch.nodes.map((node) => {
+  const mergedNodes = flow.nodes.map((node) => {
     const s = nodeStyles[node.id] ?? {};
     const { position, ...visual } = s;
     return {
@@ -23,23 +23,23 @@ export function mergeArchitectureAndStyle(arch: Architecture, style: Style): Flo
     };
   });
 
-  const mergedConnectors = arch.connectors.map((conn) => {
+  const mergedConnectors = flow.connectors.map((conn) => {
     const s = connectorStyles[conn.id] ?? {};
     return { ...conn, ...s };
   });
 
   return {
-    version: arch.version,
-    name: arch.name,
-    ...(arch.resetAction ? { resetAction: arch.resetAction } : {}),
+    version: flow.version,
+    name: flow.name,
+    ...(flow.resetAction ? { resetAction: flow.resetAction } : {}),
     nodes: mergedNodes,
     connectors: mergedConnectors,
-  } as Flow;
+  } as ResolvedFlow;
 }
 
-// Fields that live in a node's `data` block on architecture.json. Every other
-// data field is visual and routes to style.json.
-const NODE_DATA_ARCH_KEYS = new Set([
+// Fields that live in a node's `data` block on flow.json. Every other data
+// field is visual and routes to style.json.
+const NODE_DATA_FLOW_KEYS = new Set([
   'name',
   'kind',
   'stateSource',
@@ -65,14 +65,13 @@ const NODE_STYLE_KEYS = new Set([
   'fontSize',
   'textColor',
   'cornerRadius',
-  'locked',
   'borderWidth',
   'color',
   'strokeWidth',
   'autoSize',
 ]);
 
-const CONNECTOR_ARCH_KEYS = new Set([
+const CONNECTOR_FLOW_KEYS = new Set([
   'id',
   'source',
   'target',
@@ -100,28 +99,28 @@ const CONNECTOR_STYLE_KEYS = new Set([
 ]);
 
 /**
- * Split a merged Flow back into (architecture, style) for atomic write. The
- * inverse of mergeArchitectureAndStyle: position and every visual field on
- * each node moves to `style.nodes[id]`; handles, pins, and visual fields on
- * each connector move to `style.connectors[id]`. Architecture keeps every
- * semantic data field — the routing tables above are the source of truth.
+ * Split a merged ResolvedFlow back into (flow, style) for atomic write. The
+ * inverse of mergeFlowAndStyle: position and every visual field on each node
+ * moves to `style.nodes[id]`; handles, pins, and visual fields on each
+ * connector move to `style.connectors[id]`. Flow keeps every semantic data
+ * field — the routing tables above are the source of truth.
  *
  * Style entries that end up empty are omitted from the output so the file
  * stays compact (matches the design's "delete style.json when {}" rule).
  */
-export function splitFlow(flow: {
+export function splitFlow(resolved: {
   version: number;
   name: string;
   resetAction?: unknown;
   nodes: Array<Record<string, unknown>>;
   connectors: Array<Record<string, unknown>>;
-}): { architecture: Record<string, unknown>; style: Record<string, unknown> } {
-  const archNodes: Array<Record<string, unknown>> = [];
+}): { flow: Record<string, unknown>; style: Record<string, unknown> } {
+  const flowNodes: Array<Record<string, unknown>> = [];
   const styleNodes: Record<string, Record<string, unknown>> = {};
 
-  for (const node of flow.nodes) {
+  for (const node of resolved.nodes) {
     const id = node.id as string;
-    const archNode: Record<string, unknown> = { id, type: node.type };
+    const flowNode: Record<string, unknown> = { id, type: node.type };
     const styleEntry: Record<string, unknown> = {};
 
     if (node.position && typeof node.position === 'object') {
@@ -129,62 +128,62 @@ export function splitFlow(flow: {
     }
 
     const data = (node.data ?? {}) as Record<string, unknown>;
-    const archData: Record<string, unknown> = {};
+    const flowData: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data)) {
       if (v === undefined) continue;
-      if (NODE_DATA_ARCH_KEYS.has(k)) {
-        archData[k] = v;
+      if (NODE_DATA_FLOW_KEYS.has(k)) {
+        flowData[k] = v;
       } else if (NODE_STYLE_KEYS.has(k)) {
         styleEntry[k] = v;
       } else {
-        // Unknown forward-compat key — keep on architecture side so the
-        // schema's strict() will catch typos but extension is possible by
-        // updating the routing tables here.
-        archData[k] = v;
+        // Unknown forward-compat key — keep on flow side so the schema's
+        // strict() will catch typos but extension is possible by updating
+        // the routing tables here.
+        flowData[k] = v;
       }
     }
-    archNode.data = archData;
-    archNodes.push(archNode);
+    flowNode.data = flowData;
+    flowNodes.push(flowNode);
 
     if (Object.keys(styleEntry).length > 0) {
       styleNodes[id] = styleEntry;
     }
   }
 
-  const archConnectors: Array<Record<string, unknown>> = [];
+  const flowConnectors: Array<Record<string, unknown>> = [];
   const styleConnectors: Record<string, Record<string, unknown>> = {};
 
-  for (const conn of flow.connectors) {
+  for (const conn of resolved.connectors) {
     const id = conn.id as string;
-    const archConn: Record<string, unknown> = {};
+    const flowConn: Record<string, unknown> = {};
     const styleEntry: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(conn)) {
       if (v === undefined) continue;
-      if (CONNECTOR_ARCH_KEYS.has(k)) {
-        archConn[k] = v;
+      if (CONNECTOR_FLOW_KEYS.has(k)) {
+        flowConn[k] = v;
       } else if (CONNECTOR_STYLE_KEYS.has(k)) {
         styleEntry[k] = v;
       } else {
-        archConn[k] = v;
+        flowConn[k] = v;
       }
     }
-    archConnectors.push(archConn);
+    flowConnectors.push(flowConn);
     if (Object.keys(styleEntry).length > 0) {
       styleConnectors[id] = styleEntry;
     }
   }
 
-  const architecture: Record<string, unknown> = {
-    version: flow.version,
-    name: flow.name,
-    nodes: archNodes,
-    connectors: archConnectors,
+  const flow: Record<string, unknown> = {
+    version: resolved.version,
+    name: resolved.name,
+    nodes: flowNodes,
+    connectors: flowConnectors,
   };
-  if (flow.resetAction !== undefined) architecture.resetAction = flow.resetAction;
+  if (resolved.resetAction !== undefined) flow.resetAction = resolved.resetAction;
 
   const style: Record<string, unknown> = {};
   if (Object.keys(styleNodes).length > 0) style.nodes = styleNodes;
   if (Object.keys(styleConnectors).length > 0) style.connectors = styleConnectors;
 
-  return { architecture, style };
+  return { flow, style };
 }