@tuongaz/seeflow 0.1.91 → 0.1.97

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 '@seeflow/canvas/catalog';
 import type { ZodTypeAny } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import {
@@ -37,6 +38,9 @@ import {
 export interface SchemaCategory {
   name: string;
   description: string;
+  // Every drill target valid for `seeflow schema <name> <subname>`. Lets the
+  // agent pick a variant without a second round-trip to listCategorySubnames.
+  subnames: string[];
 }
 
 export interface SchemaPayload {
@@ -44,13 +48,52 @@ export interface SchemaPayload {
   notes: string[];
 }
 
+// Hint payload attached to every schema response so the agent can drill in
+// 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). `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.
 const toJsonSchema = (schema: ZodTypeAny): unknown =>
   zodToJsonSchema(schema, { $refStrategy: 'none', target: 'jsonSchema7' });
 
-const CATEGORIES: SchemaCategory[] = [
+// Recipe block returned on the schema index (CLI / REST / MCP) so the agent
+// sees the drill + filter pattern in the response itself, not just in
+// `seeflow help schema`.
+export const SCHEMA_INDEX_USAGE = {
+  drill: 'seeflow schema <category> [<subname>]',
+  filter: 'seeflow schema <category> [<subname>] --jq <jq-path>',
+  examples: [
+    'seeflow schema node',
+    'seeflow schema node rectangle',
+    'seeflow schema node rectangle --jq .schemas.rectangle.properties.data.properties.playAction',
+    'seeflow schema action playAction',
+  ],
+} as const;
+
+// Description metadata. `subnames` are filled in by listSchemaCategories()
+// at call time from PAYLOADS, so the two stay in lockstep automatically.
+const CATEGORY_META: Array<Omit<SchemaCategory, 'subnames'>> = [
   { name: 'flow', description: 'Top-level flow.json envelope.' },
   {
     name: 'node',
@@ -71,6 +114,11 @@ const CATEGORIES: SchemaCategory[] = [
     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).' },
 ];
 
@@ -101,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.',
     ],
@@ -132,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: {
@@ -141,7 +206,10 @@ const PAYLOADS: Record<string, SchemaPayload> = {
 };
 
 export function listSchemaCategories(): SchemaCategory[] {
-  return CATEGORIES.map((c) => ({ ...c }));
+  return CATEGORY_META.map((c) => ({
+    ...c,
+    subnames: Object.keys(PAYLOADS[c.name]?.schemas ?? {}),
+  }));
 }
 
 export function getSchemaCategory(name: string): SchemaPayload | null {
@@ -151,7 +219,7 @@ export function getSchemaCategory(name: string): SchemaPayload | null {
 }
 
 export function schemaCategoryNames(): string[] {
-  return CATEGORIES.map((c) => c.name);
+  return CATEGORY_META.map((c) => c.name);
 }
 
 // Drill into one named schema inside a category — e.g. ('node', 'rectangle')
@@ -176,3 +244,99 @@ export function listCategorySubnames(category: string): string[] | null {
   if (!payload) return null;
   return Object.keys(payload.schemas);
 }
+
+// Top-level keys under `data.properties` for a single node variant — i.e.
+// the per-shape data fields an author actually sets on a flow.json node
+// (`name`, `icon`, `playAction`, etc.). Returns null when the variant has
+// no `data.properties` wrapper (action / connector / style / componentSpec
+// schemas, plus anything malformed). Pure helper consumed by buildJqHints
+// to surface concrete drill-down paths.
+export function getDataFieldNames(category: string, subname: string): string[] | null {
+  const sub = PAYLOADS[category]?.schemas[subname] as
+    | { properties?: { data?: { properties?: Record<string, unknown> } } }
+    | undefined;
+  const dataProps = sub?.properties?.data?.properties;
+  if (!dataProps) return null;
+  return Object.keys(dataProps);
+}
+
+// Build ready-to-paste jq path examples for a schema response. When `subname`
+// is provided, the examples drill into that single variant — including one
+// path per `data.<field>` so the agent can `--jq` straight to (say)
+// `.schemas.rectangle.properties.data.properties.playAction` without first
+// reading the whole envelope. When `subname` is omitted, the hints cover the
+// whole category (iteration, one sample variant, notes). `dataFields` only
+// surfaces on single-variant lookups for shapes that actually carry a
+// `data.properties` wrapper.
+export function buildJqHints(category: string, subname?: string): JqHints | null {
+  const payload = PAYLOADS[category];
+  if (!payload) return null;
+  if (subname) {
+    if (payload.schemas[subname] === undefined) return null;
+    const dataFields = getDataFieldNames(category, subname);
+    const examples = [
+      `.schemas.${subname}`,
+      `.schemas.${subname}.required`,
+      ...(dataFields && dataFields.length > 0
+        ? [
+            `.schemas.${subname}.properties.data.properties`,
+            ...dataFields
+              .slice(0, 6)
+              .map((f) => `.schemas.${subname}.properties.data.properties.${f}`),
+          ]
+        : [`.schemas.${subname}.properties`]),
+      '.notes',
+      '.notes[]',
+    ];
+    const hint = dataFields
+      ? `dataFields lists every \`data.<field>\` available on this variant — point \`--jq\` at any of them with \`.schemas.${subname}.properties.data.properties.<field>\`.`
+      : `Use \`--jq\` to pluck a single property — e.g. \`.schemas.${subname}.required\`.`;
+    return {
+      ...(dataFields ? { dataFields } : {}),
+      examples,
+      rootPath: `.schemas.${subname}`,
+      tip: withResultTip(hint),
+    };
+  }
+  const subs = Object.keys(payload.schemas);
+  const sample = subs[0];
+  if (!sample) {
+    return {
+      examples: ['.schemas', '.notes', '.notes[]'],
+      rootPath: '.schemas',
+      tip: JQ_RESULT_TIP,
+    };
+  }
+  const examples = [
+    '.schemas',
+    `.schemas.${sample}`,
+    `.schemas.${sample}.required`,
+    `.schemas.${sample}.properties.data.properties`,
+    '.schemas[]',
+    '.notes',
+    '.notes[]',
+  ];
+  return {
+    examples,
+    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

@@ -14,25 +14,26 @@ const HttpMethodSchema = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 // them to actual CSS values (theme-aware, light + dark).
 export const ColorTokenSchema = z.enum([
   // `'none'` renders transparent border / fill on nodes (no stroke, no fill).
-  // Hidden from the text-color and connector-color pickers — invisible text
-  // and edges aren't useful, and `'default'` already covers "inherit".
+  // Hidden from the connector-color picker — invisible edges aren't useful,
+  // and `'default'` already covers "inherit".
   'none',
   'default',
   'white',
   'slate',
   'gray',
   'red',
-  'rose',
   'orange',
   'amber',
+  'yellow',
   'lime',
   'green',
   'teal',
   'cyan',
+  'sky',
   'blue',
   'indigo',
   'violet',
-  'purple',
+  'fuchsia',
   'pink',
 ]);
 
@@ -47,7 +48,6 @@ const NodeVisualBaseShape = {
   borderSize: z.number().min(0).optional(),
   borderStyle: z.enum(['solid', 'dashed', 'dotted']).optional(),
   fontSize: z.number().positive().optional(),
-  textColor: ColorTokenSchema.optional(),
   // Horizontal alignment for the node's text content. Defaults to 'center'
   // at render time when omitted; explicit picks from the toolbar's Align
   // toggle persist here.
@@ -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(),
@@ -711,7 +716,6 @@ const NodeStyleSchema = z
     borderSize: z.number().min(0).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(),

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-CilAQwI4.js

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

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

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-2Se8RGwW.js";import{a as i}from"./mermaid.core-CRo4rzDL.js";import"./index-DFpY3RpV.js";import"./chunk-FMBD7UC4-BJX_21R2.js";import"./chunk-ND2GUHAM-DFBKXknR.js";import"./chunk-55IACEB6-DlboNFJr.js";import"./chunk-2J33WTMH-9vQ1xqy3.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-fiT0MjXY.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-2Se8RGwW.js";import{a as i}from"./mermaid.core-CRo4rzDL.js";import"./index-DFpY3RpV.js";import"./chunk-FMBD7UC4-BJX_21R2.js";import"./chunk-ND2GUHAM-DFBKXknR.js";import"./chunk-55IACEB6-DlboNFJr.js";import"./chunk-2J33WTMH-9vQ1xqy3.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};