@skyf0xx/hedgehog 2.0.7 → 2.0.9

package/src/skills/hedgehog-bootstrap-landing-page-core/SKILL.md

@@ -10,8 +10,8 @@ add-on layer to run after it, unlike `full-stack-app`'s
 `hedgehog-bootstrap` — by copying a pre-built, pre-verified workspace
 (`src/golden-cores/landing-page/` in the Hedgehog package) rather than
 generating it live: Astro workspace, Tailwind v4 CSS-first token-layer
-config, the library set this core is built on (GSAP, Lenis, SplitType,
-p5.js, ogl).
+config, the library set this core is built on (Motion, Lenis, SplitType,
+Paper.js, ogl).
 This piece is deterministic — the same commands produce the same output
 on every project — so the output is committed once, upstream, and copied
 here instead of re-derived by an agent on every run.

package/src/skills/motif-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: motif-authoring
-description: Use whenever `landing-systems` authors the signature motif (Chain Method step 6, `hedgehog-landing-loop`) or `landing-builder` implements one from `src/motifs/`. Trigger on "draw the motif", "author the motif", "write src/motifs/". Picks the right construction technique — p5.js, CSS, or Canvas 2D — per motif type, and gives the technique for producing each without hand-typed coordinate guessing.
+description: Use whenever `landing-systems` authors the signature motif (Chain Method step 6, `hedgehog-landing-loop`) or `landing-builder` implements one from `src/motifs/`. Trigger on "draw the motif", "author the motif", "write src/motifs/". Picks the right construction technique — Paper.js, CSS, or Canvas 2D — per motif type, and gives the technique for producing each without hand-typed coordinate guessing.
 ---
 
 # Motif Authoring
@@ -20,15 +20,18 @@ continuity, scale range, and literalness. That spec determines which of
 three techniques applies — pick one, don't mix by default:
 
 1. **Organic / generative** (a material's grain, a growth pattern, a
-   natural form that evolves) → **p5.js**. Write the motif as a rule —
-   noise, jitter, growth, a formula-driven point set — not a curve typed
-   out point by point. The generator is legible and adjustable; a
-   hand-typed curve is neither.
+   natural form that evolves) → **Paper.js**. Write the motif as a rule —
+   noise, jitter, growth, a formula-driven point set — driving a scene
+   graph of `Path`/`Group` objects, not a curve typed out point by point.
+   The generator is legible and adjustable; a hand-typed curve is
+   neither. See `paper-js-motifs` for the concrete API patterns
+   (`PaperScope` setup, seeded randomness, the `params` object,
+   setter-based redraw) once this technique is chosen.
 2. **Static geometric** (a spine, a chevron, a blob, a simple silhouette
    that doesn't need to evolve) → **CSS** (`clip-path`, gradients,
    `border-radius`). Build the shape from `clip-path` polygon/shape
    functions, layered gradients, or `border-radius` percentage strings —
-   values you can reason about exactly, animatable directly by GSAP
+   values you can reason about exactly, animatable directly by Motion
    (e.g. tweening a `border-radius` string in place of shape morphing).
 3. **Measured / connective** (a thread, a line, a connector that must
    align to real element positions across the page) → **Canvas 2D with
@@ -42,33 +45,16 @@ three techniques applies — pick one, don't mix by default:
 **Never hand-write multi-point geometry as raw guessed numbers**, in any
 of the three:
 
-- **p5.js** — construct from a formula (sine-based waveform, noise
+- **Paper.js** — construct from a formula (sine-based waveform, noise
   function, L-system, Voronoi cell, particle rule) with named parameters,
   not a manually plotted point list. Express motif variation
   (augmentation/inversion/retrograde, per `landing-systems` step 6's
-  music-theory vocabulary) as parameter changes on the same generator,
-  not a hand-edited copy.
-  - Use **instance mode** (`new p5(sketch, container)`), not global mode
-    — a global-mode sketch leaks `setup`/`draw`/every p5 function onto
-    `window`, which collides with Astro's own module scope and with
-    GSAP/ScrollTrigger's own render loop running on the same page.
-  - Seed every source of randomness explicitly —
-    `p.randomSeed(seed); p.noiseSeed(seed);` — with a fixed, committed
-    seed value. This is what makes "derive from a formula" mean anything
-    in practice: the same seed must always reproduce the exact same
-    motif, so a reviewer (or `landing-critic`) can re-run it and get the
-    committed result, not a fresh roll.
-  - Collect the formula's inputs (particle count, noise scale, growth
-    rate, angle — whatever the generator exposes) into one named
-    `params` object at the top of the sketch, not scattered magic
-    numbers through `draw()`. This is the same object the "state the
-    parameters and what each one is for" verification step below reads
-    from — an ungrouped generator is harder to audit, not just harder to
-    read.
-  - Mount inside a `client:*` island only where the sequencer's beat
-    structure actually calls for the motif to animate; a motif that's
-    static per section doesn't need a live p5 instance at all — render
-    once and let CSS/GSAP handle any transform-level movement instead.
+  music-theory vocabulary) as parameter changes that update the same
+  scene graph's object properties, not a hand-edited copy. See
+  `paper-js-motifs` for the concrete implementation patterns (scoped
+  `PaperScope`, seeded PRNG, the `params` object, setter-based redraw)
+  — this skill governs the choice and the audit, that one governs the
+  code.
 - **CSS** — build from `clip-path`'s named shape functions
   (`polygon()`, `circle()`, `ellipse()`, `inset()` with rounded corners)
   or `border-radius`'s percentage syntax, composed via layering and
@@ -87,12 +73,15 @@ A motif is not correct because it compiles. Before writing it into
 - **Render it and look.** Use the Bash tool to run the dev server or a
   standalone preview and view the actual output — don't judge geometry
   or a Canvas draw call from the source alone.
+- **If the scene graph exposes setters, call every one of them at least
+  once before judging it correct** — confirm each produces the visual
+  update it's meant to, not just that the initial render looks right.
 - **State the construction's parameters and what each one is for** — a
-  p5.js formula's inputs, a `clip-path` shape's control values, a Canvas
-  draw's measured inputs — before accepting it. If you can't say why a
-  value is what it is, it was guessed, not authored — redo it via the
-  technique's proper primitives.
-- **For p5.js, confirm the seed is fixed and committed**, not left to
+  Paper.js formula's inputs, a `clip-path` shape's control values, a
+  Canvas draw's measured inputs — before accepting it. If you can't say
+  why a value is what it is, it was guessed, not authored — redo it via
+  the technique's proper primitives.
+- **For Paper.js, confirm the seed is fixed and committed**, not left to
   default/time-based randomness — re-running the sketch must reproduce
   the exact motif that was reviewed, not a new variation each load.
 - **Check symmetry/proportion deliberately** where the source motif
@@ -118,10 +107,10 @@ A motif is not correct because it compiles. Before writing it into
   numbers are unreadable — there's no way to tell what a curve looks
   like from its `d` string while writing it, so hand-typed paths drift
   into lumpy, asymmetric, or self-intersecting geometry regardless of
-  how carefully they're written. If a motif genuinely doesn't fit p5.js,
-  CSS, or Canvas 2D, that's a signal to reconsider the motif's source or
-  literalness with `landing-systems` — not a reason to fall back to
-  hand-authored SVG.
+  how carefully they're written. If a motif genuinely doesn't fit
+  Paper.js, CSS, or Canvas 2D, that's a signal to reconsider the motif's
+  source or literalness with `landing-systems` — not a reason to fall
+  back to hand-authored SVG.
 - `landing-builder` implements the motif exactly as authored here — a
   motif that's hard to render cleanly should be fixed at this step, not
   smoothed over during build.

package/src/skills/paper-js-motifs/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: paper-js-motifs
+description: Use whenever `landing-builder` implements a motif that `motif-authoring` has routed to Paper.js (organic/generative source — noise, jitter, growth, a formula-driven point set). Trigger on "implement the motif in Paper.js", "write the PaperScope sketch", "src/motifs/*.ts" for an organic motif. Gives the concrete API patterns — scoping, seeded randomness, the params object, setter-based redraw — that keep a Paper.js sketch a formula instead of hand-plotted geometry.
+---
+
+# Paper.js Motifs
+
+`motif-authoring` decides *that* a motif is organic/generative and
+therefore Paper.js; this skill covers *how* to write the Paper.js sketch
+itself once that decision is made. Every pattern below exists to keep
+the sketch a legible, re-runnable formula — not a one-off script that
+happens to draw the right thing once.
+
+## Scope the sketch to its own `PaperScope`
+
+Never call the global `paper.setup(canvas)` API. A landing page runs an
+Astro island's own module scope, Motion's render loop, and potentially
+more than one motif on the same page — the global `paper` object is
+shared mutable state across all of them, and one sketch's `paper.project`
+silently becomes another's.
+
+```ts
+import paper from 'paper';
+
+const scope = new paper.PaperScope();
+scope.setup(canvasEl);
+
+scope.activate();
+// construct the scene graph here — every paper.* call inside this
+// block resolves against `scope`, not the global instance
+scope.view.draw();
+```
+
+Every exported function this skill's patterns produce (draw, and any
+setter) must call `scope.activate()` before touching `paper.*`,
+including on repeat calls — a setter invoked after some other scope
+activated in between will otherwise mutate the wrong project.
+
+## Seed every source of randomness
+
+Paper.js has no built-in seeded noise or random. Bring a small,
+dependency-free PRNG (a mulberry32 or sfc32-style function is enough —
+a few lines, no package) and seed it with a fixed literal committed in
+the sketch:
+
+```ts
+function mulberry32(seed: number) {
+  return function () {
+    seed |= 0;
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const rand = mulberry32(0x5eed); // fixed seed — never Date.now() or Math.random()
+```
+
+Use `rand()` for every stochastic input the formula needs (jitter
+amount, particle position, growth angle). This is what makes "derive
+from a formula" a real guarantee rather than a one-time roll: re-running
+the sketch, in dev or in `landing-critic`'s review, must reproduce the
+exact motif that was committed — never a fresh variation per load.
+
+## Collect inputs into one `params` object
+
+```ts
+const params = {
+  pointCount: 48,
+  noiseScale: 0.08,
+  growthRate: 1.4,
+  baseAngle: Math.PI / 6,
+  seed: 0x5eed,
+};
+```
+
+Every magic number the construction function reads comes from this
+object, not a literal scattered through the formula. This object is
+also the answer to "state the construction's parameters and what each
+one is for" — `motif-authoring`'s verification step reads directly from
+it, so an ungrouped generator is a review blocker, not just a style
+complaint.
+
+## Build the scene graph from the formula, once
+
+Construct `Path`/`Group` objects by iterating the formula's output —
+never by typing coordinates by hand:
+
+```ts
+scope.activate();
+
+const path = new scope.Path({
+  strokeColor: 'var(--color-accent)',
+  strokeWidth: 2,
+});
+
+for (let i = 0; i < params.pointCount; i++) {
+  const t = i / params.pointCount;
+  const angle = params.baseAngle * i + rand() * params.noiseScale;
+  const radius = 40 + params.growthRate * i;
+  path.add(
+    new scope.Point(Math.cos(angle) * radius, Math.sin(angle) * radius),
+  );
+}
+path.smooth();
+
+scope.view.draw();
+```
+
+Don't add a `view.onFrame` handler unless `landing-sequencer`'s beat
+structure specifies continuous motion for this motif. A motif that's
+static per section needs exactly this: build once, `view.draw()` once.
+
+## Setters mutate scene graph state directly — never replay the script
+
+Motif variation (augmentation/inversion/retrograde, per
+`landing-systems` step 6's vocabulary) is a property assignment on the
+already-built objects, followed by a redraw — not a second call into the
+construction function:
+
+```ts
+export function setGrowth(factor: number) {
+  scope.activate();
+  path.segments.forEach((seg, i) => {
+    seg.point = seg.point.multiply(factor);
+  });
+  scope.view.draw();
+}
+```
+
+There's no transform/style stack to reset before a setter runs, because
+nothing replays — the scene graph holds current state directly, and the
+setter changes that state in place. If a redraw needs a genuinely
+different point set (not a transform of the existing one), recompute
+from `params` and reassign `path.segments = newSegments`, still followed
+by `scope.view.draw()`, still without reconstructing `path` itself.
+
+## Common mistakes this skill exists to prevent
+
+- **Calling `paper.setup()` on the global scope** instead of a scoped
+  `PaperScope` instance — breaks the moment a second motif or another
+  Paper.js consumer runs on the same page.
+- **Using `Math.random()` or a time-based seed** — makes the motif
+  non-reproducible; every reload or every review produces a different
+  shape.
+- **A draw loop (`view.onFrame`) on a motif the spec says is static** —
+  wastes render budget and fights Motion's own scroll-driven timeline
+  for the same frame budget.
+- **Reconstructing the whole `Path` inside a setter** instead of mutating
+  existing segments/properties — loses the "retained-mode scene graph"
+  property that's the entire reason `motif-authoring` picked Paper.js
+  over an imperative Canvas redraw.
+- **A literal scattered through the loop body** instead of a named field
+  on `params` — indistinguishable from a guessed number to a reviewer,
+  even when it was in fact derived from something real.
+
+## Constraints
+
+- This skill covers Paper.js API usage only. Whether a given motif
+  belongs in Paper.js at all — versus CSS or Canvas 2D — is
+  `motif-authoring`'s decision (source, persistence, continuity, scale
+  range, literalness from `landing-systems` step 6), not this skill's.
+- `paper` is already a pinned dependency in the `landing-page` core
+  (`src/golden-cores/landing-page/package.json`) — never add a
+  competing geometry/animation library to work around something this
+  skill's patterns don't cover.

package/src/templates/CLAUDE.core.landing-page.md

@@ -44,8 +44,8 @@ edited after a phase closes.
   the token system that reconciles them, and the signature motif. Owns
   everything that becomes a Tailwind token or a copy rule.
 - **`landing-sequencer`** — per-section transition type, weight, spacing,
-  and beat structure — the GSAP/ScrollTrigger/Lenis pacing spec the
-  Builder implements against.
+  and beat structure — the Motion/Lenis pacing spec the Builder
+  implements against.
 - **`landing-copywriter`** — the final page copy: headline (2 backups),
   every section's body text, CTA text — written to the voice spec and
   the sequence's beat structure. Presented as its own artifact for the
@@ -66,15 +66,16 @@ edited after a phase closes.
 
 **Astro** (zero-JS-by-default shell, islands only where interaction is
 genuinely needed) · **Tailwind v4, CSS-first** (config as token layer
-only — no component library on top) · **GSAP + ScrollTrigger**, scoped to
+only — no component library on top) · **Motion**, scoped to
 CSS/transform targets only, no plugins (primary animation engine; owns
-Sequencer pacing and top/heart/base fade timing) · **Lenis** (smooth-
-scroll feel, the "weight and suspension" dial) · **SplitType**
-(line/word/char copy-reveal splitting) · **p5.js** (organic/generative
-motifs — described as a rule: noise, jitter, growth — not hand-typed path
-data) · **CSS `clip-path` / gradients / `border-radius`** (static
-geometric motifs — spines, chevrons, blobs — GSAP-animatable directly,
-zero coordinate-guessing risk) · **Canvas 2D with computed coordinates**
+Sequencer pacing and top/heart/base fade timing) · **Lenis**
+(smooth-scroll feel, the "weight and suspension" dial) · **SplitType**
+(line/word/char copy-reveal splitting) · **Paper.js** (organic/generative
+motifs — described as a rule: noise, jitter, growth — not hand-typed
+path data; see the `paper-js-motifs` skill for implementation patterns)
+· **CSS `clip-path` / gradients / `border-radius`** (static geometric
+motifs — spines, chevrons, blobs — Motion-animatable directly, zero
+coordinate-guessing risk) · **Canvas 2D with computed coordinates**
 (measured/connective motifs — threads/lines that align to real DOM
 positions, drawn from measured values) · **`ogl`** (lightweight WebGL) or
 a raw shader (a continuous background field spanning the full page
@@ -97,11 +98,11 @@ Vocabulary and derive the right choice, not to default to something
 off-the-shelf.
 
 Motifs are always constructed from a formula or a measurement, never
-hand-typed coordinates: an organic motif is a p5.js rule (noise, jitter,
-growth), a static geometric motif is CSS (`clip-path`, gradients,
-`border-radius`), and a measured/connective motif is Canvas 2D drawn from
-real DOM positions. See the `motif-authoring` skill for the technique
-per motif type.
+hand-typed coordinates: an organic motif is a Paper.js scene graph driven
+by a rule (noise, jitter, growth), a static geometric motif is CSS
+(`clip-path`, gradients, `border-radius`), and a measured/connective
+motif is Canvas 2D drawn from real DOM positions. See the
+`motif-authoring` skill for the technique per motif type.
 
 ### Layout
 
@@ -110,7 +111,7 @@ astro.config.mjs     Astro workspace root
 src/
   pages/              one file per page (usually just index.astro)
   sections/           one component per page section, in Sequencer order
-  motifs/             the signature motif (p5.js / CSS / Canvas 2D) + its variation rules
+  motifs/             the signature motif (Paper.js / CSS / Canvas 2D) + its variation rules
   styles/             global.css — Tailwind v4 CSS-first import + the `@theme` token layer (hex values, type roles, spacing unit, easing family from Step 5)
 .hedgehog/
   BMAD/               vendored BMAD-METHOD shelf's raw output (brief, PR-FAQ, PRD, UX spec, research) —