@tuongaz/seeflow 0.1.3

package/src/api.ts

@@ -0,0 +1,1093 @@
+import { existsSync, mkdirSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { z } from 'zod';
+import {
+  AssembleRequestSchema,
+  ProposeScopeRequestSchema,
+  ValidateRequestSchema,
+  assembleDemo,
+  proposeScope,
+  validateDemo,
+} from './diagram.ts';
+import type { EventBus } from './events.ts';
+import {
+  ConnectorPatchBodySchema,
+  CreateProjectBodySchema,
+  NodePatchBodySchema,
+  PositionBodySchema,
+  RegisterBodySchema,
+  ReorderBodySchema,
+  addConnectorImpl,
+  addNodeImpl,
+  createProjectImpl,
+  deleteConnectorImpl,
+  deleteDemoImpl,
+  deleteNodeImpl,
+  getDemoImpl,
+  listDemosImpl,
+  moveNodeImpl,
+  patchConnectorImpl,
+  patchNodeImpl,
+  registerDemoImpl,
+  reorderNodeImpl,
+  resolveDemoPath,
+} from './operations.ts';
+import type { ProcessSpawner } from './process-spawner.ts';
+import {
+  type PlayResult,
+  type ResetResult,
+  type RunPlayOptions,
+  type RunResetOptions,
+  runPlay as defaultRunPlay,
+  runReset as defaultRunReset,
+  stopAllPlays as defaultStopAllPlays,
+} from './proxy.ts';
+import type { Registry } from './registry.ts';
+import { DemoSchema } from './schema.ts';
+import { type Spawner, defaultSpawner } from './shellout.ts';
+import type { StatusRunner } from './status-runner.ts';
+import type { DemoWatcher } from './watcher.ts';
+
+const EmitBodySchema = z.object({
+  demoId: z.string().min(1),
+  nodeId: z.string().min(1),
+  status: z.enum(['running', 'done', 'error']),
+  runId: z.string().optional(),
+  payload: z.unknown().optional(),
+});
+
+type RelativePathCheck = { kind: 'ok' } | { kind: 'invalid'; reason: string };
+
+// Reject absolute paths and `..` traversal before any filesystem touch.
+// Realpath verification is layered on top by the caller for symlink defense.
+const validateRelativePath = (path: string): RelativePathCheck => {
+  if (path.length === 0) return { kind: 'invalid', reason: 'path is empty' };
+  if (isAbsolute(path) || path.startsWith('/') || path.startsWith('\\')) {
+    return { kind: 'invalid', reason: 'absolute paths are not allowed' };
+  }
+  const segments = path.split(/[\\/]/);
+  if (segments.some((s) => s === '..')) {
+    return { kind: 'invalid', reason: 'path traversal is not allowed' };
+  }
+  return { kind: 'ok' };
+};
+
+const EMIT_STATUS_TO_EVENT = {
+  running: 'node:running',
+  done: 'node:done',
+  error: 'node:error',
+} as const;
+
+const FilePathBodySchema = z.object({ path: z.string() });
+
+type ResolvedProjectFile =
+  | { kind: 'ok'; absPath: string; seeflowRoot: string }
+  | { kind: 'unknownProject' }
+  | { kind: 'invalidPath'; reason: string }
+  | { kind: 'fileMissing'; absPath: string };
+
+// Shared path-safety + filesystem resolution for project-scoped file routes.
+// Performs textual rejection of absolute paths / `..` traversal, then layered
+// realpath verification that the resolved file stays inside `<project>/.seeflow/`
+// (defense against symlink escapes). Returns the realpath of an existing file
+// on success, or `fileMissing` with the would-be absolute path so callers can
+// soft-fail with that path included for clipboard fallback.
+function resolveProjectFile(
+  registry: Registry,
+  projectId: string,
+  relPath: string,
+): ResolvedProjectFile {
+  const entry = registry.getById(projectId);
+  if (!entry) return { kind: 'unknownProject' };
+
+  const guard = validateRelativePath(relPath);
+  if (guard.kind === 'invalid') return { kind: 'invalidPath', reason: guard.reason };
+
+  const seeflowRoot = join(entry.repoPath, '.seeflow');
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(seeflowRoot);
+  } catch {
+    return { kind: 'fileMissing', absPath: resolve(seeflowRoot, relPath) };
+  }
+
+  const target = resolve(seeflowRoot, relPath);
+  let realTarget: string;
+  try {
+    realTarget = realpathSync(target);
+  } catch {
+    return { kind: 'fileMissing', absPath: target };
+  }
+
+  const rootWithSep = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  if (realTarget !== realRoot && !realTarget.startsWith(rootWithSep)) {
+    return { kind: 'invalidPath', reason: 'path escapes project root' };
+  }
+
+  return { kind: 'ok', absPath: realTarget, seeflowRoot: realRoot };
+}
+
+// Allowed extensions for /files/upload. Lowercased; matched after dropping the
+// leading `.`. Stored as a Set so future expansion (PDF, video) is one-edit.
+const UPLOAD_ALLOWED_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
+const UPLOAD_MAX_BYTES = 5 * 1024 * 1024;
+
+// Turn a user-supplied filename into a `<slug>.<ext>` pair. Returns null when
+// the extension isn't on the allowlist or the slug is empty after sanitization.
+function sanitizeUploadFilename(name: string): { base: string; ext: string } | null {
+  const last = name.split(/[\\/]/).pop() ?? name;
+  const dotIdx = last.lastIndexOf('.');
+  if (dotIdx <= 0 || dotIdx === last.length - 1) return null;
+  const ext = last.slice(dotIdx).toLowerCase();
+  if (!UPLOAD_ALLOWED_EXTS.has(ext)) return null;
+  const slug = last
+    .slice(0, dotIdx)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (slug.length === 0) return null;
+  return { base: slug, ext };
+}
+
+// Find the first unused `<base>.<ext>` (then `<base>-2.<ext>`, `<base>-3.<ext>`,
+// …) inside `assetsDir`. Caps at 999 attempts to avoid an unbounded loop on a
+// pathologically full directory.
+function pickUploadFilename(assetsDir: string, base: string, ext: string): string {
+  const first = `${base}${ext}`;
+  if (!existsSync(join(assetsDir, first))) return first;
+  for (let i = 2; i < 1000; i++) {
+    const candidate = `${base}-${i}${ext}`;
+    if (!existsSync(join(assetsDir, candidate))) return candidate;
+  }
+  return `${base}-${Date.now()}${ext}`;
+}
+
+export interface ApiOptions {
+  registry: Registry;
+  events?: EventBus;
+  watcher?: DemoWatcher;
+  /** Injectable shellout for tests; defaults to Bun.spawn fire-and-forget. */
+  spawner?: Spawner;
+  /** Override `process.platform` for tests covering darwin/win32/linux branches. */
+  platform?: NodeJS.Platform;
+  /** Long-running statusAction runner; fanned out on each /play click. */
+  statusRunner?: StatusRunner;
+  /** Injectable ProcessSpawner threaded into runPlay; tests use this to avoid
+   *  launching real child processes for the play-action script. */
+  processSpawner?: ProcessSpawner;
+  /** Injectable proxy facade — defaults wrap the proxy.ts module exports.
+   *  Tests use this to record call order across runPlay / runReset /
+   *  stopAllPlays and to drive each in isolation. */
+  proxy?: ProxyFacade;
+  /** Override base directory for new projects. Defaults to ~/.seeflow. Tests inject a tmp dir. */
+  projectBaseDir?: string;
+}
+
+/**
+ * Thin call-through wrapper around the proxy.ts module exports. Lets tests
+ * inject a recording fake to assert call order across runPlay, runReset, and
+ * stopAllPlays — none of which can be observed via the underlying
+ * ProcessSpawner alone because the play-run map and event broadcasts are
+ * encapsulated inside proxy.ts.
+ */
+export interface ProxyFacade {
+  runPlay(options: RunPlayOptions): Promise<PlayResult>;
+  runReset(options: RunResetOptions): Promise<ResetResult>;
+  stopAllPlays(demoId: string): Promise<void>;
+}
+
+export const defaultProxyFacade: ProxyFacade = {
+  runPlay: defaultRunPlay,
+  runReset: defaultRunReset,
+  stopAllPlays: defaultStopAllPlays,
+};
+
+export function createApi(options: ApiOptions): Hono {
+  const { registry, events, watcher, statusRunner } = options;
+  const spawner = options.spawner ?? defaultSpawner;
+  const platform = options.platform ?? process.platform;
+  const processSpawner = options.processSpawner;
+  const proxy = options.proxy ?? defaultProxyFacade;
+  const projectBaseDir = options.projectBaseDir;
+  const api = new Hono();
+
+  api.post('/demos/register', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+
+    const parsed = RegisterBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid register body', issues: parsed.error.issues }, 400);
+    }
+
+    const result = await registerDemoImpl({ registry, watcher }, parsed.data);
+    switch (result.kind) {
+      case 'ok':
+        return c.json(result.data);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 400);
+      case 'badJson':
+        return c.json({ error: 'Demo file is not valid JSON', detail: result.detail }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo file failed schema validation', issues: result.issues }, 400);
+      case 'sdkWriteFailed':
+        return c.json(
+          {
+            error: `Failed to write SDK helper: ${result.message}`,
+            id: result.id,
+            slug: result.slug,
+          },
+          500,
+        );
+    }
+  });
+
+  // POST /api/demos/validate — dry-run validation. The skill's diagram
+  // pipeline calls this between assemble and register to decide whether to
+  // rewire. Runs the Zod schema, the soft node cap, and the tier playability
+  // check. Filesystem-bound checks (harness coverage, event emitter index)
+  // stay in the skill since the studio doesn't see the user's $TARGET.
+  api.post('/demos/validate', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = ValidateRequestSchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid validate body', issues: parsed.error.issues }, 400);
+    }
+    return c.json(validateDemo(parsed.data));
+  });
+
+  // POST /api/diagram/propose-scope — Phase 2 helper. The skill POSTs the
+  // scan-result.json shape and gets back ranked entry-point candidates.
+  // Pure compute; skill writes the response to intermediate/entry-candidates.json.
+  api.post('/diagram/propose-scope', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = ProposeScopeRequestSchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid propose-scope body', issues: parsed.error.issues }, 400);
+    }
+    return c.json(proposeScope(parsed.data));
+  });
+
+  // POST /api/diagram/assemble — Phase 7a. The skill POSTs wiring + layout
+  // and gets back the assembled demo (IDs normalized, dupes dropped, dangling
+  // connectors removed, positions snapped to a 24px grid). Pure compute; the
+  // skill writes the response to $TARGET/.seeflow/seeflow.json. No schema
+  // validation here — call /demos/validate for that.
+  api.post('/diagram/assemble', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = AssembleRequestSchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid assemble body', issues: parsed.error.issues }, 400);
+    }
+    return c.json(assembleDemo(parsed.data));
+  });
+
+  // POST /api/projects — UI-driven "Create new project" flow (US-020). Two
+  // branches based on whether the target folder already has a SeeFlow
+  // project set up at `<folderPath>/.seeflow/seeflow.json`:
+  //   1. Existing setup: read + validate the on-disk demo and register it
+  //      as-is (no overwrite, no scaffolding). The user-supplied `name`
+  //      becomes the registry display name; the on-disk demo's `name` is
+  //      preserved on disk.
+  //   2. Fresh scaffold: mkdir -p the folder + .seeflow/, write a default
+  //      scaffold seeflow.json keyed off `name`, and run the same SDK-emit
+  //      helper write the CLI register flow uses (a no-op for an empty
+  //      scaffold, but kept for parity).
+  api.post('/projects', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+
+    const parsed = CreateProjectBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid create project body', issues: parsed.error.issues }, 400);
+    }
+
+    const result = await createProjectImpl({ registry, watcher, projectBaseDir }, parsed.data);
+    switch (result.kind) {
+      case 'ok':
+        return c.json(result.data);
+      case 'badJson':
+        return c.json({ error: `Existing demo file is not valid JSON: ${result.detail}` }, 400);
+      case 'badSchema':
+        return c.json(
+          { error: 'Existing demo file failed schema validation', issues: result.issues },
+          400,
+        );
+      case 'scaffoldFailed':
+        return c.json({ error: `Failed to scaffold project: ${result.message}` }, 500);
+      case 'sdkWriteFailed':
+        return c.json({ error: `Failed to write SDK helper: ${result.message}` }, 500);
+    }
+  });
+
+  api.get('/demos', (c) => {
+    const result = listDemosImpl({ registry });
+    return c.json(result.data);
+  });
+
+  api.get('/demos/:id', async (c) => {
+    const result = await getDemoImpl({ registry, watcher }, c.req.param('id'));
+    switch (result.kind) {
+      case 'ok':
+        return c.json(result.data);
+      case 'notFound':
+        return c.json({ error: 'not found' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+    }
+  });
+
+  // GET /api/projects/:id/files/<path> — stream a project-scoped file from
+  // <repoPath>/.seeflow/<path>. Path safety is layered: textual rejection
+  // (absolute / traversal), then realpath check that the resolved file stays
+  // inside the project's .seeflow root (defends against symlink escapes).
+  api.get('/projects/:id/files/:path{.+}', async (c) => {
+    const rawPath = c.req.param('path');
+    let relPath: string;
+    try {
+      relPath = decodeURIComponent(rawPath);
+    } catch {
+      return c.json({ error: 'invalid path encoding' }, 400);
+    }
+
+    const resolved = resolveProjectFile(registry, c.req.param('id'), relPath);
+    switch (resolved.kind) {
+      case 'unknownProject':
+        return c.json({ error: 'unknown project' }, 404);
+      case 'invalidPath':
+        return c.json({ error: resolved.reason }, 400);
+      case 'fileMissing':
+        return c.json({ error: 'file not found' }, 404);
+    }
+
+    const file = Bun.file(resolved.absPath);
+    if (!(await file.exists())) {
+      return c.json({ error: 'file not found' }, 404);
+    }
+
+    return new Response(file.stream(), {
+      headers: {
+        'content-type': file.type || 'application/octet-stream',
+        'content-length': String(file.size),
+      },
+    });
+  });
+
+  // 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
+  // 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.
+  api.post('/projects/:id/files/open', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = FilePathBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid open body', issues: parsed.error.issues }, 400);
+    }
+
+    const resolved = resolveProjectFile(registry, c.req.param('id'), parsed.data.path);
+    switch (resolved.kind) {
+      case 'unknownProject':
+        return c.json({ error: 'unknown project' }, 404);
+      case 'invalidPath':
+        return c.json({ error: resolved.reason }, 400);
+      case 'fileMissing':
+        return c.json({ error: 'file not found', absPath: resolved.absPath }, 404);
+    }
+
+    const editor = process.env.EDITOR;
+    if (!editor || editor.trim().length === 0) {
+      return c.json({ ok: false, absPath: resolved.absPath, error: 'EDITOR not set' });
+    }
+
+    const run = await spawner(editor, [resolved.absPath]);
+    if (!run.ok) {
+      return c.json({ ok: false, absPath: resolved.absPath, error: run.error ?? 'spawn failed' });
+    }
+    return c.json({ ok: true, absPath: resolved.absPath });
+  });
+
+  // POST /api/projects/:id/files/reveal — open the OS file manager with the
+  // target file selected. Platform commands: `open -R <abs>` (macOS),
+  // `explorer /select,<abs>` (Windows), `xdg-open <dir>` (Linux — selects the
+  // containing directory; xdg has no portable "select-this-file" verb). Same
+  // fallback shape as /open: response always includes `absPath` for clipboard.
+  api.post('/projects/:id/files/reveal', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = FilePathBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid reveal body', issues: parsed.error.issues }, 400);
+    }
+
+    const resolved = resolveProjectFile(registry, c.req.param('id'), parsed.data.path);
+    switch (resolved.kind) {
+      case 'unknownProject':
+        return c.json({ error: 'unknown project' }, 404);
+      case 'invalidPath':
+        return c.json({ error: resolved.reason }, 400);
+      case 'fileMissing':
+        return c.json({ error: 'file not found', absPath: resolved.absPath }, 404);
+    }
+
+    let cmd: string;
+    let args: string[];
+    switch (platform) {
+      case 'darwin':
+        cmd = 'open';
+        args = ['-R', resolved.absPath];
+        break;
+      case 'win32':
+        cmd = 'explorer';
+        args = [`/select,${resolved.absPath}`];
+        break;
+      default:
+        cmd = 'xdg-open';
+        args = [dirname(resolved.absPath)];
+        break;
+    }
+
+    const run = await spawner(cmd, args);
+    if (!run.ok) {
+      return c.json({ ok: false, absPath: resolved.absPath, error: run.error ?? 'spawn failed' });
+    }
+    return c.json({ ok: true, absPath: resolved.absPath });
+  });
+
+  // POST /api/projects/:id/files/upload — accept a multipart image upload and
+  // persist it under `<project>/.seeflow/assets/`. The frontend (US-008 OS
+  // drop) sends `file` (Blob) and optionally `filename` (the original OS name)
+  // in a multipart form; we sanitize the filename to a lowercased slug,
+  // dedupe with `-2`, `-3` suffixes inside the assets dir, and return the
+  // demo-relative path. Allowlist + 5 MB cap guard against arbitrary uploads.
+  api.post('/projects/:id/files/upload', async (c) => {
+    const projectId = c.req.param('id');
+    const entry = registry.getById(projectId);
+    if (!entry) return c.json({ error: 'unknown project' }, 404);
+
+    let form: FormData;
+    try {
+      form = await c.req.formData();
+    } catch {
+      return c.json({ error: 'Body must be valid multipart form-data' }, 400);
+    }
+
+    const fileField = form.get('file');
+    if (!(fileField instanceof File)) {
+      return c.json({ error: 'Missing file field' }, 400);
+    }
+    if (fileField.size > UPLOAD_MAX_BYTES) {
+      return c.json({ error: 'file too large', maxBytes: UPLOAD_MAX_BYTES }, 413);
+    }
+
+    const suggestedRaw = form.get('filename');
+    const suggested =
+      typeof suggestedRaw === 'string' && suggestedRaw.length > 0 ? suggestedRaw : fileField.name;
+    const sanitized = sanitizeUploadFilename(suggested);
+    if (!sanitized) {
+      return c.json({ error: 'invalid filename or extension' }, 400);
+    }
+
+    const assetsDir = join(entry.repoPath, '.seeflow', 'assets');
+    try {
+      mkdirSync(assetsDir, { recursive: true });
+    } catch (err) {
+      return c.json(
+        {
+          error: `Failed to create assets dir: ${err instanceof Error ? err.message : String(err)}`,
+        },
+        500,
+      );
+    }
+
+    const finalName = pickUploadFilename(assetsDir, sanitized.base, sanitized.ext);
+    const absPath = join(assetsDir, finalName);
+    try {
+      await Bun.write(absPath, fileField);
+    } catch (err) {
+      return c.json(
+        { error: `Failed to write file: ${err instanceof Error ? err.message : String(err)}` },
+        500,
+      );
+    }
+
+    return c.json({ path: `assets/${finalName}` });
+  });
+
+  api.delete('/demos/:id', (c) => {
+    const result = deleteDemoImpl({ registry, watcher }, c.req.param('id'));
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true });
+      case 'notFound':
+        return c.json({ ok: false, error: 'not found' }, 404);
+    }
+  });
+
+  api.post('/demos/:id/play/:nodeId', async (c) => {
+    const id = c.req.param('id');
+    const nodeId = c.req.param('nodeId');
+    const entry = registry.getById(id);
+    if (!entry) return c.json({ error: 'unknown demo' }, 404);
+    if (!events) return c.json({ error: 'events not enabled' }, 500);
+
+    // Always re-read from disk so the user's most recent edit (validated or
+    // not yet observed by the watcher) drives the actual fetch.
+    const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+    if (!existsSync(fullPath)) {
+      return c.json({ error: `Demo file not found: ${fullPath}` }, 404);
+    }
+    let raw: unknown;
+    try {
+      raw = await Bun.file(fullPath).json();
+    } catch (err) {
+      return c.json(
+        {
+          error: `Demo file is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        },
+        400,
+      );
+    }
+    const parsed = DemoSchema.safeParse(raw);
+    if (!parsed.success) {
+      return c.json({ error: 'Demo failed schema validation', issues: parsed.error.issues }, 400);
+    }
+
+    const node = parsed.data.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
+    ) {
+      return c.json({ error: `Node ${nodeId} has no playAction` }, 400);
+    }
+
+    // Fan out the long-running statusAction scripts BEFORE awaiting the play
+    // spawn — fire-and-forget so a slow status batch can't delay the click.
+    // Individual spawn failures are surfaced via console.warn but never fail
+    // the /play call itself.
+    if (statusRunner) {
+      void statusRunner.restart(id).catch((err) => {
+        console.warn(
+          `[api] statusRunner.restart(${id}) failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }
+
+    const result = await proxy.runPlay({
+      events,
+      demoId: id,
+      nodeId,
+      cwd: entry.repoPath,
+      action: node.data.playAction,
+      spawner: processSpawner,
+    });
+
+    // Surface the symlink-escape error as a 400 so the frontend can show a
+    // distinct "fix your scriptPath" message instead of a generic run failure.
+    if (result.error === 'scriptPath escapes project root') {
+      return c.json({ error: result.error }, 400);
+    }
+    return c.json(result);
+  });
+
+  // POST /api/demos/:id/reset — the "Restart demo" workflow (US-008). Order:
+  //   1. Stop every live play-script + every long-running status-script for
+  //      this demo in parallel — both must complete before any reset script
+  //      spawns so the script sees no stragglers.
+  //   2. Run the demo's `resetAction` script (if declared); any non-zero exit
+  //      becomes a 502 to the caller but does NOT suppress reload/restart.
+  //   3. Broadcast `demo:reload` unconditionally so the canvas re-fetches.
+  //   4. Fire-and-forget `statusRunner.restart` so the next status batch is
+  //      spawning by the time the response lands. Individual spawn failures
+  //      surface via console.warn but never fail the /reset call.
+  api.post('/demos/:id/reset', async (c) => {
+    const id = c.req.param('id');
+    const entry = registry.getById(id);
+    if (!entry) return c.json({ error: 'unknown demo' }, 404);
+    if (!events) return c.json({ error: 'events not enabled' }, 500);
+
+    const fullPath = resolveDemoPath(entry.repoPath, entry.demoPath);
+    if (!existsSync(fullPath)) {
+      return c.json({ error: `Demo file not found: ${fullPath}` }, 404);
+    }
+    let raw: unknown;
+    try {
+      raw = await Bun.file(fullPath).json();
+    } catch (err) {
+      return c.json(
+        {
+          error: `Demo file is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        },
+        400,
+      );
+    }
+    const parsed = DemoSchema.safeParse(raw);
+    if (!parsed.success) {
+      return c.json({ error: 'Demo failed schema validation', issues: parsed.error.issues }, 400);
+    }
+
+    // 1. Stop every play + status script in parallel. await BOTH before
+    //    spawning the reset script so a still-running play can't race the
+    //    reset and re-dirty the running app's state.
+    const stopPromises: Array<Promise<void>> = [proxy.stopAllPlays(id)];
+    if (statusRunner) stopPromises.push(statusRunner.stop(id));
+    await Promise.all(stopPromises);
+
+    // 2. Run resetAction (if declared).
+    const resetAction = parsed.data.resetAction;
+    let calledResetAction = false;
+    let resetActionError: string | undefined;
+
+    if (resetAction) {
+      calledResetAction = true;
+      const result = await proxy.runReset({
+        events,
+        demoId: id,
+        cwd: entry.repoPath,
+        action: resetAction,
+      });
+      if (!result.ok && result.error) {
+        resetActionError = result.error;
+      }
+    }
+
+    // 3. Broadcast reload unconditionally — even when resetAction failed,
+    //    the canvas should still refresh from disk in case the user just
+    //    edited the file.
+    events.broadcast({
+      type: 'demo:reload',
+      demoId: id,
+      payload: {},
+    });
+
+    // 4. Fire-and-forget the next status batch.
+    if (statusRunner) {
+      void statusRunner.restart(id).catch((err) => {
+        console.warn(
+          `[api] statusRunner.restart(${id}) failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }
+
+    if (resetActionError) {
+      return c.json({ error: resetActionError, calledResetAction }, 502);
+    }
+    return c.json({ ok: true, calledResetAction });
+  });
+
+  // PATCH a single node's position back into the on-disk seeflow.json. This is
+  // the second (and only other) place the studio mutates user files — the
+  // first being the SDK helper write in `register`. Atomic write via tempfile
+  // + rename keeps editor diffs clean and avoids corruption mid-write.
+  api.patch('/demos/:id/nodes/:nodeId/position', async (c) => {
+    const id = c.req.param('id');
+    const nodeId = c.req.param('nodeId');
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = PositionBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid position body', issues: parsed.error.issues }, 400);
+    }
+
+    const result = await moveNodeImpl({ registry, watcher }, id, nodeId, parsed.data);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true, position: result.data.position });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'unknownNode':
+        return c.json({ error: `Unknown nodeId: ${nodeId}` }, 404);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  // PATCH the z-order position of a single node within demo.nodes[]. React
+  // Flow's painter renders nodes in array order, so moving a node to a later
+  // index brings it visually forward (later nodes paint over earlier ones).
+  // Five ops are supported: forward / backward (single-step swap), toFront /
+  // toBack (remove + push/unshift), and toIndex (pin to an absolute index)
+  // which the undo path uses to faithfully revert forward/backward gestures
+  // even if the array changed between the original op and the undo.
+  api.patch('/demos/:id/nodes/:nodeId/order', async (c) => {
+    const id = c.req.param('id');
+    const nodeId = c.req.param('nodeId');
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = ReorderBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid reorder body', issues: parsed.error.issues }, 400);
+    }
+
+    const result = await reorderNodeImpl({ registry, watcher }, id, nodeId, parsed.data);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'unknownNode':
+        return c.json({ error: `Unknown nodeId: ${nodeId}` }, 404);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  // PATCH a single node — partial update of position, label, detail, visual
+  // fields, or shapeNode-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
+  // is re-validated through DemoSchema before commit, preventing partial
+  // writes from breaking invariants like the connector→node superRefine.
+  api.patch('/demos/:id/nodes/:nodeId', async (c) => {
+    const id = c.req.param('id');
+    const nodeId = c.req.param('nodeId');
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = NodePatchBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid node patch body', issues: parsed.error.issues }, 400);
+    }
+
+    const result = await patchNodeImpl({ registry, watcher }, id, nodeId, parsed.data);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'unknownNode':
+        return c.json({ error: `Unknown nodeId: ${nodeId}` }, 404);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  // POST a new node into the demo. Body is the node payload (id auto-generated
+  // server-side if absent). Atomicity + final-DemoSchema validation match the
+  // PATCH path above, so a malformed node never produces a half-written file.
+  api.post('/demos/:id/nodes', async (c) => {
+    const id = c.req.param('id');
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return c.json({ error: 'Body must be an object' }, 400);
+    }
+
+    const result = await addNodeImpl({ registry, watcher }, id, body as Record<string, unknown>);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true, id: result.data.id, node: result.data.node });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  // DELETE a node and cascade-remove every connector with source === nodeId or
+  // target === nodeId in the same atomic write. Final-DemoSchema validation
+  // is still run after the mutation — connector cascade closure means it
+  // should always pass, but the check makes the failure mode honest if the
+  // file had a pre-existing schema violation we'd otherwise paper over.
+  api.delete('/demos/:id/nodes/:nodeId', async (c) => {
+    const id = c.req.param('id');
+    const nodeId = c.req.param('nodeId');
+
+    const result = await deleteNodeImpl({ registry, watcher }, id, nodeId);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'unknownNode':
+        return c.json({ error: `Unknown nodeId: ${nodeId}` }, 404);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  // PATCH a single connector — partial update of label/style/color/direction
+  // and (optionally) kind + per-kind payload fields. When `kind` changes,
+  // stale kind-specific fields are dropped before the merge. The whole demo
+  // is re-validated through DemoSchema before commit so the discriminated
+  // union catches missing-required-fields (e.g. kind='event' without
+  // eventName) and the superRefine still gates source/target referential
+  // integrity.
+  api.patch('/demos/:id/connectors/:connId', async (c) => {
+    const id = c.req.param('id');
+    const connId = c.req.param('connId');
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = ConnectorPatchBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid connector patch body', issues: parsed.error.issues }, 400);
+    }
+
+    const result = await patchConnectorImpl({ registry, watcher }, id, connId, parsed.data);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'unknownConnector':
+        return c.json({ error: `Unknown connectorId: ${connId}` }, 404);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  // POST a new connector. Body is the connector payload; `id` is auto-generated
+  // server-side if absent and `kind` defaults to 'default' (the no-semantics
+  // user-drawn variant). Source/target referential integrity is enforced by
+  // DemoSchema's superRefine on the post-mutation parse.
+  api.post('/demos/:id/connectors', async (c) => {
+    const id = c.req.param('id');
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return c.json({ error: 'Body must be an object' }, 400);
+    }
+
+    const result = await addConnectorImpl(
+      { registry, watcher },
+      id,
+      body as Record<string, unknown>,
+    );
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true, id: result.data.id });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  // DELETE a connector. Just removes the entry from demo.connectors — node
+  // deletion is what cascades, not connector deletion.
+  api.delete('/demos/:id/connectors/:connId', async (c) => {
+    const id = c.req.param('id');
+    const connId = c.req.param('connId');
+
+    const result = await deleteConnectorImpl({ registry, watcher }, id, connId);
+    switch (result.kind) {
+      case 'ok':
+        return c.json({ ok: true });
+      case 'demoNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Demo file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: `Demo file is not valid JSON: ${result.message}` }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Demo failed schema validation', issues: result.issues }, 400);
+      case 'unknownConnector':
+        return c.json({ error: `Unknown connectorId: ${connId}` }, 404);
+      case 'writeFailed':
+        return c.json({ error: `Failed to write demo file: ${result.message}` }, 500);
+    }
+  });
+
+  api.post('/emit', async (c) => {
+    if (!events) return c.json({ error: 'events not enabled' }, 500);
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+
+    const parsed = EmitBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid emit body', issues: parsed.error.issues }, 400);
+    }
+
+    const { demoId, nodeId, status, runId, payload } = parsed.data;
+    if (!registry.getById(demoId)) {
+      return c.json({ error: `Unknown demoId: ${demoId}` }, 404);
+    }
+
+    const extras =
+      payload && typeof payload === 'object' && !Array.isArray(payload)
+        ? (payload as Record<string, unknown>)
+        : {};
+    const eventPayload: Record<string, unknown> = { nodeId, ...extras };
+    if (runId !== undefined) eventPayload.runId = runId;
+
+    events.broadcast({
+      type: EMIT_STATUS_TO_EVENT[status],
+      demoId,
+      payload: eventPayload,
+    });
+
+    return c.json({ ok: true });
+  });
+
+  api.get('/events', (c) => {
+    const demoId = c.req.query('demoId');
+    if (!demoId) return c.json({ error: 'demoId query param required' }, 400);
+    if (!registry.getById(demoId)) return c.json({ error: 'unknown demoId' }, 404);
+    if (!events) return c.json({ error: 'events not enabled' }, 500);
+
+    return streamSSE(c, async (stream) => {
+      let active = true;
+      const queue: Array<{ event: string; data: string }> = [];
+      let resume: (() => void) | null = null;
+
+      const wake = () => {
+        if (resume) {
+          const r = resume;
+          resume = null;
+          r();
+        }
+      };
+
+      const unsubscribe = events.subscribe(demoId, (e) => {
+        queue.push({ event: e.type, data: JSON.stringify({ ts: e.ts, ...(e.payload as object) }) });
+        wake();
+      });
+
+      stream.onAbort(() => {
+        active = false;
+        unsubscribe();
+        wake();
+      });
+
+      // Initial 'hello' so reconnecting clients can confirm the stream is open
+      // and trigger a re-fetch on the frontend.
+      await stream.writeSSE({
+        event: 'hello',
+        data: JSON.stringify({ demoId, ts: Date.now() }),
+      });
+
+      try {
+        while (active) {
+          while (queue.length > 0) {
+            const next = queue.shift();
+            if (!next) break;
+            await stream.writeSSE(next);
+          }
+          if (!active) break;
+          await new Promise<void>((r) => {
+            resume = r;
+          });
+        }
+      } finally {
+        unsubscribe();
+      }
+    });
+  });
+
+  return api;
+}