npm - @caddis/cli - Versions diffs - 0.0.0 → 0.1.0 - Mend

@caddis/cli 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (153) hide show

package/bundles/antigravity-plugin/skills/mockup/SKILL.md ADDED Viewed

@@ -0,0 +1,242 @@
+---
+name: mockup
+description: Create framework-aware UI mockups with feasibility checks. Prevents wasted effort by validating that proposed designs work within the target framework's constraints.
+---
+# Mockup Skill
+## Purpose
+Create visual mockups (HTML/SVG) for UI features with **mandatory framework feasibility validation**. This skill exists because of a real incident: a beautiful HTML mockup was created for a Streamlit app using `position: fixed` — which doesn't work in Streamlit's DOM. 24 hours were wasted discovering this.
+**This skill prevents that class of failure for ANY framework.**
+---
+## When to Use
+- Creating a UI mockup for a proposed feature
+- Visualizing a design before implementation
+- Producing a reference artifact for implementing agents
+- When `@ux-designer` routes mockup creation here
+---
+## Steps
+### Step 1: Read Project Context
+1. Read `project-config.md` → identify:
+   - **Frontend framework** (Streamlit, React, Vue, Angular, Next.js, etc.)
+   - **Brand colors** (from profile or placeholder values)
+   - **CSS conventions** (scoping method, custom properties, etc.)
+2. Read `copilot-instructions.md` → identify:
+   - Existing component patterns
+   - Framework-specific conventions already documented
+3. If a `chain_id` is provided, read the Intent Document from `agent-docs/intents/`
+### Step 2: Framework Feasibility Check (MANDATORY)
+**Before creating ANY mockup, validate that the proposed design is feasible in the target framework.**
+Run through this checklist:
+| Check | Question | If NO |
+|-------|----------|-------|
+| **DOM Control** | Does the framework give you full control over the DOM? | Identify which HTML/CSS features are restricted |
+| **Positioning** | Does `position: fixed/absolute` work as expected? | Document the limitation and alternative approach |
+| **Custom HTML** | Can you inject arbitrary HTML/JS? | Identify the framework's component/extension API |
+| **Event Handling** | Can you attach custom JS event listeners? | Document how events work in this framework |
+| **Styling** | Can you use global CSS freely? | Document CSS scoping constraints |
+| **Third-party Libraries** | Can you load external JS/CSS? | Check if air-gapped deployment restricts this |
+#### Known Framework Constraints
+| Framework | Key Constraints |
+|-----------|----------------|
+| **Streamlit** | No `position: fixed/absolute` (DOM wrapping breaks it). No arbitrary HTML injection without `components.html()` or `declare_component()`. CSS is scoped — use `st.container(key=)` + `.st-key-` selectors. No external CDN in air-gapped environments. |
+| **React** | JSX required. CSS-in-JS or CSS Modules typical. Virtual DOM diffing may interfere with manual DOM manipulation. |
+| **Vue** | Template syntax. Scoped styles by default. `v-html` for raw HTML but XSS risk. |
+| **Gradio** | Similar DOM constraints to Streamlit. Limited CSS control. Use `gr.HTML()` for custom elements. |
+| **Next.js** | SSR considerations. `useEffect` needed for client-only code. CSS Modules or Tailwind typical. |
+> **If ANY constraint would prevent the proposed design from working:**
+> 1. **STOP** — do not create a mockup that can't be implemented
+> 2. **WARN** the user with specific details about what won't work and why
+> 3. **PROPOSE ALTERNATIVES** that work within the framework's constraints
+> 4. **Get confirmation** before proceeding with an alternative approach
+### Step 3: Create the Mockup
+**Output format**: HTML file (preferred for interactive mockups) or SVG (for static layouts)
+**Requirements:**
+- Use brand colors from `project-config.md` (never hardcode colors — use CSS custom properties)
+- Include responsive behavior if applicable
+- Add comments explaining key layout decisions
+- If the mockup uses workarounds for framework constraints, document them clearly in comments
+**HTML mockup template:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{Feature Name} — Mockup</title>
+    <style>
+        /* Brand colors from project-config.md */
+        :root {
+            --brand-primary: {<BRAND_PRIMARY>};
+            --brand-dark: {<BRAND_DARK>};
+            --brand-light: {<BRAND_LIGHT>};
+            /* Additional colors from profile */
+        }
+        /* Mockup styles */
+        /* ... */
+    </style>
+</head>
+<body>
+    <!-- MOCKUP: {Feature description} -->
+    <!-- FRAMEWORK: {Target framework} -->
+    <!-- CONSTRAINTS: {Any framework constraints that shaped this design} -->
+    <!-- ALTERNATIVES: {If using a workaround, what was the original approach and why it wouldn't work} -->
+    <!-- Mockup content -->
+</body>
+</html>
+```
+### Step 3b: Implementation-Annotated Mockup (MANDATORY for handoff to implementing agents)
+When the mockup will be handed off to `@implement`, `@frontend-developer`, or `@streamlit-developer`, embed **implementation annotations** throughout the HTML so the implementing agent knows exactly what to build without guessing.
+#### Annotation Types
+Use these four comment patterns consistently:
+**1. Component annotations** — Which framework component implements this visual element:
+```html
+<!-- React: <KpiFlipCard product="broadband" data={surveys.broadband}
+     trendData={trend.historicalNPS.byProduct.broadband} /> -->
+<!-- React: <ResponsiveContainer width="100%" height={260}>
+     <AreaChart data={trendData}><Area type="monotone" dataKey="nps" ... /></AreaChart>
+     </ResponsiveContainer> -->
+<!-- React: import { ScoreChip, DeltaBadge, SparkBar, TrendDot } from '@/components/table-cells' -->
+```
+**2. Data source annotations** — Which JSON key / API response field provides the data:
+```html
+<!-- DATA-SOURCE: surveys.broadband.nps, surveys.broadband.responses -->
+<!-- DATA-SOURCE: trend.historicalNPS.byProduct.broadband (array of monthly values) -->
+<!-- DATA-SOURCE: ceoInsight.headline, ceoInsight.keyFindings[] (objects with title, detail) -->
+```
+**3. Implementation notes** — Broader guidance for the implementing agent:
+```html
+<!-- IMPLEMENTATION NOTE [DATA-SOURCE]: This section uses hardcoded mock values for
+     layout reference. React implementation must fetch period-filtered data from the
+     /api/nps/overview endpoint and compute all KPIs dynamically. -->
+<!-- IMPLEMENTATION NOTE [CHART]: Use Recharts AreaChart with gradient fill.
+     Spread CHART_DEFAULTS from chartTheme.ts. No axes/grid for sparkline variant. -->
+<!-- IMPLEMENTATION NOTE [ANIMATION]: Use framer-motion rotateY for card flip.
+     duration: 0.52, ease: [0.4, 0.2, 0.2, 1]. backfaceVisibility: "hidden". -->
+```
+**4. Styling annotations** — Which design tokens, CSS vars, or Tailwind classes to use:
+```html
+<!-- STYLE: bg-surface-card (var(--surface-card)), shadow-card, rounded-lg (var(--r-lg)) -->
+<!-- STYLE: Fill color uses var(--status-red) for detractor, var(--status-green) for promoter -->
+<!-- STYLE: Tailwind: text-ink-primary font-heading text-2xl font-bold -->
+```
+#### Annotation Placement Rules
+1. Place **component annotations** directly above or inside the HTML element that the component replaces
+2. Place **data source annotations** on the element that displays the data value
+3. Place **implementation notes** at the top of each major section (tab, panel, card group)
+4. Place **styling annotations** on elements where the visual appearance matters and the token name isn't obvious from the CSS
+5. Every hardcoded value in the mockup (numbers, text, colors) that will be dynamic in production MUST have a data source annotation
+#### Example: Annotated KPI Card
+```html
+<!-- React: <KpiFlipCard product="broadband" data={surveys.broadband}
+     trendData={trend.historicalNPS.byProduct.broadband} color={COLORS.broadband} /> -->
+<!-- DATA-SOURCE: surveys.broadband.nps (current score), surveys.broadband.responses (count) -->
+<!-- STYLE: var(--surface-card) bg, var(--shadow-card) shadow, 3px left border using COLORS.broadband -->
+<div class="kpi-card">
+    <div class="kpi-score">+32</div>  <!-- DATA-SOURCE: surveys.broadband.nps -->
+    <div class="kpi-delta">▲ 2.1</div>  <!-- DATA-SOURCE: deriveMom(trend.historicalNPS.byProduct.broadband) -->
+    <div class="kpi-responses">1,247 responses</div>  <!-- DATA-SOURCE: surveys.broadband.responses -->
+    <div class="sparkline">
+        <!-- React: <Sparkline data={trend.historicalNPS.byProduct.broadband}
+             color={COLORS.broadband} height={72} /> -->
+        <!-- IMPLEMENTATION NOTE [CHART]: Recharts AreaChart, no axes/grid/tooltip,
+             gradient fill from color at opacity 0.3 to opacity 0. -->
+    </div>
+</div>
+```
+#### Completeness Check
+Before saving the mockup, verify:
+- [ ] Every visual section has at least one **component annotation**
+- [ ] Every dynamic value has a **data source annotation** with the exact JSON path
+- [ ] Every chart/graph has an **implementation note** specifying the chart library and config
+- [ ] The implementing agent can build the feature using ONLY the mockup + annotations (no guessing)
+### Step 4: Write Artifact
+1. Save the mockup file to `agent-docs/ux/mockups/{feature-slug}.html` (or `.svg`)
+2. Add YAML header to a companion markdown file or embed as HTML comment:
+   ```yaml
+   agent: ux-designer
+   created: {date}
+   status: current
+   chain_id: {chain_id if provided}
+   approval: pending
+   framework: {target framework}
+   feasibility_warnings: {list any constraints encountered}
+   ```
+3. Update `agent-docs/ARTIFACTS.md` manifest with the new entry
+### Step 5: Report
+Provide:
+- Path to the mockup file
+- Framework feasibility summary (what was checked, any warnings)
+- Implementation notes for the agent that will build this (which API/component to use, what CSS approach works)
+- If alternatives were chosen, explain why the original approach wouldn't work
+---
+## Framework Feasibility Quick Reference
+### Streamlit-Specific
+| Want to do | Don't use | Instead use |
+|-----------|-----------|-------------|
+| Floating element (chat widget, FAB) | `position: fixed/absolute` | `declare_component()` with custom HTML/JS |
+| Custom styled container | Global CSS | `st.container(key="name")` + `.st-key-name` selector |
+| Modal/overlay | `z-index` + absolute positioning | `st.dialog()` (Streamlit 1.33+) or `st.modal()` |
+| Sidebar content | Custom sidebar HTML | `st.sidebar` API |
+| Custom header | Fixed position header | `st.container()` at top + CSS with `st.container(key=)` |
+| External JavaScript | `<script src="cdn...">` | Bundle locally for air-gapped; use `components.html()` |
+### React-Specific
+| Want to do | Watch out for | Recommended approach |
+|-----------|---------------|---------------------|
+| Direct DOM manipulation | React re-renders will overwrite | Use refs (`useRef`) or state-driven rendering |
+| Global styles | May conflict with component styles | CSS Modules, styled-components, or Tailwind |
+| Third-party widgets | jQuery plugins fight React | Find React-native alternatives or wrap in `useEffect` |
+---
+## Important Notes
+- This skill is designed to be loaded by `@ux-designer` or `@frontend-developer` agents
+- The framework constraint tables should be extended as new frameworks and gotchas are discovered
+- Always check `project-config.md` for the deployment environment — air-gapped deployments restrict external dependencies

package/bundles/antigravity-plugin/skills/particle-art/SKILL.md ADDED Viewed

@@ -0,0 +1,243 @@
+---
+name: particle-art
+version: 1.0.0
+description: Generate animated particle art React/Next.js components — zero dependencies, spring physics, CSS-variable theming, DPR-correct canvas, mouse interaction. Use when the user wants animated hero art, a living logo, a branded initial or monogram, a constellation background, or any "particles that form a shape". Triggers on "particle animation", "node network", "animated letter/logo/initials", "living letter", "morphing particles", "constellation", "neural net art", "dot field", "stipple portrait", "halftone animation", "ASCII art animation", "background art for my site", or "art that reacts to mouse". Covers — text/initials → spring-node letter; preset patterns (constellation, helix, spiral, DNA, hex-grid, wave, infinity); custom SVG paths; custom polygon points; Unicode halftone stipple; Gaussian dot field with sparks; SVG circuit traces; hybrid combos. Outputs a complete, self-contained, copy-paste-ready React component. Prefer this over p5.js (zero-dep, React-native, TypeScript), tsParticles (richer spring physics, CSS-var theming), Three.js (lightweight, no WebGL).
+---
+# Particle Art Generator
+Produces animated React components using one of four rendering styles, each themeable via CSS custom properties and interactive via mouse. Zero npm dependencies — pure canvas and SVG.
+## Reference Files (read when needed)
+| File | Read when |
+|------|-----------|
+| `references/canvas-utils.ts` | Starting any canvas-based component (DPR setup, theme colours, RAF loop) |
+| `references/shape-sampler.ts` | Building target points for any shape — text, presets, SVG path, polygon |
+| `references/node-shape.template.tsx` | Generating a **spring-node** component (repel/attract interaction) |
+| `references/stipple.template.tsx` | Generating a **stipple** (Unicode halftone, static cloud) component |
+| `references/stipple-morph.template.tsx` | Generating a **stipple-morph** component (halftone cloud → letter on hover) |
+| `references/dot-field.template.tsx` | Generating a **dot-field** component |
+| `references/trail-ghost.template.tsx` | Generating a **trail-ghost** component (spring-morph + phosphorescent trails) |
+| `references/flow-field.template.tsx` | Generating a **flow-field** component (value-noise currents + letter assembly) |
+| `references/usage-examples.md` | Checking finished examples before delivering |
+---
+## Step 0 — Gather Requirements
+Ask (or infer from context) these five things before writing any code:
+1. **Shape** — What should the particles form?
+   - Text / initials: `"j"`, `"JS"`, `"AI"`, `"hello"`, any Unicode char or emoji
+   - Preset: `constellation` `helix` `spiral` `dna` `hexgrid` `wave` `infinity`
+   - Custom: SVG `d` path string, or `[x,y]` polygon coordinate array
+   - Abstract: no fixed shape (ambient cloud)
+2. **Style** — Which rendering engine?
+   - `spring-nodes` — canvas nodes spring to shape + ambient network (best for letters/logos, repel interaction)
+   - `morph-nodes` — nodes scatter in idle, coalesce into letter/shape on hover (best for "appear on demand")
+   - `stipple` — animated Unicode character halftone static cloud (best for atmospheric dot portraits)
+   - `stipple-morph` — halftone cloud that resolves into a letter/shape on hover (best for atmospheric + interactive)
+   - `dot-field` — Gaussian canvas dot cloud with sparks (best for cosmic/diffuse feel)
+   - `trail-ghost` — spring-morph nodes with phosphorescent trailing smears (best for ethereal/ghostly feel)
+   - `flow-field` — value-noise particle currents, assembles into letter on hover (best for organic/fluid feel)
+   - `circuit` — SVG grid traces with traveling pulses (best for tech/infrastructure feel)
+   - `hybrid` — spring-nodes foreground + dot-field background (most dramatic)
+3. **Size** — `sm` (240px) · `md` (300px) · `lg` (380px) · `xl` (480px) · or a number
+4. **Colors** — `theme-vars` (default, CSS custom props) · `[primary, secondary]` hex pair · `monochrome`
+5. **Interaction** — `repel` (default) · `attract` · `orbit` · `none`
+If the user hasn't stated a style, recommend `spring-nodes` for text/initials, `dot-field` for abstract, `stipple` for atmospheric, `circuit` for technical backgrounds.
+---
+## Step 1 — Select and Read Reference Files
+Read the canvas-utils and the template that matches the chosen style. Always read canvas-utils first — it has the DPR setup and theme colour helpers used by all canvas components.
+For shape types:
+- **text / initials / preset / polygon / SVG path** → read `shape-sampler.ts` for the correct `sampleShape()` call
+- **abstract** → skip shape-sampler; use ambient-only config in the node-shape template
+---
+## Step 2 — Build the Component
+### Naming Convention
+```
+<Subject><Style>Art.tsx
+// Examples:
+JSpringArt.tsx       // letter "j", spring-nodes
+ConstellationArt.tsx // preset constellation
+HeroNodeArt.tsx      // abstract spring-nodes for a hero section
+```
+### File Structure
+```tsx
+"use client";
+// 1. Imports (React only — no external deps)
+// 2. Constants (physics params, sizing)
+// 3. Shape builder function (calls sampleShape or defines points inline)
+// 4. Component (useEffect → canvas setup → RAF loop → cleanup)
+// 5. Export
+```
+### Physics Parameters by Use-Case
+| Use-case | spring | friction | drift | linkDist | ambientN |
+|----------|--------|----------|-------|----------|----------|
+| Single letter | 0.036 | 0.88 | 0.06 | 72 | 14 |
+| Short word (2-4 chars) | 0.030 | 0.90 | 0.04 | 60 | 8 |
+| Long word / phrase | 0.025 | 0.92 | 0.03 | 50 | 4 |
+| Abstract / no shape | — | 0.985 | — | 82 | all |
+| Constellation preset | 0.012 | 0.94 | 0.05 | 90 | 6 |
+### Node Count Guidelines
+| Shape | Recommended node count |
+|-------|----------------------|
+| Single letter (j, A) | 22–30 letter + 14–18 ambient |
+| Two letters (JS, AI) | 35–45 letter + 12 ambient |
+| Word ≤6 chars | 50–70 letter + 8 ambient |
+| Preset shape | 28–40 |
+| Abstract cloud | 32–48 ambient only |
+---
+## Step 3 — Adapt for the Project's Theme System
+### CSS-Variable Theming (default, always prefer this)
+```ts
+// Read in the RAF loop — auto-updates on theme change
+function themeRgb(v: string): [number, number, number] {
+  const ch = getComputedStyle(document.documentElement)
+    .getPropertyValue(v).trim().split(/\s+/).map(Number);
+  return [ch[0], ch[1], ch[2]];
+}
+// Usage: themeRgb("--accent-strong") → [79, 209, 197]
+```
+Standard variable names (work with Tailwind CSS-variable setups):
+- `--accent-strong` — primary / brightest nodes, tittle glow
+- `--accent-soft` — secondary / lines and ambient nodes
+- `--fg` — foreground text colour (fallback for monochrome)
+- `--bg` — background (for any fill-behind effects)
+If the project uses different variable names, ask the user or check `globals.css`.
+### Hex / Custom Colors
+```ts
+function hexToRgb(hex: string): [number, number, number] {
+  const n = parseInt(hex.replace('#',''), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+// Hard-code in the RAF loop instead of reading CSS vars
+```
+---
+## Step 4 — Interaction Modes
+### Repel (default)
+```ts
+const mdx = p.x - mx, mdy = p.y - my;
+const md = Math.sqrt(mdx*mdx + mdy*mdy);
+if (md < REPEL_R && md > 0) {
+  const f = ((REPEL_R - md) / REPEL_R) * REPEL_F;
+  p.vx += (mdx / md) * f;
+  p.vy += (mdy / md) * f;
+}
+```
+### Attract
+```ts
+// Same but subtract instead of add
+p.vx -= (mdx / md) * f;
+p.vy -= (mdy / md) * f;
+```
+### Orbit
+```ts
+// Apply tangential force (perpendicular to cursor vector)
+p.vx += (-mdy / md) * f * 0.6;
+p.vy += ( mdx / md) * f * 0.6;
+```
+### Spring-back (always apply for letter nodes)
+```ts
+p.vx += (p.tx - p.x) * SPRING;
+p.vy += (p.ty - p.y) * SPRING;
+p.vx *= FRICTION;
+p.vy *= FRICTION;
+```
+---
+## Step 5 — Accessibility & Performance
+Always include:
+```tsx
+<canvas aria-hidden="true" />          // decorative, not content
+```
+Reduced-motion support — draw a static frame then return; never return before drawing:
+```ts
+const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+// ... build pts, set up canvas, build mouse listeners ...
+if (reduced) {
+  // Snap shape nodes to their targets and draw one static frame
+  pts.forEach(p => { if (p.isShape) { p.x = p.tx; p.y = p.ty; } });
+  tick();                  // draw once
+  cancelAnimationFrame(raf); // immediately cancel the RAF tick queued inside
+  return;
+}
+// Full animation loop starts here
+```
+⚠️ Never `return` before drawing for canvas components — that leaves the canvas blank, which is worse than any animation.
+Performance rules:
+- Read `getComputedStyle` **inside** the RAF loop (theme changes auto-apply, ~0.02ms/call)
+- Use `devicePixelRatio` for crisp retina rendering (see canvas-utils)
+- Clean up with `cancelAnimationFrame` and remove event listeners in the return callback
+- Cap velocity: `if (spd > MAX_SPEED) { vx *= MAX_SPEED/spd; vy *= MAX_SPEED/spd; }`
+---
+## Step 6 — Deliver
+Output the complete component file, then show the import + usage:
+```tsx
+// Usage in any React/Next.js component:
+import { MyArt } from "@/components/art/MyArt";
+// In JSX:
+<MyArt size={360} />
+// For Next.js App Router pages — component already has "use client"
+// For hero sections — wrap in a hidden-on-mobile div:
+<div className="hidden lg:flex items-center justify-center">
+  <MyArt size={360} />
+</div>
+```
+---
+## Quality Checklist
+Before delivering, verify:
+- [ ] `"use client"` at the top
+- [ ] Canvas size set with `devicePixelRatio` scaling (from canvas-utils)
+- [ ] `cancelAnimationFrame` + `removeEventListener` in useEffect cleanup
+- [ ] `aria-hidden="true"` on the canvas/container
+- [ ] `themeRgb()` reads CSS vars inside RAF loop (not outside)
+- [ ] Mouse leaves handled (`mouseleave` resets to off-screen coords)
+- [ ] Velocity capped to `MAX_SPEED`
+- [ ] For letter nodes: spring force applied + damped FRICTION (not AMBIENT_FRICTION)
+- [ ] TypeScript types — no `any`, interfaces for Pt/Dot/Spark
+- [ ] Prefers-reduced-motion check
+- [ ] Component is self-contained (no imports beyond React)

package/bundles/antigravity-plugin/skills/particle-art/references/canvas-utils.ts ADDED Viewed

@@ -0,0 +1,171 @@
+/**
+ * canvas-utils.ts — Shared canvas helpers for all particle-art components.
+ *
+ * Copy the functions you need directly into your component file.
+ * These are NOT meant to be imported as a module — they are reference implementations.
+ */
+// ─── DPR-Correct Canvas Setup ────────────────────────────────────────────────
+//
+// Must be called in useEffect, AFTER the canvas ref is attached.
+// Returns the 2D context; the canvas is scaled so all drawing coordinates
+// are in CSS pixels (no need to multiply by dpr elsewhere).
+//
+// Usage:
+//   const ctx = setupCanvas(ref.current!, size);
+//
+export function setupCanvas(
+  el: HTMLCanvasElement,
+  size: number,
+): CanvasRenderingContext2D {
+  const ctx = el.getContext("2d")!;
+  const dpr = window.devicePixelRatio || 1;
+  el.width = size * dpr;
+  el.height = size * dpr;
+  ctx.scale(dpr, dpr);
+  return ctx;
+}
+// ─── Theme-Aware Colour Reading ───────────────────────────────────────────────
+//
+// Reads a CSS custom property (e.g. "--accent-strong") and returns [R, G, B].
+// The value must be space-separated channels: "79 209 197".
+// Call this INSIDE the RAF loop so theme changes (light/dark toggle) auto-apply.
+//
+// Standard variable names for projects using CSS-variable design tokens:
+//   "--accent-strong"  →  primary colour (brightest nodes, tittle glow)
+//   "--accent-soft"    →  secondary colour (lines, ambient nodes)
+//   "--fg"             →  foreground / text colour
+//   "--bg"             →  page background
+//
+export function themeRgb(varName: string): [number, number, number] {
+  const raw = getComputedStyle(document.documentElement)
+    .getPropertyValue(varName)
+    .trim()
+    .split(/\s+/)
+    .map(Number);
+  return [raw[0] ?? 100, raw[1] ?? 100, raw[2] ?? 100];
+}
+// Convenience: build a CSS rgba() string from a themeRgb result + alpha
+export function rgba(
+  [r, g, b]: [number, number, number],
+  alpha: number,
+): string {
+  return `rgba(${r},${g},${b},${alpha.toFixed(3)})`;
+}
+// ─── Hex Colour Fallback ──────────────────────────────────────────────────────
+//
+// Use when the project does NOT have CSS custom properties.
+// Pass hex strings in the component's props and convert once.
+//
+export function hexToRgb(hex: string): [number, number, number] {
+  const n = parseInt(hex.replace("#", ""), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+// ─── Mouse Tracking ───────────────────────────────────────────────────────────
+//
+// Returns a ref-compatible object and attaches listeners to the canvas.
+// The position is in CSS pixels (matches drawing coordinates).
+// Returns a cleanup function — call it in the useEffect return.
+//
+// Usage:
+//   const mouse = { x: -9999, y: -9999 };
+//   const cleanupMouse = attachMouseTracking(el, mouse);
+//   return () => { cancelAnimationFrame(raf); cleanupMouse(); };
+//
+export function attachMouseTracking(
+  el: HTMLCanvasElement,
+  mouse: { x: number; y: number },
+): () => void {
+  const onMove = (e: MouseEvent) => {
+    const r = el.getBoundingClientRect();
+    mouse.x = e.clientX - r.left;
+    mouse.y = e.clientY - r.top;
+  };
+  const onLeave = () => {
+    mouse.x = -9999;
+    mouse.y = -9999;
+  };
+  el.addEventListener("mousemove", onMove);
+  el.addEventListener("mouseleave", onLeave);
+  return () => {
+    el.removeEventListener("mousemove", onMove);
+    el.removeEventListener("mouseleave", onLeave);
+  };
+}
+// ─── Velocity Cap ─────────────────────────────────────────────────────────────
+//
+// Prevents particles from flying off-screen after strong mouse interactions.
+// Apply AFTER adding forces, BEFORE updating position.
+//
+export function capVelocity(
+  p: { vx: number; vy: number },
+  maxSpeed: number,
+): void {
+  const spd = Math.sqrt(p.vx * p.vx + p.vy * p.vy);
+  if (spd > maxSpeed) {
+    p.vx *= maxSpeed / spd;
+    p.vy *= maxSpeed / spd;
+  }
+}
+// ─── Reduced-Motion Guard ─────────────────────────────────────────────────────
+//
+// ⚠️  DO NOT use this as an early `return` before drawing — that leaves the
+//     canvas completely blank, which is WORSE than showing animation.
+//
+// Correct pattern for canvas components:
+//   draw one static frame (nodes at target positions), then skip the RAF loop.
+//
+//   const reduced = prefersReducedMotion();
+//   // ... build pts, set up canvas ...
+//   if (reduced) {
+//     pts.forEach(p => { p.x = p.tx; p.y = p.ty; });  // snap to targets
+//     drawOneFrame(ctx, pts, size);                      // render static
+//     return;                                            // no RAF
+//   }
+//   tick(); // full animation
+//
+// For HTML/stipple components the early return IS fine because HTML content
+// is already visible in the DOM without JavaScript.
+//
+export function prefersReducedMotion(): boolean {
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+// ─── Connection Lines ─────────────────────────────────────────────────────────
+//
+// Draw faded lines between all particle pairs within linkDist.
+// Call this BEFORE drawing nodes so lines appear underneath.
+//
+// pts must have { x, y } properties.
+//
+export function drawConnections(
+  ctx: CanvasRenderingContext2D,
+  pts: { x: number; y: number }[],
+  linkDist: number,
+  lineColor: [number, number, number],
+  maxAlpha = 0.32,
+): void {
+  const [r, g, b] = lineColor;
+  for (let i = 0; i < pts.length; i++) {
+    for (let j = i + 1; j < pts.length; j++) {
+      const dx = pts[i].x - pts[j].x;
+      const dy = pts[i].y - pts[j].y;
+      const d = Math.sqrt(dx * dx + dy * dy);
+      if (d < linkDist) {
+        const a = (1 - d / linkDist) * maxAlpha;
+        ctx.beginPath();
+        ctx.moveTo(pts[i].x, pts[i].y);
+        ctx.lineTo(pts[j].x, pts[j].y);
+        ctx.strokeStyle = `rgba(${r},${g},${b},${a.toFixed(3)})`;
+        ctx.lineWidth = 0.65;
+        ctx.stroke();
+      }
+    }
+  }
+}