hyperframes 0.3.0 → 0.3.1

package/dist/skills/hyperframes/references/css-patterns.md

@@ -15,16 +15,16 @@ Pure CSS + GSAP implementations of all five MarkerHighlight.js drawing modes. Us
 Yellow marker sweep behind text. The most common mode.
 
 ```html
-<div class="mh-highlight-wrap">
-  <div class="mh-highlight-bar" id="hl-1"></div>
+<span class="mh-highlight-wrap">
+  <span class="mh-highlight-bar" id="hl-1"></span>
   <span class="mh-highlight-text">highlighted text</span>
-</div>
+</span>
 ```
 
 ```css
 .mh-highlight-wrap {
   position: relative;
-  display: inline-block;
+  display: inline;
 }
 .mh-highlight-bar {
   position: absolute;
@@ -75,16 +75,16 @@ tl.to(
 Hand-drawn circle around text. Use `border-radius: 50%` with a slight rotation for organic feel.
 
 ```html
-<div class="mh-circle-wrap">
+<span class="mh-circle-wrap">
   <span class="mh-circle-text" id="circle-word">IMPORTANT</span>
-  <div class="mh-circle-ring" id="circle-1"></div>
-</div>
+  <span class="mh-circle-ring" id="circle-1"></span>
+</span>
 ```
 
 ```css
 .mh-circle-wrap {
   position: relative;
-  display: inline-block;
+  display: inline;
 }
 .mh-circle-text {
   position: relative;
@@ -148,29 +148,29 @@ tl.to(
 Radiating lines from text center. Each line is a positioned div rotated to its angle.
 
 ```html
-<div class="mh-burst-wrap">
+<span class="mh-burst-wrap">
   <span class="mh-burst-text">WOW</span>
-  <div class="mh-burst-container" id="burst-1">
-    <div class="mh-burst-line" style="--angle: 0deg; --len: 70px;"></div>
-    <div class="mh-burst-line" style="--angle: 30deg; --len: 55px;"></div>
-    <div class="mh-burst-line" style="--angle: 60deg; --len: 80px;"></div>
-    <div class="mh-burst-line" style="--angle: 90deg; --len: 45px;"></div>
-    <div class="mh-burst-line" style="--angle: 120deg; --len: 65px;"></div>
-    <div class="mh-burst-line" style="--angle: 150deg; --len: 75px;"></div>
-    <div class="mh-burst-line" style="--angle: 180deg; --len: 50px;"></div>
-    <div class="mh-burst-line" style="--angle: 210deg; --len: 60px;"></div>
-    <div class="mh-burst-line" style="--angle: 240deg; --len: 80px;"></div>
-    <div class="mh-burst-line" style="--angle: 270deg; --len: 40px;"></div>
-    <div class="mh-burst-line" style="--angle: 300deg; --len: 70px;"></div>
-    <div class="mh-burst-line" style="--angle: 330deg; --len: 55px;"></div>
-  </div>
-</div>
+  <span class="mh-burst-container" id="burst-1">
+    <span class="mh-burst-line" style="--angle: 0deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 30deg; --len: 55px;"></span>
+    <span class="mh-burst-line" style="--angle: 60deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 90deg; --len: 45px;"></span>
+    <span class="mh-burst-line" style="--angle: 120deg; --len: 65px;"></span>
+    <span class="mh-burst-line" style="--angle: 150deg; --len: 75px;"></span>
+    <span class="mh-burst-line" style="--angle: 180deg; --len: 50px;"></span>
+    <span class="mh-burst-line" style="--angle: 210deg; --len: 60px;"></span>
+    <span class="mh-burst-line" style="--angle: 240deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 270deg; --len: 40px;"></span>
+    <span class="mh-burst-line" style="--angle: 300deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 330deg; --len: 55px;"></span>
+  </span>
+</span>
 ```
 
 ```css
 .mh-burst-wrap {
   position: relative;
-  display: inline-block;
+  display: inline;
 }
 .mh-burst-text {
   position: relative;
@@ -186,6 +186,7 @@ Radiating lines from text center. Each line is a positioned div rotated to its a
 }
 .mh-burst-line {
   position: absolute;
+  display: block;
   width: 3px;
   height: var(--len);
   background: #1e88e5;
@@ -214,7 +215,7 @@ tl.fromTo(
 Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffset`.
 
 ```html
-<div class="mh-scribble-wrap">
+<span class="mh-scribble-wrap">
   <span class="mh-scribble-text">underlined text</span>
   <svg class="mh-scribble-svg" viewBox="0 0 500 24" preserveAspectRatio="none">
     <path
@@ -232,7 +233,7 @@ Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffs
 ```css
 .mh-scribble-wrap {
   position: relative;
-  display: inline-block;
+  display: inline;
 }
 .mh-scribble-text {
   position: relative;
@@ -283,19 +284,19 @@ Scale the path's viewBox width to match text width. The wave pattern `Q x1,y1 x2
 Cross-hatch lines over de-emphasized text. Multiple angled lines create a "crossed out" effect.
 
 ```html
-<div class="mh-sketchout-wrap">
+<span class="mh-sketchout-wrap">
   <span class="mh-sketchout-text">old price</span>
-  <div class="mh-sketchout-lines" id="sketchout-1">
-    <div class="mh-sketchout-line mh-sketchout-fwd"></div>
-    <div class="mh-sketchout-line mh-sketchout-bwd"></div>
-  </div>
-</div>
+  <span class="mh-sketchout-lines" id="sketchout-1">
+    <span class="mh-sketchout-line mh-sketchout-fwd"></span>
+    <span class="mh-sketchout-line mh-sketchout-bwd"></span>
+  </span>
+</span>
 ```
 
 ```css
 .mh-sketchout-wrap {
   position: relative;
-  display: inline-block;
+  display: inline;
 }
 .mh-sketchout-text {
   position: relative;
@@ -312,6 +313,7 @@ Cross-hatch lines over de-emphasized text. Multiple angled lines create a "cross
 }
 .mh-sketchout-line {
   position: absolute;
+  display: block;
   top: 50%;
   left: 0;
   width: 100%;

package/dist/skills/hyperframes/references/transitions/catalog.md

@@ -28,19 +28,9 @@ These cause real bugs if violated.
 
 **Don't use:** Star iris (polygon interpolation broken), tilt-shift (no selective CSS blur), lens flare (visible shape, not optical), hinge/door (distorts too fast).
 
-## Hard Rules (Shader)
-
-Read [shader-setup.md](./shader-setup.md) for the full setup code these rules apply to.
-
-**WebGL setup:** `gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false)` — NOT true. Vertex shader flips Y: `v_uv.y = 1.0 - v_uv.y`. `preserveDrawingBuffer: true` required for HyperFrames capture. No `fwidth()` without extension — use constant `0.003`.
-
-**Rendering model:** GL canvas stays visible entire composition — DOM scenes remain `opacity: 0`. Passthrough shader for holds. Scene capture = static snapshots at load; animated GSAP tweens on elements won't appear.
-
-**Scene capture:** Canvas `fillText` doesn't match CSS fonts exactly (known, not a bug). No CSS gradients or SVGs. Images and videos ARE supported via `ctx.drawImage()`. Video scenes re-capture every frame during transitions via `recaptureVideoScene()`.
-
-**Timeline:** Use `tl.call()` for begin/end — NOT `onStart`/`onComplete`. Each tween proxy `{p:0}` must be unique. Never boomerang (`u_progress*(1.-u_progress)*4.`). Morph both scenes.
+## Shader Transitions
 
-**Shader code:** One noise library per shader (NQ or ND, not both). Always `clamp(uv, 0., 1.)`.
+Shader setup, WebGL init, capture, and fragment shaders are handled by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). Read the package source for API details. Compositions using shaders must follow the CSS rules in [transitions.md](../transitions.md) § "Shader-Compatible CSS Rules".
 
 ## Scene Template
 
@@ -118,15 +108,10 @@ All code examples use `old` for the outgoing scene-inner selector and `new` for
 | Distortion     | Glitch, chromatic aberration, ripple, VHS tape       | [css-distortion.md](./css-distortion.md)   |
 | Mechanical     | Shutter, clock wipe                                  | [css-mechanical.md](./css-mechanical.md)   |
 | Grid           | Grid dissolve                                        | [css-grid.md](./css-grid.md)               |
-| Other          | Flash cut, gravity drop, morph circle                | [css-other.md](./css-other.md)             |
+| Other          | Gravity drop, morph circle                           | [css-other.md](./css-other.md)             |
 | Blur           | Blur through, directional blur                       | [css-blur.md](./css-blur.md)               |
 | Destruction    | Page burn                                            | [css-destruction.md](./css-destruction.md) |
 
 ## Shader Transitions
 
-WebGL fragment shaders that composite between scene textures per-pixel. Require setup boilerplate.
-
-| What                                                                                                                                                                                                                                            | Reference                                        |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| Setup (canvas, capture, WebGL init, render loop, GSAP integration)                                                                                                                                                                              | [shader-setup.md](./shader-setup.md)             |
-| Fragment shaders (14 transitions: domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, flash through white, cross-warp morph, light leak) | [shader-transitions.md](./shader-transitions.md) |
+WebGL shader transitions are provided by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). The package handles setup, capture, WebGL init, render loop, and GSAP integration. Read the package source for available shaders and API — do not copy raw GLSL manually.

package/dist/skills/hyperframes/references/transitions/css-other.md

@@ -1,16 +1,5 @@
 ## Other
 
-### Flash Cut
-
-White full-screen overlay flashes at swap point. 0.03s on, 0.1s off.
-
-```js
-tl.to("#flash-overlay", { opacity: 1, duration: 0.03, ease: "power4.out" }, T);
-tl.set(old, { opacity: 0 }, T + 0.03);
-tl.set(new, { opacity: 1 }, T + 0.03);
-tl.to("#flash-overlay", { opacity: 0, duration: 0.1, ease: "power2.out" }, T + 0.05);
-```
-
 ### Gravity Drop
 
 Old scene falls down with slight rotation. New scene was behind it. Needs z-index.

package/dist/skills/hyperframes/references/transitions.md

@@ -1,14 +1,23 @@
 # Scene Transitions
 
-A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A flash cut says "wake up." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
+A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
+
+## Animation Rules for Multi-Scene Compositions
+
+These are non-negotiable for every multi-scene composition:
+
+1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.
+2. **Every scene uses entrance animations.** Elements animate IN via `gsap.from()` — opacity, position, scale, etc. No scene should pop fully-formed onto screen.
+3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.
+4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.
 
 ## Energy → Primary Transition
 
-| Energy                                   | Primary                      | Accent for key moments         | Duration  | Easing                 |
-| ---------------------------------------- | ---------------------------- | ------------------------------ | --------- | ---------------------- |
-| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |
-| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |
-| **High** (promos, sports, music, launch) | Flash cut, zoom through      | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`       |
+| Energy                                   | CSS Primary                  | Shader Primary                       | Accent                         | Duration  | Easing                 |
+| ---------------------------------------- | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ---------------------- |
+| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Cross-warp morph, thermal distortion | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |
+| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Whip pan, cinematic zoom             | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |
+| **High** (promos, sports, music, launch) | Zoom through, overexposure   | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`       |
 
 Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.
 
@@ -16,17 +25,17 @@ Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different
 
 Think about what the transition _communicates_, not just what it looks like.
 
-| Mood                     | Transitions                                                                                                                                                           | Why it works                                                                                                            |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| **Warm / inviting**      | Light leak, blur crossfade, focus pull, film burn, light leak (shader), thermal distortion                                                                            | Soft edges, warm color washes. Nothing sharp or mechanical. The transition feels like sunlight.                         |
-| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve, gravitational lens                                                                                                 | Content transforms mechanically — compressed, shrunk, sliced, gridded. Zoom out creates clinical distance. No softness. |
-| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter, whip pan                                                                                                          | Like turning a page or slicing a layout. Clean directional movement. Whip pan is a fast editorial camera move.          |
-| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration, glitch (shader), chromatic split (shader)                                                              | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines.                             |
-| **Tense / edgy**         | Glitch, VHS, chromatic aberration, flash cut, ripple, ridged burn, glitch (shader)                                                                                    | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.                               |
-| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe, ripple waves, swirl vortex                                                                              | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.                                    |
-| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, diagonal split, color dip to black, cinematic zoom (shader), gravitational lens, domain warp, flash through white | Scale, weight, light extremes. Shader transitions add per-pixel depth.                                                  |
-| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black, slow crossfade, cross-warp morph, thermal distortion                                                                  | Restraint. Cross-warp morph flows both scenes into each other organically.                                              |
-| **Retro / analog**       | Film burn, light leak, VHS, clock wipe                                                                                                                                | Organic imperfection. Warm color bleeds, scan line displacement. Clock wipe evokes broadcast TV.                        |
+| Mood                     | Transitions                                                                                                                          | Why it works                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| **Warm / inviting**      | Light leak, blur crossfade, focus pull, film burn · **Shader:** thermal distortion, light leak, cross-warp morph                     | Soft edges, warm color washes. Nothing sharp or mechanical.                                 |
+| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve · **Shader:** gravitational lens                                                   | Content transforms mechanically — compressed, shrunk, sliced, gridded.                      |
+| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter · **Shader:** whip pan                                                            | Like turning a page or slicing a layout. Clean directional movement.                        |
+| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration · **Shader:** glitch, chromatic split                                  | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines. |
+| **Tense / edgy**         | Glitch, VHS, chromatic aberration, ripple · **Shader:** ridged burn, glitch, domain warp                                             | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.   |
+| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe · **Shader:** ripple waves, swirl vortex                                | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.        |
+| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, color dip to black · **Shader:** cinematic zoom, gravitational lens, domain warp | Scale, weight, light extremes. Shader transitions add per-pixel depth.                      |
+| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black · **Shader:** cross-warp morph, thermal distortion                                    | Restraint. Cross-warp morph flows both scenes into each other organically.                  |
+| **Retro / analog**       | Film burn, light leak, VHS, clock wipe · **Shader:** light leak                                                                      | Organic imperfection. Warm color bleeds, scan line displacement.                            |
 
 ## Narrative Position
 
@@ -62,34 +71,41 @@ Think about what the transition _communicates_, not just what it looks like.
 
 Read [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.
 
-| Category             | Transitions                                                                                                                                                                                                           |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Content-transforming | Push slide, vertical push, elastic push, squeeze, zoom through, zoom out, gravity drop, 3D flip                                                                                                                       |
-| Reveal/mask          | Circle iris, diamond iris, diagonal split, clock wipe, shutter                                                                                                                                                        |
-| Dissolve             | Crossfade, blur crossfade, focus pull, color dip                                                                                                                                                                      |
-| Cover                | Staggered blocks, horizontal blinds, vertical blinds                                                                                                                                                                  |
-| Light                | Light leak, overexposure burn, film burn                                                                                                                                                                              |
-| Distortion           | Glitch, chromatic aberration, ripple, VHS tape                                                                                                                                                                        |
-| Pattern              | Grid dissolve                                                                                                                                                                                                         |
-| Instant              | Flash cut, morph circle                                                                                                                                                                                               |
-| Shader (WebGL)       | Domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, flash through white, cross-warp morph, light leak (shader) |
+| Category    | CSS                                                            | Shader (WebGL)                                                            |
+| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Push/slide  | Push slide, vertical push, elastic push, squeeze               | Whip pan                                                                  |
+| Scale/zoom  | Zoom through, zoom out, gravity drop, 3D flip                  | Cinematic zoom, gravitational lens                                        |
+| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris                                                                  |
+| Dissolve    | Crossfade, blur crossfade, focus pull, color dip               | Cross-warp morph, domain warp                                             |
+| Cover       | Staggered blocks, horizontal blinds, vertical blinds           | —                                                                         |
+| Light       | Light leak, overexposure burn, film burn                       | Light leak (shader), thermal distortion                                   |
+| Distortion  | Glitch, chromatic aberration, ripple, VHS tape                 | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |
+| Pattern     | Grid dissolve, morph circle                                    | —                                                                         |
 
 ## Transitions That Don't Work in CSS
 
 Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.
 
-## CSS vs Shader: When to Use Which
+## CSS vs Shader
+
+CSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas — they can warp, dissolve, and morph in ways CSS cannot.
+
+**Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package — import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.
+
+When a composition uses shader transitions, ALL transitions in that composition should be shader-based (the WebGL canvas replaces DOM-based scene switching). Don't mix CSS and shader transitions in the same composition.
+
+## Shader-Compatible CSS Rules
 
-Most compositions should use **CSS/GSAP transitions** (the other categories above). They're simpler, lighter, and handle most needs. Use **shader transitions** only when you need an effect that CSS can't achieve:
+Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:
 
-| Use CSS/GSAP when                              | Use Shader when                                 |
-| ---------------------------------------------- | ----------------------------------------------- |
-| Opacity, transform, clip-path, filter effects  | Per-pixel noise dissolves, domain warping       |
-| Simple crossfades, wipes, slides               | Both scenes actively morph into each other      |
-| No images/video in scenes (text + shapes only) | Live video needs to play through the transition |
-| Quick to set up, no boilerplate                | Willing to add WebGL setup layer (~200 lines)   |
+1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.
+2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.
+3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.
+4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.
+5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.
+6. **Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config.** The package captures scene elements via html2canvas. Both the CSS `background-color` on `.scene` and the `bgColor` config must match. Without either, the texture renders as black.
 
-Shader transitions require setup boilerplate (canvas, scene capture, WebGL init). Read [transitions/shader-setup.md](transitions/shader-setup.md) for the complete code. The fragment shaders themselves are in the Shader section of [transitions/catalog.md](transitions/catalog.md).
+These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
 
 ## Visual Pattern Warning
 

package/dist/skills/hyperframes/references/{fonts.md → typography.md}

@@ -4,7 +4,11 @@ The compiler embeds supported fonts — just write `font-family` in CSS.
 
 ## Banned
 
-Inter, Roboto, Open Sans, Noto Sans, Arimo, Lato, Source Sans, PT Sans, Nunito, Poppins, Outfit, Sora, Playfair Display, Cormorant Garamond, Bodoni Moda, EB Garamond, Cinzel, Prata
+Training-data defaults that every LLM reaches for. These produce monoculture across compositions.
+
+Inter, Roboto, Open Sans, Noto Sans, Arimo, Lato, Source Sans, PT Sans, Nunito, Poppins, Outfit, Sora, Playfair Display, Cormorant Garamond, Bodoni Moda, EB Garamond, Cinzel, Prata, Syne
+
+**Syne in particular** is the most overused "distinctive" display font. It is an instant AI design tell.
 
 ## Guardrails
 
@@ -34,16 +38,18 @@ Don't default to what you know. If the content is luxury, a grotesque sans might
 Save this script to `/tmp/fontquery.py` and run with `curl -s 'https://fonts.google.com/metadata/fonts' > /tmp/gfonts.json && python3 /tmp/fontquery.py /tmp/gfonts.json`:
 
 ```python
-import json, sys
+import json, sys, random
 from collections import OrderedDict
 
+random.seed()  # true random each run
+
 with open(sys.argv[1]) as f:
     data = json.load(f)
 fonts = data.get("familyMetadataList", [])
 
 ban = {"Inter","Roboto","Open Sans","Noto Sans","Lato","Poppins","Source Sans 3",
        "PT Sans","Nunito","Outfit","Sora","Playfair Display","Cormorant Garamond",
-       "Bodoni Moda","EB Garamond","Cinzel","Prata","Arimo","Source Sans Pro"}
+       "Bodoni Moda","EB Garamond","Cinzel","Prata","Arimo","Source Sans Pro","Syne"}
 skip_pfx = ("Roboto","Noto ","Google Sans","Bpmf","Playwrite","Anek","BIZ ",
             "Nanum","Shippori","Sawarabi","Zen ","Kaisei","Kiwi ","Yuji ","Radio ")
 
@@ -77,28 +83,15 @@ for f in fonts:
     if f.get("category") == "Monospace" and f.get("dateAdded","") >= "2018-01-01" and f.get("popularity",9999) < 600:
         R["Monospace"].append(f); seen.add(f["family"])
 
-# Impact & Condensed — curated names + heavy display fonts
+# Impact & Condensed — heavy display fonts with 800+ weight
 R["Impact & Condensed"] = []
-impact = {"Bebas Neue","Archivo Black","Big Shoulders Display","Teko","League Gothic",
-          "Barlow Condensed","Staatliches","Anton","Oswald","Saira","Syne",
-          "Titillium Web","Alumni Sans","Advent Pro"}
 for f in fonts:
     if not ok(f) or f["family"] in seen: continue
-    is_impact = f["family"] in impact
-    is_heavy_display = ("Display" in (f.get("classifications") or [])
-        and any(k in list(f.get("fonts",{}).keys()) for k in ("800","900"))
-        and f.get("popularity",9999) < 400
-        and f.get("category") in ("Sans Serif","Display"))
-    if is_impact or is_heavy_display:
+    has_heavy = any(k in list(f.get("fonts",{}).keys()) for k in ("800","900"))
+    is_display = f.get("category") in ("Sans Serif","Display")
+    if has_heavy and is_display and f.get("popularity",9999) < 400:
         R["Impact & Condensed"].append(f); seen.add(f["family"])
 
-# Bold Geometric Display — curated
-R["Bold Geometric Display"] = []
-for f in fonts:
-    if not ok(f) or f["family"] in seen: continue
-    if f["family"] in {"DM Serif Display","Abril Fatface","Righteous","Orbitron","Black Ops One"}:
-        R["Bold Geometric Display"].append(f); seen.add(f["family"])
-
 # Script & Handwriting — popular (<300)
 R["Script & Handwriting"] = []
 for f in fonts:
@@ -106,21 +99,16 @@ for f in fonts:
     if f.get("category") == "Handwriting" and f.get("popularity",9999) < 300:
         R["Script & Handwriting"].append(f); seen.add(f["family"])
 
-# Established Classics — good older fonts
-R["Established Classics"] = []
-classics = {"Josefin Sans","Raleway","Montserrat","Abel","Exo","Red Hat Display",
-            "Rubik","Alegreya","Arvo","Besley","Crimson Text","Fraunces",
-            "Lora","Merriweather","Vollkorn"}
-for f in fonts:
-    if f["family"] in classics and f["family"] not in seen:
-        R["Established Classics"].append(f); seen.add(f["family"])
 
-# Print
+# Randomize the top 5 in each category so the LLM doesn't always pick the same first result
 for cat in R:
     R[cat].sort(key=lambda x: x.get("popularity",9999))
+    top5 = R[cat][:5]
+    rest = R[cat][5:]
+    random.shuffle(top5)
+    R[cat] = top5 + rest
 limits = {"Trending Sans":15,"Trending Serif":12,"Monospace":8,
-          "Impact & Condensed":12,"Bold Geometric Display":8,
-          "Script & Handwriting":10,"Established Classics":20}
+          "Impact & Condensed":12,"Script & Handwriting":10}
 for cat in R:
     items = R[cat][:limits.get(cat,10)]
     if not items: continue
@@ -131,4 +119,57 @@ for cat in R:
     print()
 ```
 
-Seven categories: trending sans, trending serif, monospace, impact/condensed, bold geometric, script/handwriting, and established classics. Cross classification boundaries when pairing.
+Five categories: trending sans, trending serif, monospace, impact/condensed, script/handwriting. All dynamically filtered from Google Fonts metadata — no hardcoded font names. Cross classification boundaries when pairing.
+
+## Selection Thinking
+
+Don't pick fonts by category reflex (editorial → serif, tech → mono, modern → geometric sans). That's pattern matching, not design.
+
+1. **Name the register.** What voice is the content speaking in? Institutional authority? Personal confession? Technical precision? Casual irreverence? The register narrows the field more than the category.
+2. **Think physically.** Imagine the font as a physical object the brand could ship — a museum exhibit caption, a hand-painted shop sign, a 1970s mainframe terminal manual, a fabric label inside a coat, a children's book printed on cheap newsprint, a tax form. Whichever physical object fits the register is pointing at the right _kind_ of typeface.
+3. **Reject your first instinct.** The first font that feels right is usually your training-data default for that register. If you picked it last time too, find something else.
+4. **Cross-check the assumption.** An editorial brief does NOT need a serif. A technical brief does NOT need a sans. A children's product does NOT need a rounded display font. The most distinctive choice often contradicts the category expectation.
+
+## Similar-Font Pairing
+
+Never pair two fonts that are similar but not identical — two geometric sans-serifs, two transitional serifs, two humanist sans. They create visual friction without clear hierarchy. The viewer senses something is "off" but can't articulate it. Either use one font at two weights, or pair fonts that contrast on multiple axes: serif + sans, condensed + wide, geometric + humanist.
+
+## Dark Backgrounds
+
+Light text on dark backgrounds creates two optical illusions you need to compensate for:
+
+- **Increased apparent weight.** Light-on-dark reads heavier than dark-on-light at the same `font-weight`. Use 350 instead of 400 for body text. Headlines are less affected because size compensates.
+- **Tighter apparent spacing.** Light halos around letterforms reduce perceived gaps. Increase `line-height` by 0.05-0.1 beyond your light-background value. For display sizes, add 0.01em `letter-spacing` to counteract.
+
+## OpenType Features for Data
+
+Most fonts ship with OpenType features that are off by default. Turn them on for data compositions:
+
+```css
+/* Tabular numbers — digits align vertically in columns */
+.stat-value,
+.timer,
+.data-column {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Diagonal fractions — renders 1/2 as ½ */
+.recipe-amount,
+.ratio {
+  font-variant-numeric: diagonal-fractions;
+}
+
+/* Small caps for abbreviations — less visual shouting */
+.abbreviation,
+.unit {
+  font-variant-caps: all-small-caps;
+}
+
+/* Disable ligatures in code — fi, fl, ffi should stay separate */
+code,
+.code {
+  font-variant-ligatures: none;
+}
+```
+
+`tabular-nums` is essential any time numbers are stacked vertically — stat callouts, timers, scoreboards, data tables. Without it, digits have proportional widths and columns don't align.