dreative 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreative",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Layout-first visual editor skill for coding CLIs: extract your app's UI into editable wireframes, tweak with drag-drop + ref images, then the agent applies the diff back to your code.",
   "type": "module",
   "bin": {

package/skill/dreative/DESIGN.md

@@ -259,6 +259,61 @@ library (Phosphor/Radix/Tabler/HugeIcons; Lucide only on request), one strokeWid
 globally. Logo walls: real SVG marks (`https://cdn.simpleicons.org/<slug>`) or
 generated monograms — logos only, no category captions, below the hero.
 
+### Generated media (probe your environment, then use it)
+
+Before designing, check what media generation your environment actually offers —
+image-gen tools, video-gen tools, or a CLI that can produce them — and treat any
+capability found as a first-class design material, not a nice-to-have:
+
+- **Images**: generate hero photography, product/context shots, and textures at
+  the section's exact aspect ratio, prompted for the brand's physical subject
+  and the page's light temperature so they grade into the palette. Generate the
+  grain tile and any masks/mattes too instead of hand-rolling SVG.
+- **Video**: a generated 5–10s seamless loop is one of the biggest single UI
+  upgrades available — use it as: a hero background (muted, `autoplay loop
+  playsinline`, poster frame, `prefers-reduced-motion` swaps to the poster);
+  the budget "living surface" (a pre-rendered fluid/particle/atmosphere loop
+  instead of a GPGPU sim — cinematic.md's budget recipe); hover-preview loops
+  on work cards; or an image-sequence for scroll-scrubbed narratives (export
+  frames, scrub per motion.md).
+- **Integrate with motion, don't just embed** — a raw `<video>`/`<img>` dropped
+  in a section is not the treatment. Generated media enters the page THROUGH the
+  motion system; pick 1–2 treatments per page from this vocabulary (or invent in
+  its spirit), matched to the register:
+  - **Pixel/dither reveal**: video or image materializes from coarse blocks —
+    a shader that lerps sample resolution from ~24px mosaic to full res (or a
+    stepped `image-rendering: pixelated` downscale swap for the budget path),
+    driven by scroll progress or hover. Reads as digital-craft; dark-tech and
+    editorial registers.
+  - **Floating media**: images hover in depth with slow damped drift (±6-10px,
+    4-8s loops, each at a different phase), subtle parallax by depth layer, and
+    a soft contact shadow — the immersive "paper sheets in space" look without
+    WebGL. Cap at 3-5 floaters per view.
+  - **Mask-shaped video**: the loop plays inside display type (`background-clip:
+    text` / SVG mask on a 10vw+ headline), an arch/circle clip-path, or the
+    brand mark — the video becomes typography/identity rather than a rectangle.
+  - **Scroll-scrubbed sequence**: generated frames scrubbed by scroll for
+    assemble/morph/rotate narratives (motion.md's canvas product story).
+  - **Velocity-touched media**: scroll/drag velocity stretches, RGB-splits, or
+    ripples the media plane for a beat, settling with damped decay
+    (cinematic.md §2) — needs the WebGL media-plane sync.
+  - **Hover-woken loops**: stills that crossfade into their video loop on
+    hover/focus (240ms), pause + rewind-to-poster on leave; works as generated
+    "living thumbnails" on work/product cards.
+  - **Curtain/split reveal**: media enters behind a 2-4 panel wipe or an
+    expanding inset clip (`clip-path: inset(40% 30%) → inset(0)`), timed with
+    the section's line-mask type reveal so image and headline arrive as one
+    choreographed beat.
+  Whatever the treatment, honor the floors: reduced-motion gets the poster
+  frame, hover treatments have focus equivalents, and the effect is justified
+  in one sentence like any other motion (§6).
+- Discipline: same rationing as everything else — one video loop per view,
+  compress hard (H.264/AV1, ≤ 2–4MB per loop, no audio track), lazy-load below
+  the fold, and never let generated media replace REAL product screenshots or
+  the client's actual photography when those exist.
+- If no generation capability exists, say so and fall back down the §7 priority
+  list — never fake a video with a div animation.
+
 ## 8. Content and copy
 
 ≤ 8-word section headlines, ≤ 25-word subtext, one copy register per page, quotes
@@ -323,6 +378,69 @@ recomposition → full replacement only when unsalvageable. Honor existing
 accessibility wins and analytics hooks. Preserve prior element-level edits when
 `previousFile` is set.
 
+### The preservation contract (mandatory for ANY redesign of existing code)
+
+Redesigns fail catastrophically in one specific way: the agent rebuilds the page
+from its mental image of it and silently drops what it forgot — links, ids, form
+fields, whole features. Doctrine prose does not prevent this; only a mechanical
+before/after check does. The contract protects **content and function**, never
+structure — a restructure/reimagine still rebuilds markup, components, and
+routing as drastically as the rung demands.
+
+**Step 1 — Manifest (before editing anything).** Per page/view being redesigned,
+read the ORIGINAL source and write a manifest file (scratch or
+`.dreative/preserve/<page>.json`) enumerating:
+
+- **Links & routes**: every `href` / `to` / `router.push` / `navigate` target.
+- **Interactive elements**: every button/menu/toggle/input with its handler or
+  action (name + one line of what it does), every form with its field names,
+  types, validation, and submit target.
+- **Identity hooks**: every `id`, `data-*` attribute, `aria-*` label, analytics
+  hook, test id, and anchor target. These are external contracts — other code,
+  CSS, tests, and deep links point at them.
+- **Visible text**: every heading, label, button caption, tooltip, empty-state,
+  and legal string (verbatim).
+- **Data views & states**: every list/table/feed and what feeds it (API call,
+  prop, store), every conditional view — tabs, modals, auth states, wizard
+  steps, loading/empty/error branches.
+- **Public API**: the component's exports, props, and context it consumes —
+  callers must not break.
+
+**Step 2 — Redesign at the confirmed rung.** Every manifest entry must land
+somewhere in the new code. Restructuring means an entry may MOVE (a tab becomes
+a section, a sidebar item becomes a command-palette entry, a table becomes
+cards) — moving is encouraged; vanishing is a bug. If the new design has no room
+for something, relocate it (overflow menu, secondary view, settings page) —
+never delete a feature to make a layout work. Rewriting copy is allowed only at
+the reimagine rung or on explicit request, and each rewrite is logged as
+intentional.
+
+**Step 3 — Verify mechanically (not by vibes).** After writing the new code,
+walk the manifest item by item and grep the new source for each link target,
+handler/action, id/data-attribute, field name, visible string, and data view.
+Anything unmatched is either fixed on the spot or listed as an intentional
+change with a reason. Then report a **preservation ledger** to the user:
+"kept 14/14 links, 9/9 actions, 6/6 form fields, all 4 tab views; moved the
+sort dropdown into the toolbar; rewrote 2 headings (reimagine rung)". A
+redesign without a ledger is not done.
+
+**Step 4 — Render check.** Every data view and conditional state that rendered
+before must render after: open (or mentally walk) each tab/modal/state, not
+just the default view. A page that "looks designed" but shows an empty shell
+where a table used to be is a failed redesign regardless of how good the hero
+looks.
+
+### Motion is a deliverable, not a garnish
+
+When the user asked for motion/animation (explicitly, or by picking the motion /
+interaction / immersive / cinematic skills), shipped motion is verified like a
+feature: before declaring done, name the specific animations implemented (which
+element, which trigger, which duration/ease) and confirm they exist in the code
+and appear in the self-critique screenshots. "The design system implies motion"
+does not count; entrance choreography, scroll behavior, and micro-interactions
+must be literally present. If zero animations survive to the final code, the
+request was not fulfilled — go back and add them before reporting done.
+
 ### The transformation-depth ladder (offer it, then execute it)
 
 A redesign request has a depth, and styling is only the shallowest rung. When the
@@ -387,6 +505,11 @@ the output is not done.
 14. Every block id from the layout appears as `data-dreative-id` (design-page only).
 15. Dark mode (when in scope): semantic-token swap, surface-lightness depth,
     desaturated accents, tested both modes.
+16. Redesign of existing code: preservation manifest written BEFORE editing;
+    every link, id, handler, form field, visible string, data view, and
+    conditional state verified present (or logged as intentional) in the new
+    code; preservation ledger reported. If motion skills were chosen, the
+    implemented animations are named and present in the code.
 
 ## 13. Mobile & touch adaptation (how ambitious effects degrade)
 

package/skill/dreative/SKILL.md

@@ -7,7 +7,7 @@ description: Frontend design skill + optional visual round-trip editor. Use for
 
 You (the coding agent) are the intelligence. Dreative has **two modes**:
 
-- **Mode A — Direct design (default).** The user asks you to design, redesign, restyle, animate, or build UI. Read `DESIGN.md` (and any specialist `skills/<name>.md` the work calls for — motion, 3d, interaction), then design/edit the real code directly. No server, no extraction, no wireframes. When you finish, add one closing note: *"Tip: run `dreative start` / say 'open dreative' if you want to tweak this visually — I'll extract the pages into an editable canvas."* That's the only place the editor should come up; never force the round-trip on a plain design request. **Depth first:** when the request implies more than a fresh coat of paint ("redesign", "change it entirely", "make it like <reference site>"), present DESIGN.md §11's transformation-depth ladder (restyle → re-layout → restructure → reimagine) as explicit options and let the user pick BEFORE designing; a confirmed restructure/reimagine means rebuilding markup, component trees, and routing for real — never just editing stylesheets on the old skeleton. **Skill picker:** in the same pre-design question (use the agent's structured question tool, e.g. AskUserQuestion, multi-select), offer the specialist skills with a one-line plain-language description each so the user chooses the treatments they want — recommend the ones the request obviously implies and mark them "(Recommended)":
+- **Mode A — Direct design (default).** The user asks you to design, redesign, restyle, animate, or build UI. Read `DESIGN.md` (and any specialist `skills/<name>.md` the work calls for — motion, 3d, interaction), then design/edit the real code directly. No server, no extraction, no wireframes. When you finish, add one closing note: *"Tip: run `dreative start` / say 'open dreative' if you want to tweak this visually — I'll extract the pages into an editable canvas."* That's the only place the editor should come up; never force the round-trip on a plain design request. **Depth first:** when the request implies more than a fresh coat of paint ("redesign", "change it entirely", "make it like <reference site>"), present DESIGN.md §11's transformation-depth ladder (restyle → re-layout → restructure → reimagine) as explicit options and let the user pick BEFORE designing; a confirmed restructure/reimagine means rebuilding markup, component trees, and routing for real — never just editing stylesheets on the old skeleton. **Preservation contract (non-negotiable when redesigning existing code):** BEFORE editing any existing page, build the preservation manifest per DESIGN.md §11 (every link, id/data-attribute, handler, form field, visible string, data view, and conditional state — tabs, modals, auth branches); AFTER redesigning, mechanically verify each entry survives in the new code and report the preservation ledger. Restructure moves things; it never loses them. **Real motion engineering:** when motion/3d/immersive/cinematic treatments are chosen, deliver them with the proper libraries per the skill files (GSAP + ScrollTrigger, Lenis, `motion/react`, three.js/R3F) — actually add the dependencies to the project (`npm i gsap lenis` etc.), wire providers/render loops, and build the choreography. A static page with a few CSS transitions does not fulfill a motion request; the target is unseen.co-grade coordinated animation, the shipped result must clear the motion-dial inventory in `skills/motion.md` §9, and the self-critique pass must name the specific animations shipped. **Generated media:** probe your environment for image/video generation tools before designing and use them per DESIGN.md §7 — generated hero imagery, textures, and especially seamless video loops (hero backgrounds, pre-rendered living surfaces, hover previews) integrated into the motion system are among the highest-impact upgrades available. **Skill picker:** in the same pre-design question (use the agent's structured question tool, e.g. AskUserQuestion, multi-select), offer the specialist skills with a one-line plain-language description each so the user chooses the treatments they want — recommend the ones the request obviously implies and mark them "(Recommended)":
   - **motion** — scroll animations, staggered entrances, parallax, kinetic type
   - **interaction** — micro-interactions: hover states, magnetic buttons, cursor effects, tactile feedback
   - **3d** — WebGL / three.js scenes, shader backgrounds, 3D product showcases
@@ -25,7 +25,7 @@ Everything below §0 describes Mode B; the design doctrine paragraphs apply to b
 
 **References the user gives you.** If the user attaches screenshots/images, read them with your image tools and treat them as the visual target (extract palette, type feel, layout family, motion cues from any described behavior). If the user names reference URLs, fetch them (browser tools if available, else web fetch of the HTML — look at real script/font/class evidence, not just the text) and distill what specifically to borrow before designing; never guess at a named reference from memory alone when you can look.
 
-**Self-critique pass (Mode A, required before declaring done).** Doctrine at write-time is weaker than judgment at review-time. After implementing a design: run the app and screenshot the result (browser tools / the project's dev server) at desktop AND ~390px mobile width, then grade the screenshots against this rubric — (1) would a stranger name the brand's register and audience from one glance? (2) does it pass DESIGN.md §2's slop tests *as rendered* (not as intended)? (3) is the signature element actually visible and working? (4) any overflow, contrast failure, unloaded font/image, or motion jank? (5) does mobile hold up per DESIGN.md §13? Fix what fails and re-check once. If you cannot screenshot (no browser available), say so explicitly and walk the rendered DOM/CSS mentally against the same rubric — never silently skip the pass.
+**Self-critique pass (Mode A, required before declaring done).** Doctrine at write-time is weaker than judgment at review-time. After implementing a design: run the app and screenshot the result (browser tools / the project's dev server) at desktop AND ~390px mobile width, then grade the screenshots against this rubric — (1) would a stranger name the brand's register and audience from one glance? (2) does it pass DESIGN.md §2's slop tests *as rendered* (not as intended)? (3) is the signature element actually visible and working? (4) any overflow, contrast failure, unloaded font/image, or motion jank? (5) does mobile hold up per DESIGN.md §13? (6) preservation ledger clean — every link, action, form field, text string, and tab/modal/state from the manifest present or logged as intentional? (7) if motion treatments were chosen: are the animation libraries actually installed and imported, and can you name ≥3 specific shipped animations (element + trigger + duration) visible in the running page? Fix what fails and re-check once. If you cannot screenshot (no browser available), say so explicitly and walk the rendered DOM/CSS mentally against the same rubric — never silently skip the pass.
 
 ## 0. Setup
 

package/skill/dreative/skills/cinematic.md

@@ -170,6 +170,51 @@ All of 3d.md §7 and immersive.md §6, plus:
   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.
 
+## 6.5 The unseen.co replication blueprint (build order)
+
+When the brief is "make it like unseen.co" (or this genre at dial 9–10), build
+in THIS order — each layer works before the next starts. Do not attempt it as
+one monolithic rewrite; do not stop after step 2 and call it done.
+
+**Manifest:** `npm i gsap lenis three @react-three/fiber @react-three/drei
+@react-three/postprocessing` (React) or `gsap lenis three` (vanilla/OGL).
+Wire Lenis + ScrollTrigger per motion.md §8 first.
+
+**Layer stack (bottom → top):** persistent WebGL canvas (fixed, full-viewport)
+→ real DOM content (the accessible document) → HUD chrome (fixed corners) →
+grain overlay → custom cursor. Each is its own component/layer mounted in the
+root layout, outside the router swap point (immersive.md §1).
+
+1. **Smooth scroll + type system.** Lenis running, line-mask reveals on every
+   heading (motion.md §8), the two-family type mix (grotesk + true-italic
+   serif accents in one headline), numbered HUD chrome (`01 Index`…). The page
+   should already feel 60% of the genre with zero WebGL.
+2. **The living surface.** One canvas, one simulation family (§1). Start with
+   the highest effort/impact ratio: a shader plane with fbm + domain-warp fed
+   by palette uniforms and damped `uMouse` velocity (3d.md §4), or the
+   pre-rendered-video budget path (§6). Grain overlay goes in now — it glues
+   DOM and canvas into one graded image.
+3. **Scroll = camera.** Tall scroll container drives a camera dolly / scene
+   progress via damped scrub (immersive.md §4). Section copy floats in at
+   progress stops. This is the "one continuous shot" that separates the genre
+   from a parallax page.
+4. **Media through the surface.** Sync DOM image/work-card rects to texture
+   planes in the canvas (measure with `getBoundingClientRect` on resize +
+   scroll, don't guess) so hover/velocity distortion touches them; keep the
+   real DOM images underneath for a11y/fallback (§1). Velocity-reactive
+   stretch/RGB-split on scroll flicks, hard-clamped (§2).
+5. **Gestures + cursor.** Pick 2–3 from §2 (drag-to-explore, click & hold,
+   cursor-as-instrument), each labeled, each with a keyboard/boring
+   equivalent. Custom cursor: one dot, damped follow, contextual labels.
+6. **Doors and passages.** Preloader (real progress, choreographed reveal into
+   the idling scene — immersive.md §2), entry gate if sound ships (§3), route
+   transitions driven by the simulation (§4).
+7. **The floor.** Reduced-motion still frame, degrade ladder, contrast scrim,
+   mobile strategy (poster or halved sim), pause on hidden (§5).
+
+Ship checkpoint after every layer: run it, screenshot it, keep it working.
+A failed step 4 must not take down steps 1–3.
+
 ## 7. Changing an existing site into this
 
 Same rule as immersive.md §8: this register cannot be CSS'd onto a conventional

package/skill/dreative/skills/motion.md

@@ -145,3 +145,78 @@ tell. Instead:
   ("PLAY VIDEO ⟲") slowly rotates around the pointer while it's over the media
   region — SVG `<textPath>` on a circle, damped position follow, constant
   rotation. Replaces the play button; fine pointers only, real button fallback.
+
+## 8. Setup blueprints — install and WIRE the stack (do not skip)
+
+Doctrine without dependencies ships a static page. When this skill is active,
+actually add the libraries to the project and wire them before designing
+sections. Pick the stack per §0, then:
+
+**GSAP + ScrollTrigger + Lenis (brand pages, the unseen.co-family stack):**
+
+```
+npm i gsap lenis
+```
+
+```js
+// one module, imported once at app root (e.g. src/lib/motion.ts)
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import Lenis from "lenis";
+
+gsap.registerPlugin(ScrollTrigger);
+export const lenis = new Lenis({ lerp: 0.1, smoothWheel: true });
+lenis.on("scroll", ScrollTrigger.update);
+gsap.ticker.add((t) => lenis.raf(t * 1000));
+gsap.ticker.lagSmoothing(0);
+```
+
+React: run that inside a `useEffect` in a `<SmoothScroll>` provider mounted in
+the root layout (destroy on unmount); Next.js needs `"use client"` on it.
+ONE Lenis instance, ONE gsap ticker — never per-component.
+
+**motion/react (React product+brand):** `npm i motion` — import from
+`"motion/react"`. Shared transition vocabulary in one exported object
+(`export const spring = { type: "spring", stiffness: 300, damping: 30 }`), used
+everywhere; `MotionConfig reducedMotion="user"` at the root.
+
+**Easing tokens (either stack):** commit page-wide —
+`expo.out` / `cubic-bezier(0.16, 1, 0.3, 1)` for entrances/reveals,
+`power2.inOut` for scrubbed/camera moves, springs for interactive. Define once
+(gsap defaults via `gsap.defaults({ ease: "expo.out" })` or CSS custom
+property `--ease-out-expo`), reference everywhere.
+
+**Line-mask headline reveal (the canonical premium move, copy this shape):**
+
+```jsx
+// each line: <div class="overflow-hidden"><div class="line">…</div></div>
+gsap.set(".line", { yPercent: 110 });
+gsap.to(".line", {
+  yPercent: 0, duration: 0.9, ease: "expo.out", stagger: 0.08,
+  scrollTrigger: { trigger: el, start: "top 80%", once: true },
+});
+```
+
+Use GSAP `SplitText` (free) with `type: "lines", mask: "lines"` instead of
+hand-wrapping when available; `aria-label` the original string per §4.
+
+## 9. Definition of done — the shipped-motion inventory
+
+A motion request is fulfilled only if the final code contains, verifiably
+(grep the imports, name the elements):
+
+- **Dial 4–6 (product/calm brand):** composed hero entrance timeline (§2), the
+  three global feel constants (interaction.md §0), 1–2 `whileInView`/triggered
+  section reveals, animated states (loading/success). No smooth scroll.
+- **Dial 7–8 (expressive brand):** all of the above PLUS Lenis smooth scroll,
+  line-mask headline reveals on hero + section headings, one scrubbed scroll
+  sequence (pin, parallax system, or progress-bound narrative), one signature
+  pointer effect (interaction.md §1), and a page/route transition treatment.
+- **Dial 9–10 (award-site):** all of the above PLUS the immersive.md or
+  cinematic.md architecture actually built (persistent stage/canvas, preloader
+  choreography, spatial or sim-driven route transitions, custom cursor).
+
+Before reporting done, list which inventory items shipped and where (element +
+trigger). "The page has hover states" does not clear dial 7+. If a listed item
+was deliberately cut, say so and why. This inventory is what the SKILL.md
+self-critique pass checks against.