wizz-method 2.22.0 → 2.23.0

package/src/skills-lib/wizz-video-styles/references/film-styles/watercolor.md

@@ -0,0 +1,113 @@
+<!-- Vendored from lemo-opuscar (https://github.com/lemomo-ai/lemo-opuscar/tree/413a6bd6/styles/watercolor), MIT, (c) 2026 LemoLab; see ../../LICENSE-lemo-opuscar.txt. Paths under demo/ and core/ name that repo's engine, which is not shipped here: build the look in HyperFrames (../film-styles.md). -->
+
+# Watercolor Brush — Style Prompt
+
+> A hand-painted journal page that paints itself: translucent brush strokes with dry-brush flying white on warm cotton paper, hand-written notes beside what is painted, nothing drawn with a vector line.
+> References (grammar only): naturalist field-journal and botanical-plate watercolours (specimen + note); long horizontal handscroll panoramas (one continuous painted world); the textbook "transect" diagram (a gradient read across space). Borrow the grammar, never a specific artwork, character or layout.
+
+## 1. Essence, and what it is not
+
+- **One sheet of warm, fibrous paper** under everything; it is also the eraser (paper-coloured mist washes things away).
+- **Everything is individual brush strokes**: a variable-width ribbon at partial opacity plus a few thin **bristle tracks** that break into dashes (flying white). Strokes overlap and darken where they cross, like transparent pigment. No vector outlines; a darker edge stroke along a form is the only "line".
+- **Things paint themselves in**, stroke by stroke, structure before detail (trunk → branches → leaves; outline wash → shadow → accent).
+- **An annotation layer** in a hand the painter would write with: labels with pen leader lines, a small measured value, a quiet title.
+- Tone: calm, curious, precise. Numbers are real; the palette can carry data.
+
+Not ink wash (colour, not ink tones; no calligraphic brush-as-gesture), not impasto (no thick paint, no knife), not a children's picture book (no crayon, no cute outlines), not vector illustration with a watercolour texture laid on top.
+
+## 2. Materials & rendering
+
+- **Paper**: a pre-generated image (warm base, three octaves of smooth noise ±3.5 %, a few thousand short curved fibres, fine grain, light vignette), drawn first every frame.
+- **Stroke** (`engine.js` `mk`/`drawS`): a ribbon whose width follows a profile (`brush`, `leaf`, `even`, `tip`, `trunk`) with ~±22 % value-noise roughness, filled as a thin wash (≈ 0.55–0.6 body opacity when bristles are present), plus 3–9 bristle tracks at 30–85 % opacity, each with a random dash pattern and a random early end: that is the flying white. A stroke can be painted up to any fraction of its length (a moving brush tip).
+- **Wash**: the same polygon painted in 3 passes with jittered vertices at a third of the opacity each, so edges darken where passes disagree (a pooled watercolour edge).
+- **Depth by layers**: several parallax layers of washes and painted objects; farther = smaller, lighter, less saturated; paper-coloured mist bands between layers.
+- **Cache finished objects as sprites**; draw stroke by stroke only what is being painted or transformed.
+- **Everything is a pure function of `t`**; any stroke made inside `render(t)` is built under a fixed seed.
+
+## 3. Colour logic
+
+- **Paper is the white.** Never paint pure white; light is unpainted paper.
+- **Transparent layering**: darker = more passes, not a darker pigment on top. Keep 3–5 hues per scene plus ink.
+- **Ink** (a warm near-black and a lighter brown) for lines, text, edges and stems only.
+- **Colour may carry the data or the mood**: blend sky, ground and background by position or time so the palette itself changes with the subject. Map ramps quantised into 4–6 bands read as paint, continuous ramps read as software.
+- **One accent** (a vermilion, a rain blue) reserved for one element that recurs: a stamp, a marker, a key object.
+- Examples: arid-to-wet — red ochre → sage → straw → blue-grey → deep green; a harbour at dawn — `#f3e2c8` sky, `#9fb4c4` water, `#5f7486` hulls, accent `#c8442a` buoys; a vegetable garden — `#e8e0c0` soil light, `#8ea860` leaves, `#4e6e3c` shade, accent `#d9632e` pumpkins.
+
+## 4. Type & subtitles
+
+- An elegant serif (e.g. Cormorant Garamond) for titles and subtitles, a handwriting face (e.g. Caveat) for notes, a small mono (e.g. IBM Plex Mono, wide tracking) for measured labels, Noto Serif SC for Chinese (subset to the characters used).
+- Hand notes are drawn twice over a paper-coloured halo, revealed left to right like writing, with a pen leader line that grows to its specimen.
+- **Subtitles** sit on the paper, not in a box: centred at the bottom, serif italic ~36 px (2 balanced lines max), a second-language line beneath at ~2/3 size, ink at ~78 % over a paper-coloured halo. Hold ≥ max(1.8 s, speech + 0.6 s).
+- Numbers are spelled out in the TTS text and written as digits on screen.
+
+## 5. Motion quality
+
+- **Painting-in is the main motion**: an object's progress is a function of where it sits on screen or of a cue; strokes in a list each take a slice of that progress, so structure appears first.
+- **Sway** only after an object is finished: a small horizontal skew (`sin(1.15t+φ) + .4 sin(2.7t+2φ)`), ~0.006 for trees, 0.01–0.03 for grass.
+- **Brush-edge wipes**: a wavy vertical clip reveals a whole scene; lines grow by stroke progress; labels open with a left-to-right clip.
+- **Mist** erases: paper-coloured layers with a wavy rising edge.
+- Animated creatures and events may be phased to the music's beat grid so landings hit the beat.
+- Smooth easing (`ss`, `eio`, `eo`, `ei`); 60 fps suits the slow, fluid brush; nothing jitters.
+
+## 6. Camera grammar
+
+A vocabulary, not a route. The picture is one painted sheet; cutting is rare. Opening and ending come from the topic.
+
+| Move | What it expresses | Can serve |
+|---|---|---|
+| Long lateral dolly over a continuous world | a gradient; a journey; cause and consequence | a transect; a route; a timeline |
+| Vertical tilt along one object | scale; measurement | a tall tree; a building; a depth |
+| Locked sheet, things painted in | study; attention | a specimen plate; a recipe; a diagram |
+| Slow push into a detail | the observer leaning in | a seed; an insect; a hand-written note |
+| Pull-back to a map or diagram | the whole re-framed | where it all happened; a system |
+| Mist wash to blank paper | chapter end; time passing | a season; forgetting; a new place |
+| Page turn / new sheet slides over | a new entry in the journal | a new day; a new species; a new case |
+| Change in time on a locked view | growth; decay; history | a season cycle; before/after; deep time |
+
+Framing: generous paper margins; one hero subject per view with its note; labels never cover the subject. Transitions: brush-edge wipes, mist, a page turn, or a continuous camera move; no hard video cuts, no dissolves between unrelated pictures.
+
+## 7. Sound palette
+
+- **Music**: acoustic and gentle: felt piano, fingerpicked guitar, woodwinds, light strings, glockenspiel, kalimba, soft pads. A licensed track can be edited with beat-aligned jumps; the picture can then take its beat grid.
+- **Foley made from the scene's matter**: a paper brush rustle for each painting-in (band-passed noise, light tremolo, a panned sweep); pencil scratch for notes; a soft thump for a stamp; page flips; nature beds and creatures of the subject (birds, wind, rain plinks, water, insects, fire crackle).
+- **Silence**: the brush lifted: music out, only paper and room; it frames a single painted moment.
+- **Mix character**: voice forward (RMS a few dB over the music), music ducked ~4 dB under voice with a smoothed envelope, a short soft reverb, final −14 LUFS. Kokoro voices are peaky (~17 dB peak-to-RMS): limit before level-matching.
+- **Voice**: warm, unhurried documentary read, one line per idea.
+
+## 8. Native moves
+
+A menu: use the ones your story needs.
+
+- **Painting-in as reveal.** A new thing appears stroke by stroke as it enters. *Fits content like:* the stages of a building; the ingredients of a dish; the organs of a body.
+- **Burst.** A whole group paints in at once (≤ 1 s) for a peak. *Fits content like:* a festival crowd; a field in bloom; a city lighting up.
+- **Palette as data.** Sky, ground and background blend by a measured value. *Fits content like:* pollution along a river; temperature by altitude; noise across a city.
+- **Specimen + note.** One hero object with a hand-written label and leader line. *Fits content like:* a tool kit; a wine region's grapes; parts of a bicycle.
+- **Mist erase.** The world washes back to paper. *Fits content like:* forgetting; a dream ending; a site demolished.
+- **Map in time.** A painted map whose fills change continuously through years. *Fits content like:* a language spreading; a coastline eroding; a railway network growing.
+- **Painted transformation.** Objects cross-fade to a burnt, wet or aged sprite and regrow. *Fits content like:* a wildfire and recovery; a flood; a restoration.
+
+## 9. Pitfalls of the medium
+
+- Offscreen wash strips too short flatten tall shapes into flat tops and expose seams on tilts → size strips well beyond the frame.
+- A translucent wash that ends at its canvas edge shows a hard seam under other layers → extend below the frame and fade to paper with a gradient.
+- Classic scripts share one global scope: touching a `const` before its declaration in async init leaves `READY` false and every screenshot times out → build everything inside the init; read `[pageerror]` lines.
+- The stroke builder consumes the global RNG: any stroke created in `render(t)` must be wrapped in `withSeed` or parallel workers disagree.
+- Thousands of strokes per frame are too slow → sprite cache.
+- Beat-locked animation must be re-derived when the music edit changes.
+- New CJK subtitle characters fall back to another font until the subset is rebuilt.
+
+## 10. Engine
+
+In `demo/`: `engine.js` (RNG, easing, noise, monotone keyframe tracks; the stroke engine `mk`, `drawS`, `drawList`, `sprite`, `clump`, `edgeOf`, `withSeed`), `plants.js` (plant and prop generators, local coordinates, root at 0,0), `scene.js` (layers, wash strips `washPoly`, world placement `add`, annotations `hand` / `leader` / `note`), `main.js` (map, mist, HUD, subtitles, `render(t)`, async init → `READY`), `paper.py`, `fetch_fonts.mjs`, `mix.py`, `render.mjs`. API table and a minimal example: [DEMO.md](https://github.com/lemomo-ai/lemo-opuscar/blob/413a6bd6/styles/watercolor/DEMO.md) "Engine reference".
+
+## 11. Variation space
+
+You decide the subject, the structure, what gets painted, the palette logic, whether anything is measured, the opening, the ending and the camera. All far from our demo:
+
+- Structures: **a journal kept over one year** (locked page per month, each painted over the last); **anatomy of one object** (a single specimen dissected into labelled parts, each part a painted close-up); **a recipe or process** (steps painted top to bottom on one tall sheet, tilting down).
+- Openings: **a finished painting** that we then watch being painted backwards to its first stroke, and forwards again; **a close-up of wet pigment** spreading, pulled back to show what it became; **a hand-written question** on blank paper, answered by painting.
+- Endings: **the page left unfinished**, brush lifted mid-stroke; **a close-up of one detail** as the rest fades to paper; **the sheet dries and is filed** into a stack of other pages.
+
+---
+
+How our demo was made (story, shots, score, end card, build): [DEMO.md](https://github.com/lemomo-ai/lemo-opuscar/blob/413a6bd6/styles/watercolor/DEMO.md). Read it after your treatment exists.

package/src/skills-lib/wizz-video-styles/references/film-styles/white-model.md

@@ -0,0 +1,115 @@
+<!-- Vendored from lemo-opuscar (https://github.com/lemomo-ai/lemo-opuscar/tree/413a6bd6/styles/white-model), MIT, (c) 2026 LemoLab; see ../../LICENSE-lemo-opuscar.txt. Paths under demo/ and core/ name that repo's engine, which is not shipped here: build the look in HyperFrames (../film-styles.md). -->
+
+# Projection on White Model — Style Prompt
+
+> A pure white massing model of a real place stands on a plinth in a dark room, and a projector paints data onto it as light: one layer at a time, falling on the surfaces that face it, spilling a little past the plate. The model never changes; only the light on it does.
+> References (grammar only): projection-mapped planning models in city galleries (the dark room, the soft throw, colour only on white surfaces); macro model photography (shallow focus at rooftop height); editorial data graphics (one figure, one label, one source per layer). Copy none of their layouts, typefaces, colours or music, and never name them in the film.
+
+## 1. Essence, and what it is not
+
+- **The model is real geometry of a real place**: building footprints and heights from open data (§2), extruded at a stated scale (1:1000, 1:2000…). Nothing on the model is invented or "representative", and no generated image ever stands in for the place.
+- **The model is white; data is light.** Colour is never painted into the material: it is projected, so it brightens surfaces that face the projector, fades on walls turned away, stops at the edge of the throw and reaches a little onto the plinth.
+- **Layers arrive one at a time**, each with its own gesture of light (a wash, a pop-on, a rising level, a moving sun), and each answers the question the last one raised.
+- **A physical room**: house lights, a projector that strikes and switches, a plinth, darkness around it. Lights out is where the data starts; lights up is where it ends.
+- **Every number on screen is computed from the same buildings** that are on the table.
+
+Not Isometric Infographic (no diorama or icons), not Low-poly Island (no invented terrain), not Sci-fi Hologram HUD (no wireframes; light lands on matter), not Satellite Briefing (no imagery), not a laser-scan or point-cloud film (no scan lines; light is projected, not measured).
+
+## 2. Materials & rendering
+
+- **Model**: matte white (≈ #F3F3F1, roughness ≈ 0.9), crisp edges; water a darker satin inlay in the base plate; bridges low white slabs; a thin base plate on a dark satin plinth.
+- **Light model**: house light = one soft key + a neutral studio environment + AO on close shots. Projection = a term added to the lit surface in the shader: `colour × (0.42 + 0.58 · max(N·toProjector, 0)) × throw mask`, scaled by albedo, reduced on water. Never a texture on the mesh.
+- **Building data is the material.** First look for the place's own open 3D or footprint-with-height data: 3DBAG (Netherlands, CC BY 4.0), PLATEAU (Japan, CC BY 4.0-compatible), city open-data portals (footprints with heights or floors, zoning, plans). Fine: CC0, public domain, CC BY (credited in CREDITS and on screen). OpenStreetMap and Overture (ODbL), CC BY-SA and "no known restrictions" are not CC0: name the terms to the user and ask first. For their own site, ask the user for their data (plan, city model, survey heights).
+- **Layers depend on what exists.** Construction years per building are a Dutch luxury (BAG); elsewhere they are often missing. Substitute what the data does hold and the medium can still project: heights or floor counts, footprint area, zoning or plan status, a boundary, sun and shadow (always computable). Never invent a year layer.
+- **A layer is state, not a picture**: per-building attributes (year, height, rank, flags) live in vertex data; the shader decides each frame what colour the projector gives them.
+- **The sun is a real directional light** with shadow maps, computed from the place's latitude and a real date and time (NOAA/Meeus solar position). The projector can trace what the sun does (a shadow footprint) but never fakes a shadow.
+- **Post**: physical depth of field (stronger on close shots), bloom only above the projection highlights, vignette, light grain in ffmpeg. GTAO only on close shots: on wide grazing views it bands.
+- **Screen space only for the 2D layer**: readouts, pins, measured lines and subtitles go through the camera's world → screen function so they stay pinned to the model.
+- **Keep a FACTS.md in the project folder** (claim, source URL, quoted wording, or the measurement method) and deliver it with the film; every number on screen is computed by a script from the same data as the model.
+
+## 3. Colour logic
+
+- Neutral ground: white model, dark room (near black), dark plinth. Projector black level is a cool near-black on the plate.
+- **One hue family per layer**, chosen for the data: a single categorical accent for "the old/the exception" (e.g. warm amber), a sequential ramp for continuous data (blue → cyan → white for time, violet → magenta → peach for height).
+- **A colour may return** only with the same meaning (the "before" colour reused later marks the same set of buildings).
+- The sun is warm, its shade is a projected deep blue; data colours are put away when the sun arrives.
+- Never colour the model in the house light; never use more than two layer palettes on screen at once.
+
+## 4. Type & subtitles
+
+- **Roles**: a light grotesk for the figure (Inter Tight 200, 120–140 px), a sans for labels in the film's language (Noto Sans SC 300/500, 20–36 px), a monospace for instruments, years and coordinates (IBM Plex Mono, 18–22 px). OFL, self-hosted, CJK subset.
+- **Readout in the left third**, one per layer: index + layer name, one figure, one label, one source line, a legend bar.
+- **Pins**: a hairline from a roof or a ground point up to a tag on a dark plate (title 26 px + one sub line 20 px).
+- **Identity label** top-left, quiet: place, scale, data sources.
+- **Subtitles** centred at the bottom on a soft dark gradient, no box, measured with the real fonts; if the film is bilingual, the film's language on top, each language on a single line, split into two cues rather than wrap.
+- Nothing below 18 px at 1080p. Hold subtitles ≥ max(1.8 s, speech + 0.6 s); labels ≥ characters ÷ 4.5 + 1.5 s (CJK), letters ÷ 15 + 1.5 s (Latin).
+
+## 5. Motion quality
+
+- The camera moves continuously and slowly; it changes speed with the layers, never stops dead.
+- **Light is the actor.** Each layer arrives by a soft-edged gesture of light: a wash spreading from the projector axis, buildings switching on one by one with a short flash, a level climbing every facade, the sun's clock running. No hard line sweeping the table.
+- House lights cut fast (a relay, 0.25 s) and return slowly (1 s); the projector strikes with a brief flicker.
+- Counters roll while the light moves and land when it lands; measured lines grow from A to B with ticks.
+- What never moves: the model, the plinth, the pins' anchors on the model.
+
+## 6. Camera grammar
+
+| Move | What it expresses | Can serve |
+|---|---|---|
+| Macro glide at rooftop height, shallow focus | the model is a real object | an opening; a detail that matters |
+| Crane up and back | the whole pattern only seen from above | revealing a hole, a cluster, an edge |
+| Slow orbit with a rise | the city as a whole, layers accumulating | growth over time; comparisons across the model |
+| Boom down to a low angle against black | height, skyline | tall buildings, heights, a single tower |
+| Side-on track along a line | a measured distance on the model | a shadow, a corridor, a route, a view line |
+| Pull back as the house lights return | the data stops; the object remains | an ending; a reset between topics |
+
+At key moments the subject fills a third of the frame height; readouts left third, subtitles bottom centre, pins never over the readout. Transitions are light changes on one take (lights out, a layer replacing another, the projector going dark), not cuts, fades or wipes.
+
+## 7. Sound palette
+
+- **The room**: room tone, the projector fan (hum + filtered air) rising when the lamp strikes, relays for the house lights, a lamp strike (zap + thump), the air of a light wash (sliding band-passed noise).
+- **Light as sound**: mallets and glass for things switching on, bowed vibraphone for held light, a rising mallet line and air riser for a climbing level, one glass note per highlighted building.
+- **Weight**: timpani, gran cassa, gong, low brass for a heavy fact; warm low brass for a turn.
+- **Floor**: contrabass and cellos only as a floor under the chords; no generic piano and strings melody.
+- **Silence**: the projector goes dark and everything stops but a thin fan hum before the turn; a short suck-out before the heaviest hit. The first sound after the silence is the turn.
+- **Mix**: voice about 10 dB over the music; the two designed impacts are the loudest moments; −14 LUFS, true peak ≤ −1.2 dB. Voice: calm, short declarative lines, numbers spoken plainly.
+
+## 8. Native moves
+
+- **Lights out, lamp on.** House light, a relay, darkness, the lamp strikes, the first layer arrives. *Fits content like:* a site before and after; a district before a plan is shown; any "now look closer".
+- **The hole.** Light only the set that answers a question (built before a date, owned by one party, inside a zone) and let the absence draw the shape. *Fits content like:* a war-damaged centre; a flood plain with no housing; land a company owns; a protected zone.
+- **Layers by time.** Buildings switch on in the decade they were built, each layer faster than the last, a year counter rolling. *Fits content like:* a new town's growth; a campus master plan by phase; a port's expansion; a developer's portfolio by year.
+- **The rising level.** A soft level of light climbs every facade at once; low buildings finish first, the tallest last, the reading rides up with it. *Fits content like:* building heights; sea-level or flood depth; floor counts; a height limit being tested.
+- **The sun clock.** A real sun at a real date sweeps the shadows; the projector then traces one shadow and measures it. *Fits content like:* a new tower's shadow on a park; winter light in a courtyard; solar panels' best roofs; a street's daylight hours.
+- **The pick-out.** One building or set lights alone while the rest stay dark, with a pin. *Fits content like:* a listed building; the plot for sale; the hospital in an evacuation plan.
+- **Lights up.** The data stops, the white model comes back. An ending or a reset.
+
+## 9. Pitfalls of the medium
+
+- **Wall normals** wound the wrong way show inside faces (walls look hollow): derive the outward normal from ring orientation. **Shared walls** between parts z-fight: skip the overlap below the lower neighbour.
+- **Warm HDRIs turn the white model beige**: use a neutral studio environment.
+- **GTAO on wide grazing views** produces wedge-shaped dark bands; keep it on close shots only.
+- **A low sun lights facades, not roofs**: shoot from the sunlit side or side-on. **Narrow shadows vanish** among all the others: trace the one that matters (fill + edge) and measure it.
+- **Hairline scan lines read as laser scanning**: give every projection front a wide soft edge or switch buildings individually.
+- **Floating labels**: anchor pins on the tallest part of a building, not on its footprint centroid.
+- **Numbers from mixed sources** (official height vs measured roof): say which on screen ("roof", "measured").
+
+## 10. Engine
+
+- `demo/studio.js` — `makeStudio(W, H, model)`: renderer, post, room, the projection material (`projMaterial(kind)` injects `projLight()` / `roofGlow()` into MeshStandardMaterial), the city mesh (`buildCity`: outward normals, shared walls removed), plate, plinth, house light (index 0) and sun (index 1). Uniforms `U` drive every layer.
+- `demo/tools/prep.py` — **3DBAG + BGT only**: it reads 3DBAG fields (`b3_h_70p`, `b3_h_maaiveld`, `oorspronkelijkbouwjaar`) and Dutch RD coordinates (`tools/rd.py`). Another source needs its own adapter that writes the same `model.json`: `{size:[w,d] model metres, b:[[year|0, height_m], …] per building, p:[[building_index, height_model_m, [[[x,z],…] outer ring, …holes]], …] per roof part, decks:[[[x,z],…]]}`, with x east, z south, 1 unit = 1 model metre; plus `water.png` (plate-sized mask) and a `stats.json` with every on-screen number. `tools/sun.py` (solar position, any place and date) and the heightfield shadow are source-independent.
+- `demo/overlay.js` — readout, pin, measured range line, subtitle strip, title card; registers texts for readcheck.
+- **Extra packages and packs**: none beyond `setup.sh deps` (+ `voice`, `music` for narration and score); downloads are plain `curl` from the data portal. Reprojecting another country's data may need pyproj or shapely: the agent installs them itself into a private venv in the project folder, not into `$LIB/.venv`.
+- Minimal example, not in the demo: set `U.uPreC` to a station and `U.uPreR` growing to light everything within walking distance; or put a flood height in `U.uHgtF` with `U.uHgtBand` held at 1 and leave it still.
+
+## 11. Variation space
+
+Decide per film: place and scale, which layers in what order, their colours, the opening, the camera path, the ending, the pace.
+
+- **Structures**: a question answered layer by layer; a plan versus today (the plan's buildings switching on in a second colour); one building's story told by its neighbours.
+- **Openings**: a macro glide over white roofs; darkness and a single pick-out; the plinth from across the room as the house lights fall.
+- **Endings**: lights up on the white model; one last layer left on alone; the camera rising until the model is an object on a table in a dark room.
+
+---
+
+How our demo was made (story, shots, score, title card, build): [DEMO.md](https://github.com/lemomo-ai/lemo-opuscar/blob/413a6bd6/styles/white-model/DEMO.md). Read it after your treatment exists.

package/src/skills-lib/wizz-video-styles/references/film-styles/whiteboard.md

@@ -0,0 +1,118 @@
+<!-- Vendored from lemo-opuscar (https://github.com/lemomo-ai/lemo-opuscar/tree/413a6bd6/styles/whiteboard), MIT, (c) 2026 LemoLab; see ../../LICENSE-lemo-opuscar.txt. Paths under demo/ and core/ name that repo's engine, which is not shipped here: build the look in HyperFrames (../film-styles.md). -->
+
+# Whiteboard Explainer — Style Prompt
+
+> An explainer drawn live on one glossy dry-erase board: single-line handwriting that is actually *written* stroke by stroke, floating markers with no hand, magnets that can move, an eraser that can rewind, and a camera that travels across the board instead of cutting.
+> References (grammar only): RSA Animate / Cognitive Media (one continuous board, the camera travels instead of cutting, a full-board view); minutephysics (one sentence = one drawing, the simplest geometry that carries the idea); Steve Reich's *Piano Phase* (two copies of one figure at two tempi as a structure). Never copy their drawings, characters, hands or music.
+
+Suits explainers, usually science or "how does X work"; the length follows how many ideas the board has to hold.
+
+## 1. Essence, and what it is not
+
+- **One physical whiteboard.** Everything the viewer learns is drawn in dry-erase marker in front of them, in real handwriting order.
+- **The board is a map**: each idea lives in its own region; the camera travels between regions, often led by the pen. Distance on the board = distance in the argument.
+- **Real marker, not animated text**: ink pools where the nib lands, dry streaks and speckle, strokes overshoot and don't quite close, ghosts of old lessons remain, a glossy sheen drifts slower than the board, and **every stroke makes a sound**.
+- **No hands.** Markers float with a real cast shadow that grows when they lift, park outside the frame between phrases and fly back in. Magnets and the eraser move on their own. Never draw a hand, an arm or a cursor.
+
+Not Blueprint (no blue sheet, no drafting conventions), not Crayon Picture Book (no wax texture, no children's story), not a kinetic-type explainer (text is handwritten stroke by stroke, never animated as blocks).
+
+## 2. Materials & rendering
+
+- **Board**: a warm white gradient, a faint scuff and micro-scratch tile, a few dozen **ghost marks** (old words, circles, arrows) at 5–10 % in grey or pale blue, and a soft diagonal **window sheen** (white, 10–16 %) moving at ~0.35× the camera: this one detail sells "glossy".
+- **Ink**: alpha ~0.94, composited with **multiply** so overlaps darken like real marker. Width 6–11 px for drawing, ~13 % of cap height for lettering.
+- **Stroke character**: resampled every ~0.6 × width; low-frequency hand wobble along the normal (a few px, long wavelength) plus a finer tremor; chisel-tip width modulated by direction; a pressure ramp at the start and a small taper at the end; circles start at an angle and **overlap past closure**; rectangles are four strokes with small corner overshoot; a darker pooled dot *inside* the start of long strokes.
+- **Dry-marker texture**: a speckle-and-streak tile subtracted from the ink layer (destination-out), locked to board space, faded out when the camera is wide.
+- **Lettering**: a single-line (single-stroke) font written in stroke order, each glyph with small rotation, baseline and scale jitter. Missing symbols (μ ≈ → × − ✓ ² ° ±) are hand-defined.
+- **Props**: dry-erase markers (white barrel, colour band and cap in the ink colour, felt nib), a felt eraser, magnets (glossy, with specular highlight and soft cast shadow). Frame, tray and wall appear only if the camera ever goes past the board edge.
+
+## 3. Colour logic
+
+- **Three marker colours at most**, each with a meaning held for the whole film: one dark ink for things and structure, one for signals / measurement / process, one accent for the thing that matters (one accent per region).
+- **Monochrome variant**: everything in the dark ink, one element in the accent (the "only colour").
+- Ghost marks and board stay neutral; the accent never appears on props except its own marker cap and the hero magnet.
+- Example sets: black `#23262c` / blue `#2a5cb3` / orange `#d97757`; black / green `#2e8b57` / red `#c8363a`; navy `#1f2a44` / teal `#1f8a8a` / purple `#7a4fb3`.
+
+## 4. Type & subtitles
+
+- **Handwriting only**: a single-line hand (e.g. EMS Tech, OFL) for all board text; titles large (~120–200 px cap height), labels 30–70 px.
+- **Title and end card are written on the board** in the same hand.
+- **Burned subtitles**: an off-white rounded label (~90 %), a handwriting-like face (e.g. Architects Daughter ~44 px), dark text, a short accent-colour marker dash. Split at clauses, ≤ 44 characters per line, bottom ~12 % of the frame kept free for them in every shot. Hold ≥ max(1.8 s, speech + 0.6 s).
+- **Writing finishes on the word**: a term appears exactly when the narrator says it.
+- A label is fully in or fully out of every shot it appears in.
+
+## 5. Motion quality
+
+- **Hand speed**: every stroke follows a slow-fast-slow curve (`u − sin(2πu)/2π × 0.8`). Strokes are scheduled into a **time window** and the engine solves the speed, so writing always finishes on time.
+- **Pen hops** between strokes lift in proportion to distance (shadow slides and blurs); long gaps send the pen off-frame to park and back shortly before its next stroke.
+- **Magnet**: drop with a shrinking shadow; slide with a small lift; lift-off and sink possible.
+- **Eraser**: constant speed along a path, a wide band at ~90 % strength (a ghost always remains).
+- **Speed**: faster than real hands (a sped-up lesson) but never so fast the stroke order is lost: a label ~0.3–0.8 s, a title ~3 s.
+- Camera on ones with real motion blur when it moves fast.
+
+## 6. Camera grammar
+
+A 2D camera over a large board (e.g. 8000 × 4500): position, zoom interpolated in 1/z so pushes feel like dollies, a little roll. A vocabulary, not a route. Opening and ending come from the topic.
+
+| Move | What it expresses | Can serve |
+|---|---|---|
+| Pull back from a tiny drawing | scale | a surprising size; context |
+| Ride the line the pen is drawing | one idea leads to the next | a transition; a process; a path |
+| Hold still | read now | an equation; a definition; a list |
+| Whip to a new region | a new idea after a pause | a twist; a "but" |
+| Return to an earlier region | a callback, for free | reusing a result; a comparison |
+| Split view of two regions (zoomed out enough for both) | two things at once | a duet; before/after |
+| Slow push into one symbol | this term is the point | a unit; a variable; a name |
+| Track along a long diagram | sequence, time | a timeline; a pipeline; a journey |
+| Pull back past the board edge to the wall | the whole lesson as one picture | a summary; a scale jump |
+
+Motion blur: when the camera moves more than ~14 px per frame, render and average sub-frames (≤ 4 px apart). No cuts on the board; if a cut is needed, it is a whip.
+
+## 7. Sound palette
+
+- **Every stroke sounds**: band-passed felt-on-gloss noise (a hiss band ~2–7.5 kHz + body ~0.5–1.5 kHz) enveloped by the stroke's own speed curve, a tiny nib tick at the start, stick-slip grains, and on some long strokes the **dry-erase squeak** (a 1.5–2.6 kHz sine with 7–13 Hz vibrato). Each colour sounds slightly different. Pan = the stroke's screen x; closer camera = louder.
+- **Props**: magnet on steel = click + metal modes + a low board thump; eraser = felt rub modulated by its zig-zag; cap off/on; marker tray bounce.
+- **Room**: low room tone; a single diegetic ticker (a wall clock, a fridge hum, a projector fan) can own a silence.
+- **Music** options: a solo piano figure; a small jazz trio with brushes; plucked strings and kalimba; a synth arpeggio for tech topics; clockwork minimalism (marimba, pizzicato, woodblock, glockenspiel). Mickey-mouse details: a rising whistle for growth, pings for signals, a harp run for a fall.
+- **Techniques to pick from**: adding one instrument per step of a mechanism; a key change when the frame of reference changes; a full stop into silence before a surprise; the previous cue reversed and squeezed for a rewind; two copies of one figure at two tempi (phasing) for anything that diverges, snapping into unison when resolved.
+- **Mix**: voice on top (compressed, light room), music well under voice and ducked further under speech, foley ~11 dB under voice; −14 LUFS.
+
+## 8. Native moves
+
+A menu: use the ones your story needs.
+
+- **Writing in stroke order.** The reveal is the explanation: a formula term by term as it is spoken. *Fits content like:* compound interest; the Drake equation; a recipe's ratios.
+- **The pen leads the camera.** Transitions are drawn lines the camera rides. *Fits content like:* a nerve signal; a supply chain; the water cycle.
+- **Magnets.** The only things allowed to move on a board: give the hero to a magnet; slide, lift, drop, sink it. *Fits content like:* a delivery truck on a route; a cell in a bloodstream; a player on a pitch.
+- **The eraser rewinds.** Wiping a trail backwards reads as undoing time. *Fits content like:* an undo in software; reversing a chemical reaction; "what if we hadn't…".
+- **Two pens at once.** A live duet comparing two quantities. *Fits content like:* two savings plans; two runners; a population vs its food supply.
+- **Ghosts of the old lesson.** A faint previous drawing becomes relevant. *Fits content like:* a theory replaced; last year's forecast; a first draft.
+- **The full-board view.** Every region seen at once as one picture. *Fits content like:* a system diagram; a history; a map of a field.
+
+## 9. Pitfalls of the medium
+
+- **One pen, too many jobs** drifts later and later → give each drawing a deadline window and let overlapping jobs go to another pen.
+- **Minimum stroke duration × many dashes** makes a dashed line take seconds → dashes need their own floor.
+- **A pooled-ink dot bigger than the stroke start** leaves halos on every letter → keep it inside.
+- **Punctuation vanishes** (a font period is a 1 px stroke) → render sub-width strokes as dots.
+- **Labels half-cut by a push-in** look sloppy.
+- **Motion blur with few sub-frames** strobes text.
+- **Eraser paths** crossing labels you want to keep.
+- **Voice and phoneme set mismatch** (a British voice with US phonemes) mispronounces → match the language code to the voice; ASR-check.
+
+## 10. Engine
+
+`demo/engine/wb.js`: hand-drawn shapes (`line`, `curve`, `poly`, `arc`, `circle`, `rect`, `arrow`, `dashed`, `hatch`), `text()` in writing order from a single-line font (`loadFont`), `Stroke`, floating `Pen`s, `Timeline.draw(pen, shapes, t, {by})` (solves hand speed to a deadline), `Timeline.erase`, `Timeline.cue`, keyed `Camera`, `Board` (ink multiply, dry texture, erasers, sheen, props), prop drawers. API table and a minimal example that draws something new: [DEMO.md](https://github.com/lemomo-ai/lemo-opuscar/blob/413a6bd6/styles/whiteboard/DEMO.md#engine-reference).
+
+## 11. Variation space
+
+You decide the topic's object, the board layout, the colours within the logic, the voice, the music family, the camera route, the opening, the ending and the length.
+
+All far from our demo:
+
+- Structures: **a proof** (one claim at the top, the board fills downward step by step, each step boxed when proven); **a debate** (two pens, two halves of the board, each drawing its side until the drawings meet in the middle); **a timeline** (one long horizontal line ridden left to right, with events hanging off it).
+- Openings: **a question mark** drawn huge in the centre, then shrunk to become a dot in the first diagram; **an erased board** where the ghost of a wrong answer is still visible; **a magnet dropping** onto an empty board with a clack.
+- Endings: **the answer circled** twice and the pen capped; **the board wiped** except for one line that survives; **a push into the smallest symbol** on the board, which becomes the title.
+
+---
+
+How our demo was made (story, shots, score, end card, build): [DEMO.md](https://github.com/lemomo-ai/lemo-opuscar/blob/413a6bd6/styles/whiteboard/DEMO.md). Read it after your treatment exists.

package/src/skills-lib/wizz-video-styles/references/film-styles/woodcut.md

@@ -0,0 +1,122 @@
+<!-- Vendored from lemo-opuscar (https://github.com/lemomo-ai/lemo-opuscar/tree/413a6bd6/styles/woodcut), MIT, (c) 2026 LemoLab; see ../../LICENSE-lemo-opuscar.txt. Paths under demo/ and core/ name that repo's engine, which is not shipped here: build the look in HyperFrames (../film-styles.md). -->
+
+# Woodcut Print — Style Prompt
+
+> A relief print that carves itself: every frame is a black wood block, and light only exists where a knife has cut it away. One colour at most, and only for the thing that burns.
+> References (grammar only): Frans Masereel *Passionate Journey* (1919) and Lynd Ward *Gods' Man* (1929), wordless woodcut novels told as a sequence of self-contained plates; Käthe Kollwitz's woodcuts, where emotion lives in the direction of the gouge; Gustave Doré's engraving, where line spacing and direction build light and volume. Never copy their plates, figures, borders or titles.
+
+## 1. Essence, and what it is not
+
+Each shot is **one printed plate**: black ink on laid paper, framed by a paper margin. It follows three rules of real relief printing:
+
+1. **Black is the wood, white is what the knife removed.** Light is *carved*: a bright area is many wide cuts, a dark area untouched wood.
+2. **Pictures appear by being carved.** Nothing fades in: cuts grow stroke by stroke along the form, coarse gouges first, fine lines after.
+3. **The block is a mirror.** Letters read backwards until the paper is pulled; that reversal is the style's own transition.
+
+Not copperplate engraving (no swelling burin lines on white, no crosshatch built up from white ground), not linocut poster art (no flat colour areas), not a black-and-white photo run through a threshold filter (the cuts must follow the form).
+
+## 2. Materials & rendering
+
+- **Print frame**: the printed image area sits inside a paper margin; the wider bottom margin holds captions. The image edge is the block edge: ragged ink, never a clean rectangle.
+- **Knife classes** (widths in 1080p pixels at 1× camera):
+
+| Tool | Width | Use |
+|---|---|---|
+| Knife `k` | 1.2–2 | contours, the white outline that separates a black figure from a black ground |
+| V-gouge `v` | 2–8 | hatching, hair, beard, fine light |
+| U-gouge `u` | 10–22 | rays, sky sweeps, the first rough-out |
+| Stab `stab` | r 3–8 | snow, sparks, flecks of loam, wood chips |
+
+- **Hatching (Doré grammar in wood)**: line **direction follows form** (a round object is wrapped in arcs, slopes follow the fall line, fire and light radiate, cloth follows its folds). **Width follows tone**: bright = wide cuts almost merging into white, mid-tone = thin cuts, dark = no cuts. Far = dense and fine, near = sparse and coarse. Every line is a separate cut (30–160 px, blunt entry, tapered exit, chipped edge), never a continuous machine line.
+- **Figures**: black silhouette + white knife halo + grazing-light hatching on the lit edge only (light z ≈ 0.2, so flat areas stay black). **Skin carved white, features left black** (the wordless-novel rule).
+- **Close-ups (hands, objects)**: sculpt a small height field (capsules, blobs, planks, creases), light it and run it through `woodcutFilter` (§10), so cuts follow the isophotes like an engraver's.
+- **Printing**: the mask (white = cut) goes through a WebGL2 compositor: knife burr on edges, ±6 % ink unevenness, wood-grain streaks, specks where ink didn't take, a mottled colour plate with a small fixed misregistration. Block mode: glossy inked wood with grain sheen, pale wood in the grooves.
+
+## 3. Colour logic
+
+- Two values carry everything: near-black ink and warm laid-paper white. The raw wood colour appears only in shots that show the block itself.
+- **At most one colour plate**, printed only where white has been carved, so it glows out of the cuts and never sits on the black. A colour plate over ink is nearly invisible, so plan it on carved white.
+- The colour is reserved for the one thing that matters (a flame, molten metal, a heart, a signal lamp). It can spread at a peak and shrink to a single highlight afterwards; it is never decoration.
+- Examples of a plate: a burnt copper-orange for heat; a cold Prussian blue for water or night; a deep oxblood for a wound or a seal. Choose it from the topic.
+
+## 4. Type & subtitles
+
+- **Captions are letterpress in the paper margin**, below the plate, like a plate caption in a woodcut novel. They never cover the image. A letterpress old-style face (IM Fell English, OFL) around 40–44 px, in ink, pushed through the same print shader. The ink comes up in 0.1 s with no slide and fades over 0.15 s. Hold ≥ max(1.8 s, speech + 0.6 s).
+- **Titles are carved, not typed**: cut into the block (IM Fell English SC), mirrored if the block is shown before the print is pulled.
+- Any closing text is a fresh print: letterpress in the margin or carved out of a black panel.
+
+## 5. Motion quality
+
+- **Characters on twos (12 fps)**; camera, particles, fire and light on ones (24 fps). Hatching lives in each body part's local space, so cuts move with the limb and don't boil; only fire and liquids re-cut every 2 frames, as deliberate boil.
+- **Anticipation / action / follow-through** on every key action: a few frames back → a 2-frame strike → settle + a short shake.
+- **Carve reveal**: each stroke has its own start time and speed (0.08–0.35 s). Reveal keys: `light` (bright areas first, coarse to fine), `radial` (from a point: rays, a pour), `down`, or any function.
+- **Hard cut = a new impression**: two frames of misregistration (a few pixels, then back).
+- **Paper transition** (the one transition grammar): brayer rolls ink (a wet highlight sweeps) → paper lays down → baren spirals, the image soaks through → the sheet peels on a cylinder toward camera, heavy then fast, its back showing the mirrored show-through.
+- What never moves: the paper margin.
+
+## 6. Camera grammar
+
+The camera moves over the paper; the margin stays fixed. The knife tip, or the brightest cut, is the focus.
+
+| Move | What it expresses | Can serve |
+|---|---|---|
+| Track with the knife tip | Making; the line is the story | a first mark; a route drawn on a map; a signature |
+| Continuous pull-back as cuts spread | A line becomes a world; scale | a city from one street; a family tree; a reach of sound or news |
+| Locked plate | A page of a wordless novel; reading time | a decision; a portrait; the aftermath |
+| Slow macro push on a sculpted close-up | Patience, touch, labour | hands at work; a tool; a letter being read |
+| Snap zoom and hold | Shock; the detail that breaks | a crack; a wrong number; a face turning |
+| Frame in a frame (door, window, arch) | Distance, exclusion, waiting | a crowd outside; a sickroom; a border |
+| Hard cuts on the beat, each a new impression | Accumulation, a series of prints | offerings; days passing; a list of names |
+| Crane up from a detail to the whole | Consequence | a flood reaching a village; a light reaching faces |
+| Rack between two plates via the peel | One state printed over another | before/after; a promise kept; generations |
+
+Opening and ending come from the topic. Framing: black masses on carved white or white on uncut black, never grey on grey; text only in the margin. Transitions: hard cut (new impression) or the peel; never a dissolve.
+
+## 7. Sound palette
+
+- **Instruments**: low strings (contrabass, cellos; spiccato, pizzicato), wood and skin (log drum, woodblock, frame drum), gran cassa, timpani, one tam-tam, synthesised struck metal (modal: 3–5 inharmonic partials + hammer transient); a bowed saw or hurdy-gurdy drone for a folk colour.
+- **Options**: withhold the timbre of the story's object until it appears; a metric modulation instead of a tempo jump; a modal shift inside a long decay; one drone under a locked plate.
+- **Foley follows the material**, all synthesisable: knife into wood (transient + band-passed fibre tearing tied to knife speed), chips, brayer tack, paper air, baren rasp, the wet peel; metals by size (large = low, small = high and pure); resonant objects as modal models plus echoes for distance.
+- **Silence is a tool**: near-silence with one faint ambience, or true digital silence before the loudest moment; the first sound after it is chosen.
+- **J/L cuts** carry sound across plates and peels.
+- **Mix**: music ducks ~8 dB under voice and a little under key foley; **foley ducks too** under voice. Pan hard transients off centre. −14 LUFS.
+- **Voice**: few lines, low and plain, like captions spoken; the plates tell the rest.
+
+## 8. Native moves
+
+A menu: use the ones your story needs.
+
+- **Light is carved.** A burst of radial cuts from a point. *Fits content like:* a power grid switched on; a scientific insight; a lighthouse restored.
+- **Carving = time.** Patient work on screen, cut by cut. *Fits content like:* a year of training; a building rising; a craft apprenticeship.
+- **Mirrored block → true print.** A backwards word reads true when the sheet is pulled. *Fits content like:* a vote result; a name cleared; a misunderstanding put right.
+- **Stab cuts as texture.** White dots can freeze mid-air or be inked back in until the black is clean. *Fits content like:* stars going out over a city; rain stopping; a disease receding on a map.
+- **The one colour plate spreads and withdraws.** *Fits content like:* a blood donation; a sunrise over a harvest; a single lit window in a blackout.
+- **Filter a sculpt or a frame** into form-following cuts. *Fits content like:* a portrait of a real person drawn from a photo; a machine part; an archive image re-cut.
+- **Wordless-novel sequencing.** Self-contained plates, few or no lines; a gap can be silent. *Fits content like:* a migration; a strike; a life in seven plates.
+
+## 9. Pitfalls of the medium
+
+- **White marks on white areas are invisible** → stab cuts need dark masses behind them.
+- **Hatching every surface looks like fur or rain** → grazing light; 3–6 cuts on the lit edge only.
+- **Black faces with white cuts don't read small** → skin white, features black, a black keep-line around white parts.
+- **Hand-drawn close-up props look like mittens and blobs** → height field + `woodcutFilter`.
+- **Short hatch segments with a tonal wobble turn into zig-zag chevrons** → long cuts (14–50 × spacing), one broad highlight band, a thin rim light, a stronger halo.
+- **Steam or smoke on top of the subject reads as flames** → draw it behind, so only wisps escape.
+- **Lazily cached strokes shared between shots** make frames depend on the render worker → every cache builds itself on first use.
+- **Fine hatching + ink noise + grain inflate the file** → a higher CRF with `-tune grain`; check a 1:1 crop. `woodcutFilter` NaN in flat areas → clamp before `sqrt`.
+
+## 10. Engine
+
+`demo/engine/index.js` (imports only `/core/lib.js`) carves and prints **any path or shape**, on two canvases: a **mask** (black = uncut, white = cut) and an optional **colour plate**. Main functions: `shape` (carved solid with halo and form-following hatching), `cutAlong` (a path as hand-cut strokes), `hatch` (streamline hatching of a region), `flecks` (stab cuts), `rays` (carved light), `drawStrokes`, `plate`, `woodcutFilter` (image or frame → cuts), `makePrinter(W,H).render` (print / block compositor). Reusable demo pieces: `demo/trans.js` (paper peel), `demo/hands.js` (height-field sculpts). Option table, a minimal example and the filter recipe: [DEMO.md](https://github.com/lemomo-ai/lemo-opuscar/blob/413a6bd6/styles/woodcut/DEMO.md#engine-reference).
+
+## 11. Variation space
+
+You decide the story, characters (or none), plates, opening, ending, camera path, pacing and what the one colour is for. All far from our demo:
+
+- Structures: **a book of hours** (seven locked plates, one per hour, no moves inside a plate); **the same block recut** (carved deeper each scene, the image changing as wood goes); **two blocks printed in turn** (two places alternate impressions until one sheet carries both).
+- Openings: **the finished print on a wall** (then back into the block to see it cut); **white paper** (an inked block pressed onto it: the first image arrives whole); **wood grain** that becomes water or a field as the first cuts follow it.
+- Endings: **the block cleaned** (ink washed off, pale carved wood remains); **a stack of prints** (rising over many sheets of one plate); **an uncarved corner** (holding on black wood the knife never reached).
+
+---
+
+How our demo was made (story, shots, score, end card, build, engine reference): [DEMO.md](https://github.com/lemomo-ai/lemo-opuscar/blob/413a6bd6/styles/woodcut/DEMO.md). Read it after your treatment exists.