@tuongaz/seeflow 0.1.71 → 0.1.75

package/src/schema.ts

@@ -58,12 +58,30 @@ const NodeVisualBaseShape = {
 // 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(),
+  name: z
+    .string()
+    .optional()
+    .describe(
+      "Short human-readable label rendered in the node header. Omit on decorative nodes (sticky, type:'text') where the body content IS the label.",
+    ),
+  description: z
+    .string()
+    .optional()
+    .describe(
+      'One-sentence summary surfaced in the detail sidebar and tooltips. Set whenever a reader would benefit from more context than the name alone.',
+    ),
+  detail: z
+    .string()
+    .optional()
+    .describe(
+      'Long-form markdown shown in the detail sidebar. Supports headings, lists, code, and ```mermaid``` blocks (the canvas renders mermaid inline). Use for runbooks, schemas, sequence diagrams.',
+    ),
+  icon: z
+    .string()
+    .optional()
+    .describe(
+      "Decorative header glyph (Lucide icon name in kebab-case, e.g. 'database', 'cloud-upload'). Falls back to a placeholder when unknown. On type:'icon' nodes the icon IS the visual and is required.",
+    ),
 };
 
 // Relative-path safety refine (textual). Mirrors the same rule used for
@@ -124,10 +142,22 @@ export const StatusReportSchema = z.object({
   ts: z.number().int().positive().optional(),
 });
 
-export const StateSourceSchema = z.discriminatedUnion('kind', [
-  z.object({ kind: z.literal('request') }),
-  z.object({ kind: z.literal('event') }),
-]);
+export const StateSourceSchema = z
+  .discriminatedUnion('kind', [
+    z
+      .object({ kind: z.literal('request') })
+      .describe(
+        'Poll-based state: `statusAction` samples an endpoint on an interval (REST GET, healthcheck, DB query). Use for services you can probe.',
+      ),
+    z
+      .object({ kind: z.literal('event') })
+      .describe(
+        'Push-based state: `statusAction` subscribes to a stream (SSE, webhook, queue topic). Use for message buses, async pipelines, anything that announces state changes.',
+      ),
+  ])
+  .describe(
+    "Declares how this node's live state is sourced. Pair with `statusAction` so observers can tell at a glance whether the node's status is polled or pushed.",
+  );
 
 // Capabilities — any subset of these makes a node Playable / Stateful. All
 // optional, valid on every node type. A node is Playable iff `playAction` is
@@ -135,16 +165,27 @@ export const StateSourceSchema = z.discriminatedUnion('kind', [
 // 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(),
-  stateSource: StateSourceSchema.optional(),
-  handlerModule: z.string().optional(),
+  playAction: PlayActionSchema.optional().describe(
+    'One-shot script the user invokes by clicking the node (a "Play" affordance). Studio spawns `<interpreter> [...args] <scriptPath>` from the project root with the optional `input` JSON-serialized to stdin. Use for HTTP calls, CLI invocations, anything triggered on demand.',
+  ),
+  statusAction: StatusActionSchema.optional().describe(
+    "Long-running status probe. Same spawn shape as `playAction` but the script ticks continuously and writes one JSON `StatusReport` per line to stdout; the canvas renders the most recent state badge. Pair with `stateSource` so observers know whether it's poll- or push-based.",
+  ),
+  stateSource: StateSourceSchema.optional().describe(
+    'Set this on any node that has a `statusAction`. Choose `request` for poll-based sources, `event` for push-based sources. Omit on decorative nodes (sticky, label-only text) and on action nodes whose only behavior is `playAction`.',
+  ),
+  handlerModule: z
+    .string()
+    .optional()
+    .describe(
+      'Reserved for the v2 skills runtime. Schema-only at v1 — set by tooling; leave undefined when authoring flows by hand.',
+    ),
 };
 
-// 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.
+// 13 flat node types. The first 9 are geometric/illustrative and share
+// GeometricNodeData. `image`, `html`, `icon`, `component` 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',
@@ -454,10 +495,19 @@ 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(),
+    path: z
+      .string()
+      .min(1)
+      .refine(isCleanRelativePath, {
+        message: 'path must be a relative path under the project root (no absolute / traversal)',
+      })
+      .describe(
+        "Project-root-relative path to the image file. MUST start with 'nodes/<id>/' so the delete_node cascade owns cleanup. Supported formats: PNG, JPEG, SVG, GIF, WebP.",
+      ),
+    alt: z
+      .string()
+      .optional()
+      .describe('Accessibility alt text. Set on every non-decorative image.'),
   })
   .strict();
 
@@ -465,7 +515,12 @@ const FlowHtmlNodeData = z
   .object({
     ...NodeSemanticBaseShape,
     ...NodeCapabilitiesShape,
-    html: z.string().optional(),
+    html: z
+      .string()
+      .optional()
+      .describe(
+        "Inline HTML rendered inside the node. Studio externalizes this to `<project>/nodes/<id>/view.html` on write and inlines it back on read, so authors always see the actual string. Sanitized before injection. Escape-hatch for content the geometric/icon/component visuals don't cover.",
+      ),
   })
   .strict();
 
@@ -473,8 +528,13 @@ const FlowIconNodeData = z
   .object({
     ...NodeSemanticBaseShape,
     ...NodeCapabilitiesShape,
-    icon: z.string().min(1),
-    alt: z.string().optional(),
+    icon: z
+      .string()
+      .min(1)
+      .describe(
+        "Required Lucide icon name (kebab-case, e.g. 'cloud-upload', 'database'). On type:'icon' nodes the icon IS the visual — overrides the optional decorative `icon` from the semantic base.",
+      ),
+    alt: z.string().optional().describe('Accessibility alt text for the icon glyph.'),
   })
   .strict();
 
@@ -486,7 +546,12 @@ const FlowComponentNodeData = z
   .object({
     ...NodeSemanticBaseShape,
     ...NodeCapabilitiesShape,
-    autoSize: z.boolean().optional(),
+    autoSize: z
+      .boolean()
+      .optional()
+      .describe(
+        'When true the renderer measures its content and React Flow sizes the wrapper around it. Default (undefined / false) uses the persisted width/height path.',
+      ),
   })
   .strict();
 

package/src/watcher.ts

@@ -20,6 +20,15 @@ import {
 
 const DEFAULT_DEBOUNCE_MS = 100;
 
+/**
+ * Polling backup interval. fs.watch on macOS occasionally drops events
+ * (notably right after a fresh watcher is registered), so a low-frequency
+ * stat poll over every watched handle guarantees external writes still
+ * trigger reparse+broadcast. Own-write echoes are still suppressed by
+ * the writtenHashes ring, so this doesn't double-fire on server writes.
+ */
+const DEFAULT_POLL_INTERVAL_MS = 500;
+
 /** Max recent self-write hashes retained per flow for own-echo suppression. */
 const WRITTEN_HASH_RING_SIZE = 4;
 
@@ -52,6 +61,12 @@ export interface WatcherDeps {
   events: EventBus;
   /** Override for tests. */
   debounceMs?: number;
+  /**
+   * Polling backup interval for missed fs.watch events. Defaults to 500ms.
+   * Pass `0` to disable (tests that rely on deterministic fs.watch-only
+   * behaviour).
+   */
+  pollIntervalMs?: number;
 }
 
 export interface FlowWatcher {
@@ -276,6 +291,7 @@ const closeFileWatchers = (handle: WatchHandle): void => {
 export function createWatcher(deps: WatcherDeps): FlowWatcher {
   const { registry, events } = deps;
   const debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
 
   const handles = new Map<string, WatchHandle>();
   const snapshots = new Map<string, FlowSnapshot>();
@@ -455,6 +471,49 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
     });
   };
 
+  /**
+   * Common path for "something on disk may have changed" — used by both
+   * fs.watch callbacks and the polling backup. Debounces, drops own-write
+   * echoes, then reparses + broadcasts. Idempotent under repeated calls
+   * within the debounce window.
+   */
+  const scheduleChange = (flowId: string): void => {
+    const handle = handles.get(flowId);
+    if (!handle) return;
+    if (handle.debounceTimer) clearTimeout(handle.debounceTimer);
+    handle.debounceTimer = setTimeout(() => {
+      handle.debounceTimer = null;
+      // Own-write dedupe: if the on-disk bytes match what the server just
+      // wrote (recent hash in the ring), this is our own echo — drop it.
+      // notifyWritten already broadcast and seeded the snapshot.
+      const combined = readCombinedFromDisk(handle.filePath);
+      if (combined !== null && isOwnWriteEcho(flowId, sha256Hex(combined))) return;
+      const snap = reparse(flowId);
+      if (snap) broadcastReload(flowId, snap);
+    }, debounceMs);
+  };
+
+  // Single shared interval that stat-polls every watched handle. Cheap (one
+  // statSync per watched flow per tick) and bounded — flows that registry
+  // doesn't know about aren't watched, so the loop scales with active
+  // projects, not historic ones. Backs up macOS fs.watch's occasional
+  // dropped events; the debounce + own-write dedupe in scheduleChange
+  // keeps it from double-firing alongside a fs.watch hit.
+  const pollTimer: ReturnType<typeof setInterval> | null =
+    pollIntervalMs > 0
+      ? setInterval(() => {
+          for (const [flowId, handle] of handles) {
+            const seen = lastSeenMtimes.get(flowId);
+            if (seen === undefined) continue;
+            const now = combinedMtimeMs(handle.filePath);
+            if (now > seen) scheduleChange(flowId);
+          }
+        }, pollIntervalMs)
+      : null;
+  // Don't keep the event loop alive on this timer alone — the studio process
+  // should exit cleanly when nothing else is pending.
+  pollTimer?.unref?.();
+
   const startWatch = (flowId: string) => {
     const existing = handles.get(flowId);
     if (existing) {
@@ -484,19 +543,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
         // React to flow.json, style.json, or rename-on-save events
         // (some platforms emit those with no filename).
         if (changed && changed !== base && changed !== 'style.json') return;
-        const handle = handles.get(flowId);
-        if (!handle) return;
-        if (handle.debounceTimer) clearTimeout(handle.debounceTimer);
-        handle.debounceTimer = setTimeout(() => {
-          handle.debounceTimer = null;
-          // Own-write dedupe: if the on-disk bytes match what the server just
-          // wrote (recent hash in the ring), this is our own echo — drop it.
-          // notifyWritten already broadcast and seeded the snapshot.
-          const combined = readCombinedFromDisk(filePath);
-          if (combined !== null && isOwnWriteEcho(flowId, sha256Hex(combined))) return;
-          const snap = reparse(flowId);
-          if (snap) broadcastReload(flowId, snap);
-        }, debounceMs);
+        scheduleChange(flowId);
       });
     } catch (err) {
       console.error(`[watcher] failed to watch ${dir} for flow ${flowId}:`, err);
@@ -551,6 +598,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
       for (const entry of registry.list()) startWatch(entry.id);
     },
     closeAll() {
+      if (pollTimer) clearInterval(pollTimer);
       for (const [, h] of handles) {
         h.fsWatcher.close();
         if (h.debounceTimer) clearTimeout(h.debounceTimer);