@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/flow/flow-edge.md

@@ -0,0 +1,128 @@
+# FlowEdge
+
+**Category:** display  
+**Description:** An SVG edge with bezier/straight/smoothstep paths, an arrowhead, an optional label, and animation.
+
+## When to use
+
+- Connecting two nodes with a directed path and arrowhead
+- Animating flow direction along a connection ("marching ants")
+
+## When NOT to use
+
+- For undirected relationships where an arrowhead would mislead — set markerEnd={false}
+
+## Anti-patterns
+
+### The compositor animates CSS for free; a JS loop re-renders every frame.
+
+**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 components
+
+- **FlowNode** (pairs-with): Edges connect nodes.
+- **FlowStory** (pairs-with): Storylines animate edges in sequence.
+
+## Accessibility rationale
+
+Decorative SVG (aria-hidden); animation is disabled under prefers-reduced-motion.
+
+## Props
+
+| Name          | Type                                     | Required | Default | Description                                                                           |
+| ------------- | ---------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
+| `sourceX`     | `number`                                 | Yes      | —       | Source anchor x (flow coords).                                                        |
+| `sourceY`     | `number`                                 | Yes      | —       | Y coordinate of the edge’s source point.                                              |
+| `targetX`     | `number`                                 | Yes      | —       | X coordinate of the edge’s target point.                                              |
+| `targetY`     | `number`                                 | Yes      | —       | Y coordinate of the edge’s target point.                                              |
+| `type`        | `'bezier' \| 'straight' \| 'smoothstep'` | No       | bezier  | Edge path style ('bezier' \| 'straight' \| 'smoothstep').                             |
+| `animated`    | `boolean`                                | No       | false   | When true, animates the edge path (dashed flow).                                      |
+| `label`       | `ReactNode`                              | No       | —       | Text label for the control.                                                           |
+| `selected`    | `boolean`                                | No       | false   | Whether the edge is rendered as selected.                                             |
+| `markerStart` | `boolean`                                | No       | false   | Arrowhead at the source (points back toward the source) — set both for bidirectional. |
+| `markerEnd`   | `boolean`                                | No       | true    | Arrowhead at the target. Set false for an undirected line.                            |
+| `className`   | `string`                                 | No       | —       | Additional CSS class names merged onto the root element.                              |
+
+## Tokens
+
+- `--cascivo-color-border-strong`
+- `--cascivo-color-accent`
+- `--cascivo-color-surface`
+
+## Examples
+
+### Edge path types
+
+Bezier, straight, smoothstep, and an animated edge.
+
+```jsx
+;() => (
+  <div style={{ position: 'relative', height: 220 }}>
+    <FlowEdge sourceX={20} sourceY={30} targetX={260} targetY={30} type="bezier" label="bezier" />
+    <FlowEdge sourceX={20} sourceY={90} targetX={260} targetY={90} type="smoothstep" label="step" />
+    <FlowEdge sourceX={20} sourceY={150} targetX={260} targetY={150} animated label="animated" />
+  </div>
+)
+```
+
+### Arrow direction
+
+Forward (default), backward, bidirectional, or undirected — via markerStart/markerEnd.
+
+```jsx
+;() => (
+  <div style={{ position: 'relative', height: 260 }}>
+    <FlowEdge sourceX={20} sourceY={30} targetX={260} targetY={30} label="forward" />
+    <FlowEdge
+      sourceX={20}
+      sourceY={90}
+      targetX={260}
+      targetY={90}
+      markerEnd={false}
+      markerStart
+      label="backward"
+    />
+    <FlowEdge sourceX={20} sourceY={150} targetX={260} targetY={150} markerStart label="both" />
+    <FlowEdge
+      sourceX={20}
+      sourceY={210}
+      targetX={260}
+      targetY={210}
+      markerEnd={false}
+      label="undirected"
+    />
+  </div>
+)
+```
+
+## Boundaries
+
+| Area      | Level    | Note                              |
+| --------- | -------- | --------------------------------- |
+| path      | flexible | bezier \| straight \| smoothstep. |
+| animation | flexible | Optional, reduced-motion-safe.    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo FlowEdge component (display). An SVG edge with bezier/straight/smoothstep paths, an arrowhead, an optional label, and animation.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+FlowEdge is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border-strong, --cascivo-color-accent, --cascivo-color-surface
+
+Accessibility: role "presentation", WCAG 2.1-AA. Keep it AA.
+Flexible: path, animation.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/flow/flow-handle.md

@@ -0,0 +1,83 @@
+# FlowHandle
+
+**Category:** display  
+**Description:** A connection port on a node edge — where edges attach and interactive connect starts.
+
+## When to use
+
+- Marking where edges connect to a node
+- Enabling interactive connect (drag from a source to a target)
+
+## When NOT to use
+
+- On nodes that are never connected
+
+## Related components
+
+- **FlowNode** (contained-by): Ports live inside a node.
+- **FlowEdge** (pairs-with): Edges anchor to handles.
+
+## Accessibility rationale
+
+Focusable with a ≥44px coarse-pointer hit area around the visible dot.
+
+## Props
+
+| Name            | Type                                     | Required | Default | Description                                                                 |
+| --------------- | ---------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- |
+| `type`          | `'source' \| 'target'`                   | Yes      | —       | Whether the handle is a connection source or target ('source' \| 'target'). |
+| `position`      | `'top' \| 'right' \| 'bottom' \| 'left'` | No       | —       | Edge of the node (defaults: source→right, target→left).                     |
+| `id`            | `string`                                 | No       | —       | Handle id for multi-handle nodes.                                           |
+| `isConnectable` | `boolean`                                | No       | true    | Whether new connections can start or end at this handle.                    |
+| `className`     | `string`                                 | No       | —       | Additional CSS class names merged onto the root element.                    |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-surface`
+- `--cascivo-target-min-coarse`
+
+## Examples
+
+### Source and target ports
+
+```jsx
+;() => (
+  <div style={{ position: 'relative', height: 160 }}>
+    <FlowNode id="api" defaultPosition={{ x: 70, y: 55 }}>
+      API
+      <FlowHandle type="target" position="left" />
+      <FlowHandle type="source" position="right" />
+    </FlowNode>
+  </div>
+)
+```
+
+## Boundaries
+
+| Area     | Level    | Note                            |
+| -------- | -------- | ------------------------------- |
+| position | flexible | top \| right \| bottom \| left. |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo FlowHandle component (display). A connection port on a node edge — where edges attach and interactive connect starts.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+FlowHandle is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-surface, --cascivo-target-min-coarse
+
+Accessibility: role "button", WCAG 2.1-AA, keyboard: Tab (focus the port). Keep it AA.
+Flexible: position.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/flow/flow-minimap.md

@@ -0,0 +1,89 @@
+# FlowMiniMap
+
+**Category:** display  
+**Description:** A scaled SVG overview of the graph with a draggable viewport rectangle.
+
+## When to use
+
+- Orienting users in a large graph
+- Letting users jump around by dragging the view rect
+
+## When NOT to use
+
+- Tiny graphs that fit on screen
+
+## Related components
+
+- **FlowControls** (pairs-with): Complementary navigation chrome.
+
+## Accessibility rationale
+
+role="img" with an i18n-defaulted label describing the overview.
+
+## Props
+
+| Name               | Type                                                           | Required | Default      | Description                                               |
+| ------------------ | -------------------------------------------------------------- | -------- | ------------ | --------------------------------------------------------- |
+| `nodes`            | `FlowNode[]`                                                   | Yes      | —            | The nodes to render.                                      |
+| `viewport`         | `Viewport`                                                     | Yes      | —            | The current pan/zoom viewport to reflect in the minimap.  |
+| `containerWidth`   | `number`                                                       | No       | —            | Width of the flow container, used to scale the minimap.   |
+| `containerHeight`  | `number`                                                       | No       | —            | Height of the flow container, used to scale the minimap.  |
+| `width`            | `number`                                                       | No       | 200          | Width of the component.                                   |
+| `height`           | `number`                                                       | No       | 150          | Height of the component.                                  |
+| `position`         | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | No       | bottom-right | Position of the component.                                |
+| `onViewportChange` | `(viewport: Viewport) => void`                                 | No       | —            | Called with the new viewport when the minimap is dragged. |
+| `className`        | `string`                                                       | No       | —            | Additional CSS class names merged onto the root element.  |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-accent`
+
+## Examples
+
+### Graph overview
+
+```jsx
+;() => (
+  <FlowMiniMap
+    nodes={[
+      { id: 'a', position: { x: 0, y: 0 } },
+      { id: 'b', position: { x: 220, y: 120 } },
+      { id: 'c', position: { x: 440, y: 0 } },
+    ]}
+    viewport={{ x: 0, y: 0, zoom: 1 }}
+    containerWidth={400}
+    containerHeight={300}
+  />
+)
+```
+
+## Boundaries
+
+| Area | Level    | Note                       |
+| ---- | -------- | -------------------------- |
+| size | flexible | Configurable width/height. |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo FlowMiniMap component (display). A scaled SVG overview of the graph with a draggable viewport rectangle.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+FlowMiniMap is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border-strong, --cascivo-color-accent
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+Flexible: size.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/flow/flow-node.md

@@ -0,0 +1,97 @@
+# FlowNode
+
+**Category:** display  
+**Description:** An HTML node box positioned in the viewport pane — draggable, selectable, with arbitrary children.
+
+## When to use
+
+- Representing a unit in a graph that holds arbitrary themed content
+- When you hand-compose a flow and need draggable, selectable boxes
+
+## When NOT to use
+
+- For the common case — the declarative <Flow> renders nodes for you
+
+## Anti-patterns
+
+### HTML nodes inherit the data-theme scope and can contain any cascivo component.
+
+**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 components
+
+- **FlowHandle** (contains): Connection ports live inside a node.
+- **FlowEdge** (pairs-with): Edges route between nodes.
+
+## Accessibility rationale
+
+Focusable group; Enter/Space select. Visual states (hover/focus/selected) are CSS.
+
+## Props
+
+| Name               | Type                             | Required | Default | Description                                                                 |
+| ------------------ | -------------------------------- | -------- | ------- | --------------------------------------------------------------------------- |
+| `id`               | `string`                         | Yes      | —       | Stable node id.                                                             |
+| `position`         | `{ x: number; y: number }`       | No       | —       | Position in flow coords (controllable).                                     |
+| `onPositionChange` | `(position: XYPosition) => void` | No       | —       | Fired while dragging.                                                       |
+| `zoom`             | `number`                         | No       | 1       | Current zoom (drag deltas are divided by it).                               |
+| `selected`         | `boolean`                        | No       | false   | Whether the node is rendered as selected.                                   |
+| `draggable`        | `boolean`                        | No       | true    | Whether the node can be dragged.                                            |
+| `interactive`      | `boolean`                        | No       | true    | When false, the node is view-only: not draggable, selectable, or focusable. |
+| `onSelect`         | `(id: string) => void`           | No       | —       | Called with the selected value.                                             |
+| `children`         | `ReactNode`                      | No       | —       | Any cascivo content.                                                        |
+| `className`        | `string`                         | No       | —       | Additional CSS class names merged onto the root element.                    |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-radius-md`
+- `--cascivo-shadow-sm`
+
+## Examples
+
+### A draggable node
+
+```jsx
+;() => (
+  <div style={{ position: 'relative', height: 160 }}>
+    <FlowNode id="a" defaultPosition={{ x: 40, y: 50 }}>
+      Service A
+    </FlowNode>
+  </div>
+)
+```
+
+## Boundaries
+
+| Area     | Level    | Note                                |
+| -------- | -------- | ----------------------------------- |
+| content  | flexible | Renders any children.               |
+| position | flexible | Controllable; draggable toggleable. |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo FlowNode component (display). An HTML node box positioned in the viewport pane — draggable, selectable, with arbitrary children.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+FlowNode is strictly bound to these tokens — use only these, do not invent token names:
+  --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). Keep it AA.
+Flexible: content, position.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/flow/flow-panel.md

@@ -0,0 +1,75 @@
+# FlowPanel
+
+**Category:** display  
+**Description:** An absolutely-positioned slot for custom flow-canvas UI (legend, toolbar).
+
+## When to use
+
+- Overlaying custom UI (a legend, a toolbar) on a flow canvas
+
+## When NOT to use
+
+- For zoom/fit controls — use FlowControls
+
+## Related components
+
+- **FlowControls** (alternative): Purpose-built zoom/fit chrome.
+
+## Accessibility rationale
+
+A plain positioned container; semantics come from its children.
+
+## Props
+
+| Name        | Type                                                                                              | Required | Default   | Description                                              |
+| ----------- | ------------------------------------------------------------------------------------------------- | -------- | --------- | -------------------------------------------------------- |
+| `position`  | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | No       | top-right | Position of the component.                               |
+| `children`  | `ReactNode`                                                                                       | No       | —         | Content rendered inside the component.                   |
+| `className` | `string`                                                                                          | No       | —         | Additional CSS class names merged onto the root element. |
+
+## Tokens
+
+- `--cascivo-space-3`
+
+## Examples
+
+### A legend panel
+
+```jsx
+;() => (
+  <div
+    style={{ position: 'relative', height: 160, border: '1px solid var(--cascivo-color-border)' }}
+  >
+    <FlowPanel position="top-right">Legend</FlowPanel>
+  </div>
+)
+```
+
+## Boundaries
+
+| Area     | Level    | Note                  |
+| -------- | -------- | --------------------- |
+| position | flexible | Six anchor positions. |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo FlowPanel component (display). An absolutely-positioned slot for custom flow-canvas UI (legend, toolbar).
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+FlowPanel is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-3
+
+Accessibility: role "group", WCAG 2.1-AA. Keep it AA.
+Flexible: position.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/flow/flow-story.md

@@ -0,0 +1,145 @@
+# FlowStory
+
+**Category:** display  
+**Description:** A scripted, sequenced, looping flow animation — walks a graph step by step with fade-in captions.
+
+## When to use
+
+- Explaining how a flow works step by step, not just showing a static diagram
+- Onboarding, architecture walkthroughs, and request/response narratives
+
+## When NOT to use
+
+- A static or freely-explorable graph — use <Flow>
+- A single always-on animated edge — set animated on a FlowEdge
+
+## Anti-patterns
+
+### CLAUDE.md bans the useEffect-style loop; the signal+timer idiom is deterministic + testable.
+
+**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 components
+
+- **Flow** (contains): Renders the graph the storyline animates.
+- **FlowEdge** (pairs-with): Reuses the animated-edge keyframe per step.
+
+## Accessibility rationale
+
+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.
+
+## Props
+
+| Name           | Type                     | Required | Default | Description                                                                           |
+| -------------- | ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------- |
+| `nodes`        | `FlowNode[]`             | Yes      | —       | The nodes to render.                                                                  |
+| `edges`        | `FlowEdge[]`             | Yes      | —       | The edges to render at each step.                                                     |
+| `script`       | `StoryStep[]`            | Yes      | —       | Ordered steps: { from, to, label? } or { edge, reverse? }.                            |
+| `loop`         | `boolean`                | No       | true    | When true, navigation wraps around from end to start.                                 |
+| `stepDuration` | `number`                 | No       | 1500    | How long (ms) each step is shown during playback.                                     |
+| `stepGap`      | `number`                 | No       | 0       | Extra pause after each step before advancing (ms) — makes the story easier to follow. |
+| `playing`      | `boolean`                | No       | —       | Whether the story is currently playing (controlled).                                  |
+| `currentStep`  | `number`                 | No       | —       | The controlled current step index.                                                    |
+| `onStepChange` | `(step: number) => void` | No       | —       | Called with the new step index when it changes.                                       |
+| `controls`     | `boolean`                | No       | true    | Whether to show the controls.                                                         |
+| `autoPlay`     | `boolean`                | No       | true    | When true, starts playback automatically on mount.                                    |
+| `interactive`  | `boolean`                | No       | false   | A storyline is a view by default — set true to allow selecting/dragging/connecting.   |
+| `className`    | `string`                 | No       | —       | Additional CSS class names merged onto the root element.                              |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-accent`
+- `--cascivo-color-text-muted`
+
+## Examples
+
+### A request/response storyboard
+
+A<->B-->C: animate A→B, B→A, A→B, B→C, looping — each step fades in its caption.
+
+```jsx
+;() => (
+  <FlowStory
+    style={{ height: 340 }}
+    nodes={[
+      { id: 'A', position: { x: 0, y: 100 }, data: { label: 'Client' } },
+      { id: 'B', position: { x: 240, y: 100 }, data: { label: 'Gateway' } },
+      { id: 'C', position: { x: 480, y: 100 }, data: { label: 'Service' } },
+    ]}
+    edges={[
+      { id: 'ab', source: 'A', target: 'B' },
+      { id: 'bc', source: 'B', target: 'C' },
+    ]}
+    script={[
+      { from: 'A', to: 'B', label: 'Request sent' },
+      { from: 'B', to: 'A', label: 'Acknowledged' },
+      { from: 'A', to: 'B', label: 'Payload streamed' },
+      { from: 'B', to: 'C', label: 'Forwarded to Service' },
+    ]}
+    loop
+  />
+)
+```
+
+### A linear pipeline
+
+Each stage animates and is captioned in turn.
+
+```jsx
+;() => (
+  <FlowStory
+    style={{ height: 320 }}
+    nodes={[
+      { id: 'ingest', position: { x: 0, y: 100 }, data: { label: 'Ingest' } },
+      { id: 'transform', position: { x: 240, y: 100 }, data: { label: 'Transform' } },
+      { id: 'load', position: { x: 480, y: 100 }, data: { label: 'Load' } },
+    ]}
+    edges={[
+      { id: 'it', source: 'ingest', target: 'transform' },
+      { id: 'tl', source: 'transform', target: 'load' },
+    ]}
+    script={[
+      {
+        from: 'ingest',
+        to: 'transform',
+        label: 'Records ingested',
+        description: 'Raw events read from the source',
+      },
+      { from: 'transform', to: 'load', label: 'Transformed', description: 'Cleaned and enriched' },
+    ]}
+  />
+)
+```
+
+## Boundaries
+
+| Area     | Level    | Note                                                        |
+| -------- | -------- | ----------------------------------------------------------- |
+| script   | flexible | Serializable steps — { from, to } or { edge, reverse }.     |
+| playback | flexible | Controllable playing/currentStep; loop + per-step duration. |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo FlowStory component (display). A scripted, sequenced, looping flow animation — walks a graph step by step with fade-in captions.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+FlowStory is strictly bound to these tokens — use only these, do not invent token names:
+  --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). Keep it AA.
+Flexible: script, playback.
+
+Do not invent props, tokens, or global viewport media queries.
+```