sheleg-design-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssheleg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# SHELEG Design — agent skill
+
+> A motion + particle interface methodology for building cinematic,
+> scroll-driven landing pages — packaged as an installable agent skill for
+> Cursor and Claude.
+
+Install it into any project with one command:
+
+```bash
+npx sheleg-design-skill
+```
+
+That drops a `SKILL.md` + `SHELEG_DESIGN.md` bundle into your project so your
+coding agent can discover the skill and build sites on its principles.
+
+## What is SHELEG Design?
+
+A page feels *alive* not from many animations, but from a **single source of
+truth** (scroll position) driving **many cheap, layered responses** that are
+individually quiet and collectively cinematic. One scroll "clock" feeds a WebGL
+particle field, a 2D fallback, attention dimming, parallax, scrubbed
+instruments, and a progress rail — each an independent, degrade-to-calm layer.
+Nothing crossfades; things *redeploy*. The result reads as one precision
+instrument responding to your hand.
+
+It was reverse-engineered from a production landing page (a 14-scene particle
+narrative that morphs through formations and culminates in a brand "N" that
+charges and bursts). The skill distills the architecture and the principles so
+an agent can rebuild that level on a new site.
+
+### The five principles
+
+1. **One clock.** All motion derives from one measured scroll state.
+2. **Read per frame, notify rarely.** Hot consumers read imperatively; only
+   coarse changes hit the framework's render path.
+3. **Hold, then redeploy.** Hold a formation ~80% of a section, then morph in a
+   short, phase-staggered, arc-curved wave. No crossfades.
+4. **Earned motion.** Scrub is for instruments that narrate state over time;
+   entrance motion stays sub-500ms and never gates content.
+5. **Degrade to calm.** Reduced-motion / coarse pointer / no-WebGL collapse to a
+   static, fully-legible page.
+
+## Usage
+
+```bash
+# Auto-detect (.cursor/ or .claude/), default to .cursor/skills/sheleg-design/
+npx sheleg-design-skill
+
+# Force a flavor
+npx sheleg-design-skill --cursor
+npx sheleg-design-skill --claude
+
+# Custom location
+npx sheleg-design-skill --dir docs/skills/sheleg-design
+
+# Overwrite an existing install
+npx sheleg-design-skill --force
+
+# Help
+npx sheleg-design-skill --help
+```
+
+### What gets installed
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Agent-facing skill: discovery trigger + the principles + how to apply them |
+| `SHELEG_DESIGN.md` | The full reference: architecture, layer-by-layer mechanics with code, the exact morph math, the DOM↔WebGL projection bridge, a build-from-scratch recipe, and the "why it works" |
+
+After installing, a Cursor or Claude agent in that project can discover the
+skill and use it when you ask it to build or upgrade a cinematic,
+scroll-driven, particle-backed page.
+
+## Stack-agnostic
+
+The skill teaches **principles and architecture**, not a fixed dependency set.
+The reference implementation happens to use Next.js + React + three /
+react-three-fiber + GSAP ScrollTrigger + Lenis + Framer Motion, but the method
+applies to any stack that can render to a canvas/WebGL surface and read scroll.
+
+## Zero dependencies
+
+The installer is a single zero-dependency Node script, so `npx` runs instantly
+with no install step and no supply-chain surface.
+
+## License
+
+MIT © ssheleg

package/bin/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * sheleg-design-skill installer.
+ *
+ * Copies the SHELEG Design skill bundle (SKILL.md + SHELEG_DESIGN.md) into the
+ * current project so a Cursor / Claude agent can discover and apply it.
+ *
+ * Zero dependencies on purpose: it must run instantly via `npx` with no install
+ * step and no supply-chain surface.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const SKILL_DIR = path.join(__dirname, "..", "skill");
+const SKILL_SLUG = "sheleg-design";
+const FILES = ["SKILL.md", "SHELEG_DESIGN.md"];
+
+const pkg = require(path.join(__dirname, "..", "package.json"));
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  blue: "\x1b[38;5;75m",
+  green: "\x1b[38;5;42m",
+  yellow: "\x1b[38;5;214m",
+};
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (color, s) => (useColor ? COLORS[color] + s + COLORS.reset : s);
+
+function parseArgs(argv) {
+  const opts = {
+    target: null, // explicit --dir
+    flavor: null, // "cursor" | "claude"
+    force: false,
+    help: false,
+    version: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") opts.help = true;
+    else if (a === "--version" || a === "-v") opts.version = true;
+    else if (a === "--force" || a === "-f") opts.force = true;
+    else if (a === "--cursor") opts.flavor = "cursor";
+    else if (a === "--claude") opts.flavor = "claude";
+    else if (a === "--dir") opts.target = argv[++i];
+    else if (a.startsWith("--dir=")) opts.target = a.slice("--dir=".length);
+    else {
+      console.error(c("yellow", `Unknown argument: ${a}`));
+      opts.help = true;
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+${c("bold", "SHELEG Design")} ${c("dim", "v" + pkg.version)}
+Install the SHELEG Design skill into your project.
+
+${c("bold", "Usage")}
+  npx sheleg-design-skill [options]
+
+${c("bold", "Options")}
+  --cursor        Install to .cursor/skills/${SKILL_SLUG}/
+  --claude        Install to .claude/skills/${SKILL_SLUG}/
+  --dir <path>    Install to a custom directory
+  --force, -f     Overwrite existing files
+  --help, -h      Show this help
+  --version, -v   Show version
+
+${c("bold", "Default")}
+  Auto-detects: uses .cursor/ if present, else .claude/ if present,
+  otherwise creates .cursor/skills/${SKILL_SLUG}/.
+
+${c("bold", "What it installs")}
+  SKILL.md           the agent-facing skill (discovery + principles)
+  SHELEG_DESIGN.md   the full reference (architecture, recipes, why it works)
+`);
+}
+
+function resolveTargetDir(opts, cwd) {
+  if (opts.target) return path.resolve(cwd, opts.target);
+  if (opts.flavor === "cursor")
+    return path.join(cwd, ".cursor", "skills", SKILL_SLUG);
+  if (opts.flavor === "claude")
+    return path.join(cwd, ".claude", "skills", SKILL_SLUG);
+
+  const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
+  const hasClaude = fs.existsSync(path.join(cwd, ".claude"));
+  if (hasCursor) return path.join(cwd, ".cursor", "skills", SKILL_SLUG);
+  if (hasClaude) return path.join(cwd, ".claude", "skills", SKILL_SLUG);
+  return path.join(cwd, ".cursor", "skills", SKILL_SLUG);
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.version) {
+    console.log(pkg.version);
+    return;
+  }
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  const cwd = process.cwd();
+  const targetDir = resolveTargetDir(opts, cwd);
+
+  // Verify the bundle is intact before touching the filesystem.
+  for (const f of FILES) {
+    if (!fs.existsSync(path.join(SKILL_DIR, f))) {
+      console.error(
+        c("yellow", `Bundle is missing ${f}. This is a packaging bug.`),
+      );
+      process.exit(1);
+    }
+  }
+
+  const existing = FILES.filter((f) =>
+    fs.existsSync(path.join(targetDir, f)),
+  );
+  if (existing.length && !opts.force) {
+    console.error(
+      `\n${c("yellow", "Refusing to overwrite existing files:")}\n` +
+        existing.map((f) => "  " + path.join(targetDir, f)).join("\n") +
+        `\n\nRe-run with ${c("bold", "--force")} to overwrite.\n`,
+    );
+    process.exit(1);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const f of FILES) {
+    fs.copyFileSync(path.join(SKILL_DIR, f), path.join(targetDir, f));
+  }
+
+  const rel = path.relative(cwd, targetDir) || ".";
+  console.log(
+    `\n${c("green", "✓")} ${c("bold", "SHELEG Design")} installed to ${c("blue", rel + "/")}\n` +
+      `  ${c("dim", "SKILL.md")}          the agent skill\n` +
+      `  ${c("dim", "SHELEG_DESIGN.md")}  the full reference\n\n` +
+      `Your Cursor / Claude agent can now discover the skill and build\n` +
+      `cinematic, scroll-driven, particle-backed pages on its principles.\n\n` +
+      `${c("dim", "Docs: " + pkg.homepage)}\n`,
+  );
+}
+
+main();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "sheleg-design-skill",
+  "version": "0.1.0",
+  "description": "SHELEG Design — an agent skill for building cinematic, scroll-driven, particle-backed landing pages. Installs a SKILL.md + reference doc into your project so Cursor/Claude agents can build sites with a single-clock motion system, a scene-formation particle engine, and degrade-to-calm fallbacks.",
+  "bin": {
+    "sheleg-design-skill": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "commonjs",
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  },
+  "keywords": [
+    "skill",
+    "cursor",
+    "claude",
+    "agent-skill",
+    "design-system",
+    "motion",
+    "animation",
+    "particles",
+    "webgl",
+    "scroll",
+    "gsap",
+    "three",
+    "framer-motion",
+    "landing-page",
+    "sheleg"
+  ],
+  "author": "ssheleg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ssheleg/sheleg-design-skill.git"
+  },
+  "homepage": "https://github.com/ssheleg/sheleg-design-skill#readme",
+  "bugs": {
+    "url": "https://github.com/ssheleg/sheleg-design-skill/issues"
+  }
+}

package/skill/SHELEG_DESIGN.md

@@ -0,0 +1,643 @@
+# SHELEG Design
+
+A motion-and-particle interface system, reverse-engineered from the Nicegram
+Business OS landing page. This document captures *how* the page reaches its
+level — the layout discipline, the scroll narrative, the WebGL particle field,
+the DOM choreography, and the registration tricks that fuse them — so you can
+build new sites on the same principles and understand *why* each piece works.
+
+> SHELEG Design is the **motion + systems** layer. It assumes a **visual**
+> system already exists (color, type, elevation, components — the reference
+> implementation calls its visual layer "The Instrument Console": a near-black
+> aerospace console with one electric-blue signal accent). Build the visual
+> system first; layer SHELEG Design on top.
+
+---
+
+## 0. The one-paragraph thesis
+
+A landing page feels "alive" not because it has many animations, but because a
+**single source of truth** (scroll position) drives **many cheap, layered
+responses** that are individually quiet and collectively cinematic. SHELEG
+Design centralizes scroll into one external store, then lets independent layers
+(a WebGL particle field, a DOM spotlight, parallax figures, scrubbed
+instruments, a progress rail) read that store **per frame** and react in their
+own language. Every layer degrades to a calm static state. Nothing crossfades;
+things *redeploy*. The result reads as one instrument responding to your hand,
+not a pile of effects.
+
+The five principles that make it work:
+
+1. **One clock.** All motion derives from a single measured scroll state. Layers
+   never measure scroll independently, so they can never disagree.
+2. **Read per frame, notify rarely.** Hot consumers (WebGL, canvas, rail) read
+   the store imperatively each frame and never trigger React renders. Only
+   coarse, human-visible changes (the current "act") notify React.
+3. **Hold, then redeploy.** A formation is held steady for most of a section,
+   then morphs in a short, phase-staggered, arc-curved wave — points fly to new
+   posts. Crossfades are banned.
+4. **Earned motion.** Scrubbed animation belongs to instruments that narrate
+   state over time. Hover/entrance motion is sub-500ms and never gates content.
+5. **Degrade to calm.** `prefers-reduced-motion` / coarse pointer / no-WebGL all
+   collapse to a static, fully-legible page. The effect is an enhancement, never
+   a dependency.
+
+---
+
+## 1. Architecture at a glance
+
+```
+                         ┌─────────────────────────────┐
+   wheel / touch  ─────▶ │  Lenis smooth scroll         │  (SmoothScroll.tsx)
+                         │  driven by the GSAP ticker    │
+                         └──────────────┬───────────────┘
+                                        │ one scroll position / frame
+                                        ▼
+                         ┌─────────────────────────────┐
+                         │  Scroll store (single clock) │  (scroll-progress.ts)
+                         │  global · act · form · focusX │
+                         │  velocity · finale            │
+                         └──────────────┬───────────────┘
+            per-frame reads (no React)  │  coarse "act" change → React
+        ┌───────────────┬───────────────┼───────────────┬──────────────┐
+        ▼               ▼               ▼               ▼              ▼
+   SignalField     SignalMesh      FocalSpotlight   ParallaxDrift   ScrollRail
+   (WebGL field)   (2D fallback)   (dim off-band)   (figure depth)  (progress)
+        │
+        │ projects anchor points / reads chart progress
+        ▼
+   field-sync bridge ──▶ ConstellationOverlay (SVG drawn over clusters)
+                    ◀── WhyNowChart scrub (particles assemble with the line)
+```
+
+Layers are **independent**. You can delete `ParallaxDrift` or the overlay and
+everything else still works. That decoupling is the point: each layer is a small
+file with one responsibility, reading the same clock.
+
+---
+
+## 2. Layer 1 — The scroll store (the single clock)
+
+**File:** `src/lib/motion/scroll-progress.ts`
+
+This is the heart of the system. One `requestAnimationFrame` loop (scheduled on
+the native `scroll` event) measures the page and writes a plain `state` object.
+Everything else reads it.
+
+### The dual-subscription pattern
+
+The store exposes two read paths, which is what keeps it cheap:
+
+- `getScrollState()` — returns the **live, mutable** object. Hot per-frame
+  consumers (WebGL `useFrame`, the canvas loop, the rail fill) read this and
+  never cause a React render.
+- `subscribeAct()` + `useSyncExternalStore` — fires **only when the integer act
+  changes** (5 acts on the whole page). React components that show act-derived
+  UI (nav badge, rail markers) subscribe here, so they wake up a handful of
+  times per full scroll, not 60×/second.
+
+```ts
+// Per-frame, no React (rail fill, WebGL, canvas):
+const s = getScrollState();
+el.style.transform = `scaleY(${s.global})`;
+
+// Coarse, React-driven (nav badge "02 / CONTROL"):
+const act = useSyncExternalStore(subscribeAct, () => getScrollState().act, () => 0);
+```
+
+> **Why it works:** the expensive consumers are exactly the ones that must run
+> every frame anyway (rendering), so reading a mutable object is free. The cheap
+> consumers (text labels) are the only ones in React's render path, and they
+> change rarely. You get 60fps motion with almost no React churn.
+
+### What the state carries
+
+| Field | Range | Meaning | Who reads it |
+|---|---|---|---|
+| `global` | 0..1 | whole-page scroll progress | rail fill, camera dolly |
+| `act` | 0..4 | current narrative act (integer) | nav badge, rail markers |
+| `actProgress` | 0..1 | progress within the act | act-level copy |
+| `field` | 0..4 | continuous act scalar | 2D mesh gain, climax |
+| `scene` | 0..13 | current section's scene (integer) | scene lookup |
+| `form` | 0..13 | **continuous scene scalar** | particle formation morph |
+| `focusX` | -1..1 | camera pan target | WebGL camera, overlay |
+| `velocity` | -1..1 | smoothed scroll speed | field breathing, rail |
+| `finale` | 0..1 | post-waitlist epilogue progress | N charge → burst |
+| `bias` | -0.6..1 | interactive nudge added to `form` | section gestures |
+
+### The "hold then morph" measurement (the calm secret)
+
+A naïve scroll-to-formation mapping changes the backdrop continuously, which
+reads as nervous. The fix is a **hold window**. Within a scene's scroll span,
+`form` stays pinned to the scene's integer for the first `HOLD` (82%), then
+eases through the tail via smoothstep:
+
+```ts
+const sp   = spanProgress(y, sceneFrom, sceneTo);   // 0..1 within the scene
+const HOLD = 0.82;                                   // formation locked 82% of the span
+const tail = clamp01((sp - HOLD) / (1 - HOLD));      // 0..1 only in the last 18%
+const eased = tail * tail * (3 - 2 * tail);          // smoothstep
+state.form  = scene + eased;                         // integer hold → eased morph at the seam
+```
+
+Boundaries are measured when a section crosses **65% of the viewport** (`measure()`),
+so a formation "opens" as its section becomes the reading focus. A
+`ResizeObserver` on `document.body` re-measures when late layout (fonts, lazy
+GSAP pin spacers) shifts the page — without it, every boundary below a pinned
+section would be wrong.
+
+### Velocity as a feeling, not a value
+
+`setScrollVelocity()` is written from Lenis on every scroll event and normalized
+to roughly -1..1. It **does not notify React** — it is read per frame by the
+field (particles breathe faster while you scroll) and the rail (fill brightens
+with input speed). This is the cheapest possible "the instrument is responding
+to you" signal.
+
+---
+
+## 3. Layer 2 — Smooth scroll (one position per frame)
+
+**File:** `src/components/v2/motion/SmoothScroll.tsx`
+
+Lenis provides inertial scrolling, but the important move is **driving Lenis
+from the GSAP ticker** rather than its own rAF:
+
+```ts
+const lenis = new Lenis({ lerp: 0.09, wheelMultiplier: 1, touchMultiplier: 1.4 });
+gsap.ticker.add((time) => lenis.raf(time * 1000));
+gsap.ticker.lagSmoothing(0);
+lenis.on("scroll", (e) => { setScrollVelocity(e.velocity); ScrollTrigger.update(); });
+```
+
+> **Why it works:** ScrollTrigger scrubs and the particle field both read scroll
+> on the same tick, so a scrubbed chart and the background particles share one
+> inertia — they move as a single instrument. A low `lerp` (0.09) means more
+> glide between wheel notches, which is what lets formations morph as continuous
+> motion instead of discrete jumps.
+
+Reduced-motion / coarse-pointer clients skip Lenis entirely (`shouldReduceScenes()`)
+and keep native scroll. The store still runs, so the rail and nav stay in sync.
+
+---
+
+## 4. Layer 3 — The particle field (the scene-formation engine)
+
+**File:** `src/components/v2/webgl/SignalField.tsx`
+
+This is the showpiece: ~936 points (`24 × 13 × 3`) that narrate the page section
+by section. It is a single `THREE.Points` cloud whose target positions change
+per scene. All motion is CPU positional lerp — cheap, deterministic, tinted only
+with the brand accent.
+
+### 4.1 The scene registry
+
+**File:** `src/lib/motion/scenes.ts`
+
+Each section "owns" a scene; a scene is a `{ anchor, formation, focusX, energy }`
+record. The registry is the single place that maps DOM sections to particle
+behavior:
+
+```ts
+export const SCENES = [
+  { anchor: "top",       formation: "frame",         focusX: -0.3,  energy: 0.5  },
+  { anchor: "telemetry", formation: "curve",         focusX: 0,     energy: 0.45 },
+  { anchor: "problem",   formation: "turbulence",    focusX: -0.25, energy: 0.55 },
+  // … one per section …
+  { anchor: "why-now",   formation: "gapCurve",      focusX: 0,     energy: 0.7  },
+  { anchor: "waitlist",  formation: "glyphN",        focusX: 0,     energy: 1    },
+] as const;
+```
+
+- `formation` — which shape the points fly into (frame, curve, lattice, triad,
+  orbit, constellation, ecoMap, gapCurve, glyphN, …).
+- `focusX` — where the camera pans (opposite the content column, so the field
+  frames the text instead of fighting it).
+- `energy` — the brightness budget for the scene (the **One Signal Rule**: the
+  glow never out-shouts an on-stage demo). `sceneEnergy(form)` interpolates it
+  continuously.
+
+> **Why it works:** adding/reordering a scene is a one-line data edit. The field,
+> the 2D fallback, and the overlay all resolve their behavior **from the registry
+> by formation name** (`SCENES.findIndex(s => s.formation === "glyphN")`), so
+> nothing hard-codes an index. The data is the choreography.
+
+### 4.2 Formation builders (deterministic geometry)
+
+`buildFormations()` produces each formation's target positions once, at mount.
+Every builder runs its **own seeded RNG** (`mulberry32(seed)`), so:
+
+- formations are identical across sessions and machines (no hydration drift),
+- they are independent of declaration order,
+- the same point index can be given a meaningful role in multiple formations
+  (e.g. the "tight N" variant reuses the N's per-point stroke assignment so the
+  charge densification reads as the letter pulling itself sharp).
+
+Example — the "constellation" formation pulls a relaxed grid toward 8 hubs with
+tight jitter so clusters read as deliberate nodes:
+
+```ts
+const pull = 0.68;                       // strong pull → hubs read as clusters
+out[ix]   = gx + (hub[0] - gx) * pull + (rand() - 0.5) * 1.1;  // small jitter
+out[ix+1] = gy + (hub[1] - gy) * pull + (rand() - 0.5) * 1.1;
+```
+
+### 4.3 The morph (hold → smoothstep stagger → arc)
+
+Inside `useFrame`, the render-side scalar `s.form` chases the store's `form` with
+**clamped critically-damped smoothing**, so flick-scrolls and anchor jumps sweep
+through intermediate formations cinematically instead of teleporting:
+
+```ts
+const formDelta = (scroll.form + scroll.bias - s.form) * 0.028;
+s.form += Math.max(-0.04, Math.min(0.04, formDelta));   // per-frame delta cap
+```
+
+Each point then blends between the two active formations with a **per-point
+phase-staggered, smoothstepped** progress — points peel off in a wave and ease
+in and out of their posts:
+
+```ts
+const m   = clamp01((mix - phaseNorm * spread) / (1 - spread));  // spread = 0.5
+const eased = m * m * (3 - 2 * m);                                // smoothstep
+```
+
+And mid-flight, points swing **perpendicular to their travel line** — half
+clockwise, half counter — so the swarm curls between formations instead of
+sliding in straight lines:
+
+```ts
+if (m > 0.001 && m < 0.999) {
+  const arc = Math.sin(m * Math.PI) * arcAmp * (phase > Math.PI ? 1 : -1);
+  px += (-dy / dist) * arc;   // perpendicular offset, peaks mid-transition
+  py += ( dx / dist) * arc;
+}
+```
+
+> **Why it works:** crossfades look like one image fading into another (flat,
+> digital). A phase-staggered arc-curved redeploy looks like a *swarm of agents*
+> flying to new posts (alive, physical). It is the single biggest reason the
+> field reads as premium rather than as a screensaver.
+
+### 4.4 Formation profiles (the glow programs)
+
+A `PROFILES` table gives each formation a render character — how lattice-like it
+is (drives wire opacity), which glow program lights it, and how much ambient
+drift it keeps:
+
+```ts
+const PROFILES = {
+  lattice:       { lattice: 1, glow: "wave",  drift: 0.12 },  // engineered grid + wave pulse
+  constellation: { lattice: 0, glow: "hubs",  drift: 0.25 },  // hub stars twinkle, no wires
+  beam:          { lattice: 0, glow: "beam",  drift: 0.2  },  // focused vertical signal
+  glyphN:        { lattice: 0, glow: "glyph", drift: 0.1  },  // the finale "N"
+  // …
+};
+```
+
+Glow programs are blended between the two active formations, so transitions
+carry their lighting with them. Profiles are interpolated, never switched hard.
+
+### 4.5 The camera
+
+The camera does three quiet things, all smoothed:
+
+- **Dolly** back as `global` increases (the page pulls away over its length).
+- **Pan** toward the active scene's `focusX` (attention follows the content).
+- **Tilt** a fraction toward the focus side — applied *after* `lookAt` (which
+  resets rotation), from its own smoothed value. This faint instrument tilt is
+  what gives the field a sense of being observed through a lens.
+
+### 4.6 The finale (charge → burst), scrub-driven
+
+Past the waitlist, a dedicated `finale` scalar (0..1) drives an epilogue that is
+**reversible** because it is pure scrub:
+
+- **Charge** (`finale 0 → 0.55`): the N densifies toward a tight core, scales up,
+  and trembles with rising amplitude; brightness and point size climb.
+- **Burst** (`finale 0.55 → 0.85`): every point flies out along a precomputed
+  radial debris vector with a white-hot flash, then dims into an ember field.
+- The DOM **closing line** ("Join Nicegram") fades up from the afterglow.
+
+Because it is gated on the glyph actually holding (`finaleness`) and reads a
+scrubbed scalar, scrolling back up rewinds the whole explosion frame-for-frame.
+
+---
+
+## 5. Layer 4 — The 2D fallback (SignalMesh)
+
+**File:** `src/components/v2/atmosphere/SignalMesh.tsx`
+
+Touch and no-WebGL clients get a canvas mesh: two depth layers of grid nodes
+with hairline links and traveling pulses, plus **stroke overlays** that fade in
+the curve / orbit / N around their scene windows. It reads the **same store**
+(`getScrollState().form`, `sceneEnergy`, `finale`), so the escalation and the
+finale charge/burst are mirrored — the page tells the same story at lower
+fidelity. Only `prefers-reduced-motion` gets a single static frame.
+
+> **Principle:** the fallback is not a stripped logo — it reads the same clock
+> and tells the same narrative. That is why switching modes never feels like a
+> different website.
+
+---
+
+## 6. Layer 5 — The projection bridge (fusing DOM and WebGL)
+
+**File:** `src/lib/motion/field-sync.ts`
+
+The hardest problem in mixing WebGL particles with DOM labels: the camera moves,
+so you cannot hard-code where a cluster appears on screen. The bridge solves it
+with a tiny zero-allocation, no-React module that the field writes and the DOM
+reads — the same contract as `setScrollVelocity`.
+
+### 6.1 Constellation registration (ecosystem section)
+
+Every frame, `SignalField` projects the constellation's world-space anchors
+through its **own camera** and publishes viewport-pixel coordinates + a
+visibility alpha:
+
+```ts
+// In SignalField useFrame, after all camera moves:
+PROJ_SCRATCH.set(anchor.x, anchor.y, -2).project(camera);
+setEcoProjection(node,
+  (PROJ_SCRATCH.x * 0.5 + 0.5) * size.width,
+  (0.5 - PROJ_SCRATCH.y * 0.5) * size.height);
+```
+
+`ConstellationOverlay.tsx` (a fixed SVG) reads those points in its own rAF and
+positions the constellation lines, the astronomy-chart labels (with leader
+ticks), and the rotating "you are here" reticle — perfectly registered over the
+particle clusters at any scroll position. CSS `is-live` (toggled at `alpha > 0.5`)
+sequences the draw-in: lines stroke themselves, then labels stagger, then the
+reticle scales in and spins.
+
+> **Why it works:** the SVG never guesses. It uses the exact projection the GPU
+> used that frame, so the "interface drawing the constellation" illusion holds
+> through dolly, pan, and tilt. Cost: 4 `Vector3.project` calls per frame ≈ zero.
+
+### 6.2 Chart participation (why-now section)
+
+The reverse direction: the chart's GSAP scrub publishes its draw progress, and
+the field assembles its particle copy of the curve left-to-right in lockstep:
+
+```ts
+// WhyNowChart timeline:
+onUpdate: () => setChartProgress(tl.progress())
+
+// SignalField, per point of the gapCurve formation:
+const u = (px + HALF) / (HALF * 2);          // 0..1 along the curve
+if (u > chartProg + 0.04) { py -= drop; lum *= 0.5; }   // not yet assembled
+else lum += max(0, 1 - |u - chartProg| * 16) * 0.8;     // bright head at the draw front
+```
+
+The SVG line and the particles share one scrub and one inertia, so the bright
+particle "head" runs exactly where the line tip is being drawn.
+
+---
+
+## 7. Layer 6 — DOM choreography
+
+Three small components, one mechanism each, all reading the same clock.
+
+### FocalSpotlight — `src/components/v2/motion/FocalSpotlight.tsx`
+An `IntersectionObserver` with a generous center band (`rootMargin: -22% 0 -22% 0`)
+toggles a `data-dim` attribute on sections outside the band. CSS dims them to
+62% opacity. The reader's eye is always pulled to the active section. The finale
+section is excluded (`:not(#finale)`) because it runs its own fade.
+
+### ParallaxDrift — `src/components/v2/motion/ParallaxDrift.tsx`
+Wraps **at most one figure per viewport** in a GSAP `yPercent` scrub for a few
+percent of depth drift. Restraint is the rule: parallax on everything is nausea;
+parallax on the one hero figure is depth.
+
+### ScrollRail — `src/components/v2/atmosphere/ScrollRail.tsx`
+A right-edge hairline whose fill is scaled imperatively (`scaleY(global)`) and
+brightened by `velocity` — a live mission timeline, updated per frame with zero
+React renders. Act markers deep-link to their anchor sections and use the coarse
+`subscribeAct` path for their active state.
+
+---
+
+## 8. Layer 7 — Reveal primitives (act-themed entrances)
+
+**File:** `src/components/v2/design/Reveal.tsx`
+
+Entrances are not generic. Each narrative act has a reveal whose *physics* match
+its meaning — this is Disney's "staging" applied to a scroll page:
+
+| Reveal | Physics | Act it serves |
+|---|---|---|
+| `ScatterReveal` | drifts in off-axis with a blur that resolves | **Problem** — unmanaged things settling into frame |
+| `LockReveal` | scales down a hair and snaps into place | **Control** — a part machined into a slot |
+| `ClipReveal` | mechanical left-to-right clip wipe | headlines, panels |
+| `PulseReveal` | a single soft pulse as it "acquires lock" | **Signal** — the waitlist climax |
+| `Stagger` / `StaggerItem` | children cascade with a 0.06s stagger | lists, readouts |
+
+**Every reveal renders its final state plainly under `prefers-reduced-motion`** —
+the `useReducedMotion()` branch returns the plain tag. Entrances enhance; they
+never gate whether content is visible.
+
+> **Why it works:** when the *kind* of entrance matches the *meaning* of the
+> section, motion becomes narration. The page isn't decorated; it's told.
+
+---
+
+## 9. Layer 8 — Scrubbed instruments (GSAP recipe)
+
+Diagrams that narrate state over time (growth chart, comparison table, the
+pinned three-step flow, the why-now chart) use one repeatable GSAP recipe.
+
+**Files:** `WhyNowChart.tsx`, `EcosystemDiagram.tsx`, `PinnedSteps.tsx`, `gsap-client.ts`
+
+```ts
+useLayoutEffect(() => {
+  if (shouldReduceScenes()) return;          // static, fully-drawn fallback
+  let teardown;
+  loadGsap().then(({ gsap, ScrollTrigger }) => {   // lazy: GSAP never in initial bundle
+    const tl = gsap.timeline({
+      defaults: { ease: "none" },             // ease: 'none' is mandatory with scrub
+      scrollTrigger: { trigger: svg, start: "top 85%", end: "top 25%", scrub: 0.8 },
+    });
+    tl.fromTo(lines,
+      { strokeDasharray: 1, strokeDashoffset: 1 },   // pathLength={1} normalizes every path
+      { strokeDashoffset: 0, stagger: 0.08 });        // → one variable draws them all
+    teardown = () => { tl.scrollTrigger?.kill(); tl.kill(); };  // ALWAYS kill on cleanup
+    ScrollTrigger.refresh();
+  });
+  return () => teardown?.();
+}, []);
+```
+
+The non-negotiables (each learned from a real bug here):
+
+- **Lazy-load GSAP** (`loadGsap()`), register the plugin once, keep it out of the
+  initial bundle.
+- **`ease: 'none'`** on scrubbed tweens — easing fights the scrub.
+- **`pathLength={1}`** on SVG paths so a single 0..1 variable can draw any path,
+  regardless of its real length.
+- **Always `tl.kill()` + `scrollTrigger.kill()`** in cleanup — un-killed
+  timelines leak and double up on fast-refresh / route changes.
+- **Reduced-motion renders the final drawn state** with no trigger attached.
+
+---
+
+## 10. Cross-cutting rules
+
+### Motion tokens — `src/lib/motion/tokens.ts`
+No component invents its own curve. Everything uses:
+
+- **`EASE = cubic-bezier(0.16, 1, 0.3, 1)`** (an easeOutExpo-like signature),
+  mirrored in CSS as `--v2-ease`.
+- **`DUR`** — `fast 0.18` / `base 0.32` / `slow 0.55` / `epic 0.8` seconds.
+- **`STAGGER = 0.07`** — the standard interval between sibling reveals.
+
+One ease + a tiny duration set is what makes twelve independent animations feel
+like one designed system rather than twelve developers' defaults.
+
+### The fallback policy (single source: `shouldReduceScenes()`)
+`gsap-client.ts` centralizes the decision: `prefers-reduced-motion` **or**
+`pointer: coarse` ⇒ skip motion-heavy scenes. Consequences everywhere:
+
+- WebGL field → 2D `SignalMesh`.
+- Lenis smooth scroll → native scroll.
+- Pinned scrub scenes → static fully-drawn diagrams.
+- Reveals → final state, instant.
+- Constellation overlay → not mounted; section shows the boxed diagram.
+
+### Performance budget
+- WebGL is **always** `dynamic(() => import(...), { ssr: false })` — never in the
+  first bundle, mounted one frame after hydration paints.
+- Hot loops mutate typed arrays / plain objects and **never call `setState`**.
+- Animate only `transform` and `opacity` in DOM/CSS; avoid `width`/`height`/
+  `box-shadow` transitions.
+- Pinned scroll is budgeted at ≈30% of total page height.
+- Particle count (936) and DPR cap (`[1, 1.75]`) keep the field on a
+  `low-power` GL context.
+
+### Accessibility parity
+Tabs follow WAI-ARIA roving-tabindex (`use-tabs.ts`); the mobile nav is a
+focus-trapped `role="dialog"`; every canvas/field is `aria-hidden` with a
+text-equivalent in the DOM (e.g. the ecosystem stage keeps the diagram's
+`aria-label` as `sr-only`). Motion is never the only carrier of meaning.
+
+---
+
+## 11. Recipe — build a new SHELEG site from scratch
+
+A pragmatic order that front-loads the parts everything else depends on.
+
+1. **Lay the visual system first.** Implement `DESIGN.md`: near-black canvas,
+   one signal accent, hairline structure, mono telemetry labels, the panel /
+   button / status-pill components. Motion on top of a weak visual system just
+   amplifies the weakness.
+
+2. **Stand up the clock.** Port `scroll-progress.ts`: the `state` object, the
+   dual subscriptions (`getScrollState` for per-frame, `subscribeAct` for
+   React), the rAF `update()`, the 65%-viewport `measure()`, and the
+   `ResizeObserver` re-measure. Verify with a temporary readout of `global` /
+   `act` / `form`.
+
+3. **Add smooth scroll.** `SmoothScroll.tsx` with Lenis on the GSAP ticker,
+   feeding `setScrollVelocity`. Gate it behind `shouldReduceScenes()`.
+
+4. **Define scenes.** Write your `scenes.ts` registry — one `{ anchor,
+   formation, focusX, energy }` per section. Give each section an `id` matching
+   its anchor. This is your storyboard; iterate on it in data before touching
+   rendering.
+
+5. **Build the field.** `SignalField.tsx`: a seeded point cloud, one builder per
+   formation, the `PROFILES` table, and the `useFrame` morph (clamped smoothing
+   + per-point smoothstep stagger + arcs). Get *one* formation looking right,
+   then add the rest as data.
+
+6. **Mirror it in 2D.** `SignalMesh.tsx` reading the same store, so touch / no-
+   WebGL tells the same story. Wire the `AtmosphereField` capability probe.
+
+7. **Layer the DOM choreography.** `FocalSpotlight`, `ParallaxDrift` (one figure
+   per viewport), `ScrollRail`. Each is tiny and independent.
+
+8. **Theme the entrances.** Build the `Reveal` family; assign a reveal physics to
+   each act's meaning. Always branch reduced-motion to plain.
+
+9. **Add scrubbed instruments** with the Section 9 GSAP recipe for any diagram
+   that narrates state over time.
+
+10. **Fuse DOM ↔ WebGL where it earns it.** Only when you want labels exactly on
+    clusters or particles synced to a chart: add the `field-sync` bridge, project
+    anchors in `useFrame`, read them in a fixed SVG overlay.
+
+11. **Pay the fallback + a11y tax as you go**, not at the end. Every layer ships
+    with its reduced-motion branch in the same commit.
+
+12. **Verify like the runbook:** `tsc --noEmit`, `eslint`, `build` clean;
+    screenshot each scene mid-hold and mid-morph; emulate reduced-motion; check a
+    ~390px viewport. Then deploy.
+
+---
+
+## 12. Why it works (the deeper principles)
+
+- **A single clock removes disagreement.** Most "janky" multi-effect pages have
+  each effect measuring scroll on its own schedule; they drift apart by a frame
+  and the eye reads chaos. One measured state, read by all, makes layers
+  *phase-locked* — they look intentional because they literally share a clock.
+
+- **Cheap-but-many beats expensive-but-few.** 936 points doing simple positional
+  lerps, plus five DOM layers reading a mutable object, costs less than one
+  heavy library effect — and reads richer, because richness comes from *layers
+  agreeing*, not from any single layer's complexity.
+
+- **Redeploy, don't crossfade.** Human attention tracks *moving objects*. A
+  phase-staggered, arc-curved migration of points gives the eye things to
+  follow; a crossfade gives it nothing and reads as flat compositing.
+
+- **Hold creates legibility; morph creates delight.** Long holds let each
+  formation be *understood* (it's the why-now curve, it's the constellation);
+  the short morph at the seam is the reward. Constant motion would sacrifice
+  both — nothing is understood and nothing is special.
+
+- **Earned motion respects the reader.** Scrub is reserved for instruments that
+  genuinely encode time/state. Decorative scrub (parallax everything, scrub the
+  hero) is the tell of a template; restraint is the tell of a system.
+
+- **Degrade-to-calm is a feature, not a chore.** Because every layer has a
+  static state, the page is *correct* on a low-power phone or for a motion-
+  sensitive user, and the rich version is a pure bonus. The fallback isn't a
+  worse site; it's the same site, quieter.
+
+- **Data-driven choreography scales.** The whole narrative lives in one `SCENES`
+  array and a `PROFILES` table. Re-storyboarding the page is editing data, not
+  rewriting render loops. That is why this system can keep growing (ecosystem
+  constellation, chart particles, the N finale) without collapsing.
+
+---
+
+## 13. File map (where each idea lives)
+
+| Concern | File |
+|---|---|
+| The clock / scroll state | `src/lib/motion/scroll-progress.ts` |
+| Scene storyboard | `src/lib/motion/scenes.ts` |
+| Motion tokens (ease/dur/stagger) | `src/lib/motion/tokens.ts` |
+| Lazy GSAP + reduced-motion gate | `src/lib/motion/gsap-client.ts` |
+| DOM↔WebGL bridge | `src/lib/motion/field-sync.ts` |
+| Interactive field gestures | `src/lib/motion/use-section-field.ts` |
+| WebGL particle field | `src/components/v2/webgl/SignalField.tsx` |
+| 2D fallback field | `src/components/v2/atmosphere/SignalMesh.tsx` |
+| Field/fallback mode switch | `src/components/v2/atmosphere/AtmosphereField.tsx` |
+| Constellation SVG overlay | `src/components/v2/atmosphere/ConstellationOverlay.tsx` |
+| Progress rail | `src/components/v2/atmosphere/ScrollRail.tsx` |
+| Smooth scroll | `src/components/v2/motion/SmoothScroll.tsx` |
+| Attention dimming | `src/components/v2/motion/FocalSpotlight.tsx` |
+| Figure parallax | `src/components/v2/motion/ParallaxDrift.tsx` |
+| Reveal primitives | `src/components/v2/design/Reveal.tsx` |
+| Epilogue runway | `src/components/v2/sections/FinaleSectionV2.tsx` |
+| Scrubbed instruments (examples) | `WhyNowChart.tsx`, `EcosystemDiagram.tsx`, `PinnedSteps.tsx` |
+| CSS tokens + all `v2-*` styles | `src/app/v2.css` |
+
+---
+
+*SHELEG Design is the motion + systems half of this site's identity; pair it
+with `DESIGN.md` for the visual half. The north star for both: it should feel
+like a precision instrument responding to your hand — authority through
+accuracy and restraint, not spectacle.*

package/skill/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: sheleg-design
+description: Use when building or upgrading a cinematic, scroll-driven landing page, marketing site, or hero experience — especially one with a particle/WebGL background, scroll-linked animation, parallax, pinned/scrubbed sections, or formation-changing motion. SHELEG Design is a motion + systems methodology: one scroll "clock" drives many cheap, layered, independently-degradable responses (a particle field, a 2D fallback, attention dimming, parallax, scrubbed instruments, a progress rail) so the page reads as a single precision instrument. Read this before designing the motion architecture of such a site; it pairs with a visual system, not replaces one.
+---
+
+# SHELEG Design
+
+A methodology for landing pages that feel *alive* without feeling busy. Full
+reference (architecture, code-level mechanics, build-from-scratch recipe, file
+map, and the deeper "why") lives in [`SHELEG_DESIGN.md`](./SHELEG_DESIGN.md) next
+to this file — read it before implementing.
+
+## The thesis
+
+A page feels cinematic not from many animations, but from a **single source of
+truth** (scroll position) driving **many cheap, layered responses** that are
+individually quiet and collectively rich. Centralize scroll into one external
+store; let independent layers read it per frame and react in their own language.
+Nothing crossfades — things *redeploy*. Every layer degrades to a calm static
+state.
+
+## The five principles (apply in order)
+
+1. **One clock.** All motion derives from one measured scroll state. Layers never
+   measure scroll independently, so they can never drift out of phase.
+2. **Read per frame, notify rarely.** Hot consumers (WebGL/canvas/rail) read the
+   store imperatively each frame and cause zero React renders. Only coarse,
+   human-visible changes (the current "act"/section) notify the framework.
+3. **Hold, then redeploy.** Hold a formation steady for ~80% of a section, then
+   morph in a short, phase-staggered, arc-curved wave. Ban crossfades.
+4. **Earned motion.** Scrub belongs to instruments that narrate state over time
+   (charts, step flows). Hover/entrance motion stays sub-500ms and never gates
+   content visibility.
+5. **Degrade to calm.** `prefers-reduced-motion` / coarse pointer / no-WebGL all
+   collapse to a static, fully-legible page. The effect is a bonus, never a
+   dependency.
+
+## How to use this skill
+
+When asked to build or upgrade such a site:
+
+1. **Lay the visual system first** (color, type, spacing, components). Motion on
+   top of a weak visual system amplifies the weakness. SHELEG Design is the
+   motion layer — it assumes a visual foundation exists.
+2. **Build bottom-up following the layer order** in `SHELEG_DESIGN.md` §11:
+   the scroll clock → smooth scroll → particle field → 2D fallback → DOM
+   choreography → reveal primitives → scrubbed instruments → (optional) DOM↔WebGL
+   bridge. Each layer is a small, single-responsibility file reading the one clock.
+3. **Storyboard in data.** Express the narrative as a `SCENES` registry (one
+   `{ anchor, formation, focusX, energy }` per section). Iterate on the data
+   before touching render loops.
+4. **Pay the fallback + a11y tax in the same commit** as each layer, never at the
+   end. Every animated component ships its reduced-motion branch immediately.
+5. **Verify** with typecheck/lint/build, screenshots of each scene mid-hold and
+   mid-morph, a reduced-motion pass, and a narrow-viewport pass.
+
+## Non-negotiables (each prevents a real failure mode)
+
+- Centralize scroll in ONE store with two read paths: a live getter for
+  per-frame readers and a coarse subscription for framework-rendered UI.
+- Hold-then-morph (long hold, short smoothstepped tail) — constant morphing
+  reads as nervous; this is the single biggest "calm" lever.
+- Redeploy with a per-point phase-staggered, perpendicular-arc migration — this
+  is what makes a particle field read as premium rather than a screensaver.
+- Drive smooth scroll (e.g. Lenis) from the animation library's ticker so
+  scrubbed instruments and the particle field share one inertia.
+- Lazy-load heavy libs (GSAP/WebGL) out of the initial bundle; WebGL mounts one
+  frame after hydration paints.
+- One ease + a tiny duration/stagger token set for the whole site; no component
+  invents its own curve.
+- For scrubbed SVG: `ease: 'none'`, `pathLength={1}` to normalize paths, and
+  always kill timelines + triggers on cleanup.
+- Animate only `transform` and `opacity`; reserve scrub for genuine instruments.
+
+## When NOT to use it
+
+Skip for static content sites, docs, dashboards, or anything where motion is not
+a goal. Do not bolt the particle field onto a page whose visual system or copy
+isn't finished — fix those first.
+
+---
+
+Read [`SHELEG_DESIGN.md`](./SHELEG_DESIGN.md) for the full architecture, code
+mechanics, the exact morph math, the DOM↔WebGL projection bridge, the
+build-from-scratch recipe, and the file map.