@caddis/cli 0.4.44 → 0.4.46

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

@@ -0,0 +1,22 @@
+import { useMemo } from "react";
+import { autoLayout } from "../../src/autolayout.ts";
+import { computeGeometry } from "../../src/layout.ts";
+import type { Model } from "../../src/model.ts";
+import { defaultView, nodeVisible } from "../../src/rules.ts";
+import type { View } from "../../src/viewport.ts";
+
+// Shared default. A fresh Set() per render would change the memo identity below and recompute
+// the geometry on every render. Never mutate it.
+const EMPTY_COLLAPSED = new Set<string>();
+
+/** Layout is world-space; the returned view is applied as a transform by the canvas. */
+export function useFlowGeometry(model: Model, view: View, collapsed: Set<string> = EMPTY_COLLAPSED, mode = defaultView(model)) {
+  const laidOut = useMemo(() => model.layout === "auto" ? autoLayout(model) : model, [model]);
+  const geometry = useMemo(() => computeGeometry(laidOut, {
+    visible: id => {
+      const node = laidOut.nodes.find(item => item.id === id);
+      return !!node && nodeVisible(laidOut, mode, node, collapsed);
+    },
+  }), [laidOut, collapsed, mode]);
+  return { model: laidOut, geometry, view };
+}

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

@@ -0,0 +1,29 @@
+import { useEffect, useMemo, useState } from "react";
+import type { Model } from "../../src/model.ts";
+import { canonOf, defaultView, effectiveLinks, initialCollapsed, nodeVisible, toggleGroupState } from "../../src/rules.ts";
+import { connected, relatives } from "../../src/trace.ts";
+
+export function useTrace(model: Model, mode = defaultView(model)) {
+  const [selected, setSelected] = useState<string | null>(null);
+  const [hover, setHover] = useState<string | null>(null);
+  const [collapsed, setCollapsed] = useState<Set<string>>(() => initialCollapsed(model));
+  const nodes = useMemo(() => new Map(model.nodes.map(node => [node.id, node])), [model]);
+  const links = useMemo(() => effectiveLinks(model, mode, collapsed, nodes), [model, mode, collapsed, nodes]);
+  const visible = useMemo(() => new Set(model.nodes.filter(node => nodeVisible(model, mode, node, collapsed)).map(node => node.id)), [model, mode, collapsed]);
+  const focus = selected ?? hover;
+  const canonical = (id: string) => canonOf(nodes, id);
+  const upstream = useMemo(() => focus ? relatives(links, canonical, focus, "up") : new Set<string>(), [links, focus, nodes]);
+  const downstream = useMemo(() => focus ? relatives(links, canonical, focus, "down") : new Set<string>(), [links, focus, nodes]);
+  const connectedNodes = useMemo(() => focus ? connected(links, canonical, focus) : new Set<string>(), [links, focus, nodes]);
+  const toggleGroup = (id: string) => {
+    const next = toggleGroupState(model, mode, collapsed, id);
+    if (next) { setCollapsed(next.collapsed); setSelected(next.selected); }
+  };
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent) => { if (event.key === "Escape") setSelected(null); };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, []);
+  useEffect(() => { if (selected && !visible.has(selected)) setSelected(null); }, [visible, selected]);
+  return { selected, setSelected, hover, setHover, collapsed, toggleGroup, links, visible, connected: connectedNodes, upstream, downstream };
+}

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

@@ -0,0 +1,75 @@
+import { useCallback, useRef, useState, type KeyboardEventHandler, type PointerEventHandler } from "react";
+import { clampPan, fitRect, zoomAt, type Rect, type Size, type View } from "../../src/viewport.ts";
+
+export interface ViewportBind {
+  /** Spread onto the viewport element. The hook owns this ref: it measures the element and listens here. */
+  ref: (element: HTMLElement | null) => void;
+  onPointerDown: PointerEventHandler<HTMLElement>;
+  onPointerMove: PointerEventHandler<HTMLElement>;
+  onPointerUp: PointerEventHandler<HTMLElement>;
+  onPointerCancel: PointerEventHandler<HTMLElement>;
+  onKeyDown: KeyboardEventHandler<HTMLElement>;
+  tabIndex: number;
+}
+
+/** Canvas state and DOM bindings. Coordinates passed to zoomBy are local to the viewport. */
+export function useViewport(bounds: Rect, initial: View = { x: 0, y: 0, k: 1 }) {
+  const [view, setView] = useState<View>(initial);
+  const viewport = useRef<HTMLElement | null>(null);
+  const drag = useRef<{ x: number; y: number; view: View } | null>(null);
+  const zoomBy = useCallback((factor: number, x: number, y: number) => {
+    setView(previous => zoomAt(previous, factor, x, y));
+  }, []);
+  /** Zoom by a factor about the center of the attached viewport element. */
+  const zoomAboutCenter = useCallback((factor: number) => {
+    const element = viewport.current;
+    zoomBy(factor, (element?.clientWidth ?? 0) / 2, (element?.clientHeight ?? 0) / 2);
+  }, [zoomBy]);
+  const fit = useCallback((size?: Size) => {
+    const measured = size ?? { w: viewport.current?.clientWidth ?? 0, h: viewport.current?.clientHeight ?? 0 };
+    setView(fitRect(bounds, measured, 24, 44));
+  }, [bounds]);
+  // React's synthetic onWheel listener is passive, so its preventDefault cannot stop the page
+  // scrolling. Wheel zoom must be a native listener with { passive: false } on the viewport element.
+  const onWheelZoom = useCallback((event: WheelEvent) => {
+    event.preventDefault();
+    const element = event.currentTarget as HTMLElement | null;
+    if (!element) return;
+    const rect = element.getBoundingClientRect();
+    zoomBy(Math.exp(-event.deltaY * 0.001), event.clientX - rect.left, event.clientY - rect.top);
+  }, [zoomBy]);
+  // The element ref is also what makes fit() work before the first pointer or wheel interaction.
+  const setViewportElement = useCallback((element: HTMLElement | null) => {
+    if (viewport.current === element) return;
+    viewport.current?.removeEventListener("wheel", onWheelZoom);
+    viewport.current = element;
+    element?.addEventListener("wheel", onWheelZoom, { passive: false });
+  }, [onWheelZoom]);
+  const stop: PointerEventHandler<HTMLElement> = event => {
+    if (drag.current) event.currentTarget.releasePointerCapture?.(event.pointerId);
+    drag.current = null;
+  };
+  const bind: ViewportBind = {
+    tabIndex: 0,
+    ref: setViewportElement,
+    onPointerDown: event => {
+      if (event.button !== 0 || (event.target as Element).closest("button,a,input")) return;
+      drag.current = { x: event.clientX, y: event.clientY, view };
+      event.currentTarget.setPointerCapture?.(event.pointerId);
+    },
+    onPointerMove: event => {
+      if (!drag.current) return;
+      const { x, y, view: start } = drag.current;
+      const size = { w: event.currentTarget.clientWidth, h: event.currentTarget.clientHeight };
+      setView(clampPan({ ...start, x: start.x + event.clientX - x, y: start.y + event.clientY - y }, bounds, size));
+    },
+    onPointerUp: stop,
+    onPointerCancel: stop,
+    onKeyDown: event => {
+      if (event.key === "+" || event.key === "=") { event.preventDefault(); zoomAboutCenter(1.2); }
+      if (event.key === "-") { event.preventDefault(); zoomAboutCenter(1 / 1.2); }
+      if (event.key === "0") { event.preventDefault(); fit(); }
+    },
+  };
+  return { view, bind, fit, zoomBy, zoomAboutCenter, setView };
+}

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

@@ -0,0 +1,13 @@
+import type { Model } from "../src/model.ts";
+
+export function FlowLoading() {
+  return <p role="status">Loading flow…</p>;
+}
+
+export function FlowEmpty({ model }: { model: Model }) {
+  return model.nodes.length === 0 ? <p role="status">No flow items to show.</p> : null;
+}
+
+export function FlowError({ message, onRetry }: { message: string; onRetry?: () => void }) {
+  return <div role="alert"><p>{message}</p>{onRetry && <button type="button" onClick={onRetry}>Retry</button>}</div>;
+}

package/bundles/antigravity-plugin/skills/flow-studio/references/design-language.md

@@ -0,0 +1,169 @@
+# Design language
+
+Grounded in `src/styles.css`. This document defines the visual design system, CSS custom properties, typography, spatial scales, state encodings, motion catalogue, and dark theme strategy for flow-studio.
+
+## 1. Design tokens
+
+Tokens are defined on `:root` and adapted for dark mode via `@media (prefers-color-scheme: dark)` and `:root[data-theme="dark"]`.
+
+| Token | Light value | Dark value | Description / Purpose |
+|---|---|---|---|
+| `--bg` | `#f6f8fa` | `#0d1117` | Canvas and page background |
+| `--panel` | `#ffffff` | `#161b22` | Cards, drawer, top header, surfaces |
+| `--panel2` | `#f6f8fa` | `#0d1117` | Secondary surface, subtle contrast, table header |
+| `--fg` | `#1f2328` | `#e6edf3` | Primary text and foreground elements |
+| `--muted` | `#59636e` | `#9198a1` | Secondary text, captions, inactive icons |
+| `--edge` | `#d0d7de` | `#30363d` | Element borders, tool dividers, card outlines |
+| `--rule` | `#d8dee4` | `#2b323a` | Dividers, grid separators, table borders |
+| `--accent` | `#0969da` | `#4493f8` | Primary brand accent, selected state, hot trails |
+| `--accent-solid` | `#0969da` | `#1f6feb` | Solid button background, active tab pill |
+| `--ok` | `#1a7f37` | `#3fb950` | Healthy, passed, on-time indicators |
+| `--warn` | `#9a6700` | `#d29922` | Warning, degraded, late indicators |
+| `--crit` | `#cf222e` | `#f85149` | Critical failure, breach, error indicators |
+| `--up` | `#0a7ea4` | `#6fcbe6` | Upstream relation count and badge color |
+| `--down` | `#8250df` | `#d0a0ee` | Downstream relation count and notes marker |
+| `--glow` | `rgba(9,105,218,.22)` | `rgba(68,147,248,.35)` | Accent halo for selection, hover, and canvas focus |
+| `--shadow` | `0 1px 0 rgba(31,35,40,.04), 0 6px 18px rgba(31,35,40,.08)` | `0 1px 0 rgba(0,0,0,.4), 0 8px 24px rgba(0,0,0,.45)` | Elevated card and modal elevation shadow |
+| `--grid` | `rgba(31,35,40,.035)` | `rgba(255,255,255,.04)` | Viewport grid pattern dots and lines |
+| `--ok-bg` | `rgba(26,127,55,.10)` | `rgba(63,185,80,.12)` | Subtle tinted background for healthy states |
+| `--warn-bg` | `rgba(154,103,0,.10)` | `rgba(210,153,34,.14)` | Subtle tinted background for warning states |
+| `--crit-bg` | `rgba(207,34,46,.08)` | `rgba(248,81,73,.12)` | Subtle tinted background for critical states |
+| `--info-bg` | `rgba(9,105,218,.10)` | `rgba(68,147,248,.14)` | Subtle tinted background for informational badges |
+| `--mono` | `"IBM Plex Mono", ui-monospace, ...` | Same | Monospace font family for metrics, counters, and code |
+
+---
+
+## 2. Typography scale
+
+Flow-studio uses system sans-serif (`Inter, "Segoe UI", system-ui, -apple-system, sans-serif`) for readable text and `--mono` for tabular numerals and technical metadata.
+
+| Role | Size | Weight | Line height | Letter spacing | Font family |
+|---|---|---|---|---|---|
+| Page title (`h1`) | 20px | 700 | 1.2 | normal | Sans-serif |
+| KPI / Tile numbers (`.tn`, `.cn`) | 20px | 600 | 1.1 | tabular-nums | Sans-serif |
+| Inspector node title (`.nname`) | 15px | 600 | 1.25 | normal | Sans-serif |
+| Drawer heading (`#drawer h2`) | 15px | 700 | 1.3 | normal | Sans-serif |
+| Body / Default | 14px | 400 | 1.45 | normal | Sans-serif |
+| Card title (`.node .t`) | 13px | 600 | 1.25 | normal | Sans-serif |
+| Lane label (`.bandlabel b`) | 13px | 700 | 1.2 | normal | Sans-serif |
+| Card subtitle / state (`.node .s`) | 12px | 400 | 1.3 | normal | Sans-serif |
+| Help text / Footer | 12px | 400 | 1.4 | normal | Sans-serif |
+| Column header (`#cols .hd`) | 10.5px | 700 | 1.2 | 0.08em (caps) | Sans-serif |
+| Phase pill (`#cols .ph`) | 10px | 700 | 1.2 | 0.14em (caps) | Sans-serif |
+| Evidence / Badges (`.ev`, `.pill`) | 9.5px to 10.5px | 700 | 1.2 | 0.03em (caps) | Sans-serif |
+| Metric badges & code (`.mono`, `code`) | 11px to 11.5px | 500 | 1.2 | normal | Monospace |
+
+---
+
+## 3. Spacing scale
+
+Layout elements follow a strict 4px grid rhythm:
+
+| Scale | Value | Typical usage |
+|---|---|---|
+| 2xs | 2px to 4px | Inline icon gaps, badge vertical padding, bottom border highlights |
+| xs | 4px to 7px | Button vertical padding (`4px 11px`), card vertical padding (`5px 10px 7px`), playbar gaps (`7px`) |
+| sm | 8px to 10px | Card horizontal padding (`10px`), toolbar item gaps, summary grid gaps |
+| md | 12px to 16px | Page padding (`12px 14px 20px`), header gaps, inspector body padding |
+| lg | 20px to 28px | Section margins, top header padding, grid line pitch (28px canvas grid) |
+| xl | 32px to 44px | Column header heights (44px), tool button dimensions (34px x 32px) |
+
+---
+
+## 4. Border radius and shadow tiers
+
+### Border radius
+- **Sharp (0px):** Segmented buttons inside groups, summary tiles inside strips, tools.
+- **Small (6px):** Buttons, search inputs, dropdowns, segmented group wrappers.
+- **Medium (8px):** Node cards (`.node`).
+- **Pill (9px to 10px):** Edge labels (`.elabel`), lane bands (`.band` radius 10px).
+- **Large (12px):** Workspace container (`.workspace`).
+- **Circular (50%):** Markers, status dots, tokens, and avatar chips.
+
+### Shadow tiers
+- **Subtle border shadow (`var(--shadow)`):** `0 1px 0 rgba(31,35,40,.04), 0 6px 18px rgba(31,35,40,.08)` (Light) / `0 1px 0 rgba(0,0,0,.4), 0 8px 24px rgba(0,0,0,.45)` (Dark).
+- **Interactive hover:** `box-shadow: 0 0 0 3px var(--glow), var(--shadow)`.
+- **Slide-in drawer elevation:** `box-shadow: -14px 0 34px rgba(0,0,0,.16), -1px 0 0 var(--glow)`.
+- **Marker pulse halo:** `box-shadow: 0 0 0 3px rgba(130,80,223,.3)`.
+
+---
+
+## 5. Glow tiers
+
+Glows communicate focus, connection, and selection:
+1. **Normal:** `box-shadow: 0 0 14px -4px color-mix(in srgb, <tone> 55%, transparent)` on healthy or highlighted cards.
+2. **Hover:** `box-shadow: 0 0 0 3px var(--glow)` with border color change to `--accent`.
+3. **Selected / Lit:** `box-shadow: 0 0 0 2px var(--glow), 0 0 18px var(--glow)` plus animated ripple or trail.
+
+---
+
+## 6. State encoding table
+
+The engine generates CSS from 12 canonical domain states defined in `src/stateCss.ts`:
+
+| State ID | Tone | Border Style | Edge Style | Motion | Bucket | Semantic Meaning |
+|---|---|---|---|---|---|---|
+| `ok` | `ok` | `solid` | `flow` | `flow` | `good` | Fully healthy, active, operational |
+| `healthy` | `ok` | `solid` | `flow` | `flow` | `good` | System running within normal operating SLAs |
+| `planned` | `muted` | `dashed` | `dash` | `flow-slow` | `neutral` | Future work or planned integration |
+| `in-progress` | `accent` | `solid` | `flow` | `flow` | `neutral` | Actively processing or undergoing update |
+| `waiting` | `warn` | `dashed` | `dash-short` | `breathe` | `neutral` | Blocked on upstream dependency or approval |
+| `late` | `warn` | `solid` | `flow` | `flow` | `neutral` | Running behind schedule but executing |
+| `degraded` | `warn` | `dashed` | `dash` | `breathe` | `neutral` | Performance or capacity reduced |
+| `failed` | `crit` | `solid` | `flow` | `flow` | `gap` | Execution halted due to fatal defect |
+| `breached` | `crit` | `solid` | `flow` | `flow` | `gap` | SLA threshold crossed |
+| `blocked` | `crit` | `dashed` | `dot` | `none` | `gap` | Cannot proceed due to hard impediment |
+| `unknown` | `warn` | `dotted` | `dot` | `breathe` | `gap` | No telemetry or unverified source |
+| `skipped` | `muted` | `dotted` | `dot` | `none` | `neutral` | Deliberately omitted execution step |
+
+---
+
+## 7. Motion catalogue
+
+`src/styles.css` defines 12 `@keyframes`; the count treats the three flow dash variants (`flow`, `flowd`, `flowc`) separately. Motion is never decorative; every animation carries status information.
+
+| Animation name | Duration | Easing | Meaning / State Carried |
+|---|---|---|---|
+| `beat` | 2.6s | ease (default), infinite | Live indicator pulse on the header brand dot. Indicates the engine session is active. |
+| `fadein` | 0.6s / 1s (0.5s delay) | ease (default) | Lane bands and the edge layer fade in during initial canvas load. |
+| `rise` | 0.5s / 0.55s / 1.2s | ease (default) / ease-out | Cards, tiles and summary cells enter with subtle upward movement (`translateY(8px)` to `none`); `1.2s` marks a node added by a live update. |
+| `flow` | 3s or 7s | linear infinite | Dash-offset marching on links whose state has `edge: "flow"` (`3s` with `motion: "flow"`, `7s` with `motion: "flow-slow"`). Indicates active data transit. |
+| `flowd` | 3s or 7s | linear infinite | Same marching for `edge: "dash"` links. |
+| `flowc` | 3s or 7s | linear infinite | Same marching for `edge: "dash-short"` links. |
+| `flowhot` | 0.9s | linear infinite | Faster marching on highlighted (hot) edges: search trails, relations, playback. |
+| `selpulse` | 2.4s / 1.8s | ease-out infinite | Expanding glowing ring around a selected card (`2.4s`) or the active playback node (`1.8s`). |
+| `breathe` | 3.2s | ease-in-out infinite | Soft pulsing box-shadow on warning or waiting nodes (`color-mix` with `--warn` or the state tone). |
+| `failflash` | 0.9s | ease-out 1 | Red box-shadow burst indicating SLA breach or what-if blast-radius failure. |
+| `newring` | 1.2s / 1.8s | ease-out 1 | Accent ring on a node changed by a live update (`1.2s`) or newly appeared in a view (`1.8s`). |
+| `ring` | - | - | Defined but referenced by no rule today; reserved. |
+
+---
+
+## 8. Reduced motion fallback rules
+
+Accessibility rules respect user OS preferences:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation: none !important;
+    transition: none !important;
+  }
+  path.edge.hot {
+    stroke-dasharray: none;
+  }
+}
+```
+
+- When reduced motion is active, token animations are immediate without transitions.
+- Selection rings remain solid outlines without pulsating box-shadows.
+- Links show solid or static dashed strokes without moving dashes.
+
+---
+
+## 9. Dark theme strategy
+
+1. The page listens to system preference: `@media (prefers-color-scheme: dark)` applies dark tokens to `:root:not([data-theme="light"])`.
+2. Manual override is supported via the `data-theme="dark"` attribute set on `<html>` or `:root`.
+3. The theme toggle button switches between light and dark without page reload.
+4. Colors do not invert naively; backgrounds use `#0d1117`, card panels use `#161b22`, borders use `#30363d`, and semantic colors (ok, warn, crit) use high-contrast luminance tuned for dark backgrounds.

package/bundles/antigravity-plugin/skills/flow-studio/references/implement-in-app.md

@@ -0,0 +1,213 @@
+# Implement a flow in an application
+
+Use an approved flow model as input. Validate it against `model.schema.json` before connecting live data. The demo page shows the intended interaction. Keep this guide with the skill when copying files into an application.
+
+In the commands, `<skill>` is the path to the flow-studio skill folder in your checkout. Your app has no copy of the skill's scripts, so commands that run them always name the `<skill>` path.
+
+## 1. Pick the route
+
+| Requirement | Route | Implementation |
+|---|---|---|
+| The app may use the flow engine's own styling and controls | Fast wrapper / library embed | `templates/flow-studio.lib.mjs` provides the full self-contained engine. |
+| The app must use its own design tokens, buttons, and drawer | Native components & hooks | Pure modules (`src/`) supply geometry, layout, and trace logic to app components. |
+
+The files are copyable source, not a published npm package. Both routes need a caller that supplies a valid `Model`; neither fetches app data for you.
+
+---
+
+## 2. Lock the model and data contract
+
+1. Save the approved model as JSON. Run `node --experimental-strip-types <skill>/scripts/validate.mjs <model.json>`. Fix any reported errors.
+2. Define a typed state for the app's data source: `loading`, `ready` with a `Model`, `empty`, or `error` with a user-facing message and retry action.
+3. Map node IDs from immutable business keys (e.g. `order-service-uuid`). Map link IDs from immutable relation keys. Never use array indices or volatile titles.
+4. Keep absent values absent. Do not turn a missing measurement into `0`. Use state words and timestamps (`asOf`) to distinguish measured data from declarations.
+5. On refresh error, keep the last valid model visible and show a notification banner. On a valid refresh, pass the new model with stable IDs so `engine.update(model)` preserves pan, zoom, and active selection.
+6. Render all model strings as plain text. Never use raw `innerHTML` for titles, subtitles, or labels.
+
+---
+
+## 3. Test-first workflow in the target app
+
+1. **Verify skill tests:** Run the test suite:
+   ```bash
+   node --experimental-strip-types --no-warnings --test "src/*.test.ts" "scripts/lib/*.test.mjs"
+   ```
+2. **Author mapping test:** Write an app test verifying the data-to-model mapper produces stable IDs, preserves absent fields, and handles loading/error states. See the test fail before implementing the mapper.
+3. **Author component test:** Write a test verifying component mount, node selection callback, and update behavior.
+4. **Implement iteratively:** Implement mapping and component wiring, re-running the focused test after each step until green.
+
+---
+
+## 4. Integration guides by framework
+
+### A. React
+
+Copy `templates/flow-studio.lib.mjs`, `templates/flow-studio.lib.d.mts`, `templates/flow-studio.css`, `react/`, and `src/` into the app, keeping the relative layout.
+
+```tsx
+import React, { useEffect, useRef } from "react";
+import { FlowStudioView, FlowLoading, FlowError } from "./react/index";
+import type { Model } from "./src/model";
+import "./templates/flow-studio.css";
+
+export function FlowContainer({ model, status, error, onRetry }: { model?: Model; status: string; error?: string; onRetry: () => void }) {
+  const [selectedId, setSelectedId] = React.useState<string | null>(null);
+
+  if (status === "loading") return <FlowLoading />;
+  if (status === "error") return <FlowError message={error!} onRetry={onRetry} />;
+  if (!model || model.nodes.length === 0) return <div>No data available</div>;
+
+  return (
+    <div style={{ height: "80vh", width: "100%" }}>
+      <FlowStudioView
+        model={model}
+        onSelect={(id) => setSelectedId(id)}
+      />
+    </div>
+  );
+}
+```
+
+### B. Vue (Vue 3 / Vite)
+
+Copy `templates/flow-studio.lib.mjs`, `templates/flow-studio.lib.d.mts`, and `templates/flow-studio.css` to your application assets directory.
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted, onBeforeUnmount, watch } from "vue";
+import { mount } from "../assets/flow-studio.lib.mjs";
+import "../assets/flow-studio.css";
+
+const props = defineProps<{ model: any }>();
+const emit = defineEmits(["select"]);
+const containerRef = ref<HTMLDivElement | null>(null);
+let engineInstance: any = null;
+
+onMounted(() => {
+  if (containerRef.value && props.model) {
+    engineInstance = mount(containerRef.value, props.model, {
+      onSelect: (id: string | null) => emit("select", id)
+    });
+  }
+});
+
+watch(() => props.model, (newModel) => {
+  if (engineInstance && newModel) {
+    engineInstance.update(newModel);
+  }
+});
+
+onBeforeUnmount(() => {
+  if (engineInstance) {
+    engineInstance.destroy();
+    engineInstance = null;
+  }
+});
+</script>
+
+<template>
+  <div ref="containerRef" class="flow-container"></div>
+</template>
+
+<style scoped>
+.flow-container { width: 100%; height: 80vh; position: relative; }
+</style>
+```
+
+### C. Svelte (Svelte 4 / 5)
+
+Copy the same library files as for Vue. The import is aliased because Svelte 5 exports its own `mount`.
+
+```svelte
+<script lang="ts">
+  import { onMount, onDestroy } from "svelte";
+  import { mount as mountFlow } from "./flow-studio.lib.mjs";
+  import "./flow-studio.css";
+
+  export let model: any;
+  export let onSelect: (id: string | null) => void = () => {};
+
+  let container: HTMLDivElement;
+  let engine: any;
+
+  onMount(() => {
+    engine = mountFlow(container, model, { onSelect });
+  });
+
+  $: if (engine && model) {
+    engine.update(model);
+  }
+
+  onDestroy(() => {
+    if (engine) engine.destroy();
+  });
+</script>
+
+<div bind:this={container} class="flow-container"></div>
+
+<style>
+  .flow-container { width: 100%; height: 80vh; position: relative; }
+</style>
+```
+
+### D. Vanilla HTML & JavaScript
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <link rel="stylesheet" href="./templates/flow-studio.css">
+  <style>
+    #flowHost { width: 100vw; height: 100vh; }
+  </style>
+</head>
+<body>
+  <div id="flowHost"></div>
+  <script type="module">
+    import { mount } from "./templates/flow-studio.lib.mjs";
+
+    const response = await fetch("/api/lineage-model");
+    const model = await response.json();
+
+    const engine = mount(document.getElementById("flowHost"), model, {
+      onSelect: (selectedId) => {
+        console.log("Selected node:", selectedId);
+      }
+    });
+
+    // Expose for external live event updates
+    window.updateFlow = (newModel) => engine.update(newModel);
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 5. State synchronization and host events
+
+`mount()` returns the engine API, and every mount also publishes the same API object on `window.FlowStudio`. Hold the value that `mount()` returns in a variable named `engine` in the examples below:
+
+1. **Selection listening:** pass `onSelect(nodeId: string | null)` as a mount option to receive updates when a user selects a card or chip, or clears the selection.
+2. **Programmatic selection:** call `engine.select(nodeId)` (or `window.FlowStudio.select(nodeId)`) to focus and inspect a node from outside the canvas, for example from an app table row.
+3. **Reading active state:** call `engine.selected()`, `engine.view()`, or `engine.mode()` to read the current canvas state.
+4. **Live topology updates:** call `engine.update(newModel)` to refresh node metrics, statuses, or structure without losing the user's pan and zoom. A model that fails validation is rejected, the last good graph stays, and the engine shows a banner.
+
+In the React wrapper route the engine instance is private to `FlowStudioView`: use the `onSelect` prop for selection changes and drive new data through the `model` prop (the wrapper calls `update` itself). Use `window.FlowStudio` for a direct call only while exactly one view is mounted.
+
+---
+
+## 6. Verifying the app in browser check harness
+
+Run the skill's check harness against your local dev server:
+
+```bash
+node <skill>/scripts/check.mjs http://127.0.0.1:5173/flow --out shots --channel msedge --skip hostile
+```
+
+The harness is not copied into your app, so the command always names the `<skill>` path. Run it from a folder whose `node_modules` resolves `playwright`.
+
+- When tests fail, inspect the screenshot in `shots/` and read the error detail.
+- Ensure the app container provides at least 540px height for desktop viewports.
+- `--skip` takes a comma-separated list of groups (`notes`, `playback`, `update`, `hostile`). Skip a group only when the app intentionally omits that feature. Record every skipped group in your verification notes. Never treat a skipped check as a pass.