@tuongaz/seeflow 0.1.91 → 0.1.97

package/src/cli-manifest.ts

@@ -499,7 +499,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     ],
     body: { schemaRef: 'CreateProjectBody' },
     outputs: {
-      okExample: { id: 'abc12345', slug: 'checkout' },
+      okExample: { id: 'abc12345', slug: 'checkout/main' },
       errorKinds: ['alreadyExists', 'scaffoldFailed'],
     },
     requiresStudio: false,
@@ -872,26 +872,36 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     synopsis: 'seeflow schema [<category> [<subname>]] [--jq <filter>]',
     description:
       'Introspect the SeeFlow flow.json / style.json / spec.json schemas at ' +
-      'runtime. Call without arguments to list the six categories (flow, node, ' +
-      'connector, action, componentSpec, style); call with a category name to ' +
-      'get its full JSON Schema(s) (Draft-07) plus a `notes` array of cross-' +
-      "field invariants the schema can't express. The `node` payload includes " +
-      "all 13 flat variants (including type:'component', whose `spec` field " +
-      'lives in a sidecar — drill into `componentSpec` for that shape).\n\n' +
-      'Pass a third positional `subname` to get just one named schema within ' +
-      'the category — e.g. `seeflow schema node component`, `seeflow schema ' +
-      'node rectangle`, `seeflow schema action playAction`. The category-' +
-      'level `notes` ride along unchanged because the cross-variant invariants ' +
-      'still apply when looking at one variant. Use this before authoring any ' +
-      'flow.json / spec.json write — never memorise field shapes.\n\n' +
-      'Pass --jq <filter> to extract a slice of the response with a jq path ' +
-      'expression. Supported subset: identity (`.`), field access ' +
-      '(`.foo.bar`), bracket access (`.["foo"]`, `.[3]`, negative indices ' +
-      'allowed), iteration (`.foo[]`), optional `?` (e.g. `.foo?` to suppress ' +
-      'type errors), and pipe (`|`). Single-output filters return the value ' +
-      'under `{ result: <value> }`; multi-output filters (from `[]` or `|`) ' +
-      'return `{ result: [<v1>, <v2>, ...] }`. Bad filters exit with code 2 ' +
-      'and `code:"badJq"`.',
+      'runtime. **Run this before designing or authoring any node** — the CLI ' +
+      'is the only source of truth for field shapes, never memorise them.\n\n' +
+      'Progressive workflow:\n' +
+      '  1. `seeflow schema` → index of the six categories (flow, node, ' +
+      'connector, action, componentSpec, style) with every drill `subname` ' +
+      'inlined under each `categories[].subnames`, plus a `usage` block with ' +
+      'copy-paste examples.\n' +
+      '  2. `seeflow schema <category>` → full JSON Schema(s) (Draft-07) for ' +
+      "every variant in the category, the cross-variant `notes`, the category's " +
+      '`subnames`, and a `jqHints` block listing concrete filter paths to try ' +
+      'next.\n' +
+      '  3. `seeflow schema <category> <subname>` → just one named schema ' +
+      "(e.g. `node rectangle`, `action playAction`). The response's " +
+      '`jqHints.dataFields` lists every `data.<field>` available on the variant, ' +
+      'and `jqHints.examples` gives ready-to-paste `--jq` paths pointing at ' +
+      'each one — drill straight to the field you care about without re-paying ' +
+      'for the full schema.\n\n' +
+      "The `node` payload includes all 13 flat variants (including type:'component', " +
+      'whose `spec` field lives in a sidecar — drill into `componentSpec` for ' +
+      'that shape). The category-level `notes` ride along unchanged on subname ' +
+      'lookups because the cross-variant invariants still apply.\n\n' +
+      'Pass `--jq <filter>` to extract a slice of the response with a jq path ' +
+      'expression. Supported subset: identity (`.`), field access (`.foo.bar`), ' +
+      'bracket access (`.["foo"]`, `.[3]`, negative indices allowed), iteration ' +
+      '(`.foo[]`), optional `?` (e.g. `.foo?` to suppress type errors), and pipe ' +
+      '(`|`). Single-output filters return the value under `{ result: <value> }`; ' +
+      'multi-output filters (from `[]` or `|`) return `{ result: [<v1>, <v2>, ...] }`. ' +
+      'Bad filters exit with code 2 and `code:"badJq"`. The fastest pattern is ' +
+      '`seeflow schema <category> <subname> --jq .schemas.<subname>.properties.data.properties.<field>` ' +
+      '— pulls one field shape and nothing else.',
     category: 'meta',
     args: [
       {
@@ -915,13 +925,27 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
         name: 'jq',
         valuePlaceholder: '<filter>',
         description:
-          'Apply a jq path-subset filter to the response payload. Examples: ' +
-          '`.schemas.rectangle`, `.schemas.image.properties.data.properties.path`, ' +
-          '`.schemas[]`, `.notes[0]`.',
+          'Apply a jq path-subset filter to the response payload. Common paths: ' +
+          '`.schemas.<subname>` (one variant), ' +
+          '`.schemas.<subname>.required` (required fields), ' +
+          '`.schemas.<subname>.properties.data.properties` (every data.* shape), ' +
+          '`.schemas.<subname>.properties.data.properties.<field>` (one data.* ' +
+          'shape — `jqHints.dataFields` enumerates `<field>` for you), ' +
+          '`.schemas[]` (iterate variants), `.notes[]` (iterate invariants). ' +
+          'Single-variant lookups surface `jqHints.examples` with these paths ' +
+          'pre-built for the chosen subname.',
       },
     ],
     outputs: {
-      okExample: { categories: [{ name: 'flow', description: 'Top-level flow.json envelope.' }] },
+      okExample: {
+        categories: [
+          { name: 'flow', description: 'Top-level flow.json envelope.', subnames: ['flow'] },
+        ],
+        usage: {
+          drill: 'seeflow schema <category> [<subname>]',
+          filter: 'seeflow schema <category> [<subname>] --jq <jq-path>',
+        },
+      },
       errorKinds: ['notFound', 'badJq'],
     },
     requiresStudio: false,
@@ -934,6 +958,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'seeflow schema connector',
       'seeflow schema componentSpec',
       'seeflow schema node --jq .schemas.rectangle',
+      "seeflow schema node rectangle --jq '.schemas.rectangle.properties.data.properties.playAction'",
       "seeflow schema node --jq '.schemas.image.properties.data.properties.path'",
       "seeflow schema node --jq '.schemas[]'",
     ],

package/src/cli.ts

@@ -268,11 +268,18 @@ Commands (work without a running studio):
   connectors:patch <connId>  Patch a connector (--project <p> --flow <f>) [--json/--file/--stdin]
   connectors:delete <connId> Delete a connector (--project <p> --flow <f>)
   validate             Schema-validate a flow.json (--file <file> [--style <file>])
-  schema [<category> [<subname>]]
-                       Get the flow.json schema. No arg → category index;
-                       category arg → full JSON Schema(s) for that category;
-                       subname arg → just that named schema (e.g.
-                       'schema node component', 'schema node rectangle')
+  schema [<category> [<subname>]] [--jq <path>]
+                       Get the flow.json schema. Run this before designing /
+                       authoring nodes. No arg → category index with subnames
+                       inlined; category arg → full JSON Schema(s) + jqHints;
+                       subname arg → one variant + jqHints.dataFields listing
+                       every data.<field> available. The 'componentCatalog'
+                       category lists every legal componentSpec.elements[].type
+                       and its props (drill: 'schema componentCatalog <Name>').
+                       Every response carries jqHints.rootPath (the jq prefix
+                       for that level). Pair with --jq to slice (e.g. 'schema
+                       node rectangle --jq
+                       .schemas.rectangle.properties.data.properties.playAction').
   ids <type> <count>   Print <count> short ids of the given <type>, one per
                        line. <type> is 'node' (-> 'node-...') or 'connector'
                        (-> 'conn-...'). <count> is 1..100. Call once per type
@@ -1100,10 +1107,21 @@ async function runSchema() {
   const category = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
   const subname = argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined;
   const jqFilter = flagValue('jq');
-  const { listSchemaCategories, getSchemaCategory, getCategorySubschema, listCategorySubnames } =
-    await import('./schema-catalog.ts');
+  const {
+    listSchemaCategories,
+    getSchemaCategory,
+    getCategorySubschema,
+    listCategorySubnames,
+    buildJqHints,
+    buildIndexJqHints,
+    SCHEMA_INDEX_USAGE,
+  } = await import('./schema-catalog.ts');
   if (!category) {
-    const base = { categories: listSchemaCategories() };
+    const base = {
+      categories: listSchemaCategories(),
+      usage: SCHEMA_INDEX_USAGE,
+      jqHints: buildIndexJqHints(),
+    };
     if (jqFilter !== undefined) {
       printOk({ result: applyJqOrDie(base, jqFilter) });
     }
@@ -1141,6 +1159,7 @@ async function runSchema() {
       subname,
       schemas: single.schemas,
       notes: single.notes,
+      jqHints: buildJqHints(category as string, subname),
     };
     if (jqFilter !== undefined) {
       printOk({ name: category, subname, result: applyJqOrDie(base, jqFilter) });
@@ -1154,7 +1173,13 @@ async function runSchema() {
     process.stderr.write(`${JSON.stringify({ error: message, code: 'notFound', available })}\n`);
     process.exit(3);
   }
-  const base = { name: category, schemas: payload.schemas, notes: payload.notes };
+  const base = {
+    name: category,
+    schemas: payload.schemas,
+    notes: payload.notes,
+    subnames: listCategorySubnames(category as string) ?? [],
+    jqHints: buildJqHints(category as string),
+  };
   if (jqFilter !== undefined) {
     printOk({ name: category, result: applyJqOrDie(base, jqFilter) });
   }

package/src/mcp.ts

@@ -30,6 +30,9 @@ import {
 } from './operations.ts';
 import type { Registry } from './registry.ts';
 import {
+  SCHEMA_INDEX_USAGE,
+  buildIndexJqHints,
+  buildJqHints,
   getCategorySubschema,
   getSchemaCategory,
   listCategorySubnames,
@@ -329,7 +332,11 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
         if (subname !== undefined && subname !== null && subname !== '') {
           return errorResult('Invalid arguments: `subname` requires `name` to be set');
         }
-        return okResult({ categories: listSchemaCategories() });
+        return okResult({
+          categories: listSchemaCategories(),
+          usage: SCHEMA_INDEX_USAGE,
+          jqHints: buildIndexJqHints(),
+        });
       }
       if (typeof name !== 'string') {
         return errorResult('Invalid arguments: `name` must be a string when present');
@@ -345,6 +352,7 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
             subname,
             schemas: single.schemas,
             notes: single.notes,
+            jqHints: buildJqHints(name, subname),
           });
         }
         const availableSubs = listCategorySubnames(name);
@@ -363,7 +371,13 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
           `unknown schema category: ${name} (available: ${schemaCategoryNames().join(', ')})`,
         );
       }
-      return okResult({ name, schemas: payload.schemas, notes: payload.notes });
+      return okResult({
+        name,
+        schemas: payload.schemas,
+        notes: payload.notes,
+        subnames: listCategorySubnames(name) ?? [],
+        jqHints: buildJqHints(name),
+      });
     },
   },
   {

package/src/merge.ts

@@ -64,7 +64,6 @@ const NODE_STYLE_KEYS = new Set([
   'borderSize',
   'borderStyle',
   'fontSize',
-  'textColor',
   'textAlign',
   'cornerRadius',
   'shadow',

package/src/node-files.ts

@@ -8,16 +8,54 @@ import { writeFileAtomic } from './atomic-write.ts';
 // `flows/<flow-id>/nodes/<id>/`; for legacy single-flow fixtures with
 // `flowPath: 'flow.json'` it collapses to the project root. `nodeTypes` (when
 // present) scopes the spec entry to specific node types; absent means
-// "applies to every node type". Adding a future text field is one line.
+// "applies to every node type".
+//
+// Two flavors of externalization:
+// - `kind: 'ref'` (default) — write the file, replace `data[field]` with
+//   `file://<fileName>`. The ref survives splitFlow (the field is in
+//   NODE_DATA_FLOW_KEYS in merge.ts). Used by string fields like `detail`
+//   and `html`.
+// - `kind: 'sidecar'` — write the file, leave `data[field]` untouched on
+//   the in-memory node so the post-mutation parse still sees the original
+//   value. splitFlow drops the field from flow.json on write; the resolver
+//   inlines it from disk on read. Used by JSON fields like component `spec`.
+//
+// `serialize` turns the in-memory value into file contents. Returning `null`
+// skips the write entirely — used by `spec` to no-op when the caller didn't
+// supply one, instead of writing an empty file that would fail JSON parse
+// on the next read.
 export interface ExternalizedFieldSpec {
   field: string;
   fileName: string;
   nodeTypes?: readonly string[];
+  kind?: 'ref' | 'sidecar';
+  serialize?: (value: unknown) => string | null;
 }
 
+// Default serializer: strings pass through; non-strings coerce to empty.
+// Keeps the historical detail/html behavior — an absent detail still writes
+// an empty detail.md so the file:// ref points somewhere.
+export const defaultExternalizedSerializer = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+// JSON serializer for sidecar fields: pretty-print plain objects with a
+// trailing newline. Returns null for anything else so the loop can skip the
+// write rather than emit an invalid sidecar.
+const jsonExternalizedSerializer = (value: unknown): string | null =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? `${JSON.stringify(value, null, 2)}\n`
+    : null;
+
 export const EXTERNALIZED_NODE_FIELDS: readonly ExternalizedFieldSpec[] = [
   { field: 'detail', fileName: 'detail.md' },
   { field: 'html', fileName: 'view.html', nodeTypes: ['html'] },
+  {
+    field: 'spec',
+    fileName: 'spec.json',
+    nodeTypes: ['component'],
+    kind: 'sidecar',
+    serialize: jsonExternalizedSerializer,
+  },
 ];
 
 export const externalizedFieldsForNodeType = (

package/src/operations.ts

@@ -16,12 +16,14 @@ import { type LayoutOptions, computeLayout } from './layout.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import {
   EXTERNALIZED_NODE_FIELDS,
+  defaultExternalizedSerializer,
   externalizedFieldsForNodeType,
   nodeFileAbsPath,
   nodeFileRef,
   removeNodeDir,
   writeNodeFile,
 } from './node-files.ts';
+import { seeflowHome } from './paths.ts';
 import { readProjectManifest, scanProject } from './project-scanner.ts';
 import { type FlowEntry, type Registry, slugify } from './registry.ts';
 import {
@@ -52,7 +54,9 @@ export const RegisterBodySchema = z.object({
 export type RegisterBody = z.infer<typeof RegisterBodySchema>;
 
 export const CreateProjectBodySchema = z.object({
-  path: z.string().min(1),
+  // Optional: when omitted the project is scaffolded under
+  // <seeflowHome>/projects/<slug-of-name>. See createProjectImpl.
+  path: z.string().min(1).optional(),
   name: z.string().min(1),
   description: z.string().min(1).optional(),
 });
@@ -94,16 +98,19 @@ export const NodePatchBodySchema = z
     type: NodeTypeSchema.optional(),
     position: PositionBodySchema.optional(),
     name: z.string().optional(),
-    borderColor: ColorTokenSchema.optional(),
-    backgroundColor: ColorTokenSchema.optional(),
-    borderSize: z.number().min(0).optional(),
-    borderWidth: z.number().min(0).max(8).optional(),
-    borderStyle: z.enum(['solid', 'dashed', 'dotted']).optional(),
-    fontSize: z.number().positive().optional(),
-    textColor: ColorTokenSchema.optional(),
-    textAlign: z.enum(['left', 'center', 'right']).optional(),
-    cornerRadius: z.number().min(0).optional(),
-    shadow: z.number().int().min(0).max(5).optional(),
+    // Style/visual keys accept explicit `null` as the clear signal (mirrors
+    // `icon`): mergeNodeUpdates strips the key from disk, so undo can revert a
+    // style field back to its pre-edit "unset" default instead of being a
+    // no-op (a dropped-undefined PATCH leaves the field untouched).
+    borderColor: ColorTokenSchema.nullable().optional(),
+    backgroundColor: ColorTokenSchema.nullable().optional(),
+    borderSize: z.number().min(0).nullable().optional(),
+    borderWidth: z.number().min(0).max(8).nullable().optional(),
+    borderStyle: z.enum(['solid', 'dashed', 'dotted']).nullable().optional(),
+    fontSize: z.number().positive().nullable().optional(),
+    textAlign: z.enum(['left', 'center', 'right']).nullable().optional(),
+    cornerRadius: z.number().min(0).nullable().optional(),
+    shadow: z.number().int().min(0).max(5).nullable().optional(),
     width: z.number().positive().optional(),
     height: z.number().positive().optional(),
     // type:'html'-only: when true, the renderer measures content and React Flow
@@ -112,11 +119,12 @@ export const NodePatchBodySchema = z
     autoSize: z.boolean().optional(),
     // type:'icon'-only: stroke color token. Lands at data.color; the
     // post-merge ResolvedFlowSchema reparse gates that this is only valid on
-    // type:'icon'.
-    color: ColorTokenSchema.optional(),
+    // type:'icon'. Nullable: explicit null clears it (undo of an icon recolor).
+    color: ColorTokenSchema.nullable().optional(),
     // type:'icon'-only: glyph stroke width. Lands at data.strokeWidth; the
-    // post-merge reparse gates the [0.5, 4] bound and arm validity.
-    strokeWidth: z.number().min(0.5).max(4).optional(),
+    // post-merge reparse gates the [0.5, 4] bound and arm validity. Nullable:
+    // explicit null clears it (undo back to the default stroke width).
+    strokeWidth: z.number().min(0.5).max(4).nullable().optional(),
     // type:'icon'/type:'image'-only: accessible alt text. Lands at data.alt.
     alt: z.string().optional(),
     // kebab-case Lucide icon name. Lands at data.icon. The post-merge reparse
@@ -164,7 +172,6 @@ const NODE_DATA_PATCH_KEYS = [
   'borderWidth',
   'borderStyle',
   'fontSize',
-  'textColor',
   'textAlign',
   'cornerRadius',
   'shadow',
@@ -267,7 +274,6 @@ const NODE_VISUAL_KEYS = new Set([
   'borderSize',
   'borderStyle',
   'fontSize',
-  'textColor',
   'textAlign',
   'cornerRadius',
   'shadow',
@@ -304,10 +310,12 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
       }
       continue;
     }
-    // US-009: explicit null on icon is the clear signal (`.min(1)` rules out
-    // the empty-string convention used for description / detail). Strip the
-    // key from disk so a re-parsed demo doesn't reintroduce it.
-    if (key === 'icon' && updates[key] === null) {
+    // Explicit null is the clear signal for every nullable key (style/visual
+    // tokens + US-009's `icon`): strip the key from disk so a re-parsed demo
+    // doesn't reintroduce it, and so an undo can restore a field to its
+    // pre-edit "unset" default. Only keys declared `.nullable()` in
+    // NodePatchBodySchema can reach here carrying null.
+    if (updates[key] === null) {
       if (key in data) {
         delete data[key];
         touchedData = true;
@@ -1241,7 +1249,15 @@ export async function createProjectImpl(
   body: CreateProjectBody,
 ): Promise<CreateProjectOutcome> {
   const { registry, watcher } = deps;
-  const { path: folderPath, name, description } = body;
+  const { name, description } = body;
+
+  // Path is optional: when the caller omits it, scaffold under the studio's
+  // home at <seeflowHome>/projects/<slug-of-name> so projects created from the
+  // UI without a path land in a predictable, writable location.
+  const folderPath =
+    body.path && body.path.trim().length > 0
+      ? body.path
+      : join(seeflowHome(), 'projects', slugify(name));
 
   // 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
@@ -1347,12 +1363,16 @@ export async function addNodeImpl(
       ? { ...(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);
+    for (const spec of externalizedFieldsForNodeType(newNode.type)) {
+      const incoming = data[spec.field];
+      const serializer = spec.serialize ?? defaultExternalizedSerializer;
+      const content = serializer(incoming);
+      if (content === null) continue; // serializer opted out (e.g. spec absent)
+      if ((spec.kind ?? 'ref') === 'ref') {
+        data[spec.field] = nodeFileRef(newId, spec.fileName);
+      }
       externalized.push({
-        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, fileName),
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, spec.fileName),
         content,
       });
     }
@@ -1431,12 +1451,16 @@ export async function addFlowBulkImpl(
     const data: Record<string, unknown> = dataIsRecord
       ? { ...(newNode.data as Record<string, unknown>) }
       : {};
-    for (const { field, fileName } of externalizedFieldsForNodeType(newNode.type)) {
-      const incoming = data[field];
-      const content = typeof incoming === 'string' ? incoming : '';
-      data[field] = nodeFileRef(newId, fileName);
+    for (const spec of externalizedFieldsForNodeType(newNode.type)) {
+      const incoming = data[spec.field];
+      const serializer = spec.serialize ?? defaultExternalizedSerializer;
+      const content = serializer(incoming);
+      if (content === null) continue; // serializer opted out (e.g. spec absent)
+      if ((spec.kind ?? 'ref') === 'ref') {
+        data[spec.field] = nodeFileRef(newId, spec.fileName);
+      }
       externalized.push({
-        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, fileName),
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, newId, spec.fileName),
         content,
       });
     }
@@ -1637,15 +1661,27 @@ export async function patchNodeImpl(
       ref: string;
       field: string;
       content: string;
+      kind: 'ref' | 'sidecar';
+      value: unknown;
     }> = [];
-    for (const { field, fileName } of externalizedFieldsForNodeType(node.type)) {
-      const incoming = (updates as Record<string, unknown>)[field];
+    // Externalize against the node's *target* type: a retype-into-component
+    // carrying `spec` in the same patch is still geometric at this point, so
+    // keying off `node.type` would miss `spec` (only externalized for
+    // 'component'), leaving spec.json unwritten and data.spec unpopulated.
+    const targetType = updates.type ?? node.type;
+    for (const spec of externalizedFieldsForNodeType(targetType)) {
+      const incoming = (updates as Record<string, unknown>)[spec.field];
       if (incoming === undefined) continue;
+      const serializer = spec.serialize ?? defaultExternalizedSerializer;
+      const content = serializer(incoming);
+      if (content === null) continue; // serializer opted out
       externalizedWrites.push({
-        absPath: nodeFileAbsPath(entry.repoPath, flowDir, nodeId, fileName),
-        ref: nodeFileRef(nodeId, fileName),
-        field,
-        content: typeof incoming === 'string' ? incoming : '',
+        absPath: nodeFileAbsPath(entry.repoPath, flowDir, nodeId, spec.fileName),
+        ref: nodeFileRef(nodeId, spec.fileName),
+        field: spec.field,
+        content,
+        kind: spec.kind ?? 'ref',
+        value: incoming,
       });
     }
     mergeNodeUpdates(node, updates);
@@ -1664,26 +1700,16 @@ export async function patchNodeImpl(
             message: err instanceof Error ? err.message : String(err),
           };
         }
-        data[w.field] = w.ref;
+        // 'ref' fields swap data[field] for a file:// pointer; 'sidecar'
+        // fields (e.g. component spec) keep the incoming value in memory so the
+        // post-mutation reparse + SSE broadcast see it — splitFlow drops it
+        // from flow.json on write and the resolver inlines it back from disk on
+        // read. Setting it here is required for a retype-into-component patch,
+        // where there is no pre-inlined data.spec to fall back on.
+        data[w.field] = w.kind === 'ref' ? w.ref : w.value;
       }
       node.data = data;
     }
-    // Component spec sidecar — write the pretty-printed JSON to
-    // `<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, flowDir, 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' };
   });
 }