@tuongaz/seeflow 0.1.41 → 0.1.47

package/src/operations.ts

@@ -7,18 +7,19 @@
 // Helpers extracted in US-003: node lifecycle (add/delete/move/reorder).
 // Future stories add patch_node + connector helpers alongside these.
 
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
 import { type ZodIssue, z } from 'zod';
+import { writeFileAtomic } from './atomic-write.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
+import {
+  EXTERNALIZED_NODE_FIELDS,
+  externalizedFieldsForNodeType,
+  nodeFileAbsPath,
+  nodeFileRef,
+  removeNodeDir,
+  writeNodeFile,
+} from './node-files.ts';
 import { seeflowHome } from './paths.ts';
 import { type Registry, slugify } from './registry.ts';
 import {
@@ -26,13 +27,18 @@ import {
   EdgePinSchema,
   type Flow,
   FlowSchema,
+  PlayActionSchema,
   type ResolvedFlow,
   ResolvedFlowSchema,
+  ShapeKindSchema,
   SourceHandleIdSchema,
+  StateSourceSchema,
+  StatusActionSchema,
   StyleSchema,
   TargetHandleIdSchema,
 } from './schema.ts';
 import { writeSdkEmitIfNeeded } from './sdk-writer.ts';
+import { shortId } from './short-id.ts';
 import { type FlowSnapshot, type FlowWatcher, readMergedFlow } from './watcher.ts';
 
 const DEFAULT_FLOW_RELATIVE_PATH = '.seeflow/flow.json';
@@ -90,7 +96,7 @@ export const NodePatchBodySchema = z
     // sizes the wrapper around it. mergeNodeUpdates enforces the invariant
     // that autoSize:true never coexists with persisted width/height.
     autoSize: z.boolean().optional(),
-    shape: z.enum(['rectangle', 'ellipse', 'sticky', 'text']).optional(),
+    shape: ShapeKindSchema.optional(),
     // iconNode-only: stroke color token. Lands at data.color; ResolvedFlowSchema's
     // post-merge reparse gates that this is only valid on an iconNode.
     color: ColorTokenSchema.optional(),
@@ -110,6 +116,17 @@ export const NodePatchBodySchema = z
     // serialize signal — `mergeNodeUpdates` strips the key from disk.
     description: z.string().optional(),
     detail: z.string().optional(),
+    // htmlNode-only: inline HTML content. Externalized to
+    // `<project>/.seeflow/nodes/<id>/view.html` by patchNodeImpl; the file://
+    // ref on the node persists. Empty string empties the file but keeps the ref.
+    html: z.string().optional(),
+    // P5 overlay attach: lets the skill (or any consumer) wire executable
+    // behaviour onto a previously-created node without re-issuing it. Final
+    // validity is enforced by the post-merge ResolvedFlowSchema reparse —
+    // e.g. statusAction is only valid on playNode / stateNode.
+    playAction: PlayActionSchema.optional(),
+    statusAction: StatusActionSchema.optional(),
+    stateSource: StateSourceSchema.optional(),
   })
   .strict();
 export type NodePatchBody = z.infer<typeof NodePatchBodySchema>;
@@ -138,8 +155,14 @@ const NODE_DATA_PATCH_KEYS = [
   'icon',
   'description',
   'detail',
+  'html',
+  'playAction',
+  'statusAction',
+  'stateSource',
 ] as const satisfies ReadonlyArray<keyof NodePatchBody>;
 
+const EXTERNALIZED_FIELD_NAMES = new Set<string>(EXTERNALIZED_NODE_FIELDS.map((e) => e.field));
+
 export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePatchBody): void => {
   if (updates.position !== undefined) {
     node.position = updates.position;
@@ -152,6 +175,10 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
   let touchedData = false;
   for (const key of NODE_DATA_PATCH_KEYS) {
     if (updates[key] === undefined) continue;
+    // Externalized fields (detail, ...) flow through patchNodeImpl's own
+    // pre-process — keep merge out of it so the file:// ref on disk stays
+    // stable and the file is the source of truth for content.
+    if (EXTERNALIZED_FIELD_NAMES.has(key)) continue;
     // Empty string on the two free-text metadata fields is the documented
     // clear-on-serialize signal — strip the key instead of writing "" to disk
     // so flow.json stays compact and round-tripping a cleared node doesn't
@@ -286,6 +313,21 @@ export type AddNodeOutcome =
   | { kind: 'badSchema'; issues: ZodIssue[] }
   | { kind: 'writeFailed'; message: string };
 
+// Bulk add: ok payload carries every created node so the caller can read
+// server-assigned ids back. duplicateIdInBatch fires when two items in the
+// same request share an id; idAlreadyExists fires when a request id collides
+// with a node already on disk. Both are pre-write rejections, no rollback
+// needed. writeFailed/badSchema cover the post-mutation failure modes.
+export type AddNodesBulkOutcome =
+  | { kind: 'ok'; data: { nodes: Array<{ id: string; node: Record<string, unknown> }> } }
+  | { kind: 'flowNotFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; message: string }
+  | { kind: 'badSchema'; issues: ZodIssue[] }
+  | { kind: 'duplicateIdInBatch'; id: string }
+  | { kind: 'idAlreadyExists'; id: string }
+  | { kind: 'writeFailed'; message: string };
+
 export type DeleteNodeOutcome =
   | { kind: 'ok' }
   | { kind: 'flowNotFound' }
@@ -401,6 +443,21 @@ export const mergeConnectorUpdates = (
   }
 };
 
+// Bulk-add envelopes. Body shape gated here; per-item shape is implicit and
+// enforced by ResolvedFlowSchema after the whole batch is merged in — same
+// pattern the singular add endpoints already rely on. The 100-item cap keeps
+// one SSE broadcast payload reasonable; the LLM caller is meant to chunk if
+// it ever needs more.
+const BULK_MAX_ITEMS = 100;
+export const NodesBulkBodySchema = z.object({
+  nodes: z.array(z.record(z.unknown())).min(1).max(BULK_MAX_ITEMS),
+});
+export type NodesBulkBody = z.infer<typeof NodesBulkBodySchema>;
+export const ConnectorsBulkBodySchema = z.object({
+  connectors: z.array(z.record(z.unknown())).min(1).max(BULK_MAX_ITEMS),
+});
+export type ConnectorsBulkBody = z.infer<typeof ConnectorsBulkBodySchema>;
+
 export type AddConnectorOutcome =
   | { kind: 'ok'; data: { id: string } }
   | { kind: 'flowNotFound' }
@@ -409,6 +466,16 @@ export type AddConnectorOutcome =
   | { kind: 'badSchema'; issues: ZodIssue[] }
   | { kind: 'writeFailed'; message: string };
 
+export type AddConnectorsBulkOutcome =
+  | { kind: 'ok'; data: { connectors: Array<{ id: string }> } }
+  | { kind: 'flowNotFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; message: string }
+  | { kind: 'badSchema'; issues: ZodIssue[] }
+  | { kind: 'duplicateIdInBatch'; id: string }
+  | { kind: 'idAlreadyExists'; id: string }
+  | { kind: 'writeFailed'; message: string };
+
 export type PatchConnectorOutcome =
   | { kind: 'ok' }
   | { kind: 'flowNotFound' }
@@ -454,20 +521,7 @@ export const withFlowWriteLock = <T>(flowId: string, fn: () => Promise<T>): Prom
  * editor diffs clean (single fs.watch event for the rename) and means a crash
  * during write can never corrupt the original.
  */
-export const writeFileAtomic = (filePath: string, content: string): void => {
-  const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
-  try {
-    writeFileSync(tempPath, content);
-    renameSync(tempPath, filePath);
-  } catch (err) {
-    try {
-      if (existsSync(tempPath)) unlinkSync(tempPath);
-    } catch {
-      // best-effort cleanup
-    }
-    throw err;
-  }
-};
+export { writeFileAtomic } from './atomic-write.ts';
 
 /**
  * Read flow.json + optional style.json, return the raw parsed JSON so
@@ -604,13 +658,27 @@ export async function mutateMergedFlow<E extends { kind: string }>(
     return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
   }
 
-  const snap: FlowSnapshot = {
-    flow: finalParse.data as ResolvedFlow,
-    valid: true,
-    error: null,
-    filePath: flowPath,
-    parsedAt: Date.now(),
-  };
+  // Re-read through readMergedFlow so the snapshot we hand to notifyWritten
+  // carries file://-resolved content (detail.md, view.html, …). The in-memory
+  // `merged` tree above still holds raw `file://<name>` strings — broadcasting
+  // it would clobber the watcher's resolved seed and ship unresolved refs to
+  // every SSE subscriber until the next reparse.
+  const reread = readMergedFlow(flowPath);
+  const snap: FlowSnapshot = reread.valid
+    ? {
+        flow: reread.flow,
+        valid: true,
+        error: null,
+        filePath: flowPath,
+        parsedAt: Date.now(),
+      }
+    : {
+        flow: finalParse.data as ResolvedFlow,
+        valid: true,
+        error: null,
+        filePath: flowPath,
+        parsedAt: Date.now(),
+      };
   return { kind: 'ok', snap, flowContent, styleContent };
 }
 
@@ -889,7 +957,7 @@ export async function addNodeImpl(
 
   const newNode = { ...nodeBody };
   if (typeof newNode.id !== 'string' || newNode.id.length === 0) {
-    newNode.id = `node-${crypto.randomUUID()}`;
+    newNode.id = `node-${shortId()}`;
   }
   const newId = newNode.id as string;
   // Default position so the post-merge ResolvedFlowSchema parse passes. Position lives
@@ -898,32 +966,27 @@ export async function addNodeImpl(
     newNode.position = { x: 0, y: 0 };
   }
 
-  // US-015: for htmlNode without a client-supplied htmlPath, allocate the
-  // studio-managed `blocks/<id>.html` path and queue a starter-file write.
-  // Client-supplied htmlPath wins and we skip the starter file (symmetric
-  // with US-016's hand-edited-path leave-alone rule).
-  let starterFile: { absPath: string; content: string } | undefined;
-  if (newNode.type === 'htmlNode') {
+  // Generic spec-driven externalization. For each spec entry that applies to
+  // this node type, capture inbound content (default empty string), replace
+  // data[field] with the file:// ref, and queue a write inside the mutator
+  // below — so flow.json only commits when the write succeeded.
+  const externalized: Array<{ absPath: string; content: string }> = [];
+  {
     const dataIsRecord =
       newNode.data !== null && typeof newNode.data === 'object' && !Array.isArray(newNode.data);
-    const existingData: Record<string, unknown> = dataIsRecord
+    const data: Record<string, unknown> = dataIsRecord
       ? { ...(newNode.data as Record<string, unknown>) }
       : {};
-    const clientProvidedHtmlPath =
-      typeof existingData.htmlPath === 'string' && existingData.htmlPath.length > 0;
-    if (!clientProvidedHtmlPath) {
-      const htmlPath = `blocks/${newId}.html`;
-      existingData.htmlPath = htmlPath;
-      newNode.data = existingData;
-      starterFile = {
-        absPath: join(entry.repoPath, '.seeflow', htmlPath),
-        content: buildHtmlNodeStarter(newId),
-      };
-    } else if (!dataIsRecord) {
-      // Coerce non-object data into the spread'd record so the schema parse
-      // sees the right shape — shouldn't happen in practice but keeps types honest.
-      newNode.data = existingData;
+    for (const { field, fileName } of externalizedFieldsForNodeType(newNode.type)) {
+      const incoming = data[field];
+      const content = typeof incoming === 'string' ? incoming : '';
+      data[field] = nodeFileRef(newId, fileName);
+      externalized.push({
+        absPath: nodeFileAbsPath(entry.repoPath, newId, fileName),
+        content,
+      });
     }
+    newNode.data = data;
   }
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -935,10 +998,9 @@ export async function addNodeImpl(
     fullPath,
     (flow) => {
       flow.nodes.push(newNode);
-      if (starterFile) {
+      for (const ext of externalized) {
         try {
-          mkdirSync(dirname(starterFile.absPath), { recursive: true });
-          writeFileAtomic(starterFile.absPath, starterFile.content);
+          writeNodeFile(ext.absPath, ext.content);
         } catch (err) {
           return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
         }
@@ -951,26 +1013,115 @@ export async function addNodeImpl(
   return result;
 }
 
-// US-015: starter HTML content for studio-created htmlNodes. Centered 'Edit me'
-// card with a `blocks/<id>.html` subtitle — matches the design's Section 6
-// markup exactly so the renderer paints a useful first impression while the
-// author hasn't yet edited the file.
-const buildHtmlNodeStarter = (nodeId: string): string =>
-  `<div class="flex h-full w-full items-center justify-center rounded-lg border border-slate-300 bg-white p-4 text-slate-900">
-  <div class="text-center">
-    <div class="font-semibold">Edit me</div>
-    <div class="text-xs text-slate-500">blocks/${nodeId}.html</div>
-  </div>
-</div>
-`;
+// Bulk add — N nodes in one read-validate-write-broadcast cycle. Transactional:
+// any single item failing the post-mutation ResolvedFlowSchema parse rolls
+// back the whole batch (nothing on flow.json, no per-node folders created).
+// Per-node externalization runs per item exactly like the singular path; the
+// queued file writes all happen inside the mutator so a writeFailed on item
+// K leaves items 0..K-1 with stranded folders — same shape as the singular
+// path's writeFailed, but amplified by N. Caller is expected to retry.
+export async function addNodesBulkImpl(
+  deps: OperationsDeps,
+  flowId: string,
+  body: NodesBulkBody,
+): Promise<AddNodesBulkOutcome> {
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
+
+  // Pre-allocate ids + capture externalization writes per item. Doing this
+  // outside the mutator means the duplicateIdInBatch check runs before any
+  // disk IO; the collide-with-existing check happens inside the mutator where
+  // it can see the freshly-read flow.nodes.
+  const prepared: Array<{
+    id: string;
+    node: Record<string, unknown>;
+    externalized: Array<{ absPath: string; content: string }>;
+  }> = [];
+  const idsInBatch = new Set<string>();
+  for (const item of body.nodes) {
+    const newNode = { ...item };
+    if (typeof newNode.id !== 'string' || newNode.id.length === 0) {
+      newNode.id = `node-${shortId()}`;
+    }
+    const newId = newNode.id as string;
+    if (idsInBatch.has(newId)) return { kind: 'duplicateIdInBatch', id: newId };
+    idsInBatch.add(newId);
+    if (!newNode.position || typeof newNode.position !== 'object') {
+      newNode.position = { x: 0, y: 0 };
+    }
+    const externalized: Array<{ absPath: string; content: string }> = [];
+    const dataIsRecord =
+      newNode.data !== null && typeof newNode.data === 'object' && !Array.isArray(newNode.data);
+    const data: Record<string, unknown> = dataIsRecord
+      ? { ...(newNode.data as Record<string, unknown>) }
+      : {};
+    for (const { field, fileName } of externalizedFieldsForNodeType(newNode.type)) {
+      const incoming = data[field];
+      const content = typeof incoming === 'string' ? incoming : '';
+      data[field] = nodeFileRef(newId, fileName);
+      externalized.push({
+        absPath: nodeFileAbsPath(entry.repoPath, newId, fileName),
+        content,
+      });
+    }
+    newNode.data = data;
+    prepared.push({ id: newId, node: newNode, externalized });
+  }
+
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
+  if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
+
+  const result = await mutateMergedFlowAndBroadcast<
+    { kind: 'idAlreadyExists'; id: string } | { kind: 'writeFailed'; message: string }
+  >(deps, flowId, fullPath, (flow) => {
+    const existing = new Set(
+      flow.nodes
+        .map((n) => (typeof n.id === 'string' ? n.id : null))
+        .filter((id): id is string => id !== null),
+    );
+    for (const p of prepared) {
+      if (existing.has(p.id)) return { kind: 'idAlreadyExists', id: p.id };
+    }
+    for (const p of prepared) {
+      flow.nodes.push(p.node);
+    }
+    for (const p of prepared) {
+      for (const ext of p.externalized) {
+        try {
+          writeNodeFile(ext.absPath, ext.content);
+        } catch (err) {
+          return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+        }
+      }
+    }
+    return { kind: 'ok' };
+  });
+
+  if (result.kind === 'ok') {
+    return {
+      kind: 'ok',
+      data: { nodes: prepared.map((p) => ({ id: p.id, node: p.node })) },
+    };
+  }
+
+  // Non-ok branch: the post-mutation ResolvedFlowSchema parse (or a later
+  // writeFailed) ran AFTER the mutator already wrote per-node folders. The
+  // collide-with-existing check ran first inside the mutator, so any folder
+  // at `nodes/<prepared.id>/` was created by this call — safe to cascade.
+  // The idAlreadyExists branch returns before any writeNodeFile, so we still
+  // try to remove (it's a no-op when the folder doesn't exist).
+  for (const p of prepared) {
+    removeNodeDir(entry.repoPath, p.id);
+  }
+  return result;
+}
 
 // Remove a node and cascade-delete every connector touching it in a single
 // atomic write. Final ResolvedFlowSchema parse stays in place so a pre-existing
 // schema violation surfaces honestly instead of being silently papered over.
-// US-016: when the removed node is an htmlNode whose data.htmlPath matches the
-// studio-managed shape `blocks/<id>.html`, the companion file is removed AFTER
-// the flow.json write succeeds. Hand-edited paths are left alone (symmetric
-// with US-015's "client-supplied htmlPath wins, no starter file written").
+// After the flow.json write, `removeNodeDir` cascades the node's whole
+// `<project>/.seeflow/nodes/<id>/` folder — covering detail.md, view.html,
+// and any imageNode upload that lived there.
 export async function deleteNodeImpl(
   deps: OperationsDeps,
   flowId: string,
@@ -982,8 +1133,6 @@ export async function deleteNodeImpl(
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  let managedHtmlAbsPath: string | undefined;
-
   const result = await mutateMergedFlowAndBroadcast<{ kind: 'unknownNode' }>(
     deps,
     flowId,
@@ -991,8 +1140,6 @@ export async function deleteNodeImpl(
     (flow) => {
       const idx = flow.nodes.findIndex((n) => n.id === nodeId);
       if (idx < 0) return { kind: 'unknownNode' };
-      const removed = flow.nodes[idx];
-      managedHtmlAbsPath = managedHtmlNodePath(entry.repoPath, nodeId, removed);
       flow.nodes.splice(idx, 1);
       flow.connectors = flow.connectors.filter(
         (cn) => cn.source !== nodeId && cn.target !== nodeId,
@@ -1001,41 +1148,19 @@ export async function deleteNodeImpl(
     },
   );
 
-  if (result.kind === 'ok' && managedHtmlAbsPath) {
+  if (result.kind === 'ok') {
     try {
-      unlinkSync(managedHtmlAbsPath);
+      removeNodeDir(entry.repoPath, nodeId);
     } catch (err) {
-      const code = (err as NodeJS.ErrnoException | undefined)?.code;
-      if (code !== 'ENOENT') {
-        console.warn(
-          `[operations] failed to remove managed htmlNode file ${managedHtmlAbsPath}: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-      }
+      // Best-effort: flow.json is already written and the orphan folder is
+      // recoverable manually. ids are random so a future add_node won't collide.
+      console.error(`[seeflow] failed to remove nodes/${nodeId}/`, err);
     }
   }
 
   return result;
 }
 
-// US-016: only delete the companion file when the htmlPath matches the
-// studio-managed shape `blocks/<id>.html` exactly. Hand-edited paths
-// (`custom/hero.html`, an absolute path, anything else) are left alone so
-// authors don't lose work they pointed the node at.
-const managedHtmlNodePath = (
-  repoPath: string,
-  nodeId: string,
-  removed: Record<string, unknown> | undefined,
-): string | undefined => {
-  if (!removed || removed.type !== 'htmlNode') return undefined;
-  const data = removed.data;
-  if (!data || typeof data !== 'object' || Array.isArray(data)) return undefined;
-  const htmlPath = (data as Record<string, unknown>).htmlPath;
-  if (htmlPath !== `blocks/${nodeId}.html`) return undefined;
-  return join(repoPath, '.seeflow', htmlPath);
-};
-
 // Move a single node by writing { x, y } back to its `position` on disk.
 // Mutates the *raw* parsed JSON so any unknown forward-compat fields the
 // schema doesn't yet recognize survive the round-trip untouched.
@@ -1087,10 +1212,47 @@ export async function patchNodeImpl(
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
-  return mutateMergedFlowAndBroadcast<{ kind: 'unknownNode' }>(deps, flowId, fullPath, (flow) => {
+  return mutateMergedFlowAndBroadcast<
+    { kind: 'unknownNode' } | { kind: 'writeFailed'; message: string }
+  >(deps, flowId, fullPath, (flow) => {
     const node = flow.nodes.find((n) => n.id === nodeId);
     if (!node) return { kind: 'unknownNode' };
+    const externalizedWrites: Array<{
+      absPath: string;
+      ref: string;
+      field: string;
+      content: string;
+    }> = [];
+    for (const { field, fileName } of externalizedFieldsForNodeType(node.type)) {
+      const incoming = (updates as Record<string, unknown>)[field];
+      if (incoming === undefined) continue;
+      externalizedWrites.push({
+        absPath: nodeFileAbsPath(entry.repoPath, nodeId, fileName),
+        ref: nodeFileRef(nodeId, fileName),
+        field,
+        content: typeof incoming === 'string' ? incoming : '',
+      });
+    }
     mergeNodeUpdates(node, updates);
+    if (externalizedWrites.length > 0) {
+      const dataAny = node.data;
+      const data: Record<string, unknown> =
+        dataAny && typeof dataAny === 'object' && !Array.isArray(dataAny)
+          ? (dataAny as Record<string, unknown>)
+          : {};
+      for (const w of externalizedWrites) {
+        try {
+          writeNodeFile(w.absPath, w.content);
+        } catch (err) {
+          return {
+            kind: 'writeFailed',
+            message: err instanceof Error ? err.message : String(err),
+          };
+        }
+        data[w.field] = w.ref;
+      }
+      node.data = data;
+    }
     return { kind: 'ok' };
   });
 }
@@ -1141,7 +1303,7 @@ export async function addConnectorImpl(
 
   const newConn = { ...connBody };
   if (typeof newConn.id !== 'string' || newConn.id.length === 0) {
-    newConn.id = `conn-${crypto.randomUUID()}`;
+    newConn.id = `conn-${shortId()}`;
   }
   if (typeof newConn.kind !== 'string' || newConn.kind.length === 0) {
     newConn.kind = 'default';
@@ -1160,6 +1322,64 @@ export async function addConnectorImpl(
   return result;
 }
 
+// Bulk add — N connectors in one read-validate-write-broadcast cycle. Same
+// transactional shape as addNodesBulkImpl: any single connector failing the
+// post-mutation ResolvedFlowSchema parse (dangling source/target, missing
+// kind-specific field) rolls back the whole batch. No per-item externalization
+// to manage — connectors don't own per-node folders.
+export async function addConnectorsBulkImpl(
+  deps: OperationsDeps,
+  flowId: string,
+  body: ConnectorsBulkBody,
+): Promise<AddConnectorsBulkOutcome> {
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
+
+  const prepared: Array<{ id: string; conn: Record<string, unknown> }> = [];
+  const idsInBatch = new Set<string>();
+  for (const item of body.connectors) {
+    const newConn = { ...item };
+    if (typeof newConn.id !== 'string' || newConn.id.length === 0) {
+      newConn.id = `conn-${shortId()}`;
+    }
+    if (typeof newConn.kind !== 'string' || newConn.kind.length === 0) {
+      newConn.kind = 'default';
+    }
+    const newId = newConn.id as string;
+    if (idsInBatch.has(newId)) return { kind: 'duplicateIdInBatch', id: newId };
+    idsInBatch.add(newId);
+    prepared.push({ id: newId, conn: newConn });
+  }
+
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
+  if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
+
+  const result = await mutateMergedFlowAndBroadcast<{ kind: 'idAlreadyExists'; id: string }>(
+    deps,
+    flowId,
+    fullPath,
+    (flow) => {
+      const existing = new Set(
+        flow.connectors
+          .map((c) => (typeof c.id === 'string' ? c.id : null))
+          .filter((id): id is string => id !== null),
+      );
+      for (const p of prepared) {
+        if (existing.has(p.id)) return { kind: 'idAlreadyExists', id: p.id };
+      }
+      for (const p of prepared) {
+        flow.connectors.push(p.conn);
+      }
+      return { kind: 'ok' };
+    },
+  );
+
+  if (result.kind === 'ok') {
+    return { kind: 'ok', data: { connectors: prepared.map((p) => ({ id: p.id })) } };
+  }
+  return result;
+}
+
 // Apply a partial PATCH body to a single connector. Mutation runs against
 // the raw parsed JSON (so unknown forward-compat fields survive a round-trip).
 // When `kind` changes, the previous kind's payload fields are dropped first

package/src/proxy.ts

@@ -17,6 +17,7 @@ import { join, resolve, sep } from 'node:path';
 import type { EventBus } from './events.ts';
 import { type ProcessSpawner, type SpawnHandle, defaultProcessSpawner } from './process-spawner.ts';
 import type { PlayAction, ResetAction } from './schema.ts';
+import { shortId } from './short-id.ts';
 
 export interface PlayResult {
   /** Correlates this run across SSE events + the synchronous response. */
@@ -47,9 +48,35 @@ const SCRIPT_PATH_ESCAPE = 'scriptPath escapes project root';
 
 type Resolved = { ok: true; absPath: string } | { ok: false };
 
-// Resolve `<cwd>/.seeflow/<scriptPath>` and verify via realpath it stays inside
-// the `.seeflow` root. Mirrors `resolveProjectFile` in api.ts.
-function resolveScript(cwd: string, scriptPath: string): Resolved {
+// Resolve `<cwd>/.seeflow/nodes/<nodeId>/<scriptPath>` and verify via realpath
+// it stays inside the node folder. The per-node anchor means scriptPath is
+// "scripts/play.ts" — no node id leaks into its own path.
+function resolveScript(cwd: string, nodeId: string, scriptPath: string): Resolved {
+  const nodeRoot = join(cwd, '.seeflow', 'nodes', nodeId);
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(nodeRoot);
+  } catch {
+    return { ok: false };
+  }
+  const target = resolve(nodeRoot, scriptPath);
+  let realTarget: string;
+  try {
+    realTarget = realpathSync(target);
+  } catch {
+    return { ok: false };
+  }
+  const rootWithSep = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  if (realTarget !== realRoot && !realTarget.startsWith(rootWithSep)) {
+    return { ok: false };
+  }
+  return { ok: true, absPath: realTarget };
+}
+
+// Legacy anchor for resetAction (kept until resetAction gets its own design
+// round). Same realpath escape check as resolveScript, but rooted at
+// <cwd>/.seeflow/ rather than a per-node folder.
+function resolveResetScript(cwd: string, scriptPath: string): Resolved {
   const seeflowRoot = join(cwd, '.seeflow');
   let realRoot: string;
   try {
@@ -154,9 +181,9 @@ export async function stopAllPlays(flowId: string): Promise<void> {
 export async function runPlay(options: RunPlayOptions): Promise<PlayResult> {
   const { events, flowId, nodeId, cwd, action } = options;
   const spawner = options.spawner ?? defaultProcessSpawner;
-  const runId = crypto.randomUUID();
+  const runId = shortId();
 
-  const resolved = resolveScript(cwd, action.scriptPath);
+  const resolved = resolveScript(cwd, nodeId, action.scriptPath);
   if (!resolved.ok) {
     events.broadcast({
       type: 'node:error',
@@ -303,7 +330,9 @@ export async function runReset(options: RunResetOptions): Promise<ResetResult> {
   const { events, flowId, cwd, action } = options;
   const spawner = options.spawner ?? defaultProcessSpawner;
 
-  const resolved = resolveScript(cwd, action.scriptPath);
+  // resetAction stays anchored at .seeflow/ for now — design defers per-node
+  // resetAction to a later round (decision #7). Mirrors the previous behaviour.
+  const resolved = resolveResetScript(cwd, action.scriptPath);
   if (!resolved.ok) {
     events.broadcast({
       type: 'demo:reset',