luckiest-co 1.0.13 → 1.0.14

package/skills/luckiest-design-website/references/worldflight.md

@@ -0,0 +1,349 @@
+# Worldflight: the continuous-world page mode
+
+Act mode cuts the page into pinned blocks. That is the right shape for a page of
+chapters and the wrong shape for one unbroken camera move, and building a
+continuous world out of acts produces exactly the page an owner described as
+"awful": you scroll down, the stage unsticks, a static page slides past, clean
+horizontal edges travel up the screen, and then you start scrolling down again.
+Every one of those defects is the same defect. A pinned act is a block in the
+document, and a document made of blocks has seams.
+
+Worldflight removes the seams by removing the blocks.
+
+There is **one** `position: fixed` stage for the whole page. Every leg of the
+flight is mounted in it at once and stays mounted. The only element in document
+flow is an empty spacer. Scroll drives two things and nothing else: the film
+timeline and the opacity of the overlay. Nothing travels, nothing pins, nothing
+unpins, and there is no boundary anywhere for a seam to show at.
+
+---
+
+## 1. The markup
+
+```html
+<div data-sc-mode="worldflight" data-sc-seam="0.12">
+
+  <div data-sc-world>
+    <div data-sc-segment data-sc-w="0.95" data-sc-linger="0.3"
+         data-sc-waypoint="Surface">
+      <img class="sc-world__poster" src="assets/p1.webp" alt="" decoding="async">
+      <video data-sc-src="assets/leg1.mp4"
+             data-sc-src-mobile="assets/leg1-m.mp4"></video>
+    </div>
+    <div data-sc-segment data-sc-w="0.9" data-sc-linger="0.42"
+         data-sc-waypoint="Thermocline">
+      <img class="sc-world__poster" src="assets/p2.webp" alt="" decoding="async">
+      <video data-sc-src="assets/leg2.mp4"
+             data-sc-src-mobile="assets/leg2-m.mp4"></video>
+    </div>
+    <!-- legs in flight order, as many as the world has -->
+  </div>
+
+  <div data-sc-world-copy>
+    <div class="sc-world__scrim sc-scrim sc-scrim--band"></div>
+    <div class="sc-copy sc-copy--lead" data-sc-copy data-sc-window="hero"> … </div>
+    <div class="sc-copy sc-copy--trail" data-sc-copy data-sc-window="0.38 0.66"> … </div>
+    <div class="sc-copy sc-copy--lead" data-sc-copy data-sc-window="finale"> … </div>
+  </div>
+
+  <div data-sc-spacer aria-hidden="true"></div>
+</div>
+```
+
+`ScrollCraft.mount(document)` as usual. The mode composes with nothing else on
+the page: a worldflight page has no acts.
+
+### Attributes
+
+| Attribute | On | Default | What it does |
+|---|---|---|---|
+| `data-sc-mode="worldflight"` | mode root | n/a | Turns the page into one flight. |
+| `data-sc-seam` | mode root | `0.12` | Crossfade band, in viewport-heights of scroll. Clamped 0.02 to 0.4. |
+| `data-sc-world` | stage | n/a | The single fixed stage. Gets `.sc-world`. |
+| `data-sc-segment` | leg | n/a | One leg. Holds a poster and a clip. |
+| `data-sc-w` | leg | `1.3` | Scroll this leg owns, in viewport-heights. |
+| `data-sc-linger` | leg | `0` | Dwell remap for this leg only. Clamped to 0.6. |
+| `data-sc-waypoint` | leg | n/a | Label published on the waypoint event. |
+| `data-sc-world-copy` | copy layer | n/a | Fixed overlay. Gets `.sc-world__copy`. |
+| `data-sc-copy` | copy block | n/a | A windowed block of type. |
+| `data-sc-window` | copy block | n/a | `hero` \| `finale` \| `from to [in [out]]`. |
+| `data-sc-spacer` | spacer | n/a | The scroll track. Engine sets its height. |
+| `data-sc-lerp` | root or `<video>` | `0.18` | Playhead smoothing. See devices.md. |
+
+The engine generates no DOM here, the same as in act mode. It sets the spacer's
+height, and it writes opacity, visibility and z-index on the legs. Everything
+else is markup you wrote.
+
+---
+
+## 2. The scroll track
+
+The spacer's height is **(sum of the leg weights + 1) viewport-heights**, set in
+pixels so it and the stage are measured on the same ruler (the stage is sized in
+`svh`, and on a phone `vh` and `svh` are different numbers).
+
+The `+ 1` is not padding. Without it the track ends at the exact scroll position
+where the last leg reaches progress 1, so the final second of the last clip is a
+place the reader can never come to rest. One extra viewport gives the last
+flight room to land.
+
+Position along the track, `t`, is measured in viewport-heights, which is the
+same unit the weights are written in. Leg *i* owns `[c_i, c_i + w_i)`, and its
+local progress is `(t - c_i) / w_i`, remapped through `lingerEase`.
+
+---
+
+## 3. The seam
+
+Two things make a boundary between clips invisible, and both are required.
+
+**The assets have to match at the seam** (section 6). The engine cannot fix a
+mismatched cut.
+
+**The crossfade has to be one-sided.** Over the seam band the incoming leg fades
+up from 0 to 1 while the outgoing leg holds at full strength underneath it, and
+the outgoing leg only drops to zero once it is completely covered. Fading both
+sides at once puts the page ground through the middle of every seam, which reads
+as a flash, and it is the obvious implementation. z-index favours the current
+leg (120) over the rest (100 + opacity × 10).
+
+Each side of the band is half a seam width, so each leg holds its seam frame for
+about 0.06vh of scroll. Those are exactly the frames the seam law matched, so a
+held frame there is invisible by construction.
+
+Nothing ever swaps a `src`. A src swap is a black frame, and a black frame is
+the cut this mode exists to remove.
+
+---
+
+## 4. The copy contract
+
+Copy lives in one fixed layer above the stage. Each block declares a window
+against the **whole track**, not against a leg.
+
+- `data-sc-window="hero"`: present from the first pixel, fades out by 0.62 of
+  the first leg. A hero that fades IN has to fade in over an empty first screen,
+  which is the one moment on the page with nothing else to look at.
+- `data-sc-window="finale"`: fades in from 0.4 of the last leg and holds to the
+  end.
+- `data-sc-window="0.38 0.66"`: a plateau window across those track fractions:
+  ramps in over the first 30%, holds at full opacity, ramps out over the last
+  30%. Add a third and fourth number to set the ramps yourself. The plateau is
+  not decoration: a pure triangle touches opacity 1 for one instant, so the
+  reader has to stop on exactly the right pixel to see the line at full strength
+  and every heading reads slightly faded.
+
+**The only transform on the copy side is `translateY`, and it is capped at 4vh
+across the whole window** (from +2vh to -2vh). Anything larger stops reading as
+a layer over a moving world and starts reading as a second page scrolling at a
+different speed, which is the cheapness this mode replaces. Pointer events are
+handed back to a block only above opacity 0.5.
+
+`.sc-world__scrim` is provided for a scrim div on the copy side. Shape it to
+where the copy actually sits. The stock `.sc-scrim--band` tops out at 58% of the
+frame, and footage that stays bright past that will fail the contrast pass even
+though the page looks fine.
+
+---
+
+## 5. The route rail
+
+The engine publishes the current leg index as `--sc-seg` and its local progress
+as `--sc-segp`, on the mode root and on `:root`, and fires a `sc:waypoint`
+CustomEvent (bubbling, `detail: { index, count, label, el, progress }`) whenever
+the leg changes.
+
+It renders no rail. A gauge, a map, a depth readout, a leg counter and a set of
+chapter dots are all the same two numbers, and a runtime that ships one of them
+ships it to every page that uses this mode. Build the rail in the page:
+
+```js
+addEventListener('sc:waypoint', (e) => {
+  document.querySelectorAll('.rail__leg').forEach((el) => {
+    el.setAttribute('aria-current', String(+el.dataset.leg === e.detail.index));
+  });
+});
+```
+
+---
+
+## 6. The seam law for assets
+
+A worldflight is only as good as the joins between its clips. Two architectures
+work; nothing else does.
+
+**Architecture A (preferred): chain on start images only.** Each leg is
+generated from a start image and left to end wherever it ends. The next leg's
+start image is a frame pulled from the previous leg's **encoded** mp4. Never
+force an end-image wide shot: an image-to-image model asked to hit both ends
+resolves the conflict by pulling the camera back, and every leg ends up as the
+same wide establishing shot.
+
+**Architecture B: connector legs.** Where two existing clips have to meet, cut a
+short connector whose start frame comes from the previous leg and whose end
+frame is the next leg's actual first frame.
+
+Extract from the ENCODED mp4, not the source render. The encode changes the
+pixels, and a poster or a chain frame taken from the pre-encode master does not
+match the frame the browser will actually decode:
+
+```bash
+# last frame of the previous leg, as the next leg's start image
+ffmpeg -sseof -0.15 -i legN.mp4 -frames:v 1 -q:v 2 chainN.png
+# first frame of a leg, for its poster
+ffmpeg -i legN.mp4 -frames:v 1 -q:v 3 pN.webp
+```
+
+### Encoding
+
+Same rules as any scrub clip, and they matter more here because a worldflight
+has more of them mounted at once.
+
+- **GOP 8 desktop, GOP 4 mobile.** Scrubbing is random access; a long GOP means
+  every seek decodes a run of frames and the playhead lags behind the hand.
+- Ship `data-sc-src-mobile` for every leg. The engine picks it on coarse
+  pointers and narrow viewports.
+- Posters as WebP, extracted as above.
+
+---
+
+## 7. Loading
+
+A leg is fetched only while the reader is within **±1.6vh** of it. Loading the
+whole flight up front is tens of megabytes before the first frame paints;
+loading on arrival means arriving at a poster.
+
+Until a leg's first real frame has painted, its poster carries the move with a
+push-in (`scale(1.03 + local × 0.14)`). A still that sits perfectly still while
+the page scrolls announces itself as a placeholder; a slow push reads as the
+camera already flying.
+
+Under reduced motion **no clip is ever fetched**. The posters are the film, they
+cross-dissolve through exactly the same seams at exactly the same scroll
+positions, the same copy windows open and close, and every transform is dropped.
+The whole story still reads.
+
+---
+
+## 7b. The spacer is sized once, at mount
+
+`layout()` writes the spacer height as `(total + 1) * innerHeight`. If
+`innerHeight` reports 0 at that moment the spacer is set to **0px**, the page
+has no scroll track, and the flight never advances.
+
+It fails silently and it looks like success. The engine mounted, every leg
+registered, the clips fetched and decoded, `sc-has-clip` is on the segments, and
+there is nothing in the console. The page is simply a still image that cannot be
+scrolled. Embedded preview panes and some early loads do exactly this.
+
+Do not fix it in the engine. One resize makes it re-measure correctly, so send
+one from the page once the window and the fonts have settled:
+
+```js
+function relayout() { dispatchEvent(new Event('resize')); }
+addEventListener('load', relayout);
+if (document.fonts && document.fonts.ready) document.fonts.ready.then(relayout);
+```
+
+The `fonts.ready` half earns its place independently: a webfont swapping in
+changes the measured height of every copy block, and anything the page sized
+against those blocks (a scrim plate, a rail) is wrong until it re-measures.
+
+Check it with one line, and check it before blaming anything else:
+
+```js
+document.documentElement.scrollHeight   // must be ~(sum of weights + 1) * innerHeight
+```
+
+## 7c. Pace: one speed, and slower than you think
+
+Two separate faults get described as "it doesn't feel smooth", and only one of
+them is smoothing.
+
+**Inconsistent pace is the worse one.** Leg weight divided by clip length is how
+fast the world moves under the reader's hand. If that number varies from leg to
+leg, the world surges and drags for no reason the reader can see, and it reads
+as a fault in the page rather than as pacing. Give every leg with the same clip
+length the **same weight**, and give a longer clip a proportional one. On
+`orrery` that number varied by 36% across ten legs on the first cut, and the
+owner's word for it was "not smooth". Evened to a 6% spread, the same footage
+reads as one continuous move.
+
+```
+rate = weight / clip_seconds        // hold this within a few percent everywhere
+```
+
+**Then slow it down.** The instinct is to spend as little scroll as possible. A
+fly-through wants the opposite: the reader is steering a camera, and a camera
+that answers too eagerly feels twitchy. **0.21 to 0.22vh per second of film is a
+good floor for a world you fly through.** 0.14 to 0.19, which is what the per-8s
+line yields, is noticeably fast.
+
+That line is a **dead-scroll guardrail, not a taste ceiling.** Exceeding it is
+fine and often correct; exceeding it without checking is not. The harness
+defines dead scroll mechanically and will tell you. At 0.216vh/s a 0.12vh sample
+gap still advances the clip by half a second, nowhere near dead.
+
+**Damp the playhead and widen the joins.** `data-sc-lerp` defaults to 0.18;
+**0.12 is the better default for a worldflight**, because a flight has more legs
+mounted and more seams than an act page, and the extra damping is what actually
+removes wheel-event judder. Widen `data-sc-seam` from 0.12 to ~0.16 for the same
+reason: a longer crossfade band gives each join more room to disappear in.
+
+Changing weights moves every leg boundary, so **every `data-sc-window` has to be
+recomputed** against the new track and then re-checked on screen. A copy window
+is tuned to a frame of film, not to a number.
+
+## 8. Hard rules
+
+| Rule | Why |
+|---|---|
+| **Nothing in document flow but the spacer.** | The moment a real block scrolls past the fixed stage, the page has a seam and the mode is pointless. If you want a section, you want act mode. |
+| **Copy translate ≤ 4vh across a window.** | Larger reads as a second page scrolling at a different speed. |
+| **The lerp is never disabled** except under reduced motion. | A 1:1 playhead reproduces every gap in the wheel event stream as a stutter. |
+| **One pace for the whole flight**, and slower than feels necessary. | Weight divided by clip length must match across legs, or the world surges and drags. ~1.5vh per 8s is the dead-scroll guardrail, not the target. See section 7c. |
+| **Every clip stays mounted. Never swap a `src`.** | A src swap is a black frame. |
+| **Seam frames come from the encoded mp4.** | The encode changes the pixels. |
+| **One accent, one scrim shape, copy anchored off the bright centre.** | Verified by the contrast pass, which grades copy blocks exactly like cues, at the worst frame each line is ever shown on. |
+
+---
+
+## 9. Verifying
+
+`shoot.mjs` detects `[data-sc-mode="worldflight"]` and switches modes. It samples
+across the spacer track at the same density it samples acts, plus four extra
+positions across every seam, and it waits for the lerp to settle before each
+shot (a screenshot taken mid-lerp is a frame the page never actually holds, and
+it makes the run unrepeatable).
+
+It reports:
+
+- **dead scroll**, defined here as no leg advancing its `currentTime`, no
+  crossfade progress, and no copy-window opacity change between two samples more
+  than 0.12vh apart. Skipped under reduced motion, where each leg legitimately
+  holds one still frame.
+- **legs that never reach full opacity**: a weight or a seam that is wrong: the
+  reader is shown a permanent dissolve and never the leg itself.
+- **legs stuck on poster**: a clip that never loaded or never decoded. It passes
+  every other check, because a poster looks exactly like a paused film.
+- **contrast** on visible copy blocks, through the same direction-aware
+  compositing path as cues.
+
+```bash
+node scripts/serve.mjs --root builds/<name> --port 45XX
+node scripts/shoot.mjs --url http://localhost:45XX --out lab/<name>-shots --per-act 8
+node scripts/shoot.mjs --url http://localhost:45XX --out lab/<name>-reduced --reduced-motion
+```
+
+The mechanical assertions ship with the skill as
+`scripts/worldflight-assert.mjs` and run against **any** worldflight page, not a
+special rig: spacer height, fixed stage, nothing in document flow, lerp
+convergence and non-overshoot, seam monotonicity, the copy transform cap, and
+the reduced-motion contract.
+
+```bash
+node <skill>/scripts/worldflight-assert.mjs --url http://localhost:45XX
+```
+
+Run it against your own build before the contact sheet. It answers "does the
+mode actually hold" in a way a screenshot cannot.

package/skills/luckiest-design-website/references/worlds.md

@@ -0,0 +1,178 @@
+# Worlds
+
+The art direction the whole page lives inside. Pick one, write it as a **style
+preamble**, and paste that preamble verbatim at the top of every image and video
+prompt. Reusing it word for word is what makes eight separately generated assets
+look like one shoot. Paraphrasing it is what makes them look like eight prompts.
+
+---
+
+## The default is photographic
+
+Soft matte low-poly clay diorama, isometric miniature, tilt-shift toy world:
+**banned as a default.** It is the house style of AI scroll sites, it announces
+that nothing on the page is real, and for any brand selling an actual product it
+actively works against the sale. A clay render of a can does not make anyone
+thirsty.
+
+Use an illustrated world only when the brand is genuinely illustrated: a
+children's product, a game, a brand whose existing identity is drawn. Then
+commit to it properly, matched to the brand's real illustration style, not to
+the generic diorama look.
+
+---
+
+## The eight
+
+Each is a starting preamble. Tune the light, lens and grade to the brand; keep
+the structure.
+
+### 1. Low-key cinematic: the default
+Dark, controlled, one light source. Works for almost anything premium: spirits,
+coffee, tools, apparel, software, professional services.
+
+> Cinematic product photography shot on 35mm anamorphic lenses. Shallow depth of
+> field, high dynamic range, true blacks, matte film grain. Low-key lighting:
+> one warm key, cool ambient fill, deep falloff into shadow. Colour grade of deep
+> charcoal, warm amber highlights, desaturated mid-tones. Photographic realism.
+> NOT 3D render, NOT clay, NOT illustration, NOT CGI, no digital glow, no plastic
+> sheen.
+
+### 2. High-key editorial
+Bright, airy, shadowless. Wellness, skincare, home goods, healthcare, fintech
+that wants to feel calm.
+
+> Editorial still-life photography on a seamless bone-white cyclorama. Large soft
+> overhead source, huge white bounce, near-shadowless with one soft contact
+> shadow. High key, gentle contrast, colour grade of warm white and pale
+> neutrals. Medium-format sharpness, fine grain. Photographic realism, no CGI.
+
+### 3. Natural documentary
+Real people, real places, available light. Service businesses, trades,
+restaurants, anything where trust comes from "these are actual humans."
+
+> Documentary photography, available light only, handheld 35mm. Natural skin
+> tones, honest imperfect surfaces, slight motion in the frame. Muted realistic
+> grade, no colour cast, visible grain. Candid, unposed, nobody looking at
+> camera. Absolutely not stock-photo styling, no fake smiles, no CGI.
+
+### 4. Hard-light graphic
+Direct sun, saturated ground, sharp shadows as composition. Streetwear, energy
+drinks, sports, youth brands.
+
+> Studio product photography with a single hard undiffused source. Crisp
+> high-contrast shadows used as graphic shapes. Saturated seamless colour
+> backdrop. Punchy contrast, slight halation on specular highlights. Shot on
+> digital medium format, sharp throughout. Photographic, not rendered.
+
+### 5. Macro texture
+Closer than the eye gets. Food, drink, materials, ingredients, craft.
+
+> Extreme macro photography, 100mm macro lens at high magnification. Razor-thin
+> plane of focus, everything else falling to soft black. Backlit so edges glow.
+> Visible surface texture, condensation, grain of the material. Near-black
+> negative space. Photographic realism, no CGI, no illustration.
+
+### 6. Architectural
+Space, scale, geometry, almost no people. Real estate, agencies, manufacturing,
+B2B infrastructure.
+
+> Architectural photography, tilt-shift corrected verticals, wide 24mm. Vast
+> negative space, strong linear geometry, raking daylight through structure.
+> Cool neutral grade with one warm accent. Long exposure stillness. Photographic,
+> no render, no CGI.
+
+### 7. Nocturne
+Night, practical lights, wet surfaces, reflection. Nightlife, automotive,
+gaming, security, anything with edge.
+
+> Night photography, practical light sources only: neon, sodium, screen glow.
+> Wet reflective surfaces doubling every light. Deep blue-black shadows, warm
+> point highlights, heavy atmosphere. Anamorphic flare, visible grain.
+> Photographic, cinematic, not rendered.
+
+### 8. Technical drawing
+The one non-photographic world that reads as premium rather than cheap, because
+it is honest about being a diagram. Engineering, hardware, complex services.
+
+> Precise technical illustration in the style of a patent drawing or exploded
+> assembly diagram. Fine consistent line weight, no fills, monochrome ink on
+> warm paper ground, dimension lines and leader callouts. Orthographic
+> projection. Restrained, engineered, no shading, no gradients, no 3D render.
+
+---
+
+## Writing your own
+
+Every preamble names five things. Miss one and the set drifts.
+
+1. **Medium and lens**: "35mm anamorphic", "100mm macro", "handheld 35mm".
+   This is what sets depth of field and perspective.
+2. **Light**: count the sources and place them. "One warm key, cool ambient
+   fill" is directable. "Beautiful lighting" is not.
+3. **Grade**: the colour story in three words. "Deep charcoal, warm amber,
+   desaturated mid-tones."
+4. **Texture**: grain, halation, condensation, imperfection. This is what makes
+   an image read as photographed rather than generated. Skipping it is the
+   single biggest cause of the plastic AI look.
+5. **The negative list**: what it must not be. "NOT 3D render, NOT clay, NOT
+   illustration, no digital glow, no plastic sheen." Models drift toward
+   rendered-looking output; the negative list is what holds them.
+
+---
+
+## If the canvas is light
+
+Every worked example above is dark, and a high-key build inverts four things at
+once. Getting them wrong costs a full iteration:
+
+1. **The scrim washes toward the canvas, it does not darken.** Over footage on a
+   paper ground the density has to go *up*, not down, or the type has nothing to
+   sit on.
+2. **The type over media stays ink.** Light text on a light page over a bright
+   frame is unrecoverable.
+3. **`--sc-edge` is an ink-tinted inset highlight** tuned for a near-black
+   ground. On paper it reads as dirt along the top lip. Invert it to white, or
+   drop it and carry the raise with a hairline.
+4. **The `--sc-e1/2/3` shadow alphas are tuned for a near-black ground** too.
+   Halve them and re-tint `--sc-shadow-color` toward the canvas hue.
+
+The contrast direction flips with all of this: dark type fails on the *darkest*
+patch under it, not the brightest. The harness picks the direction per line, so
+it grades a high-key page correctly (see [verify.md](verify.md)).
+
+---
+
+## Composition, per shot
+
+The preamble sets the world. Each shot prompt then names the subject, the frame,
+and **where the empty space is**.
+
+**Name the empty space in every scene prompt, not only in the preamble.** This
+is a requirement, not advice. It is the single highest-leverage line in a prompt:
+seven stills across three aspect ratios came back on-grade and cohesive with zero
+rerolls on the build that did it every time. Copy sits on these images, so
+composition has to leave room for it:
+
+- "large empty shadowed space across the upper left of the frame"
+- "the subject low and to the right, negative space above"
+- "centred with even empty space on both sides"
+
+Generate the space, do not crop for it later. And never ask for text in the
+image: markup is selectable, translatable, sharp at every density, and editable
+after the fact.
+
+---
+
+## Cohesion checks
+
+Lay every generated asset side by side and look for:
+
+- **One light direction** across the set, or a deliberate reason it changes.
+- **One grade.** If one image is cooler than the rest, reroll it rather than
+  correcting it in CSS; a filter over a full-bleed image flattens it.
+- **One level of realism.** A photoreal hero followed by a rendered-looking
+  product shot is worse than either style used consistently.
+- **The brand object identical everywhere.** Pass the real packaging, logo or
+  product shot as `--ref` on every prompt that includes it. A label that drifts
+  between shots is the thing a client notices first.