@tuongaz/seeflow 0.1.63 → 0.1.65

package/examples/ecommerce-platform/flow.json

@@ -4,23 +4,22 @@
   "nodes": [
     {
       "id": "node-cQOUPXanaX",
-      "type": "shapeNode",
+      "type": "user",
       "data": {
-        "shape": "user",
         "name": "Customer",
         "description": "Web / Mobile / Partner"
       }
     },
     {
       "id": "node-CbwYqb7NfB",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "API Gateway",
+        "description": "Auth, rate-limiting, routing.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
         },
-        "description": "Auth, rate-limiting, routing.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -31,38 +30,38 @@
     },
     {
       "id": "node-3zFtHg6ENc",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Auth Service",
+        "description": "JWT issuance + OAuth2 / OIDC.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
-        },
-        "description": "JWT issuance + OAuth2 / OIDC.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-kwBY8YPmYM",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Product Catalog",
+        "description": "SKUs, variants, pricing, full-text search.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
-        },
-        "description": "SKUs, variants, pricing, full-text search.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-5F424NWbEu",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "Cart Service",
+        "description": "Add/remove items, apply coupons, checkout.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
         },
-        "description": "Add/remove items, apply coupons, checkout.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -73,14 +72,14 @@
     },
     {
       "id": "node-yKrg9DV5fJ",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "Order Service",
+        "description": "pending → confirmed → shipped → delivered.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
         },
-        "description": "pending → confirmed → shipped → delivered.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -91,40 +90,39 @@
     },
     {
       "id": "node-mPqan8rFYN",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Payment Service",
+        "description": "Stripe + PayPal gateway integration.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Stripe + PayPal gateway integration.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-fkptXw7uvs",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Notification Service",
+        "description": "Email + SMS + push via AWS SES / SNS.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Email + SMS + push via AWS SES / SNS.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-5SDiw3Wz6s",
-      "type": "shapeNode",
+      "type": "database",
       "data": {
-        "shape": "database",
         "name": "PostgreSQL",
         "description": "Orders, users, products — primary OLTP store"
       }
     },
     {
       "id": "node-XwygzfKPZ5",
-      "type": "htmlNode",
+      "type": "html",
       "data": {
         "name": "Platform Health",
         "html": "file://view.html"

package/examples/order-pipeline/flow.json

@@ -4,14 +4,14 @@
   "nodes": [
     {
       "id": "node-XKIyds0TDg",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "POST /orders",
+        "description": "Creates order, kicks off the pipeline.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
         },
-        "description": "Creates order, kicks off the pipeline.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -22,39 +22,39 @@
     },
     {
       "id": "node-GXTKUcE3ye",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Inventory Service",
-        "stateSource": {
-          "kind": "event"
-        },
         "description": "Reserves stock.",
         "detail": "file://detail.md",
-        "icon": "a-arrow-down-icon"
+        "icon": "a-arrow-down-icon",
+        "stateSource": {
+          "kind": "event"
+        }
       }
     },
     {
       "id": "node-YOYiHJpY0i",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Payment Service",
+        "description": "Charges card.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Charges card.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-zUIH7WFnhK",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Fulfillment Service",
+        "description": "Enqueues shipment.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Enqueues shipment.",
-        "detail": "file://detail.md"
+        }
       }
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuongaz/seeflow",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Local studio that hosts file-defined demos as React Flow canvases wired to a running app via REST + SSE + Zod schema.",
   "keywords": [
     "seeflow",

package/src/api.ts

@@ -345,14 +345,7 @@ export function createApi(options: ApiOptions): Hono {
       }
       const flow = flowParse.data;
       const result = await computeLayout(
-        flow.nodes.map((n) => ({
-          id: n.id,
-          type: n.type,
-          // Only `shape` matters for layout (floating-annotation detection +
-          // shape-specific sizing). Other Flow data fields are irrelevant.
-          data:
-            n.type === 'shapeNode' ? { shape: (n.data as { shape?: string }).shape } : undefined,
-        })),
+        flow.nodes.map((n) => ({ id: n.id, type: n.type })),
         flow.connectors.map((c) => ({ id: c.id, source: c.source, target: c.target })),
         options,
       );
@@ -375,12 +368,18 @@ export function createApi(options: ApiOptions): Hono {
         .map((n) => ({
           id: n.id,
           type: n.type as
-            | 'playNode'
-            | 'stateNode'
-            | 'shapeNode'
-            | 'imageNode'
-            | 'iconNode'
-            | 'htmlNode',
+            | 'rectangle'
+            | 'ellipse'
+            | 'sticky'
+            | 'text'
+            | 'database'
+            | 'server'
+            | 'user'
+            | 'queue'
+            | 'cloud'
+            | 'image'
+            | 'html'
+            | 'icon',
           data:
             typeof n.width === 'number' && typeof n.height === 'number'
               ? { width: n.width, height: n.height }
@@ -582,7 +581,7 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // POST /api/projects/:id/files/open — shell out to `$EDITOR <abs>` so the
-  // user can edit a project-scoped file (htmlNode block, image asset) in
+  // user can edit a project-scoped file (type:'html' block, image asset) in
   // their IDE. The endpoint always returns the resolved absolute path in
   // the response body so the frontend can copy-to-clipboard when $EDITOR
   // isn't set or the spawn fails. Path safety mirrors the GET route.
@@ -815,13 +814,10 @@ export function createApi(options: ApiOptions): Hono {
 
     const node = merged.flow.nodes.find((n) => n.id === nodeId);
     if (!node) return c.json({ error: `Unknown nodeId: ${nodeId}` }, 404);
-    if (
-      node.type === 'shapeNode' ||
-      node.type === 'imageNode' ||
-      node.type === 'iconNode' ||
-      node.type === 'htmlNode' ||
-      !node.data.playAction
-    ) {
+    // playAction is optional on every node type post-flat-types. The runtime
+    // gate is purely "is the field set?" — visual kind doesn't constrain
+    // playability.
+    if (!node.data.playAction) {
       return c.json({ error: `Node ${nodeId} has no playAction` }, 400);
     }
 
@@ -1007,7 +1003,7 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // PATCH a single node — partial update of position, label, detail, visual
-  // fields, or shapeNode-only fields. Every UI-driven node edit (other than
+  // fields, or geometric-only fields. Every UI-driven node edit (other than
   // the high-frequency drag fast-path above) flows through here. The mutation
   // is performed against the raw parsed JSON (so unknown v2 fields the schema
   // doesn't yet recognize survive round-trips) and the WHOLE resulting demo

package/src/cli-e2e.ts

@@ -1,5 +1,5 @@
 // End-to-end validator used by `seeflow e2e <flowId>`. Opens an SSE channel to
-// the studio, triggers every playNode's playAction (sequentially), then drains
+// the studio, triggers every node carrying a playAction (sequentially), then drains
 // the channel for node:done/error + node:status reports. Mirrors the algorithm
 // in skills/seeflow/scripts/validate-end-to-end.ts — kept here so the CLI does
 // not depend on the skill folder.
@@ -167,15 +167,14 @@ function openSseChannel(body: ReadableStream<Uint8Array>): SseChannel {
 }
 
 function hasPlayAction(node: NodeShape): boolean {
-  return (
-    (node.type === 'playNode' || node.type === 'stateNode') && node.data?.playAction !== undefined
-  );
+  // Flat-types refactor: capabilities are top-level data fields on every
+  // type, not gated by the type tag. The e2e runner iterates every node
+  // carrying a playAction regardless of variant.
+  return node.data?.playAction !== undefined;
 }
 
 function hasStatusAction(node: NodeShape): boolean {
-  return (
-    (node.type === 'playNode' || node.type === 'stateNode') && node.data?.statusAction !== undefined
-  );
+  return node.data?.statusAction !== undefined;
 }
 
 export async function validateEndToEnd(options: ValidateOptions): Promise<ValidationReport> {

package/src/cli-manifest.ts

@@ -281,7 +281,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     },
     requiresStudio: false,
     examples: [
-      'seeflow flow:add-bulk abc12345 --json \'{"nodes":[{"id":"a","type":"shapeNode","data":{"shape":"rectangle"}}],"connectors":[]}\'',
+      'seeflow flow:add-bulk abc12345 --json \'{"nodes":[{"id":"a","type":"rectangle","data":{}}],"connectors":[]}\'',
       'seeflow flow:add-bulk abc12345 --file batch.json',
     ],
   },
@@ -344,7 +344,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     flags: BODY_FLAGS,
     body: {
       example: {
-        type: 'stateNode',
+        type: 'rectangle',
         data: { name: 'hello', stateSource: { kind: 'request' } },
       },
     },
@@ -360,9 +360,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       ],
     },
     requiresStudio: false,
-    examples: [
-      'seeflow nodes:add abc12345 --json \'{"type":"shapeNode","data":{"shape":"rectangle"}}\'',
-    ],
+    examples: ['seeflow nodes:add abc12345 --json \'{"type":"rectangle","data":{}}\''],
   },
   {
     name: 'nodes:get',

package/src/cli.ts

@@ -20,6 +20,7 @@ import {
   clearPid,
   defaultPidPath,
   isPidAlive,
+  portInUse,
   readConfig,
   readPid,
   studioUrl,
@@ -266,6 +267,20 @@ async function runHelp() {
   console.log(renderCommandList());
 }
 
+// Pre-flight: refuse to start if the studio port already has a TCP listener.
+// We deliberately do NOT probe Vite's port (5173) here — `bun run dev` spawns
+// Vite alongside the studio, so Vite legitimately owns 5173 in dev mode and a
+// probe can't distinguish "our Vite" from a stranger. If Vite's port is taken
+// by something else, Vite itself surfaces the conflict.
+async function assertPortFree(studioPort: number, host: string): Promise<void> {
+  if (!(await portInUse(host, studioPort))) return;
+  console.error(
+    `Cannot start SeeFlow: port ${studioPort} already in use.\n` +
+      `Stop the running server on ${studioPort} first, then retry.`,
+  );
+  process.exit(1);
+}
+
 async function runStart() {
   mkdirSync(seeflowHome(), { recursive: true });
   const config = readConfig();
@@ -294,6 +309,12 @@ async function runStart() {
     return;
   }
 
+  // Defense-in-depth: parent already checked in spawnDaemon, but a race
+  // between parent-check and child-bind can still let another process grab
+  // the port. Re-check here so the child fails fast with a clear error
+  // instead of EADDRINUSE at bind time.
+  await assertPortFree(port, config.host);
+
   // persist the chosen address so other subcommands can find us
   writeConfig({ port, host: config.host });
 
@@ -368,6 +389,11 @@ async function spawnDaemon(port: number, host: string) {
     return;
   }
 
+  // Studio port must be free before we fork a detached child — otherwise the
+  // user waits HEALTH_TIMEOUT_MS for a doomed health probe before seeing a
+  // generic timeout error.
+  await assertPortFree(port, host);
+
   const proc = spawnDetachedStudio(port);
   writePid(proc.pid);
   writeConfig({ port, host });

package/src/diagram.ts

@@ -240,9 +240,10 @@ const normalizeConnectors = (
 // Single-flow-node graphs short-circuit so callers can pin standalone
 // nodes via `layout.positions`.
 const isFloatingAnnotation = (n: Record<string, unknown>): boolean => {
-  if (n.type !== 'shapeNode') return false;
-  const shape = (n.data as { shape?: string } | undefined)?.shape;
-  return shape === 'sticky' || shape === 'text';
+  // Flat-types refactor: visual kind IS the type. The annotation shapes
+  // (sticky + text) live as top-level type tags rather than nested shape
+  // under a generic shape variant.
+  return n.type === 'sticky' || n.type === 'text';
 };
 
 const autoLayout = async (
@@ -354,12 +355,14 @@ export const validateDemo = (req: ValidateRequest): ValidateReport => {
 
   const playable = nodes.filter((n) => {
     const data = n.data as { playAction?: unknown } | undefined;
-    return n.type === 'playNode' || (n.type === 'stateNode' && data?.playAction !== undefined);
+    // Flat-types refactor: a node is playable iff it carries a playAction
+    // capability, regardless of variant.
+    return data?.playAction !== undefined;
   });
   if (tier !== 'static' && playable.length === 0) {
     issues.push({
       kind: 'tier-mismatch',
-      message: `Tier '${tier}' requires at least one playable node; found 0. Either add a playNode or set tier=static.`,
+      message: `Tier '${tier}' requires at least one playable node; found 0. Set data.playAction on a node or set tier=static.`,
     });
   }
 

package/src/layout.ts

@@ -51,7 +51,7 @@ export interface LayoutResult {
 export interface LayoutNode {
   id: string;
   type: FlowNode['type'];
-  data?: { width?: number; height?: number; shape?: string };
+  data?: { width?: number; height?: number };
 }
 
 export interface LayoutEdge {
@@ -60,42 +60,38 @@ export interface LayoutEdge {
   target: string;
 }
 
+// Per-type default size used when a node has no explicit width/height. Mirrors
+// the canvas's SHAPE_DEFAULT_SIZE so ELK's layout matches what the canvas will
+// paint.
 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 }> = {
+  rectangle: { width: 200, height: 120 },
+  ellipse: { width: 200, height: 120 },
+  sticky: { width: 180, height: 180 },
   text: { width: 160, height: 40 },
-  sticky: { width: 160, height: 180 },
+  database: { width: 120, height: 140 },
+  server: { width: 140, height: 120 },
+  user: { width: 100, height: 140 },
+  queue: { width: 220, height: 80 },
+  cloud: { width: 180, height: 120 },
+  image: { width: 200, height: 150 },
+  html: { width: 320, height: 200 },
+  icon: { width: 80, height: 80 },
 };
 
-const FLOATING_SHAPES = new Set(['sticky', 'text']);
+// Sticky / text variants are floating annotations. They never participate in
+// layered layout — they sit in a side column so the orthogonal flow stays
+// clean.
+const FLOATING_TYPES: ReadonlySet<FlowNode['type']> = 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);
-};
+const isFloatingAnnotation = (node: LayoutNode): boolean => FLOATING_TYPES.has(node.type);
 
 // Schema vocabulary: SourceHandle ∈ {r, b}, TargetHandle ∈ {t, l}. After
 // ELK lays out positions we pick handles geometrically — the layered LR
@@ -162,7 +158,7 @@ export const computeLayout = async (
         'elk.separateConnectedComponents': 'true',
       },
       children: laidOut.map((n) => {
-        const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.playNode;
+        const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.rectangle;
         return { id: n.id, width: d.width, height: d.height };
       }),
       edges: connectors
@@ -193,7 +189,7 @@ export const computeLayout = async (
     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;
+      const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.rectangle;
       result.nodes[n.id] = { position: { x: columnX, y: cursorY } };
       cursorY += d.height + nodeSpacing;
     }

package/src/mcp.ts

@@ -461,7 +461,7 @@ const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_add_node',
     description:
-      'Append a new node to a flow (cascade-safe; id auto-generated when omitted). Text content fields (detail on every node; html on htmlNode) are auto-externalized to <project>/nodes/<id>/ and stored as file:// refs in flow.json; reads inline the resolved content transparently.',
+      "Append a new node to a flow (cascade-safe; id auto-generated when omitted). Text content fields (detail on every node; html on type:'html') are auto-externalized to <project>/nodes/<id>/ and stored as file:// refs in flow.json; reads inline the resolved content transparently.",
     inputSchema: inputSchemaFromZod(AddNodeInputSchema),
     handler: async (args) => {
       const parsed = AddNodeInputSchema.safeParse(args);
@@ -585,7 +585,7 @@ const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_patch_node',
     description:
-      'Update fields on an existing node (position, name, description, detail, icon, colors, border, font, shape, dimensions, autoSize, plus iconNode-only color/strokeWidth/alt). Setting detail (every node) or html (htmlNode) writes the content to <project>/nodes/<id>/{detail.md|view.html}; the file:// ref on the node persists. Empty-string detail empties the file but keeps the ref.',
+      "Update fields on an existing node (position, name, description, detail, icon, colors, border, font, dimensions, autoSize, plus type:'icon'-only color/strokeWidth/alt and capabilities playAction/statusAction/stateSource). `type` can flip a node between any of the 12 visual variants (rectangle/ellipse/sticky/text/database/server/user/queue/cloud/image/html/icon); the post-merge schema reparse gates required fields on the new type (image.data.path, icon.data.icon). Setting detail (every node) or html (type:'html') writes the content to <project>/nodes/<id>/{detail.md|view.html}; the file:// ref on the node persists. Empty-string detail empties the file but keeps the ref.",
     inputSchema: inputSchemaFromZod(PatchNodeInputSchema),
     handler: async (args) => {
       const parsed = PatchNodeInputSchema.safeParse(args);

package/src/merge.ts

@@ -39,10 +39,12 @@ export function mergeFlowAndStyle(flow: Flow, style: Style): ResolvedFlow {
 }
 
 // Fields that live in a node's `data` block on flow.json. Every other data
-// field is visual and routes to style.json.
+// field is visual and routes to style.json. The flat-types refactor folds
+// the visual kind into `node.type` itself (no more nested data.shape / data.kind)
+// and makes every capability (playAction / statusAction / stateSource) valid
+// on every type.
 const NODE_DATA_FLOW_KEYS = new Set([
   'name',
-  'kind',
   'stateSource',
   'handlerModule',
   'icon',
@@ -50,7 +52,6 @@ const NODE_DATA_FLOW_KEYS = new Set([
   'detail',
   'playAction',
   'statusAction',
-  'shape',
   'path',
   'alt',
   'html',

package/src/node-files.ts

@@ -14,7 +14,7 @@ export interface ExternalizedFieldSpec {
 
 export const EXTERNALIZED_NODE_FIELDS: readonly ExternalizedFieldSpec[] = [
   { field: 'detail', fileName: 'detail.md' },
-  { field: 'html', fileName: 'view.html', nodeTypes: ['htmlNode'] },
+  { field: 'html', fileName: 'view.html', nodeTypes: ['html'] },
 ];
 
 export const externalizedFieldsForNodeType = (