@tuongaz/seeflow 0.1.93 → 0.1.98

package/src/operations.ts

@@ -23,6 +23,7 @@ import {
   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 {
@@ -53,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(),
 });
@@ -95,15 +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(),
-    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
@@ -302,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;
@@ -1239,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
@@ -1644,8 +1662,14 @@ export async function patchNodeImpl(
       field: string;
       content: string;
       kind: 'ref' | 'sidecar';
+      value: unknown;
     }> = [];
-    for (const spec of externalizedFieldsForNodeType(node.type)) {
+    // 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;
@@ -1657,6 +1681,7 @@ export async function patchNodeImpl(
         field: spec.field,
         content,
         kind: spec.kind ?? 'ref',
+        value: incoming,
       });
     }
     mergeNodeUpdates(node, updates);
@@ -1676,10 +1701,12 @@ export async function patchNodeImpl(
           };
         }
         // 'ref' fields swap data[field] for a file:// pointer; 'sidecar'
-        // fields (e.g. component spec) leave the in-memory value alone so the
-        // post-mutation parse still sees it — splitFlow drops it from flow.json
-        // on write and the resolver inlines it back from disk on read.
-        if (w.kind === 'ref') data[w.field] = w.ref;
+        // 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;
     }

package/src/schema-catalog.ts

@@ -5,6 +5,7 @@
 // module load — each call returns a fresh shallow copy so callers can't
 // mutate the cached payload.
 
+import { componentCatalog } from './vendored-canvas-catalog.ts';
 import type { ZodTypeAny } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import {
@@ -51,13 +52,25 @@ export interface SchemaPayload {
 // further without round-tripping. `examples` are ready-to-paste jq paths;
 // `dataFields` lists the node-variant `data.<field>` keys (single-variant
 // lookups only — undefined for non-node categories or category-level
-// responses).
+// responses). `rootPath` is the jq prefix that reaches the schema body at
+// this response level (`.categories` on the index, `.schemas` on a category,
+// `.schemas.<subname>` on a drill) — present in the plain (non-`--jq`)
+// response the agent reads first, so it never has to guess the prefix.
 export interface JqHints {
   dataFields?: string[];
   examples: string[];
+  rootPath: string;
   tip?: string;
 }
 
+// Appended to every `jqHints.tip`. The `--jq` filter runs against the schema
+// object itself; the `{ result }` wrapper the CLI prints under `--jq` is
+// presentational, so a filter must never be prefixed with `.result`.
+const JQ_RESULT_TIP =
+  '`--jq` runs against this object directly; the `result` wrapper in `--jq` output is presentational — never prefix your filter with `.result`.';
+
+const withResultTip = (hint: string): string => `${hint} ${JQ_RESULT_TIP}`;
+
 // Draft-07 pin matches the widest tool support; the same target string is
 // used by the MCP `tools/list` JSON Schemas (default in zod-to-json-schema)
 // so consumers see one consistent dialect across the whole surface.
@@ -101,6 +114,11 @@ const CATEGORY_META: Array<Omit<SchemaCategory, 'subnames'>> = [
     description:
       "Sidecar shape written to <project>/nodes/<id>/spec.json for type:'component' nodes. Carries the json-render element tree, initial state, and named actions the renderer dispatches on user input.",
   },
+  {
+    name: 'componentCatalog',
+    description:
+      'The legal values for componentSpec.elements[].type and the props each accepts. Drill: seeflow schema componentCatalog <Name>.',
+  },
   { name: 'style', description: 'style.json (studio-owned).' },
 ];
 
@@ -131,6 +149,7 @@ const PAYLOADS: Record<string, SchemaPayload> = {
       "type:'image' data.path must start with 'nodes/<id>/'.",
       "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
       "type:'component' nodes have no `spec` field on disk — the spec lives in <project>/nodes/<id>/spec.json (see `seeflow schema componentSpec`). The resolver inlines it into data.spec for runtime / SSE broadcasts.",
+      'The legal `elements[].type` values and their props are listed under `seeflow schema componentCatalog`.',
       "stateSource SHOULD be set on every node that has a statusAction — kind:'request' for poll-based (REST, healthcheck, DB query), kind:'event' for push-based (SSE, webhook, queue, message bus).",
       'stateSource may also be set without a statusAction on representational/architecture diagrams to signal data-flow intent (poll vs push) without wiring a runtime probe.',
     ],
@@ -162,6 +181,22 @@ const PAYLOADS: Record<string, SchemaPayload> = {
       "spec.json is the on-disk source of truth for type:'component' nodes; the resolver inlines it into data.spec at read time and splitFlow strips it back out before writing flow.json so the sidecar is never double-stored.",
       'elements is keyed by element id; `root` names the entry element. Element ids referenced from children / actions must exist in elements.',
       'state and actions are both keyed by user-chosen names. Action handles in the rendered UI reference these names; see `seeflow schema action` for the per-action shape.',
+      'The legal `elements[].type` values and their props are listed under `seeflow schema componentCatalog`.',
+    ],
+  },
+  componentCatalog: {
+    // One subname per catalog entry; schema body = the props object that
+    // element type accepts. Built dynamically so adding a catalog component
+    // surfaces here automatically (the canvas catalog is the single source).
+    schemas: Object.fromEntries(
+      Object.entries(componentCatalog.components).map(([name, def]) => [
+        name,
+        toJsonSchema(def.props),
+      ]),
+    ),
+    notes: [
+      "Each key is a legal componentSpec.elements[].type; its schema is the props object that element type accepts. Set them on the element's `props` field.",
+      'Any prop value may instead be a { $state } / { $action } / { $cond,$then,$else } ref resolved by the json-render runtime at render time — the per-prop schema shows the concrete (non-ref) shape.',
     ],
   },
   style: {
@@ -259,12 +294,19 @@ export function buildJqHints(category: string, subname?: string): JqHints | null
     return {
       ...(dataFields ? { dataFields } : {}),
       examples,
-      tip: hint,
+      rootPath: `.schemas.${subname}`,
+      tip: withResultTip(hint),
     };
   }
   const subs = Object.keys(payload.schemas);
   const sample = subs[0];
-  if (!sample) return { examples: ['.schemas', '.notes', '.notes[]'] };
+  if (!sample) {
+    return {
+      examples: ['.schemas', '.notes', '.notes[]'],
+      rootPath: '.schemas',
+      tip: JQ_RESULT_TIP,
+    };
+  }
   const examples = [
     '.schemas',
     `.schemas.${sample}`,
@@ -276,9 +318,25 @@ export function buildJqHints(category: string, subname?: string): JqHints | null
   ];
   return {
     examples,
-    tip:
+    rootPath: '.schemas',
+    tip: withResultTip(
       subs.length > 1
         ? `Pass \`seeflow schema ${category} <subname>\` (one of: ${subs.join(', ')}) to drop the other ${subs.length - 1} variant(s) from the payload before \`--jq\`-ing.`
         : `Single-variant category — \`--jq\` paths drill straight into \`.schemas.${sample}\`.`,
+    ),
+  };
+}
+
+// jqHints for the schema index (`seeflow schema` with no category). The index
+// payload is `{ categories, usage }`, so `--jq` filters root at `.categories`.
+// Surfaced so the index carries the same `rootPath` affordance as every drill
+// level — the agent never has to guess the prefix.
+export function buildIndexJqHints(): JqHints {
+  return {
+    examples: ['.categories', '.categories[].name', '.usage', '.usage.examples'],
+    rootPath: '.categories',
+    tip: withResultTip(
+      'Each entry under `.categories` names a drill target — pass its `name` as `<category>`.',
+    ),
   };
 }

package/src/schema.ts

@@ -218,7 +218,12 @@ export const NodeTypeSchema = z.enum([
 // superRefine wired in a later story.
 
 export const ComponentSpecElementSchema = z.object({
-  type: z.string().min(1),
+  type: z
+    .string()
+    .min(1)
+    .describe(
+      'Component name from the catalog — see `seeflow schema componentCatalog` for the legal values and the props each type accepts.',
+    ),
   props: z.record(z.string(), z.unknown()).optional(),
   children: z.array(z.string()).optional(),
   watch: z.record(z.string(), z.unknown()).optional(),

package/src/server.ts

@@ -227,7 +227,12 @@ export function serve(options: ServeOptions = {}) {
   const hostname = options.hostname ?? '0.0.0.0';
   mkdirSync(seeflowHome(), { recursive: true });
   const app = createApp(options);
-  return Bun.serve({ port, hostname, fetch: app.fetch });
+  // Bun's default per-connection idle timeout (~10s) reaps long-lived SSE
+  // streams between heartbeats, forcing the browser's EventSource to reconnect
+  // (each reconnect re-fires `hello` → a client refetch). Raise it well above
+  // the SSE heartbeat cadence so the keep-alive lands first and the stream
+  // stays warm. Max accepted by Bun is 255s.
+  return Bun.serve({ port, hostname, idleTimeout: 120, fetch: app.fetch });
 }
 
 if (import.meta.main) {

package/dist/web/assets/channel-C-YVVNMU.js

@@ -1 +0,0 @@
-import{U as a,C as n}from"./mermaid.core-DjNa-8Hv.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/web/assets/classDiagram-4FO5ZUOK-BklVRjbL.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-CwKBkYmr.js";import{a as i}from"./mermaid.core-DjNa-8Hv.js";import"./index-5X7OVal6.js";import"./chunk-FMBD7UC4-DCWBhj6w.js";import"./chunk-ND2GUHAM-vLte473x.js";import"./chunk-55IACEB6-DZ5Ond8O.js";import"./chunk-2J33WTMH-BLQaRMqq.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/web/assets/classDiagram-v2-Q7XG4LA2-BklVRjbL.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-CwKBkYmr.js";import{a as i}from"./mermaid.core-DjNa-8Hv.js";import"./index-5X7OVal6.js";import"./chunk-FMBD7UC4-DCWBhj6w.js";import"./chunk-ND2GUHAM-vLte473x.js";import"./chunk-55IACEB6-DZ5Ond8O.js";import"./chunk-2J33WTMH-BLQaRMqq.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};