@cascivo/mcp 0.1.2 → 0.1.5

package/dist/registry.json

@@ -1,6 +1,6 @@
 {
   "version": "0.0.0",
-  "generatedAt": "2026-06-21",
+  "generatedAt": "2026-06-23",
   "components": [
     {
       "name": "accordion",
@@ -107,6 +107,147 @@
         }
       }
     },
+    {
+      "name": "action-sheet",
+      "type": "component",
+      "description": "Bottom-rising sheet of discrete actions (iOS action-sheet pattern) with a Cancel button",
+      "category": "overlay",
+      "version": "0.0.0",
+      "files": [
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/action-sheet/action-sheet.tsx",
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/action-sheet/action-sheet.module.css"
+      ],
+      "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+      "tags": ["overlay", "action-sheet", "menu", "mobile", "sheet"],
+      "meta": {
+        "name": "ActionSheet",
+        "description": "Bottom-rising sheet of discrete actions (iOS action-sheet pattern) with a Cancel button",
+        "category": "overlay",
+        "states": ["open", "closed"],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "open",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "defaultOpen",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "onOpenChange",
+            "type": "(open: boolean) => void",
+            "required": false
+          },
+          {
+            "name": "actions",
+            "type": "ActionSheetAction[]",
+            "required": true,
+            "description": "Choices, each with a label, onSelect, and optional destructive/disabled flags"
+          },
+          {
+            "name": "title",
+            "type": "React.ReactNode",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "React.ReactNode",
+            "required": false
+          },
+          {
+            "name": "showCancel",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "labels",
+            "type": "{ cancel?: string; label?: string }",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-surface",
+          "--cascivo-color-border",
+          "--cascivo-color-accent",
+          "--cascivo-color-destructive",
+          "--cascivo-color-text",
+          "--cascivo-color-text-subtle",
+          "--cascivo-color-text-muted",
+          "--cascivo-radius-overlay",
+          "--cascivo-shadow-overlay",
+          "--cascivo-motion-enter",
+          "--cascivo-motion-exit",
+          "--cascivo-z-overlay"
+        ],
+        "accessibility": {
+          "role": "menu",
+          "wcag": "2.2-AA",
+          "keyboard": ["ArrowUp", "ArrowDown", "Home", "End", "Enter", "Space", "Escape"]
+        },
+        "examples": [],
+        "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+        "tags": ["overlay", "action-sheet", "menu", "mobile", "sheet"],
+        "intent": {
+          "whenToUse": [
+            "A short list of discrete actions on a touch surface, rising from the bottom",
+            "Confirming or choosing among a few operations (e.g. Share, Edit, Delete) on mobile",
+            "A mobile-first alternative to an anchored dropdown menu when there is no trigger anchor"
+          ],
+          "whenNotToUse": [
+            "A single yes/no confirmation — use AlertDialog",
+            "A form or scrollable content — use BottomSheet or Sheet",
+            "A menu anchored to a trigger on desktop — use Menu or Dropdown"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "<ActionSheet actions={[{ label: \"OK\", onSelect }]} />",
+              "good": "<AlertDialog title=\"Delete item?\" />",
+              "why": "A one-action sheet is a confirmation; AlertDialog states the decision clearly"
+            }
+          ],
+          "related": [
+            {
+              "name": "BottomSheet",
+              "relationship": "alternative",
+              "reason": "Use BottomSheet for rich/resizable content; ActionSheet is a fixed list of actions"
+            },
+            {
+              "name": "Menu",
+              "relationship": "alternative",
+              "reason": "Use Menu for a trigger-anchored dropdown on pointer-first surfaces"
+            }
+          ],
+          "a11yRationale": "Renders role=\"menu\" with role=\"menuitem\" buttons under vertical roving focus (Arrow keys, Home/End, wrapping). The title labels the menu via aria-labelledby (or a built-in label otherwise) and the description via aria-describedby. FocusScope traps and restores focus; DismissableLayer handles Escape and outside-pointer dismissal; a separate Cancel button provides an explicit non-destructive exit.",
+          "flexibility": [
+            {
+              "area": "actions",
+              "level": "flexible",
+              "note": "Any number of actions; each may be destructive or disabled"
+            },
+            {
+              "area": "open state",
+              "level": "flexible",
+              "note": "Controlled (open/onOpenChange) or uncontrolled (defaultOpen)"
+            },
+            {
+              "area": "cancel",
+              "level": "flexible",
+              "note": "showCancel toggles the separate Cancel button (Escape/outside press still dismiss)"
+            }
+          ]
+        }
+      }
+    },
     {
       "name": "alert",
       "type": "component",
@@ -1018,6 +1159,159 @@
         }
       }
     },
+    {
+      "name": "bottom-sheet",
+      "type": "component",
+      "description": "Mobile bottom sheet with drag-to-resize detents, velocity-projected snapping, and drag-to-dismiss",
+      "category": "overlay",
+      "version": "0.0.0",
+      "files": [
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/bottom-sheet/bottom-sheet.tsx",
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/bottom-sheet/bottom-sheet.module.css"
+      ],
+      "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+      "tags": ["overlay", "sheet", "bottom-sheet", "mobile", "drag", "detent", "gesture"],
+      "meta": {
+        "name": "BottomSheet",
+        "description": "Mobile bottom sheet with drag-to-resize detents, velocity-projected snapping, and drag-to-dismiss",
+        "category": "overlay",
+        "states": ["open", "closed", "dragging"],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "open",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "defaultOpen",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "onOpenChange",
+            "type": "(open: boolean) => void",
+            "required": false
+          },
+          {
+            "name": "snapPoints",
+            "type": "number[]",
+            "required": false,
+            "default": "[0.5, 0.92]",
+            "description": "Detent heights as ascending fractions of the viewport (0–1)"
+          },
+          {
+            "name": "activeSnap",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "defaultSnap",
+            "type": "number",
+            "required": false,
+            "default": "0"
+          },
+          {
+            "name": "onSnapChange",
+            "type": "(index: number) => void",
+            "required": false
+          },
+          {
+            "name": "title",
+            "type": "React.ReactNode",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "React.ReactNode",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "React.ReactNode",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "{ close?: string; handle?: string }",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-surface",
+          "--cascivo-color-border",
+          "--cascivo-radius-overlay",
+          "--cascivo-shadow-overlay",
+          "--cascivo-motion-enter",
+          "--cascivo-motion-exit",
+          "--cascivo-target-min-coarse",
+          "--cascivo-z-overlay"
+        ],
+        "accessibility": {
+          "role": "dialog",
+          "wcag": "2.2-AA",
+          "keyboard": ["Escape", "Tab", "Shift+Tab"]
+        },
+        "examples": [],
+        "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+        "tags": ["overlay", "sheet", "bottom-sheet", "mobile", "drag", "detent", "gesture"],
+        "intent": {
+          "whenToUse": [
+            "A mobile surface that rises from the bottom and can be resized between detents by dragging",
+            "Showing secondary content, filters, or a form where the user can peek at half height then expand",
+            "A touch-first overlay that dismisses by flinging or dragging it down past the lowest detent"
+          ],
+          "whenNotToUse": [
+            "A short yes/no confirmation — use AlertDialog",
+            "A non-resizable edge panel without gestures — use Drawer or Sheet",
+            "A desktop-first side panel for navigation — use Drawer"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "<BottomSheet title=\"Delete item?\">Are you sure?</BottomSheet>",
+              "good": "<AlertDialog title=\"Delete item?\" />",
+              "why": "A resizable gesture surface is overkill for a focused yes/no decision"
+            }
+          ],
+          "related": [
+            {
+              "name": "Sheet",
+              "relationship": "alternative",
+              "reason": "Use Sheet for a fixed-height panel from any edge; BottomSheet adds resize detents"
+            },
+            {
+              "name": "Drawer",
+              "relationship": "alternative",
+              "reason": "Use Drawer for a plain edge dialog without resize detents"
+            }
+          ],
+          "a11yRationale": "Renders role=\"dialog\" with aria-modal; the title labels it via aria-labelledby and the description via aria-describedby. FocusScope traps Tab focus and restores it on close; DismissableLayer handles Escape and outside-pointer dismissal. The grab handle is a labelled separator and a Close button gives a non-gesture dismissal path so the sheet stays keyboard-operable.",
+          "flexibility": [
+            {
+              "area": "snapPoints",
+              "level": "flexible",
+              "note": "Any ascending list of viewport fractions; the sheet snaps between them"
+            },
+            {
+              "area": "open state",
+              "level": "flexible",
+              "note": "Controlled (open/onOpenChange) or uncontrolled (defaultOpen)"
+            },
+            {
+              "area": "active detent",
+              "level": "flexible",
+              "note": "Controlled (activeSnap/onSnapChange) or uncontrolled (defaultSnap)"
+            }
+          ]
+        }
+      }
+    },
     {
       "name": "breadcrumb",
       "type": "component",
@@ -4741,38 +5035,180 @@
       }
     },
     {
-      "name": "field",
+      "name": "fab",
       "type": "component",
-      "description": "Form-field wrapper composing label, control, description, and error",
+      "description": "Floating action button anchored to a screen corner, with an optional speed-dial of secondary actions",
       "category": "inputs",
       "version": "0.0.0",
       "files": [
-        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/field/field.tsx",
-        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/field/field.module.css"
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/fab/fab.tsx",
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/fab/fab.module.css"
       ],
       "dependencies": ["@cascivo/core"],
-      "tags": ["form", "layout", "validation", "accessibility"],
+      "tags": ["inputs", "fab", "floating-action-button", "mobile", "speed-dial"],
       "meta": {
-        "name": "Field",
-        "description": "Form-field wrapper composing label, control, description, and error",
+        "name": "Fab",
+        "description": "Floating action button anchored to a screen corner, with an optional speed-dial of secondary actions",
         "category": "inputs",
-        "states": ["default", "disabled", "invalid"],
+        "states": ["default", "open", "closed"],
         "variants": [],
         "sizes": [],
         "props": [
+          {
+            "name": "children",
+            "type": "React.ReactNode",
+            "required": true,
+            "description": "The main icon"
+          },
           {
             "name": "label",
-            "type": "ReactNode",
-            "required": false
+            "type": "string",
+            "required": true,
+            "description": "Accessible name for the button"
           },
           {
-            "name": "description",
-            "type": "ReactNode",
+            "name": "onClick",
+            "type": "() => void",
             "required": false
           },
           {
-            "name": "error",
-            "type": "ReactNode",
+            "name": "actions",
+            "type": "FabAction[]",
+            "required": false,
+            "description": "Speed-dial actions; each has a label, icon, onSelect, and optional disabled"
+          },
+          {
+            "name": "position",
+            "type": "'bottom-end' | 'bottom-start'",
+            "required": false,
+            "default": "bottom-end"
+          },
+          {
+            "name": "open",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "defaultOpen",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "onOpenChange",
+            "type": "(open: boolean) => void",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-accent",
+          "--cascivo-color-accent-content",
+          "--cascivo-color-accent-hover",
+          "--cascivo-color-surface",
+          "--cascivo-color-border",
+          "--cascivo-radius-full",
+          "--cascivo-shadow-overlay",
+          "--cascivo-target-min-coarse",
+          "--cascivo-motion-enter",
+          "--cascivo-motion-exit",
+          "--cascivo-z-dropdown"
+        ],
+        "accessibility": {
+          "role": "button",
+          "wcag": "2.2-AA",
+          "keyboard": ["Enter", "Space", "ArrowUp", "ArrowDown", "Home", "End", "Escape"]
+        },
+        "examples": [],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["inputs", "fab", "floating-action-button", "mobile", "speed-dial"],
+        "intent": {
+          "whenToUse": [
+            "A single, high-emphasis primary action that floats above scrolling content (e.g. Compose, Add)",
+            "A small cluster of related create actions revealed from one corner via a speed-dial",
+            "Touch-first screens where the primary action should stay reachable at the thumb"
+          ],
+          "whenNotToUse": [
+            "Ordinary form or toolbar buttons — use Button or IconButton in the layout flow",
+            "More than a handful of actions — use a Menu, Drawer, or full navigation",
+            "Primary navigation between top-level destinations — use Dock"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "<Fab label=\"Save\"><SaveIcon /></Fab> next to a form submit button",
+              "good": "<Button type=\"submit\">Save</Button>",
+              "why": "A floating button competes with the in-flow submit and hides the action off the form"
+            }
+          ],
+          "related": [
+            {
+              "name": "IconButton",
+              "relationship": "alternative",
+              "reason": "Use IconButton for an in-flow icon control; Fab floats and is high-emphasis"
+            },
+            {
+              "name": "Dock",
+              "relationship": "alternative",
+              "reason": "Use Dock for bottom navigation between destinations rather than a single action"
+            }
+          ],
+          "a11yRationale": "The main button is icon-only and requires a `label` that becomes its aria-label. With a speed-dial it exposes aria-haspopup=\"menu\", aria-expanded, and aria-controls; the dial is a role=\"menu\" of role=\"menuitem\" buttons under vertical roving focus (Arrow keys, Home/End, wrapping). Opening moves focus to the first action and closing (Escape, outside press, or selection via DismissableLayer) returns focus to the button.",
+          "flexibility": [
+            {
+              "area": "actions",
+              "level": "flexible",
+              "note": "Omit for a single-action button, or provide a speed-dial of secondary actions"
+            },
+            {
+              "area": "position",
+              "level": "strict",
+              "note": "Anchored to bottom-end or bottom-start; honours safe-area insets"
+            },
+            {
+              "area": "open state",
+              "level": "flexible",
+              "note": "Speed-dial is controlled (open/onOpenChange) or uncontrolled (defaultOpen)"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "field",
+      "type": "component",
+      "description": "Form-field wrapper composing label, control, description, and error",
+      "category": "inputs",
+      "version": "0.0.0",
+      "files": [
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/field/field.tsx",
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/field/field.module.css"
+      ],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["form", "layout", "validation", "accessibility"],
+      "meta": {
+        "name": "Field",
+        "description": "Form-field wrapper composing label, control, description, and error",
+        "category": "inputs",
+        "states": ["default", "disabled", "invalid"],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "label",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "error",
+            "type": "ReactNode",
             "required": false
           },
           {
@@ -9577,6 +10013,114 @@
         }
       }
     },
+    {
+      "name": "pull-to-refresh",
+      "type": "component",
+      "description": "Wraps a scrollable region and triggers a refresh when pulled down past a threshold at the top",
+      "category": "feedback",
+      "version": "0.0.0",
+      "files": [
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/pull-to-refresh/pull-to-refresh.tsx",
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/pull-to-refresh/pull-to-refresh.module.css"
+      ],
+      "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+      "tags": ["feedback", "pull-to-refresh", "mobile", "gesture", "scroll", "refresh"],
+      "meta": {
+        "name": "PullToRefresh",
+        "description": "Wraps a scrollable region and triggers a refresh when pulled down past a threshold at the top",
+        "category": "feedback",
+        "states": ["idle", "pulling", "ready", "refreshing"],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "onRefresh",
+            "type": "() => Promise<unknown> | unknown",
+            "required": true,
+            "description": "Called when the pull passes the threshold; the spinner shows until it settles"
+          },
+          {
+            "name": "children",
+            "type": "React.ReactNode",
+            "required": true
+          },
+          {
+            "name": "threshold",
+            "type": "number",
+            "required": false,
+            "default": "64"
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "{ pull?: string; release?: string; refreshing?: string }",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": ["--cascivo-color-text-muted", "--cascivo-motion-enter"],
+        "accessibility": {
+          "role": "status",
+          "wcag": "2.2-AA",
+          "keyboard": []
+        },
+        "examples": [],
+        "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+        "tags": ["feedback", "pull-to-refresh", "mobile", "gesture", "scroll", "refresh"],
+        "intent": {
+          "whenToUse": [
+            "A scrollable list or feed on touch devices that the user refreshes by pulling down from the top",
+            "Mobile screens where a dedicated refresh button would be redundant or out of reach",
+            "Content that updates on demand and benefits from a familiar pull gesture"
+          ],
+          "whenNotToUse": [
+            "Desktop, pointer-first surfaces — provide an explicit Refresh button",
+            "Content that auto-refreshes or paginates on scroll — use infinite scroll instead",
+            "Regions that are not the primary scroll container of the screen"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "Wrapping a non-scrolling element and relying on pull as the only refresh path",
+              "good": "Wrap the scroll container and also expose a Refresh control for non-touch users",
+              "why": "Pull-to-refresh is touch-only; keyboard and pointer users need an explicit control"
+            }
+          ],
+          "related": [
+            {
+              "name": "Spinner",
+              "relationship": "contains",
+              "reason": "Shows the Spinner while the refresh promise settles"
+            },
+            {
+              "name": "ScrollArea",
+              "relationship": "pairs-with",
+              "reason": "Wraps a scrollable region; pair with the app’s scroll container"
+            }
+          ],
+          "a11yRationale": "The gesture is a touch-only enhancement: it arms only at scrollTop 0 and uses touch-action/overscroll containment so normal scrolling and keyboard use are unaffected. A polite aria-live status region announces the pull, release, and refreshing states (strings from the i18n catalog), and the Spinner exposes role=\"status\" while loading. Because pull-to-refresh cannot be performed without a pointer, apps should also offer an explicit refresh control for keyboard users.",
+          "flexibility": [
+            {
+              "area": "threshold",
+              "level": "flexible",
+              "note": "Pull distance required to trigger is configurable (default 64px)"
+            },
+            {
+              "area": "onRefresh",
+              "level": "flexible",
+              "note": "May return a promise; the spinner persists until it settles"
+            }
+          ]
+        }
+      }
+    },
     {
       "name": "qr-code",
       "type": "component",
@@ -11338,7 +11882,7 @@
             "name": "items",
             "type": "SideNavItem[]",
             "required": true,
-            "description": "{ label, href?, icon?, active?, items? } — items with nested items render as expandable groups"
+            "description": "{ label, href?, icon?, active?, items?, onClick?, disabled?, tone?, trailing?, render? } — an onClick-only item renders a focusable <button>; nested items render expandable menus (links, action sub-items with onSelect/selected, separators, labels); render() is an alignment-preserving escape hatch"
           },
           {
             "name": "collapsed",
@@ -11382,6 +11926,12 @@
             "default": "false",
             "description": "Widens the rail as an overlay on hover/focus-within; suppresses tooltips/flyouts"
           },
+          {
+            "name": "header",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Content rendered above the items, inside the item padding context (e.g. app-context pickers)"
+          },
           {
             "name": "footer",
             "type": "ReactNode",
@@ -11405,6 +11955,9 @@
           "--cascivo-color-bg-subtle",
           "--cascivo-color-accent",
           "--cascivo-color-accent-subtle",
+          "--cascivo-color-destructive",
+          "--cascivo-color-warning",
+          "--cascivo-color-success",
           "--cascivo-focus-ring",
           "--cascivo-motion-enter",
           "--cascivo-motion-exit",
@@ -12650,36 +13203,42 @@
       }
     },
     {
-      "name": "switcher",
+      "name": "swipe-item",
       "type": "component",
-      "description": "App/product switcher list — lives inside HeaderPanel, renders links with active indicator and optional dividers",
-      "category": "navigation",
+      "description": "List row whose leading/trailing actions are revealed by a horizontal swipe, with keyboard parity",
+      "category": "display",
       "version": "0.0.0",
       "files": [
-        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/switcher/switcher.tsx",
-        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/switcher/switcher.module.css"
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/swipe-item/swipe-item.tsx",
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/swipe-item/swipe-item.module.css"
       ],
-      "dependencies": ["@cascivo/core", "@cascivo/i18n"],
-      "tags": ["navigation", "switcher", "shell", "console", "app-switcher"],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["display", "swipe", "list", "mobile", "gesture", "actions"],
       "meta": {
-        "name": "Switcher",
-        "description": "App/product switcher list — lives inside HeaderPanel, renders links with active indicator and optional dividers",
-        "category": "navigation",
-        "states": ["default"],
+        "name": "SwipeItem",
+        "description": "List row whose leading/trailing actions are revealed by a horizontal swipe, with keyboard parity",
+        "category": "display",
+        "states": ["closed", "leading", "trailing"],
         "variants": [],
         "sizes": [],
         "props": [
           {
-            "name": "items",
-            "type": "SwitcherEntry[]",
+            "name": "children",
+            "type": "React.ReactNode",
             "required": true,
-            "description": "SwitcherLink ({ label, href, active?, icon? }) or divider ({ divider: true })"
+            "description": "The row content"
           },
           {
-            "name": "label",
-            "type": "string",
+            "name": "leadingActions",
+            "type": "SwipeAction[]",
             "required": false,
-            "default": "Switch application"
+            "description": "Actions revealed by dragging toward the end edge (shown on the start edge)"
+          },
+          {
+            "name": "trailingActions",
+            "type": "SwipeAction[]",
+            "required": false,
+            "description": "Actions revealed by dragging toward the start edge (shown on the end edge)"
           },
           {
             "name": "className",
@@ -12688,48 +13247,149 @@
           }
         ],
         "tokens": [
-          "--cascivo-color-text",
-          "--cascivo-color-bg-subtle",
+          "--cascivo-color-surface",
           "--cascivo-color-accent",
-          "--cascivo-color-accent-subtle",
-          "--cascivo-color-border",
-          "--cascivo-focus-ring"
+          "--cascivo-color-accent-content",
+          "--cascivo-color-destructive",
+          "--cascivo-color-text-on-destructive",
+          "--cascivo-target-min-coarse",
+          "--cascivo-motion-enter"
         ],
         "accessibility": {
-          "role": "list",
+          "role": "group",
           "wcag": "2.2-AA",
-          "keyboard": ["Tab", "Enter"]
+          "keyboard": ["Tab", "Enter", "Space", "Escape"]
         },
-        "examples": [
-          {
-            "title": "App switcher",
-            "code": "<Switcher\n  items={[\n    { label: 'Console', href: '/console', active: true },\n    { label: 'Billing', href: '/billing' },\n    { divider: true },\n    { label: 'Docs', href: 'https://docs.example.com' },\n  ]}\n/>",
-            "description": "Place inside a HeaderPanel opened by a Grid action in ShellHeader"
-          }
-        ],
-        "dependencies": ["@cascivo/core", "@cascivo/i18n"],
-        "tags": ["navigation", "switcher", "shell", "console", "app-switcher"],
+        "examples": [],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["display", "swipe", "list", "mobile", "gesture", "actions"],
         "intent": {
           "whenToUse": [
-            "Listing sibling apps/products the user can switch between",
-            "Rendering switch destinations inside a HeaderPanel opened from the shell header",
-            "Grouping switch targets with dividers and marking the active one"
+            "List rows on touch surfaces where secondary actions (archive, delete) should hide until swiped",
+            "Mail/inbox-style rows that reveal contextual actions behind the content",
+            "Compact lists where always-visible action buttons would crowd each row"
           ],
           "whenNotToUse": [
-            "Primary in-app navigation — use SideNav",
-            "A small action menu attached to a control — use Dropdown"
+            "A single primary action per row — render it inline as a Button",
+            "Destructive actions that need confirmation — pair with an AlertDialog instead of swipe-only",
+            "Non-list, free-form content — swipe-to-reveal is a list-row affordance"
           ],
           "antiPatterns": [
             {
-              "bad": "Using Switcher as the main page navigation",
-              "good": "<SideNav> for primary navigation; Switcher only for app/product switching",
-              "why": "Switcher models cross-app jumps, not navigation within the current app"
+              "bad": "Relying on the swipe gesture as the only way to reach Delete",
+              "good": "Action buttons stay in the DOM and a11y tree; focusing one reveals its side",
+              "why": "Gesture-only actions are unreachable by keyboard and screen-reader users"
             }
           ],
           "related": [
             {
-              "name": "HeaderPanel",
-              "relationship": "contained-by",
+              "name": "ActionSheet",
+              "relationship": "alternative",
+              "reason": "Use an ActionSheet when a row tap should present a fuller list of actions"
+            },
+            {
+              "name": "List",
+              "relationship": "contained-by",
+              "reason": "SwipeItem wraps individual rows within a list"
+            }
+          ],
+          "a11yRationale": "The action buttons are always rendered in the DOM and the accessibility tree, never gesture-only. Focusing an action (via keyboard) reveals its side so it is visible, Enter/Space activate it, and Escape closes the row — giving full keyboard and screen-reader parity with the swipe gesture. The drag uses touch-action: pan-y so vertical scrolling is unaffected.",
+          "flexibility": [
+            {
+              "area": "actions",
+              "level": "flexible",
+              "note": "Any number of leading and/or trailing actions; each may be destructive"
+            },
+            {
+              "area": "reveal direction",
+              "level": "strict",
+              "note": "Leading reveals on the start edge, trailing on the end edge (physical-axis drag)"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "switcher",
+      "type": "component",
+      "description": "App/product switcher list — lives inside HeaderPanel, renders links with active indicator and optional dividers",
+      "category": "navigation",
+      "version": "0.0.0",
+      "files": [
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/switcher/switcher.tsx",
+        "https://raw.githubusercontent.com/cascivo/cascivo/main/packages/components/src/switcher/switcher.module.css"
+      ],
+      "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+      "tags": ["navigation", "switcher", "shell", "console", "app-switcher"],
+      "meta": {
+        "name": "Switcher",
+        "description": "App/product switcher list — lives inside HeaderPanel, renders links with active indicator and optional dividers",
+        "category": "navigation",
+        "states": ["default"],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "items",
+            "type": "SwitcherEntry[]",
+            "required": true,
+            "description": "SwitcherLink ({ label, href, active?, icon? }) or divider ({ divider: true })"
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "required": false,
+            "default": "Switch application"
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-text",
+          "--cascivo-color-bg-subtle",
+          "--cascivo-color-accent",
+          "--cascivo-color-accent-subtle",
+          "--cascivo-color-border",
+          "--cascivo-focus-ring"
+        ],
+        "accessibility": {
+          "role": "list",
+          "wcag": "2.2-AA",
+          "keyboard": ["Tab", "Enter"]
+        },
+        "examples": [
+          {
+            "title": "App switcher",
+            "code": "<Switcher\n  items={[\n    { label: 'Console', href: '/console', active: true },\n    { label: 'Billing', href: '/billing' },\n    { divider: true },\n    { label: 'Docs', href: 'https://docs.example.com' },\n  ]}\n/>",
+            "description": "Place inside a HeaderPanel opened by a Grid action in ShellHeader"
+          }
+        ],
+        "dependencies": ["@cascivo/core", "@cascivo/i18n"],
+        "tags": ["navigation", "switcher", "shell", "console", "app-switcher"],
+        "intent": {
+          "whenToUse": [
+            "Listing sibling apps/products the user can switch between",
+            "Rendering switch destinations inside a HeaderPanel opened from the shell header",
+            "Grouping switch targets with dividers and marking the active one"
+          ],
+          "whenNotToUse": [
+            "Primary in-app navigation — use SideNav",
+            "A small action menu attached to a control — use Dropdown"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "Using Switcher as the main page navigation",
+              "good": "<SideNav> for primary navigation; Switcher only for app/product switching",
+              "why": "Switcher models cross-app jumps, not navigation within the current app"
+            }
+          ],
+          "related": [
+            {
+              "name": "HeaderPanel",
+              "relationship": "contained-by",
               "reason": "Switcher is placed inside a HeaderPanel opened by a ShellHeader action"
             }
           ],
@@ -19166,6 +19826,1123 @@
           "flexibility": []
         }
       }
+    },
+    {
+      "name": "flow/flow",
+      "type": "flow",
+      "description": "The declarative, AI-first flow surface — render a node/edge graph from plain serializable data.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "graph", "declarative", "diagram", "ai-first"],
+      "meta": {
+        "name": "Flow",
+        "description": "The declarative, AI-first flow surface — render a node/edge graph from plain serializable data.",
+        "category": "display",
+        "states": [],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "nodes",
+            "type": "FlowNode[]",
+            "required": true,
+            "description": "Initial nodes (serializable)."
+          },
+          {
+            "name": "edges",
+            "type": "FlowEdge[]",
+            "required": true,
+            "description": "Initial edges (serializable)."
+          },
+          {
+            "name": "onNodesChange",
+            "type": "(nodes: FlowNode[]) => void",
+            "required": false
+          },
+          {
+            "name": "onEdgesChange",
+            "type": "(edges: FlowEdge[]) => void",
+            "required": false
+          },
+          {
+            "name": "onConnect",
+            "type": "(connection: Connection) => void",
+            "required": false
+          },
+          {
+            "name": "nodeTypes",
+            "type": "Record<string, NodeRenderer>",
+            "required": false,
+            "description": "Custom node renderers keyed by node.type."
+          },
+          {
+            "name": "fitView",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "background",
+            "type": "boolean | FlowBackgroundProps",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "controls",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "minimap",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "layout",
+            "type": "'grid' | 'layered' | ((nodes, edges) => FlowNode[])",
+            "required": false,
+            "description": "Optional dependency-free layout."
+          },
+          {
+            "name": "interactive",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "When false (view mode), nodes cannot be selected, dragged, or connected and handles are hidden; pan/zoom still work."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": ["--cascivo-color-bg", "--cascivo-color-surface", "--cascivo-color-accent"],
+        "accessibility": {
+          "role": "application",
+          "wcag": "2.1-AA",
+          "keyboard": [
+            "Tab (focus nodes)",
+            "Enter/Space (select)",
+            "Drag (pan/move)",
+            "Wheel (zoom)"
+          ]
+        },
+        "examples": [
+          {
+            "title": "Declarative pipeline",
+            "description": "A flow from plain serializable data, with background, controls, and an animated edge.",
+            "code": "() => (\n  <Flow\n    style={{ height: 280 }}\n    background\n    controls\n    nodes={[\n      { id: 'a', position: { x: 0, y: 60 }, data: { label: 'Client' } },\n      { id: 'b', position: { x: 240, y: 60 }, data: { label: 'Gateway' } },\n      { id: 'c', position: { x: 480, y: 60 }, data: { label: 'Service' } },\n    ]}\n    edges={[\n      { id: 'ab', source: 'a', target: 'b', animated: true, label: 'request' },\n      { id: 'bc', source: 'b', target: 'c' },\n    ]}\n  />\n)"
+          },
+          {
+            "title": "Layered layout",
+            "description": "Let the dependency-free layered layout arrange a small DAG.",
+            "code": "() => (\n  <Flow\n    style={{ height: 300 }}\n    layout=\"layered\"\n    background\n    minimap\n    nodes={[\n      { id: 'a', position: { x: 0, y: 0 }, data: { label: 'Ingest' } },\n      { id: 'b', position: { x: 0, y: 0 }, data: { label: 'Transform' } },\n      { id: 'c', position: { x: 0, y: 0 }, data: { label: 'Validate' } },\n      { id: 'd', position: { x: 0, y: 0 }, data: { label: 'Load' } },\n    ]}\n    edges={[\n      { id: 'ab', source: 'a', target: 'b' },\n      { id: 'ac', source: 'a', target: 'c' },\n      { id: 'bd', source: 'b', target: 'd' },\n      { id: 'cd', source: 'c', target: 'd' },\n    ]}\n  />\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "graph", "declarative", "diagram", "ai-first"],
+        "intent": {
+          "whenToUse": [
+            "Rendering a graph from data — the common case and the agent-emittable surface",
+            "Flowcharts, DAGs, pipelines, and mind-maps from plain nodes/edges arrays"
+          ],
+          "whenNotToUse": [
+            "A scripted, sequenced walkthrough — use FlowStory",
+            "Heavy graph editing (undo/redo, resize/rotate) — out of scope"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "Imperatively building the graph with graph.addNode(...)",
+              "good": "<Flow nodes={…} edges={…} />",
+              "why": "Declarative serializable data is what an agent can emit and what stays in sync with props."
+            }
+          ],
+          "related": [
+            {
+              "name": "FlowStory",
+              "relationship": "alternative",
+              "reason": "Scripted, captioned storyline animation."
+            },
+            {
+              "name": "FlowNode",
+              "relationship": "contains",
+              "reason": "Renders a node per entry."
+            },
+            {
+              "name": "FlowEdge",
+              "relationship": "contains",
+              "reason": "Renders an edge per entry."
+            }
+          ],
+          "a11yRationale": "role=\"application\" canvas; nodes are focusable groups; controls are real i18n-labeled buttons.",
+          "flexibility": [
+            {
+              "area": "rendering",
+              "level": "flexible",
+              "note": "Custom node renderers via nodeTypes."
+            },
+            {
+              "area": "layout",
+              "level": "flexible",
+              "note": "grid | layered | bring-your-own positions."
+            },
+            {
+              "area": "chrome",
+              "level": "flexible",
+              "note": "Optional background / controls / minimap."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-background",
+      "type": "flow",
+      "description": "Decorative dots / grid / cross canvas background, drawn purely in CSS gradients.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "background", "grid", "dots", "canvas"],
+      "meta": {
+        "name": "FlowBackground",
+        "description": "Decorative dots / grid / cross canvas background, drawn purely in CSS gradients.",
+        "category": "display",
+        "states": [],
+        "variants": ["dots", "grid", "cross"],
+        "sizes": [],
+        "props": [
+          {
+            "name": "variant",
+            "type": "'dots' | 'grid' | 'cross'",
+            "required": false,
+            "default": "dots",
+            "description": "Pattern style."
+          },
+          {
+            "name": "gap",
+            "type": "number",
+            "required": false,
+            "default": "20",
+            "description": "Cell spacing (px)."
+          },
+          {
+            "name": "size",
+            "type": "number",
+            "required": false,
+            "default": "1",
+            "description": "Dot radius / line thickness (px)."
+          },
+          {
+            "name": "color",
+            "type": "string",
+            "required": false,
+            "description": "Pattern color (defaults to the border token)."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": ["--cascivo-color-border"],
+        "accessibility": {
+          "role": "presentation",
+          "wcag": "2.1-AA",
+          "keyboard": []
+        },
+        "examples": [
+          {
+            "title": "Dotted background",
+            "description": "A dotted grid behind a flow canvas.",
+            "code": "() => (\n  <div style={{ position: 'relative', height: 220, overflow: 'hidden' }}>\n    <FlowBackground variant=\"dots\" gap={24} />\n  </div>\n)"
+          },
+          {
+            "title": "Grid and cross",
+            "description": "The grid and cross variants.",
+            "code": "() => (\n  <div style={{ display: 'grid', gap: 16, gridTemplateColumns: '1fr 1fr' }}>\n    <div style={{ position: 'relative', height: 180, overflow: 'hidden' }}>\n      <FlowBackground variant=\"grid\" gap={28} />\n    </div>\n    <div style={{ position: 'relative', height: 180, overflow: 'hidden' }}>\n      <FlowBackground variant=\"cross\" gap={28} size={4} />\n    </div>\n  </div>\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "background", "grid", "dots", "canvas"],
+        "intent": {
+          "whenToUse": [
+            "Giving a flow canvas a sense of space and scale with a dotted or grid backdrop",
+            "Reinforcing pan/zoom by letting the pattern move and scale with the viewport"
+          ],
+          "whenNotToUse": [
+            "As a page background — this is a flow-canvas decoration, not a general surface"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "Rendering a DOM node per grid cell",
+              "good": "A single CSS gradient layer",
+              "why": "Per-cell DOM is needlessly expensive; one repeating gradient costs nothing."
+            }
+          ],
+          "related": [
+            {
+              "name": "FlowCanvas",
+              "relationship": "contained-by",
+              "reason": "Lives inside the canvas pane."
+            }
+          ],
+          "a11yRationale": "Purely decorative — marked aria-hidden and presentation, never in the a11y tree.",
+          "flexibility": [
+            {
+              "area": "pattern",
+              "level": "flexible",
+              "note": "dots | grid | cross with configurable gap/size."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-controls",
+      "type": "flow",
+      "description": "Zoom in / out / fit-view controls for a flow canvas — real, i18n-labeled buttons.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "controls", "zoom", "chrome"],
+      "meta": {
+        "name": "FlowControls",
+        "description": "Zoom in / out / fit-view controls for a flow canvas — real, i18n-labeled buttons.",
+        "category": "display",
+        "states": [],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "position",
+            "type": "'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'",
+            "required": false,
+            "default": "bottom-left"
+          },
+          {
+            "name": "showZoom",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "showFitView",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "onZoomIn",
+            "type": "() => void",
+            "required": false
+          },
+          {
+            "name": "onZoomOut",
+            "type": "() => void",
+            "required": false
+          },
+          {
+            "name": "onFitView",
+            "type": "() => void",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "FlowControlsLabels",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-surface",
+          "--cascivo-color-border",
+          "--cascivo-target-min-coarse"
+        ],
+        "accessibility": {
+          "role": "group",
+          "wcag": "2.1-AA",
+          "keyboard": ["Tab (focus)", "Enter/Space (activate)"]
+        },
+        "examples": [
+          {
+            "title": "Canvas controls",
+            "code": "() => (\n  <div style={{ position: 'relative', height: 200, border: '1px solid var(--cascivo-color-border)' }}>\n    <FlowControls onZoomIn={() => {}} onZoomOut={() => {}} onFitView={() => {}} />\n  </div>\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "controls", "zoom", "chrome"],
+        "intent": {
+          "whenToUse": ["Giving users explicit zoom/fit controls on a flow canvas"],
+          "whenNotToUse": ["When the canvas is static/non-interactive"],
+          "antiPatterns": [],
+          "related": [
+            {
+              "name": "FlowCanvas",
+              "relationship": "pairs-with",
+              "reason": "Calls its viewport actions."
+            },
+            {
+              "name": "FlowMiniMap",
+              "relationship": "pairs-with",
+              "reason": "Complementary navigation chrome."
+            }
+          ],
+          "a11yRationale": "Real <button>s with i18n-defaulted aria-labels; ≥44px coarse targets.",
+          "flexibility": [
+            {
+              "area": "position",
+              "level": "flexible",
+              "note": "Four corners."
+            },
+            {
+              "area": "buttons",
+              "level": "flexible",
+              "note": "Zoom / fit toggleable."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-edge",
+      "type": "flow",
+      "description": "An SVG edge with bezier/straight/smoothstep paths, an arrowhead, an optional label, and animation.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "edge", "connector", "animated", "svg"],
+      "meta": {
+        "name": "FlowEdge",
+        "description": "An SVG edge with bezier/straight/smoothstep paths, an arrowhead, an optional label, and animation.",
+        "category": "display",
+        "states": ["default", "selected", "animated"],
+        "variants": ["bezier", "straight", "smoothstep"],
+        "sizes": [],
+        "props": [
+          {
+            "name": "sourceX",
+            "type": "number",
+            "required": true,
+            "description": "Source anchor x (flow coords)."
+          },
+          {
+            "name": "sourceY",
+            "type": "number",
+            "required": true
+          },
+          {
+            "name": "targetX",
+            "type": "number",
+            "required": true
+          },
+          {
+            "name": "targetY",
+            "type": "number",
+            "required": true
+          },
+          {
+            "name": "type",
+            "type": "'bezier' | 'straight' | 'smoothstep'",
+            "required": false,
+            "default": "bezier"
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "label",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "selected",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "markerStart",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Arrowhead at the source (points back toward the source) — set both for bidirectional."
+          },
+          {
+            "name": "markerEnd",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Arrowhead at the target. Set false for an undirected line."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-border-strong",
+          "--cascivo-color-accent",
+          "--cascivo-color-surface"
+        ],
+        "accessibility": {
+          "role": "presentation",
+          "wcag": "2.1-AA",
+          "keyboard": [],
+          "reducedMotion": true
+        },
+        "examples": [
+          {
+            "title": "Edge path types",
+            "description": "Bezier, straight, smoothstep, and an animated edge.",
+            "code": "() => (\n  <div style={{ position: 'relative', height: 220 }}>\n    <FlowEdge sourceX={20} sourceY={30} targetX={260} targetY={30} type=\"bezier\" label=\"bezier\" />\n    <FlowEdge sourceX={20} sourceY={90} targetX={260} targetY={90} type=\"smoothstep\" label=\"step\" />\n    <FlowEdge sourceX={20} sourceY={150} targetX={260} targetY={150} animated label=\"animated\" />\n  </div>\n)"
+          },
+          {
+            "title": "Arrow direction",
+            "description": "Forward (default), backward, bidirectional, or undirected — via markerStart/markerEnd.",
+            "code": "() => (\n  <div style={{ position: 'relative', height: 260 }}>\n    <FlowEdge sourceX={20} sourceY={30} targetX={260} targetY={30} label=\"forward\" />\n    <FlowEdge sourceX={20} sourceY={90} targetX={260} targetY={90} markerEnd={false} markerStart label=\"backward\" />\n    <FlowEdge sourceX={20} sourceY={150} targetX={260} targetY={150} markerStart label=\"both\" />\n    <FlowEdge sourceX={20} sourceY={210} targetX={260} targetY={210} markerEnd={false} label=\"undirected\" />\n  </div>\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "edge", "connector", "animated", "svg"],
+        "intent": {
+          "whenToUse": [
+            "Connecting two nodes with a directed path and arrowhead",
+            "Animating flow direction along a connection (\"marching ants\")"
+          ],
+          "whenNotToUse": [
+            "For undirected relationships where an arrowhead would mislead — set markerEnd={false}"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "A requestAnimationFrame loop to animate the dash",
+              "good": "A CSS stroke-dashoffset keyframe",
+              "why": "The compositor animates CSS for free; a JS loop re-renders every frame."
+            }
+          ],
+          "related": [
+            {
+              "name": "FlowNode",
+              "relationship": "pairs-with",
+              "reason": "Edges connect nodes."
+            },
+            {
+              "name": "FlowStory",
+              "relationship": "pairs-with",
+              "reason": "Storylines animate edges in sequence."
+            }
+          ],
+          "a11yRationale": "Decorative SVG (aria-hidden); animation is disabled under prefers-reduced-motion.",
+          "flexibility": [
+            {
+              "area": "path",
+              "level": "flexible",
+              "note": "bezier | straight | smoothstep."
+            },
+            {
+              "area": "animation",
+              "level": "flexible",
+              "note": "Optional, reduced-motion-safe."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-handle",
+      "type": "flow",
+      "description": "A connection port on a node edge — where edges attach and interactive connect starts.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "handle", "port", "connect"],
+      "meta": {
+        "name": "FlowHandle",
+        "description": "A connection port on a node edge — where edges attach and interactive connect starts.",
+        "category": "display",
+        "states": ["default", "hover", "focus"],
+        "variants": ["source", "target"],
+        "sizes": [],
+        "props": [
+          {
+            "name": "type",
+            "type": "'source' | 'target'",
+            "required": true
+          },
+          {
+            "name": "position",
+            "type": "'top' | 'right' | 'bottom' | 'left'",
+            "required": false,
+            "description": "Edge of the node (defaults: source→right, target→left)."
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "required": false,
+            "description": "Handle id for multi-handle nodes."
+          },
+          {
+            "name": "isConnectable",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-accent",
+          "--cascivo-color-surface",
+          "--cascivo-target-min-coarse"
+        ],
+        "accessibility": {
+          "role": "button",
+          "wcag": "2.1-AA",
+          "keyboard": ["Tab (focus the port)"]
+        },
+        "examples": [
+          {
+            "title": "Source and target ports",
+            "code": "() => (\n  <div style={{ position: 'relative', height: 160 }}>\n    <FlowNode id=\"api\" defaultPosition={{ x: 70, y: 55 }}>\n      API\n      <FlowHandle type=\"target\" position=\"left\" />\n      <FlowHandle type=\"source\" position=\"right\" />\n    </FlowNode>\n  </div>\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "handle", "port", "connect"],
+        "intent": {
+          "whenToUse": [
+            "Marking where edges connect to a node",
+            "Enabling interactive connect (drag from a source to a target)"
+          ],
+          "whenNotToUse": ["On nodes that are never connected"],
+          "antiPatterns": [],
+          "related": [
+            {
+              "name": "FlowNode",
+              "relationship": "contained-by",
+              "reason": "Ports live inside a node."
+            },
+            {
+              "name": "FlowEdge",
+              "relationship": "pairs-with",
+              "reason": "Edges anchor to handles."
+            }
+          ],
+          "a11yRationale": "Focusable with a ≥44px coarse-pointer hit area around the visible dot.",
+          "flexibility": [
+            {
+              "area": "position",
+              "level": "flexible",
+              "note": "top | right | bottom | left."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-minimap",
+      "type": "flow",
+      "description": "A scaled SVG overview of the graph with a draggable viewport rectangle.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "minimap", "overview", "chrome"],
+      "meta": {
+        "name": "FlowMiniMap",
+        "description": "A scaled SVG overview of the graph with a draggable viewport rectangle.",
+        "category": "display",
+        "states": [],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "nodes",
+            "type": "FlowNode[]",
+            "required": true
+          },
+          {
+            "name": "viewport",
+            "type": "Viewport",
+            "required": true
+          },
+          {
+            "name": "containerWidth",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "containerHeight",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "width",
+            "type": "number",
+            "required": false,
+            "default": "200"
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "required": false,
+            "default": "150"
+          },
+          {
+            "name": "position",
+            "type": "'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'",
+            "required": false,
+            "default": "bottom-right"
+          },
+          {
+            "name": "onViewportChange",
+            "type": "(viewport: Viewport) => void",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-surface",
+          "--cascivo-color-border-strong",
+          "--cascivo-color-accent"
+        ],
+        "accessibility": {
+          "role": "img",
+          "wcag": "2.1-AA",
+          "keyboard": []
+        },
+        "examples": [
+          {
+            "title": "Graph overview",
+            "code": "() => (\n  <FlowMiniMap\n    nodes={[\n      { id: 'a', position: { x: 0, y: 0 } },\n      { id: 'b', position: { x: 220, y: 120 } },\n      { id: 'c', position: { x: 440, y: 0 } },\n    ]}\n    viewport={{ x: 0, y: 0, zoom: 1 }}\n    containerWidth={400}\n    containerHeight={300}\n  />\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "minimap", "overview", "chrome"],
+        "intent": {
+          "whenToUse": [
+            "Orienting users in a large graph",
+            "Letting users jump around by dragging the view rect"
+          ],
+          "whenNotToUse": ["Tiny graphs that fit on screen"],
+          "antiPatterns": [],
+          "related": [
+            {
+              "name": "FlowControls",
+              "relationship": "pairs-with",
+              "reason": "Complementary navigation chrome."
+            }
+          ],
+          "a11yRationale": "role=\"img\" with an i18n-defaulted label describing the overview.",
+          "flexibility": [
+            {
+              "area": "size",
+              "level": "flexible",
+              "note": "Configurable width/height."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-node",
+      "type": "flow",
+      "description": "An HTML node box positioned in the viewport pane — draggable, selectable, with arbitrary children.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "node", "draggable", "graph"],
+      "meta": {
+        "name": "FlowNode",
+        "description": "An HTML node box positioned in the viewport pane — draggable, selectable, with arbitrary children.",
+        "category": "display",
+        "states": ["default", "dragging", "selected", "focus"],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "id",
+            "type": "string",
+            "required": true,
+            "description": "Stable node id."
+          },
+          {
+            "name": "position",
+            "type": "{ x: number; y: number }",
+            "required": false,
+            "description": "Position in flow coords (controllable)."
+          },
+          {
+            "name": "onPositionChange",
+            "type": "(position: XYPosition) => void",
+            "required": false,
+            "description": "Fired while dragging."
+          },
+          {
+            "name": "zoom",
+            "type": "number",
+            "required": false,
+            "default": "1",
+            "description": "Current zoom (drag deltas are divided by it)."
+          },
+          {
+            "name": "selected",
+            "type": "boolean",
+            "required": false,
+            "default": "false"
+          },
+          {
+            "name": "draggable",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "interactive",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "When false, the node is view-only: not draggable, selectable, or focusable."
+          },
+          {
+            "name": "onSelect",
+            "type": "(id: string) => void",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false,
+            "description": "Any cascivo content."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-surface",
+          "--cascivo-color-border",
+          "--cascivo-color-accent",
+          "--cascivo-radius-md",
+          "--cascivo-shadow-sm"
+        ],
+        "accessibility": {
+          "role": "group",
+          "wcag": "2.1-AA",
+          "keyboard": ["Tab (focus)", "Enter/Space (select)"]
+        },
+        "examples": [
+          {
+            "title": "A draggable node",
+            "code": "() => (\n  <div style={{ position: 'relative', height: 160 }}>\n    <FlowNode id=\"a\" defaultPosition={{ x: 40, y: 50 }}>Service A</FlowNode>\n  </div>\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "node", "draggable", "graph"],
+        "intent": {
+          "whenToUse": [
+            "Representing a unit in a graph that holds arbitrary themed content",
+            "When you hand-compose a flow and need draggable, selectable boxes"
+          ],
+          "whenNotToUse": ["For the common case — the declarative <Flow> renders nodes for you"],
+          "antiPatterns": [
+            {
+              "bad": "Rendering node content into an SVG",
+              "good": "HTML node boxes",
+              "why": "HTML nodes inherit the data-theme scope and can contain any cascivo component."
+            }
+          ],
+          "related": [
+            {
+              "name": "FlowHandle",
+              "relationship": "contains",
+              "reason": "Connection ports live inside a node."
+            },
+            {
+              "name": "FlowEdge",
+              "relationship": "pairs-with",
+              "reason": "Edges route between nodes."
+            }
+          ],
+          "a11yRationale": "Focusable group; Enter/Space select. Visual states (hover/focus/selected) are CSS.",
+          "flexibility": [
+            {
+              "area": "content",
+              "level": "flexible",
+              "note": "Renders any children."
+            },
+            {
+              "area": "position",
+              "level": "flexible",
+              "note": "Controllable; draggable toggleable."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-panel",
+      "type": "flow",
+      "description": "An absolutely-positioned slot for custom flow-canvas UI (legend, toolbar).",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "panel", "slot", "chrome"],
+      "meta": {
+        "name": "FlowPanel",
+        "description": "An absolutely-positioned slot for custom flow-canvas UI (legend, toolbar).",
+        "category": "display",
+        "states": [],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "position",
+            "type": "'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'",
+            "required": false,
+            "default": "top-right"
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": ["--cascivo-space-3"],
+        "accessibility": {
+          "role": "group",
+          "wcag": "2.1-AA",
+          "keyboard": []
+        },
+        "examples": [
+          {
+            "title": "A legend panel",
+            "code": "() => (\n  <div style={{ position: 'relative', height: 160, border: '1px solid var(--cascivo-color-border)' }}>\n    <FlowPanel position=\"top-right\">Legend</FlowPanel>\n  </div>\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "panel", "slot", "chrome"],
+        "intent": {
+          "whenToUse": ["Overlaying custom UI (a legend, a toolbar) on a flow canvas"],
+          "whenNotToUse": ["For zoom/fit controls — use FlowControls"],
+          "antiPatterns": [],
+          "related": [
+            {
+              "name": "FlowControls",
+              "relationship": "alternative",
+              "reason": "Purpose-built zoom/fit chrome."
+            }
+          ],
+          "a11yRationale": "A plain positioned container; semantics come from its children.",
+          "flexibility": [
+            {
+              "area": "position",
+              "level": "flexible",
+              "note": "Six anchor positions."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
+    },
+    {
+      "name": "flow/flow-story",
+      "type": "flow",
+      "description": "A scripted, sequenced, looping flow animation — walks a graph step by step with fade-in captions.",
+      "category": "display",
+      "version": "0.0.0",
+      "files": [],
+      "dependencies": ["@cascivo/core"],
+      "tags": ["flow", "animation", "storyline", "walkthrough", "sequence"],
+      "meta": {
+        "name": "FlowStory",
+        "description": "A scripted, sequenced, looping flow animation — walks a graph step by step with fade-in captions.",
+        "category": "display",
+        "states": ["playing", "paused"],
+        "variants": [],
+        "sizes": [],
+        "props": [
+          {
+            "name": "nodes",
+            "type": "FlowNode[]",
+            "required": true
+          },
+          {
+            "name": "edges",
+            "type": "FlowEdge[]",
+            "required": true
+          },
+          {
+            "name": "script",
+            "type": "StoryStep[]",
+            "required": true,
+            "description": "Ordered steps: { from, to, label? } or { edge, reverse? }."
+          },
+          {
+            "name": "loop",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "stepDuration",
+            "type": "number",
+            "required": false,
+            "default": "1500"
+          },
+          {
+            "name": "stepGap",
+            "type": "number",
+            "required": false,
+            "default": "0",
+            "description": "Extra pause after each step before advancing (ms) — makes the story easier to follow."
+          },
+          {
+            "name": "playing",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "currentStep",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "onStepChange",
+            "type": "(step: number) => void",
+            "required": false
+          },
+          {
+            "name": "controls",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "autoPlay",
+            "type": "boolean",
+            "required": false,
+            "default": "true"
+          },
+          {
+            "name": "interactive",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "A storyline is a view by default — set true to allow selecting/dragging/connecting."
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "tokens": [
+          "--cascivo-color-surface",
+          "--cascivo-color-accent",
+          "--cascivo-color-text-muted"
+        ],
+        "accessibility": {
+          "role": "group",
+          "wcag": "2.1-AA",
+          "keyboard": ["Tab (focus controls)", "Enter/Space (play/pause, prev, next)"],
+          "reducedMotion": true
+        },
+        "examples": [
+          {
+            "title": "A request/response storyboard",
+            "description": "A<->B-->C: animate A→B, B→A, A→B, B→C, looping — each step fades in its caption.",
+            "code": "() => (\n  <FlowStory\n    style={{ height: 340 }}\n    nodes={[\n      { id: 'A', position: { x: 0, y: 100 }, data: { label: 'Client' } },\n      { id: 'B', position: { x: 240, y: 100 }, data: { label: 'Gateway' } },\n      { id: 'C', position: { x: 480, y: 100 }, data: { label: 'Service' } },\n    ]}\n    edges={[\n      { id: 'ab', source: 'A', target: 'B' },\n      { id: 'bc', source: 'B', target: 'C' },\n    ]}\n    script={[\n      { from: 'A', to: 'B', label: 'Request sent' },\n      { from: 'B', to: 'A', label: 'Acknowledged' },\n      { from: 'A', to: 'B', label: 'Payload streamed' },\n      { from: 'B', to: 'C', label: 'Forwarded to Service' },\n    ]}\n    loop\n  />\n)"
+          },
+          {
+            "title": "A linear pipeline",
+            "description": "Each stage animates and is captioned in turn.",
+            "code": "() => (\n  <FlowStory\n    style={{ height: 320 }}\n    nodes={[\n      { id: 'ingest', position: { x: 0, y: 100 }, data: { label: 'Ingest' } },\n      { id: 'transform', position: { x: 240, y: 100 }, data: { label: 'Transform' } },\n      { id: 'load', position: { x: 480, y: 100 }, data: { label: 'Load' } },\n    ]}\n    edges={[\n      { id: 'it', source: 'ingest', target: 'transform' },\n      { id: 'tl', source: 'transform', target: 'load' },\n    ]}\n    script={[\n      { from: 'ingest', to: 'transform', label: 'Records ingested', description: 'Raw events read from the source' },\n      { from: 'transform', to: 'load', label: 'Transformed', description: 'Cleaned and enriched' },\n    ]}\n  />\n)"
+          }
+        ],
+        "dependencies": ["@cascivo/core"],
+        "tags": ["flow", "animation", "storyline", "walkthrough", "sequence"],
+        "intent": {
+          "whenToUse": [
+            "Explaining how a flow works step by step, not just showing a static diagram",
+            "Onboarding, architecture walkthroughs, and request/response narratives"
+          ],
+          "whenNotToUse": [
+            "A static or freely-explorable graph — use <Flow>",
+            "A single always-on animated edge — set animated on a FlowEdge"
+          ],
+          "antiPatterns": [
+            {
+              "bad": "A requestAnimationFrame loop to sequence steps",
+              "good": "A currentStep signal advanced by a timer in useSignalEffect",
+              "why": "CLAUDE.md bans the useEffect-style loop; the signal+timer idiom is deterministic + testable."
+            }
+          ],
+          "related": [
+            {
+              "name": "Flow",
+              "relationship": "contains",
+              "reason": "Renders the graph the storyline animates."
+            },
+            {
+              "name": "FlowEdge",
+              "relationship": "pairs-with",
+              "reason": "Reuses the animated-edge keyframe per step."
+            }
+          ],
+          "a11yRationale": "The caption is an aria-live region announced each step; play/pause/prev/next make it keyboard-operable; travel motion is disabled under prefers-reduced-motion while captions are preserved.",
+          "flexibility": [
+            {
+              "area": "script",
+              "level": "flexible",
+              "note": "Serializable steps — { from, to } or { edge, reverse }."
+            },
+            {
+              "area": "playback",
+              "level": "flexible",
+              "note": "Controllable playing/currentStep; loop + per-step duration."
+            }
+          ]
+        }
+      },
+      "install": "@cascivo/flow"
     }
   ],
   "blocks": [