dreative 0.1.0 → 0.2.0

package/skill/dreative/skills/cinematic.md

@@ -0,0 +1,171 @@
+# Dreative Specialist Skill — Cinematic WebGL & Experiential Interfaces
+
+Load this file when `plan.skills` includes `cinematic`, or the brief/prompt asks
+for a dark cinematic shader-driven look, "sites like unseen.co", drag-to-explore
+navigation, click-and-hold interactions, fluid/particle distortion effects,
+sound design, or "experimental / experiential" interfaces. This is the genre's
+high-fashion end: fewer elements, extreme polish, the interface itself behaves
+like a graded film.
+
+It STACKS with `immersive.md` (world architecture — read it when routes/scenes
+are involved) and `3d.md` (shader craft). DESIGN.md still governs type and
+accessibility floors. It is universal — apply directly to any codebase; the
+Dreative editor is optional. This is an OPT-IN aesthetic: propose it only when
+the brief supports it; it is never the default answer to "make it nicer".
+
+## 0. The register: cinematic restraint
+
+Where immersive.md builds a place, this genre builds a MOOD. Its rules:
+
+- **Atmosphere is the canvas.** Commit to ONE graded atmosphere and grade
+  everything into it. Dark cinematic (near-black #0a0a0c-ish base, tinted, never
+  pure #000, stage-light falloff on one subject) is the common form — but pale
+  worlds are equally genre-valid: UNSEEN's actual site is a blush-pink flooded
+  dream-room with prismatic dispersion on its arches and soft daylight. What
+  makes it cinematic is not darkness but unity of light: one light temperature,
+  one falloff logic, one grain, everything (DOM included) living inside it.
+- **Radical reduction.** Each view holds ONE visual subject + a few lines of
+  type + numbered chrome. If a section needs three columns of content, it does
+  not belong in this register — move it to a conventional subpage.
+- **Everything is graded.** One post-processing/color pass unifies DOM and
+  canvas: film grain (3-6%), subtle vignette, bloom only on emissive accents,
+  optional chromatic aberration at transition peaks ONLY (constant CA = broken
+  monitor). The grade is one system — define it once, apply globally.
+- **Typography as credits.** Restrained scale (this genre whispers where
+  immersive shouts): refined grotesk or editorial serif, generous tracking on
+  small mono/small-caps labels, and the signature **numbered index** chrome —
+  `01 Index`, `02 Projects`, coordinates, timestamps — laid out like a film
+  slate. Big type appears sparingly and is often distorted by the shader layer
+  as it passes (see §2).
+
+## 1. The living surface (the genre's engine)
+
+The background is not decoration — it's a continuously-running simulation the
+whole interface sits on. One fullscreen canvas, one of these families:
+
+- **Fluid distortion** (the UNSEEN signature): GPGPU fluid sim or cheap
+  velocity-buffer approximation; pointer movement injects velocity; the field
+  distorts whatever sits under it — images, WebGL text copies of the headlines,
+  the scene itself. Intensity tuned so idle = near-still, movement = silky wake.
+- **Particle field**: 10k-100k GPU particles (FBO/GPGPU, see 3d.md §5) forming
+  a subject — a logo, a face, a landscape — that disperses and reforms on
+  interaction or route change. Curl noise for drift; mouse as attractor/repulsor.
+- **Volumetric/raymarched fog + light**: a raymarched or layered-noise volume
+  with one light source tracking the pointer or the active section.
+
+Rules: ONE simulation per site, palette fed from the page tokens, `uTime` slow
+(3d.md §4), sim pauses off-screen and on `document.hidden`, and pointer force is
+damped — the surface reacts like water, not like a cursor-following gimmick.
+Images/media on the page render INTO the canvas layer (texture planes synced to
+DOM rects — measure, don't guess) so the distortion can touch them; keep real
+DOM (invisible or fallback-visible) underneath for a11y/SEO/selection.
+
+## 2. Interaction vocabulary
+
+The genre replaces "click around a document" with deliberate, weighty gestures.
+Pick 2-3, execute perfectly:
+
+- **Drag to explore**: the primary surface pans on drag (inertia + rubber-band
+  edges, damped) across a spatial arrangement of works. Cursor label says
+  "Drag"; a minimap/index shows position. Wheel/trackpad maps to the same pan.
+  ALWAYS pair with a conventional index list (the numbered menu) — drag is the
+  scenic route, never the only route.
+- **Click & hold**: press-and-hold to enter a project / reveal a layer — a ring
+  or bar fills during the hold (400-700ms), releasing early cancels with a
+  spring-back. Label it ("Hold"). Keyboard equivalent: Enter activates
+  immediately — the hold is texture for pointer users, not a gate.
+- **Velocity-reactive media**: scroll/drag velocity feeds shader intensity —
+  images stretch, RGB channels split for a beat, grain agitates — settling with
+  damped decay. Read velocity from Lenis/`useScroll`; clamp hard: peak effect at
+  a fast flick should still be legible.
+- **Cursor as instrument**: single dot that morphs into contextual labels
+  ("Drag", "Hold", "Play", index numbers). In this genre the cursor may also
+  cast light — the surface (§1) brightens around it. One cursor identity,
+  fine-pointer devices only.
+- **Idle cinematography**: after ~10s idle the scene performs — slow camera
+  drift, sim breathing, a highlight reel. Any input snaps back (damped, 300ms).
+
+## 3. Sound design (optional layer, genre-native)
+
+The only web genre where audio is expected — still strictly opt-in:
+
+- Entry gate offers the choice up front ("Enter with sound / without") or an
+  always-visible mute toggle in the HUD (animated equalizer bars = the
+  convention). NEVER autoplay audio; browsers block it and users hate it.
+- One ambient loop (-30dB-ish, long crossfaded loop) + micro-SFX on primary
+  interactions only (hover tick, hold-complete, transition whoosh). Web Audio
+  API with a master gain; fade in/out over 400ms on toggle, duck during video.
+- Persist the choice (localStorage), default OFF on return visits unless
+  enabled; respect `prefers-reduced-motion` as a proxy for "calm mode" — start
+  muted there.
+
+## 4. Composition & transitions in this register
+
+- Views compose like film frames: subject off-center (rule-of-thirds), type in
+  the negative space, numbered label anchoring a corner. Symmetric centered
+  compositions only for title-card moments.
+- Route transitions are CUTS and DISSOLVES driven by the surface: the sim
+  swallows the view (fluid floods, particles disperse) → beat at full abstraction
+  (~200ms, the surface alone) → next view condenses out of it. The simulation is
+  the transition medium — no white flashes, no generic slide-wipes on top of it.
+- Section changes within a view: crossfade + parallax nudge, ≤ 500ms; let the
+  surface do the drama, keep DOM motion quiet (this genre's DOM moves LESS than
+  a normal site's — contrast is what reads as expensive).
+- The loader (immersive.md §2 rules apply) is minimal here: percentage numeral +
+  the sim warming up behind it. The sim visibly "becoming ready" IS the loader.
+
+## 5. Performance & accessibility (non-negotiable, hardest here)
+
+All of 3d.md §7 and immersive.md §6, plus:
+
+- GPGPU sims are the most expensive thing on the web: cap sim resolution
+  (fluid ≤ 256², particles per device tier), halve on mobile or replace the sim
+  with a pre-rendered video loop of it — visually near-identical, free to play.
+- Measure, don't assume: if frame time > 20ms for a sustained burst, degrade
+  live (drop sim resolution → drop post-FX → static grade). Build the ladder in.
+- `prefers-reduced-motion`: sim frozen to one still frame (it's the grade's
+  texture now), velocity effects off, hold-to-enter becomes click, idle
+  cinematography off. The site must remain fully usable and still look graded.
+- Contrast discipline: dark register makes AA failures easy — body text ≥ 4.5:1
+  against the DARKEST point of the animated surface behind it (test the worst
+  frame, not the average); put text over a stabilized scrim when the sim is busy.
+- Every drag/hold/spatial interaction has a boring equivalent: real links in the
+  numbered index, tab order through works, Enter to open. Screen readers get the
+  DOM document; the canvas is `role="img"` with a scene description.
+- Battery/data respect: pause everything on `visibilitychange`, honor
+  `prefers-reduced-data` by skipping the sim entirely (grade + posters only).
+
+## 6. Recipes
+
+- **UNSEEN-style studio home** (verified on the live site): letter-cycling
+  loader (the wordmark's letters flip one at a time over the studio's one-line
+  bio) → entry gate ("Enter" pill + quieter "ENTER WITHOUT AUDIO" underneath) →
+  a pastel 3D room half-flooded with reflective water; drag pans the view and
+  reveals chrome/reflective 3D display type STANDING IN the scene (italic serif
+  + grotesk mixed in one headline), mirrored in the water. Scrolling dollies the
+  camera forward through the room into a bright gallery hall — hero and works
+  index are one continuous camera journey, with the route updating mid-flight.
+  Work cards render as sheets of paper floating in the space, subtly warped,
+  with chromatic fringing at their edges; filter pills carry counts (All 20 /
+  Branding 5…); butterfly/petal particles drift through; HUD = wordmark
+  top-left, Index/Projects/Contact top-right, globe "world" button bottom-center,
+  © year bottom-right. Heavy uniform film grain glues all of it together.
+- **Particle identity page**: brand mark as 50k particles that disperse on
+  pointer force and reform; sections change the formation target; scroll
+  velocity agitates; reduced-motion = the formed mark as a still.
+- **Cinematic case study**: dark editorial page, media rendered through the
+  distortion layer, velocity-reactive stretch on scroll, chapter numerals,
+  one raymarched-light hero; DOM otherwise quiet and typographic.
+- **Budget version (no GPGPU)**: pre-rendered fluid/particle video loops as
+  background + `mix-blend-mode` type, CSS grain, velocity-reactive transforms
+  on real DOM, click-and-hold in JS only. 70% of the mood, runs on anything —
+  the right call below motion dial 8 or on content-heavy sites.
+
+## 7. Changing an existing site into this
+
+Same rule as immersive.md §8: this register cannot be CSS'd onto a conventional
+page — it needs the canvas surface, the reduced composition, and usually a
+content edit (views hold less). Use DESIGN.md §11's transformation-depth ladder;
+this genre is almost always rung 3 (Restructure) or 4 (Reimagine). Offer the
+ladder, get the user's pick, then rebuild for real — and offer the budget recipe
+(§6) as the rung-2 alternative for users who want the mood without the rebuild.

package/skill/dreative/skills/immersive.md

@@ -0,0 +1,217 @@
+# Dreative Specialist Skill — Immersive Worlds & Spatial Transitions
+
+Load this file when `plan.skills` includes `immersive`, or the brief/prompt asks
+for an "award-site" feel, a site that behaves like a world/scene/space, spatial or
+3D page transitions, "sites like epic.net / Awwwards winners", scroll-as-journey,
+or "make it feel like an experience, not a webpage". This is the genre young
+studios and portfolios use to signal craft: the page is a continuous SPACE the
+visitor travels through, not a stack of sections.
+
+It EXTENDS DESIGN.md (register, type, color still apply) and STACKS with
+`motion.md` (timing vocabulary) and `3d.md` (WebGL craft) — read those too when
+listed. This file is about the architecture and choreography that makes a site
+read as one continuous world. It is universal: apply it to any codebase or
+framework directly; the Dreative editor is never required.
+
+## 0. Commit to the genre or don't enter it
+
+Immersive is a REGISTER, not a garnish. A normal marketing page with one fancy
+transition reads as broken; a world with one static utility page reads as
+intentional. Decide up front:
+
+- **Earns it**: portfolios, studios/agencies, campaign and launch sites, brand
+  storytelling, exhibitions, games/entertainment — anywhere the site IS the proof
+  of craft and visitors expect to explore.
+- **Doesn't**: dashboards, docs, e-commerce checkout, anything task-first.
+  Product register (DESIGN.md §1) hard-caps this genre to a hero moment.
+- The genre demands a **spatial metaphor** named in one sentence before any code:
+  "each project is a room off a corridor", "scroll descends through a tower",
+  "the cursor is a flashlight over an archive", "works float in a void you orbit".
+  No metaphor = you'll produce disconnected effects. The metaphor decides what
+  transitions, camera moves, and layout make sense — everything below serves it.
+- Immersive sites still need an **escape hatch**: visible menu with plain links,
+  working back button, deep-linkable routes. Lost visitors close tabs.
+
+## 1. Architecture: one persistent stage
+
+The defining trait of this genre is that navigation doesn't feel like page loads
+— the world persists and the camera/content moves. Structure the app accordingly:
+
+- **App shell + stage**: one persistent layer (WebGL canvas, fixed background
+  scene, or shared layout chrome) mounted OUTSIDE the router's swap point. Routes
+  change the DOM content layer; the stage transitions continuously underneath.
+  React: canvas in the root layout, never inside a page component. Vanilla/MPA:
+  use cross-document View Transitions (`@view-transition { navigation: auto; }`)
+  or an SPA-ify layer (barba.js/Taxi.js-style: fetch next page, swap `<main>`,
+  play the transition yourself).
+- **Scene manager**: each route/section maps to a named scene state (camera pose,
+  palette, fog, active objects). Transitions tween BETWEEN states — never unmount
+  scene A and mount scene B. Keep one source of truth
+  (`{ route → { cameraPos, lookAt, theme } }`) so transitions are data, not
+  scattered code.
+- **State machine for choreography**: preloading → intro → idle → transitioning.
+  Input is locked during `transitioning` (ignore clicks, queue at most one). Every
+  award-site jank bug is two transitions running at once.
+- URLs stay honest: every "place" in the world has a route; refresh lands you
+  there with the scene in the right state (read route on boot, snap camera, skip
+  the travel animation).
+
+## 2. The preloader (the genre's front door)
+
+Heavy worlds need loading; the genre turns it into the first brand moment.
+
+- Show a preloader ONLY if real assets need it (fonts+models+textures > ~1s).
+  Faking a 3-second counter on a light page is user-hostile — banned.
+- Real progress: count bytes/items from an asset manifest (`THREE.LoadingManager`
+  `onProgress`, or Promise.allSettled over fetches), display as an oversized
+  number (tabular-nums) or a filling wordmark — not a spinner.
+- Exit is a choreographed REVEAL, not a fade: counter completes → beat (~200ms) →
+  curtain wipe (clip-path/transform panel slide) or mask expansion reveals the
+  hero mid-motion (world already idling underneath). The hero entrance and the
+  preloader exit are ONE timeline.
+- Cache the visit (`sessionStorage`): returning visitors within a session skip to
+  a ≤400ms version. Preloader shows once, not per navigation.
+
+## 3. Spatial transitions (route ↔ route)
+
+The signature move: leaving a page feels like traveling, not swapping.
+
+Pick per the metaphor — every route pair uses the SAME transition language:
+
+- **Camera travel** (persistent WebGL): tween camera along a path to the next
+  scene anchor while DOM content of page A exits (fast fade + small offset) and
+  page B's content enters after arrival. Travel 600–1200ms; longer feels like a
+  loading screen.
+- **Shared-element morph**: the clicked card/image IS the next page's hero.
+  Same-doc: Motion `layoutId` or FLIP the element to its new bounds. MPA/simple
+  SPA: `view-transition-name` on the pair. This is the highest-value transition
+  per line of code — prefer it for list → detail (work index → project page).
+- **Mask/wipe**: full-viewport panel or clip-path (`inset()`/`circle()` from the
+  click point) sweeps over A, next route mounts underneath, sweep continues off.
+  Two-phase with a color/texture beat at full-cover (~150ms hold) reads as
+  premium; a plain crossfade reads as a slideshow.
+- **WebGL texture transition**: page A screenshot/render and page B as two
+  textures on a fullscreen plane, shader-blended with a noise/displacement mask
+  (see 3d.md §4). For image-heavy portfolios.
+
+Rules: exits ≤ 40% of the total; something from A must persist through the
+transition (the stage, a morphing element, the nav) or it's just a fancy reload;
+browser back plays the REVERSE direction (remember last direction); first paint
+on a cold URL never plays a transition.
+
+## 4. Scroll as travel (the world's main axis)
+
+In this genre scroll is displacement through space, not document reading:
+
+- Map document scroll to world motion: a tall scroll container
+  (`height: N * 100vh`) drives camera position along a `CatmullRomCurve3` (or
+  layered 2D transforms for a DOM-only world) via damped progress — Lenis +
+  ScrollTrigger scrub, or `useScroll` + `useTransform`. The page height IS the
+  journey length; native scrollbar, momentum, and a11y keep working. This is how
+  you get the "flying through the site" feel WITHOUT scroll-jacking — wheel
+  hijacking stays banned (motion.md §3).
+- **Chapters**: divide the journey into named stops (sections). Each chapter owns
+  a camera pose + palette shift + one content group. Snap gently
+  (`scroll-snap-type: y proximity`, never `mandatory` on long chapters). Expose a
+  progress rail / chapter index (dots or numerals, current chapter labeled) —
+  spatial sites without one feel endless.
+- Depth cues sell the space: atmospheric fade (fog / opacity by depth), scale +
+  blur on far layers, parallax speed ordered by depth (bg slowest), a subtle
+  camera sway on idle (≤ 2°, damped). 3–5 depth layers; more reads as soup.
+- Horizontal chapters: translate a wide track from vertical scroll progress
+  inside a pinned section (sticky wrapper) — one per page, ≤ 4 viewport-widths.
+- DOM content floats IN the world: copy blocks fade/rise at their chapter,
+  anchored to scene positions (drei `<Html>`, or absolutely-positioned blocks
+  keyed to progress ranges). Text always real DOM — never baked into textures.
+
+## 5. The dressing: what makes it read "award site"
+
+The genre's supporting cast — apply 3–4, not all (checklist-complete = template):
+
+- **Oversized display type** as an object in the space: 10–20vw headlines that
+  clip, sit behind/in front of the 3D subject (z-sandwiching via two text layers
+  or `occlude`), or run off-canvas. Line-mask reveals on arrival (motion.md §4).
+  The full-commitment version (unseen.co's hero) puts the headline INSIDE the
+  scene as reflective 3D type — chrome material, mirrored in the environment,
+  revealed by dragging/panning the world; pair a keep-real-DOM copy underneath
+  for a11y/SEO.
+- **Custom cursor**: small dot + trailing ring (damped follow, ~0.15 lerp),
+  morphs over interactives (scales up with a label: "View", "Drag", "Play").
+  Hide only the visual cursor layer via CSS on fine pointers; touch devices get
+  none of it and lose nothing. Magnetic pull on nav/CTAs (interaction.md).
+- **HUD chrome**: fixed corners used as an instrument panel — wordmark top-left,
+  menu top-right, chapter index + local time / coordinates bottom corners, mono
+  small-caps microtype. The frame stays put while the world moves — it's what
+  makes the motion legible.
+- **Fullscreen menu** as a scene: menu button flips a full-viewport overlay with
+  oversized nav links (staggered line-mask entrance), hover previews (image or
+  scene tint per link). The overlay is part of the world (same palette/texture),
+  not a white sheet.
+- **Textural grain**: one fullscreen noise/grain layer (CSS `mask` over an SVG
+  turbulence tile or a tiny shader) at 3–6% opacity unifies WebGL and DOM into
+  one photographic surface. Cheap, high-impact.
+- **Easter eggs** (epic.net's signature): 1–3 hidden delights — a konami code, a
+  clickable mascot, an idle-timeout animation. Never gate content behind them.
+
+## 6. Performance & accessibility (the genre's hard mode)
+
+Everything in motion.md §6 and 3d.md §7 applies, plus genre-specific:
+
+- Budget the WHOLE experience: ≤ 4–5MB initial including models/fonts; stage
+  code lazy-loaded behind the preloader; route content prefetched on hover so
+  spatial transitions never wait on network mid-flight.
+- One rAF loop owns the world (scene + cursor + scroll damping share it). Two
+  competing loops = the micro-stutter that separates good from great here.
+- `prefers-reduced-motion` gets a REAL alternative, not a broken world: static
+  scene per chapter, instant route swaps (crossfade ≤ 200ms), scroll returns to
+  plain document reading. Decide this layout up front — retrofitting it is why
+  most immersive sites fail the audit.
+- Keyboard path through the world: chapter index and nav focusable, focus moved
+  to incoming page's `<h1>`/main after a route transition, skip-link to content
+  over the intro. Announce route changes (`aria-live="polite"` region).
+- Low-power fallback ("flat mode"): detect weak GPU/`navigator.deviceMemory`/
+  first dropped-frame burst → swap stage for poster art + gradients, keep ALL
+  content and transitions-lite. Content is never hostage to the world. Offer the
+  same switch as a visible toggle if the brief allows.
+- SEO/no-JS: every route server-renders its real copy; the world enhances it.
+
+## 7. Recipes
+
+- **Scroll-dolly index (verified on unseen.co)**: one scroll axis dollies the
+  camera from the hero space directly into the works gallery — a bright hall
+  whose section heading and filter pills are DOM floating in front of the
+  scene, work cards as gently-warped paper planes hovering in depth. The route
+  updates mid-journey while the world persists. One continuous shot, zero page
+  loads.
+- **Chapter theme inversion (verified on bdsn.club)**: an editorial case-study
+  page where each full-viewport project chapter flips the ENTIRE page theme
+  (white → black → brand indigo…) as it scrolls in, with an oversized grotesk
+  project title and one product render per chapter; HUD (local time top-left,
+  CTA top-right, awards rail on the edge) stays fixed through every inversion.
+  DOM-only, no WebGL — the spatial feel comes purely from theme travel + scale.
+- **World portfolio**: persistent canvas; works as textured planes arranged in
+  depth; scroll flies the camera past them; hover tilts a plane + cursor says
+  "View"; click = camera dives to the plane which morphs into the project hero
+  (shared-element). Back = reverse flight.
+- **Scene-hopping studio site (epic-style)**: stylized environment as stage;
+  each route = a location; nav travels the camera between locations with a
+  velocity blur beat; DOM copy floats per location; playful idle animations +
+  1–2 easter eggs; HUD chrome + fullscreen menu.
+- **One-page descent**: 6–8 chapter tall-scroll journey down one axis (tower,
+  ocean, timeline); palette darkens/shifts per chapter; progress rail with
+  chapter names; ends on a contact "floor" that snaps.
+- **DOM-only spatial site (no WebGL)**: layered `translateZ`-style parallax with
+  scale/blur depth cues, View Transitions for shared-element route morphs,
+  clip-path wipes, grain overlay, custom cursor, oversized type. 80% of the feel
+  at 5% of the cost — the right call below motion dial 8 or without 3D subject
+  matter.
+
+## 8. Changing an existing site into this
+
+An existing conventional site cannot become immersive through CSS — this genre
+requires the app-shell/stage architecture (§1), which means restructuring markup,
+routing, and component boundaries. Follow DESIGN.md §11's transformation-depth
+ladder: present the depth options, and on user confirmation restructure for real
+— move the router swap point, introduce the stage layer, rebuild sections as
+chapters. Never simulate the genre by decorating the old structure; a restyled
+static page with a custom cursor is the uncanny valley of this genre.