@caddis/cli 0.4.44 → 0.4.46

package/bundles/antigravity-plugin/skills/flow-studio/model.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "flow-studio model",
+  "description": "What an author writes. The engine renders it. validate.mjs also enforces rules a schema cannot (unique ids, links that point at real nodes, no overlap, no orphan).",
+  "type": "object",
+  "required": ["version", "meta", "layout", "columns", "lanes", "states", "nodes", "links"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "meta": {
+      "type": "object",
+      "required": ["title", "help", "asOf", "source"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string" },
+        "help": { "type": "string" },
+        "asOf": { "type": "string" },
+        "source": { "type": "string" },
+        "labels": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "layout": { "enum": ["columns-lanes", "free", "auto"] },
+    "columns": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "title", "width"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" }, "title": { "type": "string" }, "short": { "type": "string" },
+          "width": { "type": "number", "minimum": 60 }, "phase": { "type": "string" }
+        }
+      }
+    },
+    "lanes": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "title"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" }, "title": { "type": "string" }, "badge": { "type": "string" },
+          "badgeTone": { "enum": ["ok", "warn", "muted"] }, "note": { "type": "string" }, "gap": { "type": "boolean" }
+        }
+      }
+    },
+    "states": {
+      "type": "object", "minProperties": 1,
+      "additionalProperties": {
+        "type": "object", "required": ["word", "tone", "border", "edge", "motion", "bucket"], "additionalProperties": false,
+        "properties": {
+          "word": { "type": "string" },
+          "tone": { "enum": ["ok", "warn", "crit", "info", "muted", "accent"] },
+          "border": { "enum": ["solid", "dashed", "dotted"] },
+          "edge": { "enum": ["flow", "dash", "dash-short", "dot"] },
+          "motion": { "enum": ["flow", "flow-slow", "breathe", "none"] },
+          "bucket": { "enum": ["good", "neutral", "gap"] }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "kind", "state", "title"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "enum": ["card", "group", "chip", "gateway", "start", "end", "event", "placeholder", "note"] },
+          "lane": { "type": "string" }, "col": { "type": "integer", "minimum": 0 }, "colSpan": { "type": "integer", "minimum": 1 },
+          "row": { "type": "number" }, "x": { "type": "number" }, "y": { "type": "number" },
+          "w": { "type": "number", "exclusiveMinimum": 0 }, "h": { "type": "number", "exclusiveMinimum": 0 },
+          "state": { "type": "string" },
+          "stateIn": { "type": "object", "additionalProperties": { "type": "string" } },
+          "visibleIn": { "type": "array", "items": { "type": "string" } },
+          "title": { "type": "string" }, "subtitle": { "type": "string" },
+          "members": { "type": "array", "items": { "type": "string" } },
+          "weight": { "type": "number", "minimum": 0 }, "ref": { "type": "string" },
+          "upgrade": { "type": "string" }, "allowIsolated": { "type": "boolean" },
+          "contains": { "type": "array", "items": { "type": "string" } }, "collapsed": { "type": "boolean", "default": true, "description": "A group with contains starts collapsed unless collapsed is false." },
+          "sla": { "type": "number", "exclusiveMinimum": 0, "description": "Target service level agreement in seconds" },
+          "metrics": { "type": "object", "required": ["value"], "additionalProperties": false,
+            "properties": { "value": { "type": "number" }, "max": { "type": ["number", "null"], "description": "Upper bound for the badge fill bar; null means there is no maximum" }, "unit": { "type": "string" }, "label": { "type": "string" },
+              "series": { "type": "array", "maxItems": 60, "items": { "type": "number" } } } }
+        }
+      }
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "from", "to", "state"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "state": { "type": "string" },
+          "stateIn": { "type": "object", "additionalProperties": { "type": "string" } },
+          "visibleIn": { "type": "array", "items": { "type": "string" } }, "label": { "type": "string" },
+          "kind": { "enum": ["forward", "loop-back"] }
+        }
+      }
+    },
+    "views": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "label"], "additionalProperties": false,
+        "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "default": { "type": "boolean" } }
+      }
+    },
+    "inspector": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "relations": {
+          "type": "array", "maxItems": 3,
+          "items": {
+            "type": "object", "required": ["id", "label", "dir"], "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string" }, "label": { "type": "string" }, "dir": { "enum": ["up", "down"] },
+              "filter": { "type": "object", "additionalProperties": false, "properties": { "col": { "type": "integer" }, "kind": { "type": "string" } } }
+            }
+          }
+        },
+        "actions": {
+          "type": "array",
+          "items": {
+            "type": "object", "required": ["id", "label", "dir", "staleText"], "additionalProperties": false,
+            "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "dir": { "const": "down" }, "staleText": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "scenarios": { "type": "array", "items": { "type": "object", "required": ["id", "label", "steps"], "additionalProperties": false,
+      "properties": { "id": { "type": "string" }, "label": { "type": "string" },
+        "steps": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["link"], "additionalProperties": false,
+          "properties": { "link": { "type": "string" }, "at": { "type": "number", "minimum": 0, "description": "Relative elapsed offset from scenario start in seconds" }, "dur": { "type": "number", "exclusiveMinimum": 0, "description": "Token travel animation duration in milliseconds (defaults to 900)" }, "caption": { "type": "string" } } } } } } },
+    "notes": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["anchor", "title", "text"], "additionalProperties": false,
+        "properties": { "anchor": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" } }
+      }
+    }
+  },
+  "allOf": [
+    { "if": { "properties": { "layout": { "const": "columns-lanes" } } },
+      "then": { "properties": { "columns": { "minItems": 1 }, "lanes": { "minItems": 1 },
+        "nodes": { "items": { "required": ["lane", "col", "row"] } } } } },
+    { "if": { "properties": { "layout": { "const": "free" } } },
+      "then": { "properties": { "lanes": { "minItems": 1 }, "nodes": { "items": { "required": ["lane", "x", "y"] } } } } }
+  ]
+}

package/bundles/antigravity-plugin/skills/flow-studio/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "flow-studio",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --experimental-strip-types --test src/*.test.ts scripts/lib/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "build:engine": "node --experimental-strip-types scripts/build-engine.mjs",
+    "check:engine": "node --experimental-strip-types scripts/build-engine.mjs --check"
+  }
+}

package/bundles/antigravity-plugin/skills/flow-studio/react/FlowStudioView.test.tsx

@@ -0,0 +1,82 @@
+import React, { StrictMode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import type { Model, NoteDef } from '../src/model.ts';
+
+const lifecycle = vi.hoisted(() => ({
+  alive: 0, updates: [] as Model[], mounts: 0, listenerCount: 0,
+  notes: [] as (NoteDef[] | undefined)[],
+  onSelect: undefined as ((id: string | null) => void) | undefined,
+}));
+vi.mock('../templates/flow-studio.lib.mjs', () => ({
+  SHELL_BODY_HTML: '<div id="viewport"></div>',
+  mount: (_root: ParentNode, _model: Model, options: { notes?: NoteDef[]; onSelect?: (id: string | null) => void }) => {
+    lifecycle.mounts++;
+    lifecycle.alive++;
+    lifecycle.listenerCount++;
+    lifecycle.notes.push(options.notes);
+    lifecycle.onSelect = options.onSelect;
+    return {
+      update: (model: Model) => { lifecycle.updates.push(model); return { ok: true, issues: [] }; },
+      destroy: () => { lifecycle.alive--; lifecycle.listenerCount--; },
+    };
+  },
+}));
+
+import { FlowStudioView } from './FlowStudioView.tsx';
+
+const model = { version: 1, columns: [], lanes: [], nodes: [], links: [], states: {} } as unknown as Model;
+
+describe('FlowStudioView', () => {
+  it('keeps one instance and listener set through StrictMode, updates once, and cleans up', () => {
+    const globals = window as Window & { flowStudioMount?: unknown };
+    const previousMount = globals.flowStudioMount;
+    lifecycle.alive = 0;
+    lifecycle.mounts = 0;
+    lifecycle.listenerCount = 0;
+    lifecycle.updates = [];
+    lifecycle.notes = [];
+    const select = vi.fn();
+    const rendered = render(<StrictMode><FlowStudioView model={model} onSelect={select} /></StrictMode>);
+    expect(lifecycle.mounts).toBe(2);
+    expect(lifecycle.alive).toBe(1);
+    expect(lifecycle.listenerCount).toBe(1);
+    expect(globals.flowStudioMount).toBeTypeOf('function');
+    lifecycle.onSelect?.('sample');
+    expect(select).toHaveBeenCalledWith('sample');
+    rendered.rerender(<StrictMode><FlowStudioView model={structuredClone(model)} onSelect={select} /></StrictMode>);
+    expect(lifecycle.updates).toHaveLength(0);
+    const changed = { ...model, meta: { title: 'Updated', help: '', asOf: '', source: '' } } as Model;
+    rendered.rerender(<StrictMode><FlowStudioView model={changed} onSelect={select} /></StrictMode>);
+    expect(lifecycle.updates).toEqual([changed]);
+    expect(lifecycle.alive).toBe(1);
+    rendered.unmount();
+    expect(lifecycle.alive).toBe(0);
+    expect(lifecycle.listenerCount).toBe(0);
+    expect(globals.flowStudioMount).toBe(previousMount);
+  });
+
+  it('passes notes at mount and ignores later notes-only changes', () => {
+    lifecycle.updates = [];
+    lifecycle.notes = [];
+    const first = [{ anchor: 'a', title: 'First', text: 'Mount-time note' }] satisfies NoteDef[];
+    const second = [{ anchor: 'b', title: 'Second', text: 'Changed note' }] satisfies NoteDef[];
+    const rendered = render(<FlowStudioView model={model} notes={first} />);
+    expect(lifecycle.notes).toEqual([first]);
+    rendered.rerender(<FlowStudioView model={model} notes={second} />);
+    expect(lifecycle.updates).toHaveLength(0);
+    expect(lifecycle.notes).toEqual([first]);
+  });
+
+  it('keeps window.flowStudioMount while any instance is mounted', () => {
+    const globals = window as Window & { flowStudioMount?: unknown };
+    const previous = globals.flowStudioMount;
+    const first = render(<FlowStudioView model={model} />);
+    const second = render(<FlowStudioView model={model} />);
+    expect(globals.flowStudioMount).toBeTypeOf('function');
+    first.unmount();
+    expect(globals.flowStudioMount).toBeTypeOf('function');
+    second.unmount();
+    expect(globals.flowStudioMount).toBe(previous);
+  });
+});

package/bundles/antigravity-plugin/skills/flow-studio/react/FlowStudioView.tsx

@@ -0,0 +1,67 @@
+import { useEffect, useRef } from "react";
+import { mount, SHELL_BODY_HTML, type FlowStudio } from "../templates/flow-studio.lib.mjs";
+import type { Model, NoteDef } from "../src/model.ts";
+
+export interface FlowStudioViewProps {
+  model: Model;
+  /** Read once at mount; later changes to this prop are ignored. For notes that change with the data, put them on `model.notes` — `update` forwards them. */
+  notes?: NoteDef[];
+  onSelect?: (id: string | null) => void;
+  className?: string;
+}
+
+// The engine publishes its mount helper on a shared global. Count mounted instances so the first
+// mount claims the global and the last unmount releases it; unmounting one of several views must
+// not clear the global while the others still run.
+let mountedViews = 0;
+let previousGlobalMount: typeof mount | undefined;
+
+/** Mounts the finished engine in React. The shell stays outside React's child tree. */
+export function FlowStudioView({ model, notes, onSelect, className }: FlowStudioViewProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const api = useRef<FlowStudio | null>(null);
+  const currentModel = useRef(model);
+  const currentNotes = useRef(notes);
+  const currentSelect = useRef(onSelect);
+  const lastModel = useRef<string | null>(null);
+  currentModel.current = model;
+  currentNotes.current = notes;
+  currentSelect.current = onSelect;
+  const modelJson = JSON.stringify(model);
+
+  useEffect(() => {
+    const container = root.current;
+    if (!container) return;
+    container.innerHTML = SHELL_BODY_HTML;
+    const instance = mount(container, currentModel.current, {
+      notes: currentNotes.current,
+      onSelect: id => currentSelect.current?.(id),
+    });
+    if (mountedViews === 0) {
+      previousGlobalMount = window.flowStudioMount;
+      window.flowStudioMount = mount;
+    }
+    mountedViews++;
+    api.current = instance;
+    lastModel.current = JSON.stringify(currentModel.current);
+    return () => {
+      instance.destroy();
+      if (api.current === instance) api.current = null;
+      lastModel.current = null;
+      mountedViews--;
+      if (mountedViews === 0) {
+        if (previousGlobalMount) window.flowStudioMount = previousGlobalMount;
+        else delete window.flowStudioMount;
+        previousGlobalMount = undefined;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!api.current || lastModel.current === modelJson) return;
+    api.current.update(model);
+    lastModel.current = modelJson;
+  }, [modelJson, model]);
+
+  return <div ref={root} className={className} />;
+}

package/bundles/antigravity-plugin/skills/flow-studio/react/README.md

@@ -0,0 +1,37 @@
+# Flow studio in a React app
+
+## Choose a route
+
+Use `FlowStudioView` when the page may use the engine's own look. It includes the complete canvas, inspector, notes, playback, search, and live update behavior. Use `native/` when the page must use the app's own components and design system. The native files are small examples built from the same pure source modules.
+
+## Install
+
+Copy `react/`, `src/`, `templates/flow-studio.lib.mjs`, `templates/flow-studio.lib.d.mts`, and `templates/flow-studio.css` into the same relative layout in your app. Install React 18 or later. The native route needs only the pure modules under `src/`; the fast route uses the bundled library. Import `flow-studio.css` once for the fast route. Import `react/native/native.css` for the native example only.
+
+```tsx
+import { FlowStudioView, FlowLoading, FlowEmpty, FlowError, type Model } from './react/index.ts';
+import './templates/flow-studio.css';
+
+type State = { kind: 'loading' } | { kind: 'ready'; model: Model; refreshError?: string } | { kind: 'error'; message: string };
+function FlowPage({ state, onRetry, onSelect }: { state: State; onRetry: () => void; onSelect: (id: string | null) => void }) {
+  if (state.kind === 'loading') return <FlowLoading />;
+  if (state.kind === 'error') return <FlowError message={state.message} onRetry={onRetry} />;
+  if (state.model.nodes.length === 0) return <FlowEmpty model={state.model} />;
+  return <>{state.refreshError && <FlowError message={state.refreshError} onRetry={onRetry} />}
+    <FlowStudioView model={state.model} onSelect={onSelect} /></>;
+}
+```
+
+`FlowStudioView` takes a required `model` and optional `notes`, `onSelect`, and `className`. `notes` is read once at mount; later changes to the prop are ignored. For notes that change with the data, put them on the model (`model.notes`) — `update` forwards them. `onSelect` receives a stable node id or `null` when selection clears. The component mounts the engine once, sends changed models to `update`, and destroys its listeners on unmount. React StrictMode's development mount cycle is supported. Several views may be mounted at once; the engine's global mount helper stays available until the last one unmounts.
+
+## Live data contract
+
+Map source rows to `Model` with stable node and link ids. Derive each id from a durable business key. Never derive ids from array positions or current sort order. Keep missing metrics typed as missing. Do not turn them into zero. Show `FlowLoading` before the first model, `FlowEmpty` when the model has no nodes, and `FlowError` for a request failure.
+
+An update that fails model validation keeps the last good graph and shows a message in the engine's `#banner`. Keep the last good model in app state when a data request fails. The engine preserves the view and surviving selection on a valid model update.
+
+## Verify
+
+From this skill folder, run `node scripts/react-proof.mjs`. It creates a disposable Vite app in the system temp folder, installs its test tools, runs Vitest and TypeScript, builds the app, starts a preview server, and runs the browser checks. It removes the app afterward. On Windows it uses the installed Edge browser; elsewhere it lets npm download Playwright's own browser. Your app can run the same browser checks with `node scripts/check.mjs http://localhost:5173/ --skip hostile`. Omit `--skip hostile` when you also provide a hostile test page.
+
+For step by step integration and failure handling, see [`implement-in-app.md`](../references/implement-in-app.md).

package/bundles/antigravity-plugin/skills/flow-studio/react/index.ts

@@ -0,0 +1,3 @@
+export { FlowStudioView, type FlowStudioViewProps } from "./FlowStudioView.tsx";
+export { FlowLoading, FlowEmpty, FlowError } from "./states.tsx";
+export type { Model, NoteDef } from "../src/model.ts";

package/bundles/antigravity-plugin/skills/flow-studio/react/native/FlowCanvas.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+import type { Model, NodeDef } from "../../src/model.ts";
+import { defaultView } from "../../src/rules.ts";
+import { elbow, loopBack } from "../../src/routing.ts";
+import { useFlowGeometry } from "./useFlowGeometry.ts";
+import { useTrace } from "./useTrace.ts";
+import { useViewport } from "./useViewport.ts";
+import { Inspector } from "./Inspector.tsx";
+import "./native.css";
+
+export interface FlowCanvasProps {
+  model: Model;
+  renderNode: (node: NodeDef, context: { selected: boolean; connected: boolean }) => ReactNode;
+  mode?: string;
+  className?: string;
+}
+
+/** Small native example. Apps can replace every element while retaining the hooks. */
+export function FlowCanvas({ model: input, renderNode, mode, className }: FlowCanvasProps) {
+  const activeMode = mode ?? defaultView(input);
+  const trace = useTrace(input, activeMode);
+  const { model, geometry } = useFlowGeometry(input, { x: 0, y: 0, k: 1 }, trace.collapsed, activeMode);
+  const viewport = useViewport(geometry.bounds);
+  const selected = model.nodes.find(node => node.id === trace.selected) ?? null;
+  const path = (link: typeof model.links[number]) => {
+    const from = geometry.nodes[link.from], to = geometry.nodes[link.to];
+    if (!from || !to) return "";
+    if (link.kind === "loop-back") return loopBack(from.x + from.w / 2, from.y + from.h, to.x + to.w / 2, to.y + to.h, geometry.loops[link.id]?.channelY ?? Math.max(from.y + from.h, to.y + to.h) + 20);
+    return elbow(from.x + from.w, from.y + from.h / 2, to.x, to.y + to.h / 2, (from.x + from.w + to.x) / 2);
+  };
+  return <section id="workspace" className={`flow-native ${className ?? ""}`}>
+    <div id="tools" className="flow-native-tools">
+      <button type="button" onClick={() => viewport.fit()} aria-label="Fit graph">Fit</button>
+      <button type="button" onClick={() => viewport.zoomAboutCenter(1.2)} aria-label="Zoom in">+</button>
+      <button type="button" onClick={() => viewport.zoomAboutCenter(1 / 1.2)} aria-label="Zoom out">−</button>
+      <span id="zoomLabel">{Math.round(viewport.view.k * 100)}%</span>
+    </div>
+    <div id="cols" className="flow-native-cols" aria-label="Columns">{model.columns.map((column, i) => <span key={column.id} style={{ left: (geometry.xs[i] ?? 0) * viewport.view.k + viewport.view.x, width: column.width * viewport.view.k }}>{column.title}</span>)}</div>
+    <div id="viewport" className="flow-native-viewport" {...viewport.bind}>
+      <div id="world" className="flow-native-world" style={{ width: geometry.world.w, height: geometry.world.h, transform: `translate(${viewport.view.x}px, ${viewport.view.y}px) scale(${viewport.view.k})` }}>
+        {model.lanes.map(lane => { const rect = geometry.lanes[lane.id]; return rect && <div key={lane.id} className="flow-native-lane" style={{ left: rect.x, top: rect.y, width: rect.w, height: rect.h }}><strong>{lane.title}</strong></div>; })}
+        <svg id="edges" className="flow-native-edges" width={geometry.world.w} height={geometry.world.h} aria-label="Links"><g id="edgeLayer">{trace.links.map(link => <path key={link.id} data-link-id={link.id} d={path(link)} fill="none" stroke="currentColor" strokeWidth="2" />)}</g></svg>
+        {model.nodes.filter(node => trace.visible.has(node.id)).map(node => {
+          const rect = geometry.nodes[node.id]; if (!rect) return null;
+          return <div key={node.id} id={`n_${node.id}`} className="flow-native-node" style={{ left: rect.x, top: rect.y, width: rect.w, height: rect.h }}>
+            <button type="button" className="flow-native-node-main" aria-label={node.title} aria-pressed={trace.selected === node.id} data-connected={trace.connected.has(node.id)}
+              onMouseEnter={() => trace.setHover(node.id)} onMouseLeave={() => trace.setHover(null)} onFocus={() => trace.setHover(node.id)} onBlur={() => trace.setHover(null)}
+              onClick={() => trace.setSelected(node.id)}>{renderNode(node, { selected: trace.selected === node.id, connected: trace.connected.has(node.id) })}</button>
+            {node.kind === "group" && node.contains?.length ? <button type="button" className="flow-native-toggle" aria-label={`${trace.collapsed.has(node.id) ? "Expand" : "Collapse"} ${node.title}`}
+              onClick={() => trace.toggleGroup(node.id)}>{trace.collapsed.has(node.id) ? "+" : "−"}</button> : null}
+          </div>;
+        })}
+      </div>
+    </div>
+    <div id="live" className="flow-native-live" aria-live="polite">{selected ? `${selected.title} selected` : ""}</div>
+    <Inspector model={model} node={selected} mode={activeMode} upstream={trace.upstream} downstream={trace.downstream} onClose={() => trace.setSelected(null)} onSelect={trace.setSelected} />
+  </section>;
+}

package/bundles/antigravity-plugin/skills/flow-studio/react/native/Inspector.tsx

@@ -0,0 +1,27 @@
+import type { Model, NodeDef } from "../../src/model.ts";
+import { bucketOf, nodeStateId } from "../../src/rules.ts";
+
+export function Inspector({ model, node, mode, upstream, downstream, onClose, onSelect }: {
+  model: Model; node: NodeDef | null; mode: string; upstream: Set<string>; downstream: Set<string>;
+  onClose: () => void; onSelect?: (id: string) => void;
+}) {
+  if (!node) return null;
+  const state = model.states[nodeStateId(model, mode, node)];
+  return <aside id="inspector" className="insp open" role="dialog" aria-label={`${node.title} details`} aria-modal="false">
+    <div className="insp-h"><div><h2>{node.title}</h2><small>{state?.word ?? "Unknown state"}</small></div><button type="button" onClick={onClose} aria-label="Close inspector">×</button></div>
+    <div className="insp-b">
+      {node.subtitle && <p>{node.subtitle}</p>}
+      <p>State: {bucketOf(model, nodeStateId(model, mode, node))}</p>
+      <div className="counts">
+        <button type="button" className="cbtn" aria-label={`${Math.max(0, upstream.size - 1)} upstream nodes`}>Upstream {Math.max(0, upstream.size - 1)}</button>
+        <button type="button" className="cbtn" aria-label={`${Math.max(0, downstream.size - 1)} downstream nodes`}>Downstream {Math.max(0, downstream.size - 1)}</button>
+      </div>
+      <div className="drill" aria-label="Connected nodes">
+        {[...new Set([...upstream, ...downstream])].filter(id => id !== node.id).map(id => {
+          const related = model.nodes.find(item => item.id === id);
+          return related && <button type="button" key={id} onClick={() => onSelect?.(id)}>{related.title}</button>;
+        })}
+      </div>
+    </div>
+  </aside>;
+}

package/bundles/antigravity-plugin/skills/flow-studio/react/native/index.ts

@@ -0,0 +1,6 @@
+export { useViewport } from "./useViewport.ts";
+export { useFlowGeometry } from "./useFlowGeometry.ts";
+export { useTrace } from "./useTrace.ts";
+export { FlowCanvas } from "./FlowCanvas.tsx";
+export { Inspector } from "./Inspector.tsx";
+export type { FlowCanvasProps } from "./FlowCanvas.tsx";

package/bundles/antigravity-plugin/skills/flow-studio/react/native/native.css

@@ -0,0 +1,18 @@
+.flow-native { position: relative; min-height: 460px; overflow: hidden; }
+.flow-native-tools { display: flex; gap: .5rem; align-items: center; padding: .5rem; }
+.flow-native-cols { position: relative; height: 2.5rem; overflow: hidden; }
+.flow-native-cols span { position: absolute; overflow: hidden; white-space: nowrap; }
+.flow-native-viewport { position: relative; height: 440px; overflow: hidden; touch-action: none; outline-offset: -2px; }
+.flow-native-world { position: absolute; transform-origin: 0 0; }
+.flow-native-lane, .flow-native-node, .flow-native-edges { position: absolute; }
+.flow-native-lane { border: 1px solid currentColor; opacity: .45; pointer-events: none; }
+.flow-native-lane strong { display: block; padding: .3rem; }
+.flow-native-node { display: flex; text-align: left; background: inherit; color: inherit; border: 1px solid currentColor; }
+.flow-native-node-main { flex: 1; min-width: 0; padding: .4rem; background: transparent; color: inherit; border: 0; text-align: left; }
+.flow-native-node-main[aria-pressed="true"] { outline: 2px solid currentColor; }
+.flow-native-toggle { align-self: start; padding: 0 .35rem; cursor: pointer; }
+.flow-native .insp { position: absolute; top: 0; right: 0; bottom: 0; width: min(320px, 90%); background: Canvas; color: CanvasText; border-left: 1px solid; overflow: auto; }
+.flow-native .insp-h { display: flex; justify-content: space-between; padding: 1rem; }
+.flow-native .insp-b { padding: 1rem; }
+.flow-native .counts, .flow-native .drill { display: flex; gap: .5rem; flex-wrap: wrap; }
+.flow-native-live { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }

package/bundles/antigravity-plugin/skills/flow-studio/react/native/native.test.tsx

@@ -0,0 +1,161 @@
+if (typeof window !== "undefined" && typeof window.PointerEvent === "undefined") {
+  class PointerEvent extends MouseEvent {
+    pointerId: number;
+    pointerType: string;
+    constructor(type: string, params: PointerEventInit = {}) {
+      super(type, params);
+      this.pointerId = params.pointerId ?? 0;
+      this.pointerType = params.pointerType ?? "mouse";
+    }
+  }
+  window.PointerEvent = PointerEvent as unknown as typeof window.PointerEvent;
+}
+import React from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import type { Model } from "../../src/model.ts";
+import { useViewport } from "./useViewport.ts";
+import { useFlowGeometry } from "./useFlowGeometry.ts";
+import { FlowCanvas } from "./FlowCanvas.tsx";
+
+const model: Model = {
+  version: 1, meta: { title: "Sample", help: "", asOf: "", source: "" }, layout: "columns-lanes",
+  columns: [{ id: "one", title: "One", width: 180 }, { id: "two", title: "Two", width: 180 }],
+  lanes: [{ id: "lane", title: "Lane" }],
+  states: { good: { word: "Ready", tone: "ok", border: "solid", edge: "flow", motion: "none", bucket: "good" } },
+  nodes: [
+    { id: "a", kind: "card", lane: "lane", col: 0, row: 0, state: "good", title: "Alpha" },
+    { id: "b", kind: "card", lane: "lane", col: 1, row: 0, state: "good", title: "Beta" },
+  ], links: [{ id: "ab", from: "a", to: "b", state: "good" }],
+};
+
+function ViewProbe() {
+  const { view, bind, fit, zoomBy, zoomAboutCenter } = useViewport({ x: 0, y: 0, w: 1000, h: 500 });
+  return <>
+    <div data-testid="pad" {...bind} />
+    <output data-testid="view">{JSON.stringify(view)}</output>
+    <button onClick={() => zoomBy(2, 100, 80)}>Zoom at point</button>
+    <button onClick={() => zoomAboutCenter(2)}>Zoom about center</button>
+    <button onClick={() => fit()}>Fit measured</button>
+    <button onClick={() => fit({ w: 500, h: 300 })}>Fit explicit</button>
+  </>;
+}
+
+const view = () => JSON.parse(screen.getByTestId("view").textContent!) as { x: number; y: number; k: number };
+/** jsdom reports 0 for every box; the hook must read the sizes from the attached element. */
+const measure = (element: Element, w: number, h: number) => {
+  Object.defineProperty(element, "clientWidth", { value: w, configurable: true });
+  Object.defineProperty(element, "clientHeight", { value: h, configurable: true });
+};
+
+afterEach(cleanup);
+
+describe("native flow viewport", () => {
+  it("keeps the point below the cursor during zoom and fits given bounds", () => {
+    render(<ViewProbe />);
+    fireEvent.click(screen.getByText("Zoom at point"));
+    expect(view()).toEqual({ x: -100, y: -80, k: 2 });
+    fireEvent.click(screen.getByText("Fit explicit"));
+    expect(view().k).toBeLessThan(1);
+  });
+
+  it("measures the attached element when fit() gets no size", () => {
+    render(<ViewProbe />);
+    measure(screen.getByTestId("pad"), 800, 400);
+    fireEvent.click(screen.getByText("Fit measured"));
+    expect(view().k).toBeCloseTo(0.616, 5);
+    expect(view().x).toBeCloseTo(92, 5);
+    expect(view().y).toBeCloseTo(68, 5);
+  });
+
+  it("zooms from a native non-passive wheel listener that can block page scroll", () => {
+    render(<ViewProbe />);
+    const pad = screen.getByTestId("pad");
+    const wheel = new WheelEvent("wheel", { deltaY: -120, clientX: 60, clientY: 40, cancelable: true, bubbles: true });
+    fireEvent(pad, wheel);
+    expect(wheel.defaultPrevented).toBe(true);
+    expect(view().k).toBeGreaterThan(1);
+  });
+
+  it("pans with a pointer drag and stops tracking after pointer up", () => {
+    render(<ViewProbe />);
+    const pad = screen.getByTestId("pad");
+    // jsdom has no real pointer capture; the pan maths must not depend on it.
+    if (typeof pad.setPointerCapture === "function") pad.setPointerCapture = () => {};
+    if (typeof pad.releasePointerCapture === "function") pad.releasePointerCapture = () => {};
+    measure(pad, 800, 400);
+    fireEvent.pointerDown(pad, { button: 0, pointerId: 1, clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(pad, { pointerId: 1, clientX: 150, clientY: 120 });
+    expect(view()).toEqual({ x: 50, y: 20, k: 1 });
+    fireEvent.pointerUp(pad, { pointerId: 1 });
+    fireEvent.pointerMove(pad, { pointerId: 1, clientX: 400, clientY: 300 });
+    expect(view()).toEqual({ x: 50, y: 20, k: 1 });
+  });
+
+  it("zooms with the keyboard about the measured center and fits with 0", () => {
+    render(<ViewProbe />);
+    const pad = screen.getByTestId("pad");
+    measure(pad, 800, 400);
+    fireEvent.keyDown(pad, { key: "+" });
+    expect(view()).toEqual({ x: -80, y: -40, k: 1.2 });
+    fireEvent.keyDown(pad, { key: "-" });
+    expect(view().k).toBeCloseTo(1, 10);
+    fireEvent.keyDown(pad, { key: "0" });
+    expect(view().k).toBeCloseTo(0.616, 5);
+  });
+
+  it("zoomAboutCenter keeps the middle of the viewport fixed", () => {
+    render(<ViewProbe />);
+    measure(screen.getByTestId("pad"), 800, 400);
+    fireEvent.click(screen.getByText("Zoom about center"));
+    expect(view()).toEqual({ x: -400, y: -200, k: 2 });
+  });
+
+  it("reuses the geometry across renders when the collapsed default is omitted", () => {
+    const seen: unknown[] = [];
+    function GeometryProbe() {
+      const { geometry } = useFlowGeometry(model, { x: 0, y: 0, k: 1 });
+      seen.push(geometry);
+      return null;
+    }
+    const rendered = render(<GeometryProbe />);
+    rendered.rerender(<GeometryProbe />);
+    rendered.rerender(<GeometryProbe />);
+    expect(seen[1]).toBe(seen[0]);
+    expect(seen[2]).toBe(seen[0]);
+  });
+});
+
+describe("native flow canvas", () => {
+  it("selects a node, traces its link, and closes the inspector with Escape", () => {
+    render(<FlowCanvas model={model} renderNode={node => <span>{node.title}</span>} />);
+    fireEvent.click(screen.getByRole("button", { name: "Alpha" }));
+    expect(screen.getByRole("dialog").textContent).toContain("Alpha");
+    expect(document.querySelector("#n_b button")?.getAttribute("data-connected")).toBe("true");
+    expect(screen.getByRole("button", { name: "0 upstream nodes" })).toBeTruthy();
+    expect(screen.getByRole("button", { name: "1 downstream nodes" })).toBeTruthy();
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("hides contained nodes while their group is collapsed", () => {
+    const grouped: Model = { ...model, nodes: [
+      { id: "g", kind: "group", lane: "lane", col: 0, row: 0, state: "good", title: "Group", contains: ["a"] },
+      { ...model.nodes[0]!, row: 1 }, model.nodes[1]!,
+    ] };
+    render(<FlowCanvas model={grouped} renderNode={node => <span>{node.title}</span>} />);
+    expect(screen.queryByRole("button", { name: "Alpha" })).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "Expand Group" }));
+    expect(screen.getByRole("button", { name: "Alpha" })).toBeTruthy();
+  });
+
+  it("zooms the tool buttons about the viewport center, not a fixed point", () => {
+    render(<FlowCanvas model={model} renderNode={node => <span>{node.title}</span>} />);
+    measure(document.getElementById("viewport")!, 800, 400);
+    fireEvent.click(screen.getByRole("button", { name: "Zoom in" }));
+    expect(document.getElementById("world")!.style.transform).toMatch(/translate\(-80px, -40px\) scale\(1\.2\)/);
+    expect(screen.getByText("120%")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Zoom out" }));
+    expect(screen.getByText("100%")).toBeTruthy();
+  });
+});