@tuongaz/seeflow 0.1.64 → 0.1.68

package/src/schema.ts

@@ -1,3 +1,4 @@
+import { COMPONENT_NAMES, componentCatalog } from '@seeflow/canvas/catalog';
 import { z } from 'zod';
 
 const PositionSchema = z.object({
@@ -5,11 +6,8 @@ const PositionSchema = z.object({
   y: z.number(),
 });
 
-// US-008: HttpAction was the original shape for both playAction and resetAction
-// in pre-script-action releases. After US-001 cut playAction to script-only and
-// US-008 cut resetAction the same way, no schema in this file uses HttpAction
-// anymore. `HttpMethodSchema` is still used for the optional `method` field on
-// connectors (documentation metadata).
+// `HttpMethodSchema` is documentation metadata on connectors. No node schema
+// uses it — PlayAction/StatusAction are script-based.
 const HttpMethodSchema = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 
 // Curated palette tokens. Stored on disk as readable names; the frontend maps
@@ -26,7 +24,8 @@ export const ColorTokenSchema = z.enum([
 ]);
 
 // Visual fields shared by every node type (functional + decorative). All
-// optional — existing demo files predate them and must continue to parse.
+// optional — every visual must work without per-field opinions. Live on
+// resolved nodes; the disk-side flow.json strips them into style.json.
 const NodeVisualBaseShape = {
   width: z.number().positive().optional(),
   height: z.number().positive().optional(),
@@ -39,19 +38,20 @@ const NodeVisualBaseShape = {
   cornerRadius: z.number().min(0).optional(),
 };
 
-// Consolidated three-field metadata shared by every node variant. `description`
-// is the short body text rendered on the canvas under the node header (and as
-// light-bold text in the sidebar). `detail` is the long-form free-text body
-// rendered only in the sidebar. Both optional so unset fields round-trip
-// unchanged. Spread into every node-data schema below since Icon doesn't
-// spread NodeVisualBaseShape.
-const NodeDescriptionBaseShape = {
+// Semantic-data fields shared by every node type. `name` is optional —
+// every visual works without a label. `icon` is decorative-by-default; the
+// `type:'icon'` variant overrides it to required.
+const NodeSemanticBaseShape = {
+  name: z.string().optional(),
   description: z.string().optional(),
   detail: z.string().optional(),
+  // Decorative header glyph. Lucide icon name (kebab-case) resolved by the
+  // canvas <Icon> primitive; falls back to a placeholder when unknown.
+  icon: z.string().optional(),
 };
 
-// US-001: relative-path safety refine (textual). Mirrors the same rule used
-// for image/html-node paths further down. Realpath verification is layered on
+// Relative-path safety refine (textual). Mirrors the same rule used for
+// image-node and html-node script paths. Realpath verification is layered on
 // top by the proxy/status-runner before any spawn (symlink-escape defense).
 const isCleanRelativePath = (s: string): boolean => {
   if (s.length === 0) return false;
@@ -68,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(),
@@ -81,11 +81,7 @@ const ScriptActionSchema = z.object({
 
 export const PlayActionSchema = ScriptActionSchema;
 
-// US-008: resetAction is a one-shot script action — same shape as a play
-// script (interpreter + args + scriptPath + optional input/timeoutMs) but
-// invoked from the /reset endpoint. The studio kills every live play and
-// status script for the demo before running this script, so the running app
-// sees a clean baseline when wiping its state.
+// resetAction is a one-shot script with the same shape as a play script.
 export const ResetActionSchema = ScriptActionSchema;
 
 // Long-running status script. Same spawn shape as ScriptAction (interpreter +
@@ -117,54 +113,23 @@ export const StateSourceSchema = z.discriminatedUnion('kind', [
   z.object({ kind: z.literal('event') }),
 ]);
 
-const NodeDataBaseSchema = z.object({
-  name: z.string().min(1),
-  stateSource: StateSourceSchema,
-  // Reserved for v2: a module path resolved by future skills runtime.
-  // Schema-only at v1 — never read at runtime.
-  handlerModule: z.string().optional(),
-  // Decorative header glyph. Lucide icon name (kebab-case) resolved by the
-  // canvas <Icon> primitive; falls back to a placeholder when unknown.
-  icon: z.string().optional(),
-  ...NodeVisualBaseShape,
-  ...NodeDescriptionBaseShape,
-});
-
-const PlayNodeDataSchema = NodeDataBaseSchema.extend({
-  playAction: PlayActionSchema,
-  statusAction: StatusActionSchema.optional(),
-});
-
-const StateNodeDataSchema = NodeDataBaseSchema.extend({
+// Capabilities — any subset of these makes a node Playable / Stateful. All
+// optional, valid on every node type. A node is Playable iff `playAction` is
+// set; Stateful iff `statusAction` is set; Both iff both. `stateSource` is
+// informational metadata that pairs with statusAction. `handlerModule` is
+// reserved for a future skills runtime and is schema-only at v1.
+const NodeCapabilitiesShape = {
   playAction: PlayActionSchema.optional(),
   statusAction: StatusActionSchema.optional(),
-});
-
-const NodeBaseShape = {
-  id: z.string().min(1),
-  position: PositionSchema,
+  stateSource: StateSourceSchema.optional(),
+  handlerModule: z.string().optional(),
 };
 
-const PlayNodeSchema = z.object({
-  ...NodeBaseShape,
-  type: z.literal('playNode'),
-  data: PlayNodeDataSchema,
-});
-
-const StateNodeSchema = z.object({
-  ...NodeBaseShape,
-  type: z.literal('stateNode'),
-  data: StateNodeDataSchema,
-});
-
-// Decorative annotation node — rectangle / ellipse / sticky. No semantic
-// payload (no kind/stateSource/playAction); reuses NodeVisualBaseShape so
-// users can theme it the same way as functional nodes.
-// US-009 added `database` as the first illustrative shape (cylinder rendered
-// via inline SVG inside shape-node.tsx). Illustrative shapes share the same
-// shapeNode wrapper and color/border fields but own their own visuals via a
-// per-shape component under `apps/web/src/components/nodes/shapes/`.
-export const ShapeKindSchema = z.enum([
+// 12 flat node types. The first 9 are geometric/illustrative and share
+// GeometricNodeData. `image`, `html`, `icon` carry per-type fields.
+// The renderer picks the SVG / chrome by `type`; the schema treats them
+// (apart from the per-type fields below) as identical.
+export const GEOMETRIC_NODE_TYPES = [
   'rectangle',
   'ellipse',
   'sticky',
@@ -174,148 +139,170 @@ export const ShapeKindSchema = z.enum([
   'user',
   'queue',
   'cloud',
+] as const;
+
+export const NodeTypeSchema = z.enum([
+  ...GEOMETRIC_NODE_TYPES,
+  'image',
+  'html',
+  'icon',
+  'component',
 ]);
 
-const ShapeNodeDataSchema = z.object({
-  shape: ShapeKindSchema,
-  name: z.string().optional(),
-  ...NodeVisualBaseShape,
-  ...NodeDescriptionBaseShape,
+// --- 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(),
 });
 
-const ShapeNodeSchema = z.object({
-  ...NodeBaseShape,
-  type: z.literal('shapeNode'),
-  data: ShapeNodeDataSchema,
+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 -------------------------------------
+
+const ResolvedGeometricNodeData = z.object({
+  ...NodeSemanticBaseShape,
+  ...NodeVisualBaseShape,
+  ...NodeCapabilitiesShape,
 });
 
-// Decorative image node — references a file under the project root by
-// relative path (US-004 hard-cut from base64 data URLs to path-backed files).
-// `path` is a relative path under the project root for imageNode uploads:
-// no leading slash, no `..` segments. The renderer fetches via
-// `GET /api/projects/:id/files/:path`.
-const ImageNodeDataSchema = z.object({
+// Image node — references a file under the project root by relative path.
+// `path` is constrained to live under `nodes/<id>/` (post-validate refine on
+// ResolvedFlowSchema below) so the delete_node cascade owns cleanup.
+const ResolvedImageNodeData = z.object({
+  ...NodeSemanticBaseShape,
+  ...NodeVisualBaseShape,
+  ...NodeCapabilitiesShape,
   path: z.string().min(1).refine(isCleanRelativePath, {
     message: 'path must be a relative path under the project root (no absolute / traversal)',
   }),
   alt: z.string().optional(),
-  ...NodeVisualBaseShape,
-  ...NodeDescriptionBaseShape,
   borderWidth: z.number().min(1).max(8).optional(),
 });
 
-const ImageNodeSchema = z.object({
-  ...NodeBaseShape,
-  type: z.literal('imageNode'),
-  data: ImageNodeDataSchema,
-});
-
-// US-011 (illustrative-shapes-htmlnode): htmlNode is the escape-hatch node type
-// for content the curated nodes don't cover — carries author-written HTML
-// inline via `data.html`. The studio externalizes the content to
-// `<project>/nodes/<id>/view.html` and stores a `file://` ref in flow.json;
-// the resolver inlines the content back on read so consumers see
-// the resolved HTML string. The renderer sanitizes before injection
-// (US-013/US-014). Spreads NodeVisualBaseShape so authors can theme the
-// wrapper (border / background / radius / font) with the same fields
-// available on every other visual node.
-export const HtmlNodeDataSchema = z.object({
+// Html node — escape-hatch for content the curated visuals don't cover.
+// `html` is externalized to `<project>/nodes/<id>/view.html` on write; the
+// file-ref resolver inlines it back on read. The renderer sanitizes before
+// injection. `autoSize:true` lets the renderer size around the content.
+const ResolvedHtmlNodeData = z.object({
+  ...NodeSemanticBaseShape,
+  ...NodeVisualBaseShape,
+  ...NodeCapabilitiesShape,
   html: z.string().optional(),
-  name: z.string().optional(),
-  // Decorative caption glyph. Lucide icon name (kebab-case) resolved by the
-  // canvas <Icon> primitive; rendered inline with the caption when set.
-  icon: z.string().optional(),
-  // When true (or absent), the renderer measures the HTML content and React
-  // Flow sizes the wrapper around it (capped at 800×600 by the renderer's
-  // measuring container styles). The studio adapter (`mergeNodeUpdates`)
-  // enforces the invariant that `autoSize === true` and persisted
-  // `width`/`height` never coexist: writing width/height flips autoSize to
-  // false; writing autoSize: true strips width/height.
   autoSize: z.boolean().optional(),
-  ...NodeVisualBaseShape,
-  ...NodeDescriptionBaseShape,
-});
-
-const HtmlNodeSchema = z.object({
-  ...NodeBaseShape,
-  type: z.literal('htmlNode'),
-  data: HtmlNodeDataSchema,
 });
 
-// Decorative icon node — renders a Lucide glyph on the canvas. Unboxed
-// (no border/cornerRadius/backgroundColor) so it does NOT spread
-// NodeVisualBaseShape; only `width` / `height` are reused for resizing.
-const IconNodeDataSchema = z.object({
+// Icon node — renders a Lucide glyph as its main visual. `icon` is required
+// here (overrides the optional decorative `icon` from NodeSemanticBaseShape).
+const ResolvedIconNodeData = z.object({
+  ...NodeSemanticBaseShape,
+  ...NodeVisualBaseShape,
+  ...NodeCapabilitiesShape,
   icon: z.string().min(1),
   color: ColorTokenSchema.optional(),
   strokeWidth: z.number().min(0.5).max(4).optional(),
-  width: z.number().positive().optional(),
-  height: z.number().positive().optional(),
   alt: z.string().optional(),
-  // US-002: optional visible caption rendered below the icon. Distinct from
-  // `alt` (screen-reader text). Absent / empty → no caption rendered and the
-  // node's bounding box is byte-identical to the unlabeled layout.
-  name: z.string().optional(),
-  ...NodeDescriptionBaseShape,
 });
 
-const IconNodeSchema = z.object({
-  ...NodeBaseShape,
-  type: z.literal('iconNode'),
-  data: IconNodeDataSchema,
+// 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,
+};
+
+const makeResolvedGeometricSchema = (type: (typeof GEOMETRIC_NODE_TYPES)[number]) =>
+  z.object({
+    ...NodeBaseShape,
+    type: z.literal(type),
+    data: ResolvedGeometricNodeData,
+  });
+
 const NodeSchema = z.discriminatedUnion('type', [
-  PlayNodeSchema,
-  StateNodeSchema,
-  ShapeNodeSchema,
-  ImageNodeSchema,
-  IconNodeSchema,
-  HtmlNodeSchema,
+  makeResolvedGeometricSchema('rectangle'),
+  makeResolvedGeometricSchema('ellipse'),
+  makeResolvedGeometricSchema('sticky'),
+  makeResolvedGeometricSchema('text'),
+  makeResolvedGeometricSchema('database'),
+  makeResolvedGeometricSchema('server'),
+  makeResolvedGeometricSchema('user'),
+  makeResolvedGeometricSchema('queue'),
+  makeResolvedGeometricSchema('cloud'),
+  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 is the edge between two nodes. The frontend derives a React Flow
-// Edge from each connector at render time (id/source/target are reused;
-// `label` becomes the edge label; visual style comes from optional
-// `style`/`color` fields). v1 has no separate `edges[]` array — connectors
-// are the sole source of truth for inter-node connections. Optional
-// metadata fields (`method`/`url`/`eventName`/`queueName`) may be present
-// for documentation purposes; the renderer does not branch on them.
+// Connector — unchanged by the flat-types refactor.
 const ConnectorStyleSchema = z.enum(['solid', 'dashed', 'dotted']);
 const ConnectorDirectionSchema = z.enum(['forward', 'backward', 'both', 'none']);
-// Path geometry — orthogonal to `style` (which means the dash pattern). Absent
-// → renders as today's smooth bezier curve. 'step' renders as a smoothstep
-// (right-angle / zigzag) path. (US-017)
 const ConnectorPathSchema = z.enum(['curve', 'step']);
 
-// Visual fields shared by every connector. All optional — existing
-// demo files predate them and must continue to parse. `direction` defaults
-// to 'forward' when absent (the historical behavior).
 const ConnectorVisualBaseShape = {
   style: ConnectorStyleSchema.optional(),
   color: ColorTokenSchema.optional(),
   direction: ConnectorDirectionSchema.optional(),
   borderSize: z.number().positive().optional(),
   path: ConnectorPathSchema.optional(),
-  // US-018: per-connector label font size in CSS pixels. Absent → fall back to
-  // the editable-edge default (11px). Mirrors NodeVisualBaseShape.fontSize.
   fontSize: z.number().positive().optional(),
 };
 
-// Handle ids — every node type in this codebase uses the same four-handle
-// layout: target-only on top + left, source-only on right + bottom (US-013).
-// `sourceHandle` MUST be a source-side id and `targetHandle` MUST be a
-// target-side id; sending the wrong role leaves a stranded endpoint at render
-// time, so the schema rejects it (US-022).
+// Handle ids — every node type uses the same four-handle layout:
+// target-only on top + left, source-only on right + bottom.
 export const SourceHandleIdSchema = z.enum(['r', 'b']);
 export const TargetHandleIdSchema = z.enum(['t', 'l']);
 
-// US-006: pinned endpoint position. `side` names one of the four perimeter
-// sides of the connected node; `t` is the parameterized position along that
-// side, [0, 1], measured from the top-left corner of the side (top/bottom →
-// left-to-right; left/right → top-to-bottom). Pins are persisted so they
-// survive node moves and resizes without drifting toward the other endpoint's
-// center the way floating endpoints do.
 const EdgePinSideSchema = z.enum(['top', 'right', 'bottom', 'left']);
 export const EdgePinSchema = z.object({
   side: EdgePinSideSchema,
@@ -326,21 +313,10 @@ const ConnectorBaseShape = {
   id: z.string().min(1),
   source: z.string().min(1),
   target: z.string().min(1),
-  // Optional — connectors authored before the four-handle layout omit them and
-  // React Flow falls back to the first matching handle.
   sourceHandle: SourceHandleIdSchema.optional(),
   targetHandle: TargetHandleIdSchema.optional(),
-  // US-021: tracks whether each endpoint's handle was auto-picked by the
-  // facing-handle picker (true) or pinned by an explicit user handle drop
-  // (false / absent). Auto-picked endpoints get re-routed when nodes move so
-  // the connector keeps facing the other end; user-pinned ones never do.
   sourceHandleAutoPicked: z.boolean().optional(),
   targetHandleAutoPicked: z.boolean().optional(),
-  // US-006: optional explicit perimeter positions for each endpoint. When
-  // set, the endpoint is computed from `(side, t)` against the connected
-  // node's current bbox at render time — the position parameterizes with the
-  // node so the pin survives moves and resizes. Absent → floating /
-  // handle-based endpoint behavior (back-compat).
   sourcePin: EdgePinSchema.optional(),
   targetPin: EdgePinSchema.optional(),
   label: z.string().optional(),
@@ -363,9 +339,8 @@ export const ResolvedFlowSchema = z
     nodes: z.array(NodeSchema),
     connectors: z.array(ConnectorSchema),
     // Optional one-shot script the studio runs when the user clicks Restart.
-    // Lets the running app wipe its own in-memory state. The studio kills
-    // every live play + status script for the flow BEFORE invoking this
-    // script (US-008), so the script sees no stragglers.
+    // The studio kills every live play + status script for the flow BEFORE
+    // invoking this script, so the script sees no stragglers.
     resetAction: ResetActionSchema.optional(),
   })
   .superRefine((resolved, ctx) => {
@@ -386,31 +361,54 @@ export const ResolvedFlowSchema = z
         });
       }
     });
-    // imageNode upload paths must live under the node's own
+    // type:'image' upload paths must live under the node's own
     // `nodes/<id>/` folder so delete_node's removeNodeDir cascade is the
     // single source of cleanup.
     resolved.nodes.forEach((node, idx) => {
-      if (node.type !== 'imageNode') return;
+      if (node.type !== 'image') return;
       const path = (node.data as { path?: string }).path;
       const expected = `nodes/${node.id}/`;
       if (typeof path === 'string' && !path.startsWith(expected)) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ['nodes', idx, 'data', 'path'],
-          message: `imageNode path must start with "${expected}"`,
+          message: `image node path must start with "${expected}"`,
         });
       }
     });
+    // 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>;
 export type ResolvedFlowNode = z.infer<typeof NodeSchema>;
-export type ShapeNode = z.infer<typeof ShapeNodeSchema>;
-export type ImageNode = z.infer<typeof ImageNodeSchema>;
-export type IconNode = z.infer<typeof IconNodeSchema>;
-export type HtmlNode = z.infer<typeof HtmlNodeSchema>;
-export type HtmlNodeData = z.infer<typeof HtmlNodeDataSchema>;
-export type ShapeKind = z.infer<typeof ShapeKindSchema>;
+export type NodeType = z.infer<typeof NodeTypeSchema>;
 export type ColorToken = z.infer<typeof ColorTokenSchema>;
 export type Connector = z.infer<typeof ConnectorSchema>;
 export type ConnectorStyle = z.infer<typeof ConnectorStyleSchema>;
@@ -429,63 +427,50 @@ export type StateSource = z.infer<typeof StateSourceSchema>;
 // What lives on disk in <project>/flow.json after the split.
 // =============================================================================
 
-const FlowNodeDataBaseShape = {
-  name: z.string().min(1),
-  stateSource: StateSourceSchema,
-  handlerModule: z.string().optional(),
-  icon: z.string().optional(),
-  ...NodeDescriptionBaseShape,
-};
-
-const FlowPlayNodeDataSchema = z
-  .object({
-    ...FlowNodeDataBaseShape,
-    playAction: PlayActionSchema,
-    statusAction: StatusActionSchema.optional(),
-  })
-  .strict();
-
-const FlowStateNodeDataSchema = z
-  .object({
-    ...FlowNodeDataBaseShape,
-    playAction: PlayActionSchema.optional(),
-    statusAction: StatusActionSchema.optional(),
-  })
-  .strict();
-
-const FlowShapeNodeDataSchema = z
+const FlowGeometricNodeData = z
   .object({
-    shape: ShapeKindSchema,
-    name: z.string().optional(),
-    ...NodeDescriptionBaseShape,
+    ...NodeSemanticBaseShape,
+    ...NodeCapabilitiesShape,
   })
   .strict();
 
-const FlowImageNodeDataSchema = z
+const FlowImageNodeData = z
   .object({
+    ...NodeSemanticBaseShape,
+    ...NodeCapabilitiesShape,
     path: z.string().min(1).refine(isCleanRelativePath, {
       message: 'path must be a relative path under the project root (no absolute / traversal)',
     }),
     alt: z.string().optional(),
-    ...NodeDescriptionBaseShape,
   })
   .strict();
 
-const FlowIconNodeDataSchema = z
+const FlowHtmlNodeData = z
+  .object({
+    ...NodeSemanticBaseShape,
+    ...NodeCapabilitiesShape,
+    html: z.string().optional(),
+  })
+  .strict();
+
+const FlowIconNodeData = z
   .object({
+    ...NodeSemanticBaseShape,
+    ...NodeCapabilitiesShape,
     icon: z.string().min(1),
     alt: z.string().optional(),
-    name: z.string().optional(),
-    ...NodeDescriptionBaseShape,
   })
   .strict();
 
-const FlowHtmlNodeDataSchema = z
+// 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({
-    html: z.string().optional(),
-    name: z.string().optional(),
-    icon: z.string().optional(),
-    ...NodeDescriptionBaseShape,
+    ...NodeSemanticBaseShape,
+    ...NodeCapabilitiesShape,
+    autoSize: z.boolean().optional(),
   })
   .strict();
 
@@ -493,61 +478,71 @@ const FlowNodeBaseShape = {
   id: z.string().min(1),
 };
 
-export const FlowPlayNodeSchema = z
-  .object({
-    ...FlowNodeBaseShape,
-    type: z.literal('playNode'),
-    data: FlowPlayNodeDataSchema,
-  })
-  .strict();
-
-export const FlowStateNodeSchema = z
-  .object({
-    ...FlowNodeBaseShape,
-    type: z.literal('stateNode'),
-    data: FlowStateNodeDataSchema,
-  })
-  .strict();
+const makeFlowGeometricSchema = (type: (typeof GEOMETRIC_NODE_TYPES)[number]) =>
+  z
+    .object({
+      ...FlowNodeBaseShape,
+      type: z.literal(type),
+      data: FlowGeometricNodeData,
+    })
+    .strict();
+
+export const FlowRectangleNodeSchema = makeFlowGeometricSchema('rectangle');
+export const FlowEllipseNodeSchema = makeFlowGeometricSchema('ellipse');
+export const FlowStickyNodeSchema = makeFlowGeometricSchema('sticky');
+export const FlowTextNodeSchema = makeFlowGeometricSchema('text');
+export const FlowDatabaseNodeSchema = makeFlowGeometricSchema('database');
+export const FlowServerNodeSchema = makeFlowGeometricSchema('server');
+export const FlowUserNodeSchema = makeFlowGeometricSchema('user');
+export const FlowQueueNodeSchema = makeFlowGeometricSchema('queue');
+export const FlowCloudNodeSchema = makeFlowGeometricSchema('cloud');
 
-export const FlowShapeNodeSchema = z
+export const FlowImageNodeSchema = z
   .object({
     ...FlowNodeBaseShape,
-    type: z.literal('shapeNode'),
-    data: FlowShapeNodeDataSchema,
+    type: z.literal('image'),
+    data: FlowImageNodeData,
   })
   .strict();
 
-export const FlowImageNodeSchema = z
+export const FlowHtmlNodeSchema = z
   .object({
     ...FlowNodeBaseShape,
-    type: z.literal('imageNode'),
-    data: FlowImageNodeDataSchema,
+    type: z.literal('html'),
+    data: FlowHtmlNodeData,
   })
   .strict();
 
 export const FlowIconNodeSchema = z
   .object({
     ...FlowNodeBaseShape,
-    type: z.literal('iconNode'),
-    data: FlowIconNodeDataSchema,
+    type: z.literal('icon'),
+    data: FlowIconNodeData,
   })
   .strict();
 
-export const FlowHtmlNodeSchema = z
+export const FlowComponentNodeSchema = z
   .object({
     ...FlowNodeBaseShape,
-    type: z.literal('htmlNode'),
-    data: FlowHtmlNodeDataSchema,
+    type: z.literal('component'),
+    data: FlowComponentNodeData,
   })
   .strict();
 
 const FlowNodeSchema = z.discriminatedUnion('type', [
-  FlowPlayNodeSchema,
-  FlowStateNodeSchema,
-  FlowShapeNodeSchema,
+  FlowRectangleNodeSchema,
+  FlowEllipseNodeSchema,
+  FlowStickyNodeSchema,
+  FlowTextNodeSchema,
+  FlowDatabaseNodeSchema,
+  FlowServerNodeSchema,
+  FlowUserNodeSchema,
+  FlowQueueNodeSchema,
+  FlowCloudNodeSchema,
   FlowImageNodeSchema,
-  FlowIconNodeSchema,
   FlowHtmlNodeSchema,
+  FlowIconNodeSchema,
+  FlowComponentNodeSchema,
 ]);
 
 const FlowConnectorBaseShape = {
@@ -602,11 +597,10 @@ export type FlowNode = z.infer<typeof FlowNodeSchema>;
 export type FlowConnector = z.infer<typeof FlowConnectorSchema>;
 
 // Envelope-only flow shape for the `seeflow schema flow` surface. The full
-// FlowSchema validates the whole graph; this companion schema describes the
-// top-level shape without inlining every node variant or the connector
-// shape, so the runtime-introspectable JSON Schema stays compact. Authors
-// drill into `seeflow schema node` / `seeflow schema connector` for the
-// detailed shapes. Not used for validation — only the catalog reads it.
+// FlowSchema validates the whole graph; this companion describes the top-level
+// shape without inlining every node variant or the connector shape, so the
+// runtime-introspectable JSON Schema stays compact. Authors drill into
+// `seeflow schema node` / `seeflow schema connector` for the detailed shapes.
 export const FlowEnvelopeSchema = z
   .object({
     version: z.literal(2),
@@ -635,12 +629,12 @@ const NodeStyleSchema = z
     fontSize: z.number().positive().optional(),
     textColor: ColorTokenSchema.optional(),
     cornerRadius: z.number().min(0).optional(),
-    // imageNode-specific
+    // type:'image'-specific
     borderWidth: z.number().min(1).max(8).optional(),
-    // iconNode-specific
+    // type:'icon'-specific
     color: ColorTokenSchema.optional(),
     strokeWidth: z.number().min(0.5).max(4).optional(),
-    // htmlNode-specific
+    // type:'html'-specific
     autoSize: z.boolean().optional(),
   })
   .strict();