@tuongaz/seeflow 0.1.76 → 0.1.80

package/src/operations.ts

@@ -22,7 +22,8 @@ import {
   removeNodeDir,
   writeNodeFile,
 } from './node-files.ts';
-import type { Registry } from './registry.ts';
+import { scanProject } from './project-scanner.ts';
+import { type Registry, slugify } from './registry.ts';
 import {
   ColorTokenSchema,
   ComponentSpecSchema,
@@ -33,6 +34,7 @@ import {
   PlayActionSchema,
   type ResolvedFlow,
   ResolvedFlowSchema,
+  type SeeflowManifest,
   SourceHandleIdSchema,
   StateSourceSchema,
   StatusActionSchema,
@@ -42,11 +44,6 @@ import {
 import { shortId } from './short-id.ts';
 import { type FlowSnapshot, type FlowWatcher, readMergedFlow } from './watcher.ts';
 
-// Both projects:create and flows:register write/read flow.json at the project
-// root. The studio never assumes a `.seeflow/` subdirectory — whatever path
-// the caller supplies is treated as the seeflow project root.
-const PROJECT_FLOW_RELATIVE_PATH = 'flow.json';
-
 export const RegisterBodySchema = z.object({
   name: z.string().min(1).optional(),
   repoPath: z.string().min(1),
@@ -1132,11 +1129,15 @@ export async function registerFlowImpl(
   if (!merged.flow) return { kind: 'badJson', detail: merged.error ?? 'unknown error' };
 
   const lastModified = statSync(fullPath).mtimeMs;
+  const flowName = body.name ?? merged.flow.name;
   const entry = registry.upsert({
-    name: body.name ?? merged.flow.name,
+    name: flowName,
     description: merged.flow.description,
     repoPath,
     flowPath,
+    projectSlug: slugify(flowName),
+    flowSlug: 'main',
+    isDefault: true,
     valid: true,
     lastModified,
   });
@@ -1168,24 +1169,36 @@ export async function createProjectImpl(
   const { registry, watcher } = deps;
   const { path: folderPath, name, description } = body;
 
-  const demoFullPath = join(folderPath, PROJECT_FLOW_RELATIVE_PATH);
+  // Manifest-driven layout (US-018): a project is the seeflow.json manifest
+  // plus one flow folder under flows/<id>/. The default flow id for a
+  // freshly-scaffolded project is always "main".
+  const manifestPath = join(folderPath, 'seeflow.json');
+  const legacyFlowPath = join(folderPath, 'flow.json');
+  const mainFlowPath = join(folderPath, 'flows', 'main', 'flow.json');
 
-  if (existsSync(demoFullPath)) {
+  if (existsSync(manifestPath) || existsSync(legacyFlowPath) || existsSync(mainFlowPath)) {
     return { kind: 'alreadyExists', path: folderPath };
   }
 
-  // Flow-only scaffold: empty nodes/connectors, no style.json needed.
-  const scaffold: Flow = {
-    version: 2,
+  const manifest: SeeflowManifest = {
+    version: 1,
     name,
     ...(description !== undefined ? { description } : {}),
+    defaultFlow: 'main',
+    flows: [{ id: 'main', name: 'Main' }],
+  };
+  const envelope: Flow = {
+    version: 2,
+    name,
     nodes: [],
     connectors: [],
   };
 
   try {
     mkdirSync(folderPath, { recursive: true });
-    writeFileSync(demoFullPath, `${JSON.stringify(scaffold, null, 2)}\n`);
+    mkdirSync(join(folderPath, 'flows', 'main'), { recursive: true });
+    writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    writeFileAtomic(mainFlowPath, `${JSON.stringify(envelope, null, 2)}\n`);
     const tmpDir = join(folderPath, '.tmp');
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, '.gitignore'), '*\n!.gitignore\n');
@@ -1193,12 +1206,32 @@ export async function createProjectImpl(
     return { kind: 'scaffoldFailed', message: err instanceof Error ? err.message : String(err) };
   }
 
-  const lastModified = statSync(demoFullPath).mtimeMs;
+  // Run the scanner so projectSlug is derived consistently with manifest-driven
+  // projects registered via the CLI's `register` verb / the file-watcher.
+  const scan = scanProject(folderPath);
+  if (scan.kind !== 'ok') {
+    return {
+      kind: 'scaffoldFailed',
+      message: `scanner refused freshly-scaffolded project: ${scan.kind}`,
+    };
+  }
+  const mainScanned = scan.flows.find((f) => f.id === 'main');
+  if (!mainScanned) {
+    return {
+      kind: 'scaffoldFailed',
+      message: 'scanner did not return the "main" flow entry',
+    };
+  }
+
+  const lastModified = statSync(mainFlowPath).mtimeMs;
   const entry = registry.upsert({
-    name,
-    description,
+    name: mainScanned.name,
+    description: scan.manifest.description,
     repoPath: folderPath,
-    flowPath: PROJECT_FLOW_RELATIVE_PATH,
+    flowPath: mainScanned.flowPath,
+    projectSlug: scan.projectSlug,
+    flowSlug: mainScanned.id,
+    isDefault: mainScanned.isDefault,
     valid: true,
     lastModified,
   });
@@ -1239,12 +1272,13 @@ export async function addNodeImpl(
     const data: Record<string, unknown> = dataIsRecord
       ? { ...(newNode.data as Record<string, unknown>) }
       : {};
+    const flowDir = dirname(entry.flowPath);
     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),
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, fileName),
         content,
       });
     }
@@ -1303,6 +1337,7 @@ export async function addFlowBulkImpl(
     externalized: Array<{ absPath: string; content: string }>;
   }> = [];
   const nodeIdsInBatch = new Set<string>();
+  const flowDir = dirname(entry.flowPath);
   for (const item of body.nodes ?? []) {
     const newNode = { ...item };
     if (typeof newNode.id !== 'string' || newNode.id.length === 0) {
@@ -1327,7 +1362,7 @@ export async function addFlowBulkImpl(
       const content = typeof incoming === 'string' ? incoming : '';
       data[field] = nodeFileRef(newId, fileName);
       externalized.push({
-        absPath: nodeFileAbsPath(entry.repoPath, newId, fileName),
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, fileName),
         content,
       });
     }
@@ -1412,11 +1447,11 @@ export async function addFlowBulkImpl(
   // 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/<p.id>/` was created by this call — safe to cascade. The
-  // idAlreadyExists branch returns before any writeNodeFile, so the rmdir is
-  // a no-op there.
+  // at `<flowDir>/nodes/<p.id>/` was created by this call — safe to cascade.
+  // The idAlreadyExists branch returns before any writeNodeFile, so the rmdir
+  // is a no-op there.
   for (const p of preparedNodes) {
-    removeNodeDir(entry.repoPath, p.id);
+    removeNodeDir(entry.repoPath, flowDir, p.id);
   }
   return result;
 }
@@ -1425,8 +1460,8 @@ export async function addFlowBulkImpl(
 // atomic write. Final ResolvedFlowSchema parse stays in place so a pre-existing
 // schema violation surfaces honestly instead of being silently papered over.
 // After the flow.json write, `removeNodeDir` cascades the node's whole
-// `<project>/nodes/<id>/` folder — covering detail.md, view.html, and any
-// type:'image' upload that lived there.
+// `<repoPath>/<flowDir>/nodes/<id>/` folder — covering detail.md, view.html,
+// and any type:'image' upload that lived there.
 export async function deleteNodeImpl(
   deps: OperationsDeps,
   flowId: string,
@@ -1455,7 +1490,7 @@ export async function deleteNodeImpl(
 
   if (result.kind === 'ok') {
     try {
-      removeNodeDir(entry.repoPath, nodeId);
+      removeNodeDir(entry.repoPath, dirname(entry.flowPath), nodeId);
     } catch (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.
@@ -1517,6 +1552,7 @@ export async function patchNodeImpl(
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
 
+  const flowDir = dirname(entry.flowPath);
   return mutateMergedFlowAndBroadcast<
     { kind: 'unknownNode' } | { kind: 'writeFailed'; message: string }
   >(deps, flowId, fullPath, (flow) => {
@@ -1532,7 +1568,7 @@ export async function patchNodeImpl(
       const incoming = (updates as Record<string, unknown>)[field];
       if (incoming === undefined) continue;
       externalizedWrites.push({
-        absPath: nodeFileAbsPath(entry.repoPath, nodeId, fileName),
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, nodeId, fileName),
         ref: nodeFileRef(nodeId, fileName),
         field,
         content: typeof incoming === 'string' ? incoming : '',
@@ -1559,12 +1595,12 @@ export async function patchNodeImpl(
       node.data = data;
     }
     // Component spec sidecar — write the pretty-printed JSON to
-    // `<project>/nodes/<id>/spec.json` so the on-disk source of truth stays
-    // in sync. mergeNodeUpdates already put data.spec on the merged tree for
-    // the post-mutation ResolvedFlowSchema parse; splitFlow strips it from
-    // flow.json so we don't double-store the spec.
+    // `<repoPath>/<flowDir>/nodes/<id>/spec.json` so the on-disk source of
+    // truth stays in sync. mergeNodeUpdates already put data.spec on the
+    // merged tree for the post-mutation ResolvedFlowSchema parse; splitFlow
+    // strips it from flow.json so we don't double-store the spec.
     if (node.type === 'component' && updates.spec !== undefined) {
-      const specAbs = nodeFileAbsPath(entry.repoPath, nodeId, 'spec.json');
+      const specAbs = nodeFileAbsPath(entry.repoPath, flowDir, nodeId, 'spec.json');
       try {
         writeNodeFile(specAbs, `${JSON.stringify(updates.spec, null, 2)}\n`);
       } catch (err) {

package/src/project-scanner.ts

@@ -0,0 +1,105 @@
+// Project scanner: turns a project directory on disk into a set of
+// `ScannedFlow` entries the registry can consume. The disk layout is
+// manifest-driven:
+//
+//   <repoPath>/seeflow.json            — top-level project manifest
+//   <repoPath>/flows/<id>/flow.json    — one folder per flow declared in manifest
+//
+// `scanProject(repoPath)` returns a discriminated union: either `{ kind: 'ok' }`
+// with the parsed manifest + per-flow entries, or one of the typed error
+// variants below. The CLI wires this into `registerProject(opts)` in US-004 and
+// turns each error variant into a structured exit.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { type SeeflowManifest, SeeflowManifestSchema } from './schema.ts';
+import { slugify } from './slugify.ts';
+
+export interface ScannedFlow {
+  /** Manifest flow id (matches /^[a-z0-9][a-z0-9-]*$/). Becomes flowSlug. */
+  id: string;
+  /** Human-readable name from manifest. */
+  name: string;
+  /** Optional decorative icon name. */
+  icon?: string;
+  /** True for the flow whose id matches manifest.defaultFlow. */
+  isDefault: boolean;
+  /** Relative path of flow.json under the project root. Always
+   *  `flows/<id>/flow.json` — the scanner does not honour overrides. */
+  flowPath: string;
+}
+
+export type ScanError =
+  | { kind: 'manifest-missing' }
+  | { kind: 'manifest-invalid'; message: string }
+  | { kind: 'legacy-root-flow' }
+  | { kind: 'flow-json-missing'; flowId: string; flowPath: string };
+
+export type ScanResult =
+  | {
+      kind: 'ok';
+      projectSlug: string;
+      manifest: SeeflowManifest;
+      flows: ScannedFlow[];
+    }
+  | ScanError;
+
+const MANIFEST_FILENAME = 'seeflow.json';
+const LEGACY_FLOW_FILENAME = 'flow.json';
+
+export function scanProject(repoPath: string): ScanResult {
+  const manifestPath = join(repoPath, MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) {
+    // Pre-multi-flow projects had `flow.json` at the project root. We refuse
+    // to silently treat those as single-flow projects — the migration story
+    // (US-005) moves them to `flows/main/flow.json` first.
+    if (existsSync(join(repoPath, LEGACY_FLOW_FILENAME))) {
+      return { kind: 'legacy-root-flow' };
+    }
+    return { kind: 'manifest-missing' };
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    return {
+      kind: 'manifest-invalid',
+      message: `failed to parse ${MANIFEST_FILENAME}: ${(err as Error).message}`,
+    };
+  }
+
+  const parsed = SeeflowManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      kind: 'manifest-invalid',
+      message: parsed.error.issues
+        .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+        .join('; '),
+    };
+  }
+
+  const manifest = parsed.data;
+  const flows: ScannedFlow[] = [];
+  for (const entry of manifest.flows) {
+    const flowPath = `flows/${entry.id}/${LEGACY_FLOW_FILENAME}`;
+    if (!existsSync(join(repoPath, flowPath))) {
+      return { kind: 'flow-json-missing', flowId: entry.id, flowPath };
+    }
+    flows.push({
+      id: entry.id,
+      name: entry.name,
+      icon: entry.icon,
+      isDefault: entry.id === manifest.defaultFlow,
+      flowPath,
+    });
+  }
+
+  // Prefer the manifest name. If slugify falls back to its `'demo'` sentinel
+  // (i.e. manifest.name had no alphanumeric content), fall back to the
+  // directory basename — which itself slugifies through to a stable identifier.
+  const nameSlug = slugify(manifest.name);
+  const projectSlug = nameSlug === 'demo' ? slugify(basename(repoPath)) : nameSlug;
+
+  return { kind: 'ok', projectSlug, manifest, flows };
+}

package/src/registry.ts

@@ -4,14 +4,23 @@ import { dirname, join } from 'node:path';
 import { writeFileAtomic } from './atomic-write.ts';
 import { seeflowHome } from './paths.ts';
 import { shortId } from './short-id.ts';
+import { slugify } from './slugify.ts';
+
+export { slugify };
 
 export interface FlowEntry {
   id: string;
+  /** Derived as `${projectSlug}/${flowSlug}` — kept on the entry for
+   *  resolve() / getBySlug() compatibility. */
   slug: string;
   name: string;
   description?: string;
   repoPath: string;
   flowPath: string;
+  projectSlug: string;
+  flowSlug: string;
+  isDefault: boolean;
+  icon?: string;
   lastModified: number;
   valid: boolean;
 }
@@ -21,6 +30,10 @@ export interface RegisterInput {
   description?: string;
   repoPath: string;
   flowPath: string;
+  projectSlug: string;
+  flowSlug: string;
+  isDefault: boolean;
+  icon?: string;
   valid?: boolean;
   lastModified?: number;
 }
@@ -50,18 +63,39 @@ export function defaultRegistryPath(): string {
   return join(seeflowHome(), 'registry.json');
 }
 
-export function slugify(name: string): string {
-  const slug = name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return slug || 'demo';
-}
+/**
+ * Production load-time predicate: only accept entries whose project still
+ * exposes a `seeflow.json` manifest at `repoPath` and whose `flowPath` matches
+ * the manifest layout (`flows/<id>/flow.json`). Anything else is a stale or
+ * pre-manifest registration and is dropped silently.
+ *
+ * Wire this into `createRegistry({ isLoadableEntry })` from every production
+ * call site (CLI, server). Tests construct registries without the predicate
+ * so they can use fake `/tmp/...` repo paths without scaffolding files.
+ */
+export const manifestOnlyEntryFilter = (entry: FlowEntry): boolean => {
+  if (!existsSync(join(entry.repoPath, 'seeflow.json'))) return false;
+  if (entry.flowPath === 'flow.json') return false;
+  return true;
+};
 
 const OWN_WRITE_RING_SIZE = 4;
 
-export function createRegistry(options: { path?: string } = {}): Registry {
+export interface CreateRegistryOptions {
+  path?: string;
+  /**
+   * Optional predicate run on every persisted entry at load time. Entries that
+   * return `false` are silently dropped from the in-memory map (and rewritten
+   * out of registry.json on the next persist). Production uses this to ignore
+   * any entry whose project no longer has a `seeflow.json` manifest — legacy
+   * support has been dropped, manifest layout is the only accepted layout.
+   */
+  isLoadableEntry?: (entry: FlowEntry) => boolean;
+}
+
+export function createRegistry(options: CreateRegistryOptions = {}): Registry {
   const path = options.path ?? defaultRegistryPath();
+  const isLoadableEntry = options.isLoadableEntry;
   const entries = new Map<string, FlowEntry>();
   const writtenHashes: string[] = [];
   const listeners = new Set<() => void>();
@@ -116,6 +150,31 @@ export function createRegistry(options: { path?: string } = {}): Registry {
           if (entry.description !== undefined && typeof entry.description !== 'string') {
             entry.description = undefined;
           }
+          // Migration shim for legacy entries written before US-002. Derive
+          // projectSlug / flowSlug / isDefault so single-flow repos keep
+          // working until they are re-scanned through registerProject(). The
+          // scanner overwrites these on the next session anyway.
+          if (typeof entry.projectSlug !== 'string') {
+            entry.projectSlug = slugify(entry.name);
+          }
+          if (typeof entry.flowSlug !== 'string') {
+            entry.flowSlug = 'main';
+          }
+          if (typeof entry.isDefault !== 'boolean') {
+            entry.isDefault = true;
+          }
+          if (entry.icon !== undefined && typeof entry.icon !== 'string') {
+            entry.icon = undefined;
+          }
+          // Always re-derive slug from project + flow so the stored slug
+          // and the on-disk fields cannot drift apart.
+          entry.slug = `${entry.projectSlug}/${entry.flowSlug}`;
+          if (isLoadableEntry && !isLoadableEntry(entry)) {
+            console.warn(
+              `[registry] dropping entry ${entry.id} (${entry.slug}) — not loadable under the manifest-only contract`,
+            );
+            continue;
+          }
           entries.set(entry.id, entry);
         }
       }
@@ -163,14 +222,6 @@ export function createRegistry(options: { path?: string } = {}): Registry {
     return undefined;
   };
 
-  const uniqueSlug = (base: string): string => {
-    const taken = new Set([...entries.values()].map((e) => e.slug));
-    if (!taken.has(base)) return base;
-    let n = 2;
-    while (taken.has(`${base}-${n}`)) n++;
-    return `${base}-${n}`;
-  };
-
   return {
     path,
     list: () => {
@@ -202,16 +253,23 @@ export function createRegistry(options: { path?: string } = {}): Registry {
     upsert(input) {
       const lastModified = input.lastModified ?? Date.now();
       const valid = input.valid ?? true;
+      const slug = `${input.projectSlug}/${input.flowSlug}`;
       const existing = findByRepoPathAndFlowPath(input.repoPath, input.flowPath);
       if (existing) {
         // input.description reflects the current flow.json on every call —
         // when an author removes the description, we drop it from the entry
-        // too (JSON.stringify skips undefined values on persist).
+        // too (JSON.stringify skips undefined values on persist). Same shape
+        // applies to icon.
         const updated: FlowEntry = {
           ...existing,
+          slug,
           name: input.name,
           description: input.description,
           flowPath: input.flowPath,
+          projectSlug: input.projectSlug,
+          flowSlug: input.flowSlug,
+          isDefault: input.isDefault,
+          icon: input.icon,
           lastModified,
           valid,
         };
@@ -220,7 +278,6 @@ export function createRegistry(options: { path?: string } = {}): Registry {
         return updated;
       }
       const id = shortId();
-      const slug = uniqueSlug(slugify(input.name));
       const entry: FlowEntry = {
         id,
         slug,
@@ -228,6 +285,10 @@ export function createRegistry(options: { path?: string } = {}): Registry {
         description: input.description,
         repoPath: input.repoPath,
         flowPath: input.flowPath,
+        projectSlug: input.projectSlug,
+        flowSlug: input.flowSlug,
+        isDefault: input.isDefault,
+        icon: input.icon,
         lastModified,
         valid,
       };

package/src/route-resolve.ts

@@ -0,0 +1,41 @@
+import type { FlowEntry, Registry } from './registry.ts';
+
+/**
+ * Discriminated result of {@link resolveProjectFlow}.
+ *
+ * The error arm uses a stable `code` field so HTTP handlers can echo the same
+ * string back to clients (`{ ok:false, error: result.code }`) without an
+ * intermediate mapping table — see the route migration in US-007 onward.
+ */
+export type ResolveProjectFlowResult =
+  | { kind: 'ok'; entry: FlowEntry }
+  | { kind: 'error'; code: 'project-not-found' | 'flow-not-found' };
+
+/**
+ * Resolve a `(projectSlug, flowSlug)` pair to its registered {@link FlowEntry}.
+ *
+ * Splits the lookup into two stages so HTTP handlers can return a precise 404:
+ *   1. If no entry shares the given `projectSlug`, the project itself doesn't
+ *      exist → `project-not-found`.
+ *   2. If some entry shares the project but none matches `flowSlug`, the
+ *      project is registered but the flow isn't → `flow-not-found`.
+ *
+ * The single canonical caller is the route layer (US-007 / US-008); CLI code
+ * keeps using `registry.resolve(idOrSlug)` because it accepts an ambiguous
+ * `<flowId-or-slug>` argument.
+ */
+export function resolveProjectFlow(
+  registry: Registry,
+  projectSlug: string,
+  flowSlug: string,
+): ResolveProjectFlowResult {
+  const projectEntries = registry.list().filter((e) => e.projectSlug === projectSlug);
+  if (projectEntries.length === 0) {
+    return { kind: 'error', code: 'project-not-found' };
+  }
+  const entry = projectEntries.find((e) => e.flowSlug === flowSlug);
+  if (!entry) {
+    return { kind: 'error', code: 'flow-not-found' };
+  }
+  return { kind: 'ok', entry };
+}

package/src/schema.ts

@@ -748,3 +748,57 @@ export const StyleSchema = z
 export type Style = z.infer<typeof StyleSchema>;
 export type NodeStyle = z.infer<typeof NodeStyleSchema>;
 export type ConnectorStyleEntry = z.infer<typeof ConnectorStyleEntrySchema>;
+
+// =============================================================================
+// Seeflow manifest — top-level descriptor for a multi-flow project.
+// Lives at <project>/seeflow.json. Declares the flows the project hosts and
+// which one to open by default. The scanner (project-scanner.ts) turns this
+// plus the flows/<id>/flow.json files into ScannedFlow entries the registry
+// can consume.
+// =============================================================================
+
+// Flow ids are URL-safe and folder-safe: lowercase alphanumerics + dashes,
+// must start with an alphanumeric character. Same pattern enforced by the
+// manifest CRUD endpoints (POST/PATCH /api/projects/:project/flows[/:flow]).
+export const FlowIdPattern = /^[a-z0-9][a-z0-9-]*$/;
+
+const SeeflowManifestFlowEntrySchema = z.object({
+  id: z.string().regex(FlowIdPattern, {
+    message: 'flow id must match /^[a-z0-9][a-z0-9-]*$/',
+  }),
+  name: z.string().min(1),
+  icon: z.string().min(1).optional(),
+});
+
+export const SeeflowManifestSchema = z
+  .object({
+    version: z.literal(1),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    defaultFlow: z.string().min(1),
+    flows: z.array(SeeflowManifestFlowEntrySchema).min(1),
+  })
+  .strict()
+  .superRefine((manifest, ctx) => {
+    const seen = new Set<string>();
+    manifest.flows.forEach((flow, idx) => {
+      if (seen.has(flow.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['flows', idx, 'id'],
+          message: `duplicate flow id "${flow.id}"`,
+        });
+      }
+      seen.add(flow.id);
+    });
+    if (!manifest.flows.some((flow) => flow.id === manifest.defaultFlow)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['defaultFlow'],
+        message: `defaultFlow "${manifest.defaultFlow}" does not match any entry in flows[]`,
+      });
+    }
+  });
+
+export type SeeflowManifest = z.infer<typeof SeeflowManifestSchema>;
+export type SeeflowManifestFlowEntry = z.infer<typeof SeeflowManifestFlowEntrySchema>;

package/src/server.ts

@@ -4,13 +4,14 @@ import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/
 import { Hono } from 'hono';
 import { serveStatic } from 'hono/bun';
 import { type ProxyFacade, createApi } from './api.ts';
+import { createCorsMiddleware } from './cors.ts';
 import { createDemoRouter } from './demo.ts';
 import { type EventBus, createEventBus } from './events.ts';
 import { createMcpServer } from './mcp.ts';
 import { seeflowHome } from './paths.ts';
 import { type ProcessSpawner, defaultProcessSpawner } from './process-spawner.ts';
 import { type RegistryWatcher, createRegistryWatcher } from './registry-watcher.ts';
-import { type Registry, createRegistry } from './registry.ts';
+import { type Registry, createRegistry, manifestOnlyEntryFilter } from './registry.ts';
 import type { Spawner } from './shellout.ts';
 import { type StatusRunner, createStatusRunner } from './status-runner.ts';
 import { type FlowWatcher, createWatcher } from './watcher.ts';
@@ -54,6 +55,19 @@ export interface CreateAppOptions {
   /** Inject a ProxyFacade — tests use this to short-circuit runPlay /
    *  runReset / stopAllPlays and assert call order. */
   proxy?: ProxyFacade;
+  /** Per-process token gating `Origin: null` requests (sandboxed MCP App
+   *  iframe). Generated at studio boot; delivered to the iframe via
+   *  `widgetState.backendToken`. Undefined disables the null-origin path —
+   *  null-origin requests are then always rejected. */
+  token?: string;
+  /** Reachable loopback URL of this Hono server, e.g.
+   *  `http://127.0.0.1:54321`. Forwarded to canvas-bearing MCP tool
+   *  handlers (via `createMcpServer`) so they can attach it to the
+   *  iframe's widgetState as `backendUrl`. Read by closure inside
+   *  `app.all('/mcp', ...)` so callers can mutate the options after
+   *  `Bun.serve` binds — useful for the ephemeral-port boot in
+   *  `mcp-shim.ts` where the URL isn't known until the server is up. */
+  httpUrl?: string;
 }
 
 const DEFAULT_VITE_DEV_URL = 'http://localhost:5173';
@@ -71,7 +85,7 @@ export function createApp(options: CreateAppOptions = {}): Hono {
   const mode = options.mode ?? inferMode();
   const viteDevUrl = options.viteDevUrl ?? DEFAULT_VITE_DEV_URL;
   const staticRoot = options.staticRoot ?? DEFAULT_STATIC_ROOT;
-  const registry = options.registry ?? createRegistry();
+  const registry = options.registry ?? createRegistry({ isLoadableEntry: manifestOnlyEntryFilter });
   const events = options.events ?? createEventBus();
   const watcher = options.disableWatcher
     ? undefined
@@ -92,6 +106,11 @@ export function createApp(options: CreateAppOptions = {}): Hono {
 
   const app = new Hono();
 
+  // CORS + token gate runs first so every downstream route inherits the
+  // null-origin rule. No-ops on requests without an Origin header (CLI
+  // calls, integration tests, top-level navigation).
+  app.use('*', createCorsMiddleware(options.token));
+
   app.get('/health', (c) => c.json({ ok: true }));
 
   // `/healthz` is the readiness probe used by the Docker entrypoint and any
@@ -155,6 +174,8 @@ export function createApp(options: CreateAppOptions = {}): Hono {
     const mcpServer = createMcpServer({
       registry,
       watcher,
+      token: options.token,
+      httpUrl: options.httpUrl,
     });
     await mcpServer.connect(transport);
     try {
@@ -211,7 +232,7 @@ export function serve(options: ServeOptions = {}) {
 }
 
 if (import.meta.main) {
-  const registry = createRegistry();
+  const registry = createRegistry({ isLoadableEntry: manifestOnlyEntryFilter });
   const events = createEventBus();
   const statusRunner = createStatusRunner({ registry, events, spawner: defaultProcessSpawner });
   const server = serve({ registry, events, statusRunner });