@tuongaz/seeflow 0.1.65 → 0.1.68

package/src/component-action-runner.ts

@@ -0,0 +1,188 @@
+/**
+ * Dispatches a component node's `script`-kind ComponentAction over HTTP:
+ * resolves `scriptPath` under `<cwd>/nodes/<nodeId>/` with the same realpath
+ * escape check used by `runPlay` (see proxy.ts), spawns the interpreter via the
+ * injectable `ProcessSpawner` seam, pipes the request payload to stdin as JSON,
+ * and parses stdout back as JSON (falling back to the raw string).
+ *
+ * `set`-kind actions are intentionally rejected with statusHint 400: those
+ * mutate canvas state locally and never round-trip through the API. The runner
+ * is the single seam the API route calls; HTTP status mapping lives in the
+ * route handler via `statusHint`.
+ */
+
+import { realpathSync } from 'node:fs';
+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 { ComponentAction } from './schema.ts';
+import { shortId } from './short-id.ts';
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const SIGKILL_GRACE_MS = 2_000;
+const SCRIPT_PATH_ESCAPE = 'scriptPath escapes node root';
+const SET_KIND_REJECTION = 'Only script actions are dispatched over HTTP';
+
+export interface RunComponentActionOptions {
+  events: EventBus;
+  flowId: string;
+  nodeId: string;
+  /** Project root (`<repoPath>`). Script resolves under `<cwd>/nodes/<nodeId>/`. */
+  cwd: string;
+  actionName: string;
+  action: ComponentAction;
+  payload: unknown;
+  /** Injectable for tests; defaults to `defaultProcessSpawner`. */
+  spawner?: ProcessSpawner;
+}
+
+export interface ComponentActionResult {
+  ok: boolean;
+  body?: unknown;
+  error?: string;
+  /** Suggested HTTP status for the API handler. */
+  statusHint: number;
+}
+
+type Resolved = { ok: true; absPath: string } | { ok: false };
+
+// Resolve `<cwd>/nodes/<nodeId>/<scriptPath>` and verify via realpath it stays
+// inside the node folder. Mirrors proxy.ts:resolveScript — symlink-escape
+// defense in line with `resolveProjectFile` in api.ts.
+function resolveScript(cwd: string, nodeId: string, scriptPath: string): Resolved {
+  const nodeRoot = join(cwd, '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 };
+}
+
+// Copy `process.env` into a string-only record, then layer the per-run extras.
+// Bun.spawn's env contract is `Record<string, string>` so the undefineds that
+// `process.env` advertises in its type must be filtered out first.
+function buildChildEnv(extra: Record<string, string>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (typeof v === 'string') env[k] = v;
+  }
+  return { ...env, ...extra };
+}
+
+async function writeStdinPayload(handle: SpawnHandle, payload: unknown): Promise<void> {
+  if (!handle.stdin) return;
+  const writer = handle.stdin.getWriter();
+  try {
+    await writer.write(new TextEncoder().encode(JSON.stringify(payload)));
+  } finally {
+    await writer.close().catch(() => {
+      /* stdin already closed by child — not fatal */
+    });
+  }
+}
+
+async function killWithGrace(handle: SpawnHandle): Promise<void> {
+  handle.kill('SIGTERM');
+  let graceTimer: ReturnType<typeof setTimeout> | undefined;
+  const gracePromise = new Promise<'grace'>((res) => {
+    graceTimer = setTimeout(() => res('grace'), SIGKILL_GRACE_MS);
+  });
+  const winner = await Promise.race([handle.exited.then(() => 'exited' as const), gracePromise]);
+  if (graceTimer) clearTimeout(graceTimer);
+  if (winner === 'grace') {
+    handle.kill('SIGKILL');
+    await handle.exited;
+  }
+}
+
+export async function runComponentAction(
+  opts: RunComponentActionOptions,
+): Promise<ComponentActionResult> {
+  if (opts.action.kind !== 'script') {
+    return { ok: false, error: SET_KIND_REJECTION, statusHint: 400 };
+  }
+  const spawner = opts.spawner ?? defaultProcessSpawner;
+  const resolved = resolveScript(opts.cwd, opts.nodeId, opts.action.scriptPath);
+  if (!resolved.ok) {
+    return { ok: false, error: SCRIPT_PATH_ESCAPE, statusHint: 400 };
+  }
+
+  const env = buildChildEnv({
+    SEEFLOW_DEMO_ID: opts.flowId,
+    SEEFLOW_NODE_ID: opts.nodeId,
+    SEEFLOW_ACTION_NAME: opts.actionName,
+    SEEFLOW_RUN_ID: shortId(),
+  });
+
+  let handle: SpawnHandle;
+  try {
+    handle = spawner.spawn({
+      cmd: [opts.action.interpreter, ...(opts.action.args ?? []), resolved.absPath],
+      cwd: opts.cwd,
+      env,
+      stdin: 'pipe',
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message, statusHint: 500 };
+  }
+
+  // Drain stdout AND stderr CONCURRENTLY with the process running so OS pipe
+  // buffers (~64 KB) don't fill up and deadlock the child.
+  const stdoutPromise = new Response(handle.stdout).text();
+  const stderrPromise = new Response(handle.stderr).text();
+
+  // Write stdin and close BEFORE awaiting exit (otherwise a child blocked on
+  // `read(stdin)` and a parent blocked on `exited` deadlock each other).
+  await writeStdinPayload(handle, opts.payload);
+
+  const timeoutMs = opts.action.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<'timeout'>((res) => {
+    timer = setTimeout(() => res('timeout'), timeoutMs);
+  });
+  const exitPromise = handle.exited.then((code) => ({ code }) as const);
+
+  const race = await Promise.race([exitPromise, timeoutPromise]);
+  if (timer) clearTimeout(timer);
+
+  if (race === 'timeout') {
+    await killWithGrace(handle);
+    await Promise.allSettled([stdoutPromise, stderrPromise]);
+    return {
+      ok: false,
+      error: `action timed out after ${timeoutMs}ms`,
+      statusHint: 504,
+    };
+  }
+
+  const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+  if (race.code !== 0) {
+    return {
+      ok: false,
+      error: stderr.trim() || `exit ${race.code}`,
+      statusHint: 500,
+    };
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(stdout);
+  } catch {
+    body = stdout;
+  }
+  return { ok: true, body, statusHint: 200 };
+}

package/src/component-spec-resolver.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ResolvedFlow } from './schema.ts';
+
+export interface SpecInlineError {
+  /** Logical path into the merged flow shape, like 'nodes/<id>/data/spec'. */
+  path: string;
+  message: string;
+}
+
+export interface InlineComponentSpecsResult {
+  flow: ResolvedFlow;
+  errors: SpecInlineError[];
+  /** Project-root-relative paths the watcher should track for live reload. */
+  refs: string[];
+}
+
+/**
+ * For every `'component'` node in `flow`, read `nodes/<id>/spec.json`,
+ * JSON.parse, and attach the result as `data.spec`. Missing files surface
+ * as a SpecInlineError; malformed JSON surfaces likewise. Non-component
+ * nodes pass through untouched.
+ *
+ * Returns a NEW flow object (no mutation of the input) so the watcher's
+ * snapshot caching stays safe.
+ */
+export function inlineComponentSpecs(
+  flow: ResolvedFlow,
+  projectRoot: string,
+): InlineComponentSpecsResult {
+  const errors: SpecInlineError[] = [];
+  const refs: string[] = [];
+
+  const nodes = flow.nodes.map((node) => {
+    if (node.type !== 'component') return node;
+    const relPath = `nodes/${node.id}/spec.json`;
+    const absPath = join(projectRoot, relPath);
+    if (!existsSync(absPath)) {
+      errors.push({
+        path: `nodes/${node.id}/data/spec`,
+        message: `Missing spec file: ${relPath}`,
+      });
+      return node;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(absPath, 'utf8'));
+    } catch (err) {
+      errors.push({
+        path: `nodes/${node.id}/data/spec`,
+        message: `Invalid JSON in ${relPath}: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      return node;
+    }
+    refs.push(relPath);
+    return { ...node, data: { ...node.data, spec: parsed } } as typeof node;
+  });
+
+  return { flow: { ...flow, nodes } as ResolvedFlow, errors, refs };
+}

package/src/layout.ts

@@ -76,6 +76,7 @@ const DEFAULT_DIMENSIONS: Record<FlowNode['type'], { width: number; height: numb
   image: { width: 200, height: 150 },
   html: { width: 320, height: 200 },
   icon: { width: 80, height: 80 },
+  component: { width: 320, height: 240 },
 };
 
 // Sticky / text variants are floating annotations. They never participate in

package/src/merge.ts

@@ -133,6 +133,10 @@ export function splitFlow(resolved: {
     const flowData: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data)) {
       if (v === undefined) continue;
+      // Component nodes externalize `spec` to <project>/nodes/<id>/spec.json
+      // (the sidecar). Drop it from flow.json so the strict on-disk schema
+      // doesn't reject it and the spec stays single-sourced on disk.
+      if (node.type === 'component' && k === 'spec') continue;
       if (NODE_DATA_FLOW_KEYS.has(k)) {
         flowData[k] = v;
       } else if (NODE_STYLE_KEYS.has(k)) {

package/src/operations.ts

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSyn
 import { dirname, isAbsolute, join } from 'node:path';
 import { type ZodIssue, z } from 'zod';
 import { writeFileAtomic } from './atomic-write.ts';
+import { inlineComponentSpecs } from './component-spec-resolver.ts';
 import { type LayoutOptions, computeLayout } from './layout.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import {
@@ -24,6 +25,7 @@ import {
 import type { Registry } from './registry.ts';
 import {
   ColorTokenSchema,
+  ComponentSpecSchema,
   EdgePinSchema,
   type Flow,
   FlowSchema,
@@ -141,6 +143,12 @@ export const NodePatchBodySchema = z
     playAction: PlayActionSchema.optional(),
     statusAction: StatusActionSchema.optional(),
     stateSource: StateSourceSchema.optional(),
+    // type:'component'-only: json-render spec describing the reactive UI.
+    // Externalized to `<project>/nodes/<id>/spec.json` by patchNodeImpl; the
+    // in-memory ResolvedFlow keeps `data.spec` populated for the post-merge
+    // reparse + SSE broadcast, but splitFlow strips it from flow.json so the
+    // sidecar is the source of truth on disk.
+    spec: ComponentSpecSchema.optional(),
   })
   .strict();
 export type NodePatchBody = z.infer<typeof NodePatchBodySchema>;
@@ -172,6 +180,7 @@ const NODE_DATA_PATCH_KEYS = [
   'playAction',
   'statusAction',
   'stateSource',
+  'spec',
 ] as const satisfies ReadonlyArray<keyof NodePatchBody>;
 
 const EXTERNALIZED_FIELD_NAMES = new Set<string>(EXTERNALIZED_NODE_FIELDS.map((e) => e.field));
@@ -238,6 +247,10 @@ const SEMANTIC_KEYS_BY_TYPE: Record<z.infer<typeof NodeTypeSchema>, ReadonlySet<
     'statusAction',
     'alt',
   ]),
+  // Component nodes externalize `spec` to <project>/nodes/<id>/spec.json; the
+  // semantic-key set covers only the universal capability fields so retype
+  // never drags `spec` through `data`. (US-007 wires the sidecar writer.)
+  component: GEOMETRIC_SEMANTIC_KEYS,
 };
 
 // Visual data keys — routed to style.json on write by splitFlow. Kept here
@@ -321,12 +334,13 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
     }
   }
 
-  // type:'html'-only invariant enforcement:
+  // type:'html' + type:'component' invariant enforcement:
   //   autoSize === true ⊻ (width and height set).
   // autoSize: true is the dominant signal — it strips width/height even if
   // the same patch tried to write them. Writing width/height implicitly
-  // flips autoSize to false.
-  if (node.type === 'html') {
+  // flips autoSize to false. Both node types default to autoSize:true in the
+  // renderer and share the same shrink-wrap-to-content mechanism.
+  if (node.type === 'html' || node.type === 'component') {
     // The autoSize invariant requires `width`/`height` to be ABSENT from the
     // serialized JSON when autoSize is true — not present with value
     // `undefined` (which would serialize as a stray `"width": null` or get
@@ -757,7 +771,16 @@ export async function mutateMergedFlow<E extends { kind: string }>(
   const styleParse = StyleSchema.safeParse(read.rawStyle);
   if (!styleParse.success) return { kind: 'badSchema', issues: styleParse.error.issues };
 
-  const merged = mergeFlowAndStyle(flowParse.data, styleParse.data) as unknown as {
+  // Inline component spec sidecars (<project>/nodes/<id>/spec.json) before the
+  // mutator runs so the post-mutation ResolvedFlowSchema parse sees `data.spec`
+  // on every existing component node. splitFlow strips `spec` back out before
+  // we write flow.json, keeping the sidecar as the on-disk source of truth.
+  const projectRoot = dirname(flowPath);
+  const { flow: inlinedFlow } = inlineComponentSpecs(
+    mergeFlowAndStyle(flowParse.data, styleParse.data),
+    projectRoot,
+  );
+  const merged = inlinedFlow as unknown as {
     version: number;
     name: string;
     resetAction?: unknown;
@@ -1532,6 +1555,22 @@ 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.
+    if (node.type === 'component' && updates.spec !== undefined) {
+      const specAbs = nodeFileAbsPath(entry.repoPath, nodeId, 'spec.json');
+      try {
+        writeNodeFile(specAbs, `${JSON.stringify(updates.spec, null, 2)}\n`);
+      } catch (err) {
+        return {
+          kind: 'writeFailed',
+          message: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
     return { kind: 'ok' };
   });
 }

package/src/schema.ts

@@ -1,3 +1,4 @@
+import { COMPONENT_NAMES, componentCatalog } from '@seeflow/canvas/catalog';
 import { z } from 'zod';
 
 const PositionSchema = z.object({
@@ -67,7 +68,7 @@ const isCleanRelativePath = (s: string): boolean => {
 // interpreter; `input` (optional) gets JSON-serialized and written to the
 // child's stdin then closed; `timeoutMs` caps execution (default applied at
 // the spawn layer, not here).
-const ScriptActionSchema = z.object({
+export const ScriptActionSchema = z.object({
   kind: z.literal('script'),
   interpreter: z.string().min(1),
   args: z.array(z.string()).optional(),
@@ -140,7 +141,58 @@ export const GEOMETRIC_NODE_TYPES = [
   'cloud',
 ] as const;
 
-export const NodeTypeSchema = z.enum([...GEOMETRIC_NODE_TYPES, 'image', 'html', 'icon']);
+export const NodeTypeSchema = z.enum([
+  ...GEOMETRIC_NODE_TYPES,
+  'image',
+  'html',
+  'icon',
+  'component',
+]);
+
+// --- Component node spec/action schemas --------------------------------------
+// The 'component' node renders a json-render-driven reactive UI on the canvas.
+// `spec` is the source of truth for layout + interactivity; on disk it lives at
+// `<project>/nodes/<id>/spec.json` (the resolver inlines it into data.spec for
+// ResolvedFlowSchema). Element types and props are catalog-validated by a
+// superRefine wired in a later story.
+
+export const ComponentSpecElementSchema = z.object({
+  type: z.string().min(1),
+  props: z.record(z.string(), z.unknown()).optional(),
+  children: z.array(z.string()).optional(),
+  watch: z.record(z.string(), z.unknown()).optional(),
+});
+
+// Declarative state mutation. `path` is a JSON Pointer (starts with '/');
+// `value` may itself carry { $param } / { $state } refs resolved by the
+// runtime at dispatch time.
+const SetActionSchema = z.object({
+  kind: z.literal('set'),
+  path: z
+    .string()
+    .min(1)
+    .startsWith('/', { message: 'path must be a JSON Pointer (start with /)' }),
+  value: z.unknown(),
+});
+
+// Script-kind component actions reuse the existing ScriptActionSchema shape
+// (interpreter, scriptPath, timeoutMs, ...). The action runner roots scriptPath
+// under `<projectRoot>/nodes/<nodeId>/`.
+export const ComponentActionSchema = z.discriminatedUnion('kind', [
+  SetActionSchema,
+  ScriptActionSchema,
+]);
+
+export const ComponentSpecSchema = z.object({
+  root: z.string().min(1),
+  elements: z.record(z.string(), ComponentSpecElementSchema),
+  state: z.record(z.string(), z.unknown()).optional(),
+  actions: z.record(z.string(), ComponentActionSchema).optional(),
+});
+
+export type ComponentSpec = z.infer<typeof ComponentSpecSchema>;
+export type ComponentAction = z.infer<typeof ComponentActionSchema>;
+export type ComponentSpecElement = z.infer<typeof ComponentSpecElementSchema>;
 
 // ---- Resolved (in-memory) per-type data -------------------------------------
 
@@ -188,6 +240,18 @@ const ResolvedIconNodeData = z.object({
   alt: z.string().optional(),
 });
 
+// Component node — `spec` is the json-render tree. On disk the spec lives in
+// `<project>/nodes/<id>/spec.json`; the resolver inlines it into data.spec
+// before ResolvedFlowSchema validates the merged shape. The on-disk
+// FlowComponentNodeData below has no `spec` field.
+const ResolvedComponentNodeData = z.object({
+  ...NodeSemanticBaseShape,
+  ...NodeVisualBaseShape,
+  ...NodeCapabilitiesShape,
+  spec: ComponentSpecSchema,
+  autoSize: z.boolean().optional(),
+});
+
 const NodeBaseShape = {
   id: z.string().min(1),
   position: PositionSchema,
@@ -213,6 +277,11 @@ const NodeSchema = z.discriminatedUnion('type', [
   z.object({ ...NodeBaseShape, type: z.literal('image'), data: ResolvedImageNodeData }),
   z.object({ ...NodeBaseShape, type: z.literal('html'), data: ResolvedHtmlNodeData }),
   z.object({ ...NodeBaseShape, type: z.literal('icon'), data: ResolvedIconNodeData }),
+  z.object({
+    ...NodeBaseShape,
+    type: z.literal('component'),
+    data: ResolvedComponentNodeData,
+  }),
 ]);
 
 // Connector — unchanged by the flat-types refactor.
@@ -307,6 +376,34 @@ export const ResolvedFlowSchema = z
         });
       }
     });
+    // type:'component' spec.elements entries are catalog-validated here so
+    // unknown component names and prop shape mismatches surface at flow-read
+    // time with paths pointing into the offending element.
+    resolved.nodes.forEach((node, idx) => {
+      if (node.type !== 'component') return;
+      const elements = node.data.spec.elements;
+      for (const [elId, entry] of Object.entries(elements)) {
+        const def = componentCatalog.components[entry.type];
+        if (!def) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['nodes', idx, 'data', 'spec', 'elements', elId, 'type'],
+            message: `Unknown component type "${entry.type}". Valid names: ${COMPONENT_NAMES.join(', ')}`,
+          });
+          continue;
+        }
+        const propsResult = def.props.safeParse(entry.props ?? {});
+        if (!propsResult.success) {
+          for (const issue of propsResult.error.issues) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ['nodes', idx, 'data', 'spec', 'elements', elId, 'props', ...issue.path],
+              message: issue.message,
+            });
+          }
+        }
+      }
+    });
   });
 
 export type ResolvedFlow = z.infer<typeof ResolvedFlowSchema>;
@@ -365,6 +462,18 @@ const FlowIconNodeData = z
   })
   .strict();
 
+// Component node, on-disk shape. `spec` is intentionally absent — the sidecar
+// `<project>/nodes/<id>/spec.json` is the source of truth. `.strict()` rejects
+// any stray spec field that slips through (the resolver layer is responsible
+// for inlining + the writer for stripping it back out).
+const FlowComponentNodeData = z
+  .object({
+    ...NodeSemanticBaseShape,
+    ...NodeCapabilitiesShape,
+    autoSize: z.boolean().optional(),
+  })
+  .strict();
+
 const FlowNodeBaseShape = {
   id: z.string().min(1),
 };
@@ -412,6 +521,14 @@ export const FlowIconNodeSchema = z
   })
   .strict();
 
+export const FlowComponentNodeSchema = z
+  .object({
+    ...FlowNodeBaseShape,
+    type: z.literal('component'),
+    data: FlowComponentNodeData,
+  })
+  .strict();
+
 const FlowNodeSchema = z.discriminatedUnion('type', [
   FlowRectangleNodeSchema,
   FlowEllipseNodeSchema,
@@ -425,6 +542,7 @@ const FlowNodeSchema = z.discriminatedUnion('type', [
   FlowImageNodeSchema,
   FlowHtmlNodeSchema,
   FlowIconNodeSchema,
+  FlowComponentNodeSchema,
 ]);
 
 const FlowConnectorBaseShape = {

package/src/watcher.ts

@@ -5,11 +5,18 @@ import { basename, dirname, isAbsolute, join } from 'node:path';
 // contains flow.json). The studio is path-agnostic — whatever path the caller
 // supplied is the project root.
 const projectRootForFlow = (flowPath: string): string => dirname(flowPath);
+import { inlineComponentSpecs } from './component-spec-resolver.ts';
 import type { EventBus } from './events.ts';
 import { resolveFileRefs } from './file-ref.ts';
 import { mergeFlowAndStyle } from './merge.ts';
 import type { Registry } from './registry.ts';
-import { type Flow, FlowSchema, type ResolvedFlow, StyleSchema } from './schema.ts';
+import {
+  type Flow,
+  FlowSchema,
+  type ResolvedFlow,
+  ResolvedFlowSchema,
+  StyleSchema,
+} from './schema.ts';
 
 const DEFAULT_DEBOUNCE_MS = 100;
 
@@ -225,8 +232,37 @@ export function readMergedFlow(flowPath: string): ReadMergedFlowResult {
     };
   }
 
-  const flow = mergeFlowAndStyle(flowParse.data as Flow, styleParse.data);
-  return { flow, valid: true, error: null, fileRefs: refs, staticRefs };
+  const merged = mergeFlowAndStyle(flowParse.data as Flow, styleParse.data);
+  const {
+    flow: inlined,
+    errors: specErrors,
+    refs: specRefs,
+  } = inlineComponentSpecs(merged, projectRoot);
+  const fileRefs = [...refs, ...specRefs];
+
+  if (specErrors.length > 0) {
+    return {
+      ...empty,
+      error: specErrors.map((e) => `${e.path}: ${e.message}`).join('; '),
+      fileRefs,
+      staticRefs,
+    };
+  }
+
+  const resolvedParse = ResolvedFlowSchema.safeParse(inlined);
+  if (!resolvedParse.success) {
+    const message = resolvedParse.error.issues
+      .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+      .join('; ');
+    return {
+      ...empty,
+      error: `ResolvedFlow validation failed: ${message}`,
+      fileRefs,
+      staticRefs,
+    };
+  }
+
+  return { flow: resolvedParse.data, valid: true, error: null, fileRefs, staticRefs };
 }
 
 const closeFileWatchers = (handle: WatchHandle): void => {