@caddis/cli 0.4.45 → 0.4.47

package/bundles/codex/.codex/skills/frontend/flow-studio/examples/state-machine.json

@@ -0,0 +1,106 @@
+{
+  "version": 1,
+  "meta": {
+    "title": "ORDER STATE MACHINE",
+    "help": "Track lifecycle transitions of an order across active processing, cancellation, fulfillment, and returns.",
+    "asOf": "2026-10-06",
+    "source": "Fictional Contoso Retail state machine. No real customer or order records are used."
+  },
+  "layout": "auto",
+  "columns": [
+    { "id": "creation", "title": "Creation", "width": 140 },
+    { "id": "payment", "title": "Payment", "width": 150 },
+    { "id": "fulfillment", "title": "Fulfillment", "width": 160 },
+    { "id": "delivery", "title": "Delivery", "width": 150 },
+    { "id": "post_sale", "title": "Post-Sale", "width": 150 }
+  ],
+  "lanes": [
+    { "id": "order", "title": "Order Lifecycle" },
+    { "id": "logistics", "title": "Fulfillment & Logistics" },
+    { "id": "service", "title": "Returns & Service" }
+  ],
+  "states": {
+    "active": { "word": "ACTIVE", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "terminal": { "word": "TERMINAL", "tone": "muted", "border": "solid", "edge": "dash-short", "motion": "none", "bucket": "good" },
+    "error": { "word": "ERROR", "tone": "crit", "border": "dotted", "edge": "dot", "motion": "breathe", "bucket": "gap" }
+  },
+  "nodes": [
+    { "id": "st_draft", "kind": "start", "lane": "order", "state": "active", "title": "Draft", "subtitle": "Cart checkout" },
+    { "id": "st_submitted", "kind": "card", "lane": "order", "state": "active", "title": "Submitted", "subtitle": "Awaiting payment" },
+    { "id": "gate_paid", "kind": "gateway", "lane": "order", "state": "active", "title": "Paid?", "subtitle": "Payment verification" },
+    { "id": "st_paid", "kind": "card", "lane": "order", "state": "active", "title": "Paid", "subtitle": "Payment settled" },
+    { "id": "st_packed", "kind": "card", "lane": "logistics", "state": "active", "title": "Packed", "subtitle": "Warehouse parcel" },
+    { "id": "st_shipped", "kind": "card", "lane": "logistics", "state": "active", "title": "Shipped", "subtitle": "In transit" },
+    { "id": "st_delivered", "kind": "card", "lane": "logistics", "state": "terminal", "title": "Delivered", "subtitle": "Handed to customer" },
+    { "id": "st_cancelled", "kind": "card", "lane": "order", "state": "error", "title": "Cancelled", "subtitle": "Order voided" },
+    { "id": "st_ret_req", "kind": "card", "lane": "service", "state": "active", "title": "Return requested", "subtitle": "RMA initiated" },
+    { "id": "st_returned", "kind": "card", "lane": "service", "state": "active", "title": "Returned", "subtitle": "Parcel received" },
+    { "id": "st_refunded", "kind": "card", "lane": "service", "state": "terminal", "title": "Refunded", "subtitle": "Funds credited", "sla": 30 },
+    { "id": "st_pay_fail", "kind": "end", "lane": "order", "state": "error", "title": "Payment failed", "subtitle": "Authorization error" },
+    { "id": "st_archived", "kind": "end", "lane": "logistics", "state": "terminal", "title": "Archived", "subtitle": "Order complete" }
+  ],
+  "links": [
+    { "id": "l_draft_sub", "from": "st_draft", "to": "st_submitted", "state": "active" },
+    { "id": "l_sub_gate", "from": "st_submitted", "to": "gate_paid", "state": "active" },
+    { "id": "l_gate_paid", "from": "gate_paid", "to": "st_paid", "state": "active", "label": "Authorized" },
+    { "id": "l_gate_fail", "from": "gate_paid", "to": "st_pay_fail", "state": "error", "label": "Declined" },
+    { "id": "l_paid_pack", "from": "st_paid", "to": "st_packed", "state": "active" },
+    { "id": "l_paid_canc", "from": "st_paid", "to": "st_cancelled", "state": "error", "label": "Customer cancel" },
+    { "id": "l_pack_ship", "from": "st_packed", "to": "st_shipped", "state": "active" },
+    { "id": "l_ship_deliv", "from": "st_shipped", "to": "st_delivered", "state": "active" },
+    { "id": "l_deliv_arch", "from": "st_delivered", "to": "st_archived", "state": "terminal" },
+    { "id": "l_deliv_ret", "from": "st_delivered", "to": "st_ret_req", "state": "active", "label": "Request return" },
+    { "id": "l_ret_deliv", "from": "st_ret_req", "to": "st_delivered", "state": "active", "kind": "loop-back", "label": "Return rejected" },
+    { "id": "l_ret_done", "from": "st_ret_req", "to": "st_returned", "state": "active", "label": "Return accepted" },
+    { "id": "l_ret_refund", "from": "st_returned", "to": "st_refunded", "state": "terminal" },
+    { "id": "l_canc_draft", "from": "st_cancelled", "to": "st_draft", "state": "active", "kind": "loop-back", "label": "Draft after cancel" },
+    { "id": "l_canc_ref", "from": "st_cancelled", "to": "st_refunded", "state": "terminal", "label": "Refund balance" }
+  ],
+  "inspector": {
+    "relations": [
+      { "id": "prior", "label": "Previous state", "dir": "up" },
+      { "id": "down", "label": "Next transition", "dir": "down" },
+      { "id": "terminal", "label": "Settled state", "dir": "down", "filter": { "kind": "end" } }
+    ],
+    "actions": [
+      {
+        "id": "sim_cancel",
+        "label": "Simulate: cancel order",
+        "dir": "down",
+        "staleText": "Order cancelled by customer. Refund process initiated."
+      }
+    ]
+  },
+  "notes": [
+    { "anchor": "#viewport", "title": "State transition model", "text": "This diagram defines legal state transitions from draft creation through post-sale settlement." },
+    { "anchor": "#n_gate_paid", "title": "Payment gateway", "text": "Orders branch to fulfillment on successful payment or terminate if payment authorization fails." },
+    { "anchor": "#n_st_ret_req", "title": "Return request evaluation", "text": "Return requests branch either to return acceptance and refund or route back to delivered status if rejected." },
+    { "anchor": "#playbar", "title": "Playback controls", "text": "Step through normal fulfillment or cancellation workflows to inspect transitions and SLA timing." }
+  ],
+  "scenarios": [
+    {
+      "id": "normal_order",
+      "label": "Normal order",
+      "steps": [
+        { "link": "l_draft_sub", "at": 0, "caption": "Customer submits order draft" },
+        { "link": "l_sub_gate", "at": 10, "caption": "Payment authorization requested" },
+        { "link": "l_gate_paid", "at": 20, "caption": "Payment confirmed successfully" },
+        { "link": "l_paid_pack", "at": 35, "caption": "Warehouse packs parcel" },
+        { "link": "l_pack_ship", "at": 50, "caption": "Courier picks up shipment" },
+        { "link": "l_ship_deliv", "at": 70, "caption": "Package delivered to customer" },
+        { "link": "l_deliv_arch", "at": 85, "caption": "Order archived after return period expires" }
+      ]
+    },
+    {
+      "id": "cancel_paid",
+      "label": "Cancel after payment",
+      "steps": [
+        { "link": "l_draft_sub", "at": 0, "caption": "Customer drafts order" },
+        { "link": "l_sub_gate", "at": 10, "caption": "Payment gateway contacted" },
+        { "link": "l_gate_paid", "at": 20, "caption": "Order paid" },
+        { "link": "l_paid_canc", "at": 30, "caption": "Customer cancels order before shipping" },
+        { "link": "l_canc_ref", "at": 45, "caption": "Refund issued after SLA target threshold" }
+      ]
+    }
+  ]
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/examples/ticket-lifecycle.json

@@ -0,0 +1,107 @@
+{
+  "version": 1,
+  "meta": {
+    "title": "SUPPORT TICKET LIFECYCLE",
+    "help": "Track support tickets from submission to resolution across four operational tiers. Follow escalation paths and identify SLA breach risks.",
+    "asOf": "2026-10-06",
+    "source": "Fictional Contoso Retail support desk data. No real customer or ticket records are used."
+  },
+  "layout": "columns-lanes",
+  "columns": [
+    { "id": "new", "title": "New", "width": 150 },
+    { "id": "triage", "title": "Triage", "width": 150 },
+    { "id": "progress", "title": "In progress", "width": 160 },
+    { "id": "waiting", "title": "Waiting", "width": 150 },
+    { "id": "resolved", "title": "Resolved", "width": 160 },
+    { "id": "closed", "title": "Closed", "width": 150 }
+  ],
+  "lanes": [
+    { "id": "customer", "title": "Customer" },
+    { "id": "l1", "title": "Support L1" },
+    { "id": "l2", "title": "Support L2" },
+    { "id": "billing", "title": "Billing team" }
+  ],
+  "states": {
+    "on_time": { "word": "ON TIME", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" },
+    "at_risk": { "word": "AT RISK", "tone": "warn", "border": "dashed", "edge": "dash", "motion": "flow-slow", "bucket": "neutral" },
+    "breached": { "word": "BREACHED", "tone": "crit", "border": "dotted", "edge": "dot", "motion": "breathe", "bucket": "gap" },
+    "closed": { "word": "CLOSED", "tone": "muted", "border": "solid", "edge": "dash-short", "motion": "none", "bucket": "good" }
+  },
+  "nodes": [
+    { "id": "cust-submit", "kind": "start", "lane": "customer", "col": 0, "row": 0, "state": "on_time", "title": "Submit ticket" },
+    { "id": "cust-notify", "kind": "event", "lane": "customer", "col": 1, "row": 0, "state": "on_time", "title": "Receipt notice" },
+    { "id": "cust-confirm", "kind": "end", "lane": "customer", "col": 5, "row": 0, "state": "closed", "title": "Confirm resolution" },
+    { "id": "l1-triage", "kind": "gateway", "lane": "l1", "col": 1, "row": 2, "state": "on_time", "title": "Triage issue" },
+    { "id": "l1-work", "kind": "card", "lane": "l1", "col": 2, "row": 2, "state": "on_time", "title": "Apply standard fix", "metrics": { "label": "Active tickets", "value": 9, "max": 15, "unit": "tickets", "series": [4, 6, 7, 9, 8, 9] } },
+    { "id": "l1-wait", "kind": "card", "lane": "l1", "col": 3, "row": 2, "state": "at_risk", "title": "Await customer", "sla": 120, "metrics": { "label": "Hold queue", "value": 5, "max": 10, "unit": "tickets" } },
+    { "id": "l1-resolve", "kind": "card", "lane": "l1", "col": 4, "row": 2, "state": "on_time", "title": "Resolve ticket", "sla": 120, "metrics": { "label": "Resolved today", "value": 24, "unit": "tickets" } },
+    { "id": "l2-investigate", "kind": "card", "lane": "l2", "col": 2, "row": 5, "state": "on_time", "title": "Diagnose fault", "metrics": { "label": "Deep analysis", "value": 4, "max": 8, "unit": "tickets" } },
+    { "id": "l2-qa", "kind": "card", "lane": "l2", "col": 3, "row": 5, "state": "on_time", "title": "Verify fix" },
+    { "id": "l2-resolve", "kind": "card", "lane": "l2", "col": 4, "row": 5, "state": "on_time", "title": "Deploy code fix" },
+    { "id": "bill-review", "kind": "card", "lane": "billing", "col": 2, "row": 8, "state": "on_time", "title": "Review charges" },
+    { "id": "bill-audit", "kind": "card", "lane": "billing", "col": 3, "row": 8, "state": "on_time", "title": "Audit credit" },
+    { "id": "bill-adjust", "kind": "card", "lane": "billing", "col": 4, "row": 8, "state": "on_time", "title": "Issue refund" },
+    { "id": "ticket-close", "kind": "end", "lane": "billing", "col": 5, "row": 8, "state": "closed", "title": "Archive file" }
+  ],
+  "links": [
+    { "id": "l-submit-triage", "from": "cust-submit", "to": "l1-triage", "state": "on_time" },
+    { "id": "l-submit-notify", "from": "cust-submit", "to": "cust-notify", "state": "on_time" },
+    { "id": "l-triage-work", "from": "l1-triage", "to": "l1-work", "state": "on_time", "label": "Tier 1 issue" },
+    { "id": "l-triage-l2", "from": "l1-triage", "to": "l2-investigate", "state": "on_time", "label": "Escalate L2" },
+    { "id": "l-triage-bill", "from": "l1-triage", "to": "bill-review", "state": "on_time", "label": "Billing issue" },
+    { "id": "l-work-wait", "from": "l1-work", "to": "l1-wait", "state": "at_risk", "label": "Request details" },
+    { "id": "l-work-resolve", "from": "l1-work", "to": "l1-resolve", "state": "on_time", "label": "Fix ready" },
+    { "id": "l-wait-resolve", "from": "l1-wait", "to": "l1-resolve", "state": "on_time", "label": "Details given" },
+    { "id": "l-l2-qa", "from": "l2-investigate", "to": "l2-qa", "state": "on_time" },
+    { "id": "l-l2-back", "from": "l2-investigate", "to": "l1-triage", "state": "at_risk", "kind": "loop-back", "label": "Back to triage" },
+    { "id": "l-qa-resolve", "from": "l2-qa", "to": "l2-resolve", "state": "on_time" },
+    { "id": "l-bill-audit", "from": "bill-review", "to": "bill-audit", "state": "on_time" },
+    { "id": "l-audit-adjust", "from": "bill-audit", "to": "bill-adjust", "state": "on_time" },
+    { "id": "l-resolve-confirm", "from": "l1-resolve", "to": "cust-confirm", "state": "on_time" },
+    { "id": "l-l2resolve-confirm", "from": "l2-resolve", "to": "cust-confirm", "state": "on_time" },
+    { "id": "l-adjust-close", "from": "bill-adjust", "to": "ticket-close", "state": "on_time" },
+    { "id": "l-reopen", "from": "cust-confirm", "to": "l1-work", "state": "at_risk", "kind": "loop-back", "label": "Reopened" }
+  ],
+  "scenarios": [
+    {
+      "id": "happy",
+      "label": "Happy path",
+      "steps": [
+        { "link": "l-submit-triage", "at": 0, "caption": "Ticket submitted by customer" },
+        { "link": "l-triage-work", "at": 15, "caption": "Triaged as standard Tier 1 fix" },
+        { "link": "l-work-resolve", "at": 45, "caption": "Standard solution applied" },
+        { "link": "l-resolve-confirm", "at": 65, "caption": "Solution submitted for customer review" }
+      ]
+    },
+    {
+      "id": "escalated",
+      "label": "Escalated",
+      "steps": [
+        { "link": "l-submit-triage", "at": 0, "caption": "Customer submits urgent ticket" },
+        { "link": "l-triage-work", "at": 15, "caption": "Initial triage begins in Tier 1" },
+        { "link": "l-work-wait", "at": 40, "caption": "Additional system logs requested" },
+        { "link": "l-wait-resolve", "at": 150, "caption": "Customer responds after SLA threshold" },
+        { "link": "l-resolve-confirm", "at": 170, "caption": "Resolution sent to customer" },
+        { "link": "l-reopen", "at": 190, "caption": "Customer reports recurrence" },
+        { "link": "l-work-resolve", "at": 215, "caption": "Secondary remediation verified" },
+        { "link": "l-resolve-confirm", "at": 235, "caption": "Updated fix accepted" }
+      ]
+    }
+  ],
+  "inspector": {
+    "relations": [
+      { "id": "preceding", "label": "Came from", "dir": "up" },
+      { "id": "down", "label": "Hands off to", "dir": "down" },
+      { "id": "closing", "label": "Resolution path", "dir": "down", "filter": { "kind": "end" } }
+    ],
+    "actions": [
+      { "id": "sim-breach", "label": "Simulate: SLA breach", "dir": "down", "staleText": "Simulating SLA breach ripple across support queues" }
+    ]
+  },
+  "notes": [
+    { "anchor": "#n_l1-triage", "title": "Initial triage gateway", "text": "Tier 1 triage evaluates request urgency and routes tickets to appropriate support queues." },
+    { "anchor": "#n_l1-wait", "title": "Customer response SLA", "text": "Tickets placed on hold await customer details and carry a strict two-hour target window." },
+    { "anchor": "#n_cust-confirm", "title": "Resolution verification", "text": "The ticket is reopened if customer validation fails during final review." },
+    { "anchor": "#playbar", "title": "Scenario playback", "text": "Switch between happy path and escalated breach workflows to observe token movement." }
+  ]
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/model.schema.json

@@ -19,9 +19,9 @@
         "labels": { "type": "object", "additionalProperties": { "type": "string" } }
       }
     },
-    "layout": { "const": "columns-lanes" },
+    "layout": { "enum": ["columns-lanes", "free", "auto"] },
     "columns": {
-      "type": "array", "minItems": 1,
+      "type": "array",
       "items": {
         "type": "object", "required": ["id", "title", "width"], "additionalProperties": false,
         "properties": {
@@ -31,7 +31,7 @@
       }
     },
     "lanes": {
-      "type": "array", "minItems": 1,
+      "type": "array",
       "items": {
         "type": "object", "required": ["id", "title"], "additionalProperties": false,
         "properties": {
@@ -57,18 +57,25 @@
     "nodes": {
       "type": "array",
       "items": {
-        "type": "object", "required": ["id", "kind", "lane", "col", "row", "state", "title"], "additionalProperties": false,
+        "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" }, "state": { "type": "string" },
+          "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" }
+          "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" } } } }
         }
       }
     },
@@ -79,7 +86,8 @@
         "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" }
+          "visibleIn": { "type": "array", "items": { "type": "string" } }, "label": { "type": "string" },
+          "kind": { "enum": ["forward", "loop-back"] }
         }
       }
     },
@@ -112,6 +120,10 @@
         }
       }
     },
+    "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": {
@@ -119,5 +131,12 @@
         "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/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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";