@prismer/runtime 2.2.55 → 2.2.64

package/built-in-skills/prismer-ascii-video/references/scenes.md

@@ -0,0 +1,1018 @@
+# Scene System & Creative Composition
+
+> **See also:** architecture.md · composition.md · effects.md · shaders.md
+
+## Scene Design Philosophy
+
+Scenes are storytelling units, not effect demos. Every scene needs:
+- A **concept** — what is happening visually? Not "plasma + rings" but "emergence from void" or "crystallization"
+- An **arc** — how does it change over its duration? Build, decay, transform, reveal?
+- A **role** — how does it serve the larger video narrative? Opening tension, peak energy, resolution?
+
+The design patterns below provide compositional techniques. The scene examples show them in practice at increasing complexity. The protocol section covers the technical contract.
+
+Good scene design starts with the concept, then selects effects and parameters that serve it. The design patterns section shows *how* to compose layers intentionally. The examples section shows complete working scenes at every complexity level. The protocol section covers the technical contract that all scenes must follow.
+
+---
+
+## Scene Design Patterns
+
+Higher-order patterns for composing scenes that feel intentional rather than random. These patterns use the existing building blocks (value fields, blend modes, shaders, feedback) but organize them with compositional intent.
+
+## Layer Hierarchy
+
+Every scene should have clear visual layers with distinct roles:
+
+| Layer | Grid | Brightness | Purpose |
+|-------|------|-----------|---------|
+| **Background** | xs or sm (dense) | 0.1–0.25 | Atmosphere, texture. Never competes with content. |
+| **Content** | md (balanced) | 0.4–0.8 | The main visual idea. Carries the scene's concept. |
+| **Accent** | lg or sm (sparse) | 0.5–1.0 (sparse coverage) | Highlights, punctuation, sparse bright points. |
+
+The background sets mood. The content layer is what the scene *is about*. The accent adds visual interest without overwhelming.
+
+```python
+def fx_example(r, f, t, S):
+    local = t
+    progress = min(local / 5.0, 1.0)
+
+    g_bg = r.get_grid("sm")
+    g_main = r.get_grid("md")
+    g_accent = r.get_grid("lg")
+
+    # --- Background: dim atmosphere ---
+    bg_val = vf_smooth_noise(g_bg, f, t * 0.3, S, octaves=2, bri=0.15)
+    # ... render bg to canvas
+
+    # --- Content: the main visual idea ---
+    content_val = vf_spiral(g_main, f, t, S, n_arms=n_arms, tightness=tightness)
+    # ... render content on top of canvas
+
+    # --- Accent: sparse highlights ---
+    accent_val = vf_noise_static(g_accent, f, t, S, density=0.05)
+    # ... render accent on top
+
+    return canvas
+```
+
+## Directional Parameter Arcs
+
+Parameters should *go somewhere* over the scene's duration — not oscillate aimlessly with `sin(t * N)`.
+
+**Bad:** `twist = 3.0 + 2.0 * math.sin(t * 0.6)` — wobbles back and forth, feels aimless.
+
+**Good:** `twist = 2.0 + progress * 5.0` — starts gentle, ends intense. The scene *builds*.
+
+Use `progress = min(local / duration, 1.0)` (0→1 over the scene) to drive directional change:
+
+| Pattern | Formula | Feel |
+|---------|---------|------|
+| Linear ramp | `progress * range` | Steady buildup |
+| Ease-out | `1 - (1 - progress) ** 2` | Fast start, gentle finish |
+| Ease-in | `progress ** 2` | Slow start, accelerating |
+| Step reveal | `np.clip((progress - 0.5) / 0.25, 0, 1)` | Nothing until 50%, then fades in |
+| Build + plateau | `min(1.0, progress * 1.5)` | Reaches full at 67%, holds |
+
+Oscillation is fine for *secondary* parameters (saturation shimmer, hue drift). But the *defining* parameter of the scene should have a direction.
+
+### Examples of Directional Arcs
+
+| Scene concept | Parameter | Arc |
+|--------------|-----------|-----|
+| Emergence | Ring radius | 0 → max (ease-out) |
+| Shatter | Voronoi cell count | 8 → 38 (linear) |
+| Descent | Tunnel speed | 2.0 → 10.0 (linear) |
+| Mandala | Shape complexity | ring → +polygon → +star → +rosette (step reveals) |
+| Crescendo | Layer count | 1 → 7 (staggered entry) |
+| Entropy | Geometry visibility | 1.0 → 0.0 (consumed) |
+
+## Scene Concepts
+
+Each scene should be built around a *visual idea*, not an effect name.
+
+**Bad:** "fx_plasma_cascade" — named after the effect. No concept.
+**Good:** "fx_emergence" — a point of light expands into a field. The name tells you *what happens*.
+
+Good scene concepts have:
+1. A **visual metaphor** (emergence, descent, collision, entropy)
+2. A **directional arc** (things change from A to B, not oscillate)
+3. **Motivated layer choices** (each layer serves the concept)
+4. **Motivated feedback** (transform direction matches the metaphor)
+
+| Concept | Metaphor | Feedback transform | Why |
+|---------|----------|-------------------|-----|
+| Emergence | Birth, expansion | zoom-out | Past frames expand outward |
+| Descent | Falling, acceleration | zoom-in | Past frames rush toward center |
+| Inferno | Rising fire | shift-up | Past frames rise with the flames |
+| Entropy | Decay, dissolution | none | Clean, no persistence — things disappear |
+| Crescendo | Accumulation | zoom + hue_shift | Everything compounds and shifts |
+
+## Compositional Techniques
+
+### Counter-Rotating Dual Systems
+
+Two instances of the same effect rotating in opposite directions create visual interference:
+
+```python
+# Primary spiral (clockwise)
+s1_val = vf_spiral(g_main, f, t * 1.5, S, n_arms=n_arms_1, tightness=tightness_1)
+
+# Counter-rotating spiral (counter-clockwise via negative time)
+s2_val = vf_spiral(g_accent, f, -t * 1.2, S, n_arms=n_arms_2, tightness=tightness_2)
+
+# Screen blend creates bright interference at crossing points
+canvas = blend_canvas(canvas_with_s1, c2, "screen", 0.7)
+```
+
+Works with spirals, vortexes, rings. The counter-rotation creates constantly shifting interference patterns.
+
+### Wave Collision
+
+Two wave fronts converging from opposite sides, meeting at a collision point:
+
+```python
+collision_phase = abs(progress - 0.5) * 2  # 1→0→1 (0 at collision)
+
+# Wave A approaches from left
+offset_a = (1 - progress) * g.cols * 0.4
+wave_a = np.sin((g.cc + offset_a) * 0.08 + t * 2) * 0.5 + 0.5
+
+# Wave B approaches from right
+offset_b = -(1 - progress) * g.cols * 0.4
+wave_b = np.sin((g.cc + offset_b) * 0.08 - t * 2) * 0.5 + 0.5
+
+# Interference peaks at collision
+combined = wave_a * 0.5 + wave_b * 0.5 + np.abs(wave_a - wave_b) * (1 - collision_phase) * 0.5
+```
+
+### Progressive Fragmentation
+
+Voronoi with cell count increasing over time — visual shattering:
+
+```python
+n_pts = int(8 + progress * 30)  # 8 cells → 38 cells
+# Pre-generate enough points, slice to n_pts
+px = base_x[:n_pts] + np.sin(t * 0.3 + np.arange(n_pts) * 0.7) * (3 + progress * 3)
+```
+
+The edge glow width can also increase with progress to emphasize the cracks.
+
+### Entropy / Consumption
+
+A clean geometric pattern being overtaken by an organic process:
+
+```python
+# Geometry fades out
+geo_val = clean_pattern * max(0.05, 1.0 - progress * 0.9)
+
+# Organic process grows in
+rd_val = vf_reaction_diffusion(g, f, t, S) * min(1.0, progress * 1.5)
+
+# Render geometry first, organic on top — organic consumes geometry
+```
+
+### Staggered Layer Entry (Crescendo)
+
+Layers enter one at a time, building to overwhelming density:
+
+```python
+def layer_strength(enter_t, ramp=1.5):
+    """0.0 until enter_t, ramps to 1.0 over ramp seconds."""
+    return max(0.0, min(1.0, (local - enter_t) / ramp))
+
+# Layer 1: always present
+s1 = layer_strength(0.0)
+# Layer 2: enters at 2s
+s2 = layer_strength(2.0)
+# Layer 3: enters at 4s
+s3 = layer_strength(4.0)
+# ... etc
+
+# Each layer uses a different effect, grid, palette, and blend mode
+# Screen blend between layers so they accumulate light
+```
+
+For a 15-second crescendo, 7 layers entering every 2 seconds works well. Use different blend modes (screen for most, add for energy, colordodge for the final wash).
+
+## Scene Ordering
+
+For a multi-scene reel or video:
+- **Vary mood between adjacent scenes** — don't put two calm scenes next to each other
+- **Randomize order** rather than grouping by type — prevents "effect demo" feel
+- **End on the strongest scene** — crescendo or something with a clear payoff
+- **Open with energy** — grab attention in the first 2 seconds
+
+---
+
+## Scene Protocol
+
+Scenes are the top-level creative unit. Each scene is a time-bounded segment with its own effect function, shader chain, feedback configuration, and tone-mapping gamma.
+
+### Scene Protocol (v2)
+
+### Function Signature
+
+```python
+def fx_scene_name(r, f, t, S) -> canvas:
+    """
+    Args:
+        r: Renderer instance — access multiple grids via r.get_grid("sm")
+        f: dict of audio/video features, all values normalized to [0, 1]
+        t: time in seconds — local to scene (0.0 at scene start)
+        S: dict for persistent state (particles, rain columns, etc.)
+
+    Returns:
+        canvas: numpy uint8 array, shape (VH, VW, 3) — full pixel frame
+    """
+```
+
+**Local time convention:** Scene functions receive `t` starting at 0.0 for the first frame of the scene, regardless of where the scene appears in the timeline. The render loop subtracts the scene's start time before calling the function:
+
+```python
+# In render_clip:
+t_local = fi / FPS - scene_start
+canvas = fx_fn(r, feat, t_local, S)
+```
+
+This makes scenes reorderable without modifying their code. Compute scene progress as:
+
+```python
+progress = min(t / scene_duration, 1.0)  # 0→1 over the scene
+```
+
+This replaces the v1 protocol where scenes returned `(chars, colors)` tuples. The v2 protocol gives scenes full control over multi-grid rendering and pixel-level composition internally.
+
+### The Renderer Class
+
+```python
+class Renderer:
+    def __init__(self):
+        self.grids = {}   # lazy-initialized grid cache
+        self.g = None      # "active" grid (for backward compat)
+        self.S = {}        # persistent state dict
+
+    def get_grid(self, key):
+        """Get or create a GridLayer by size key."""
+        if key not in self.grids:
+            sizes = {"xs": 8, "sm": 10, "md": 16, "lg": 20, "xl": 24, "xxl": 40}
+            self.grids[key] = GridLayer(FONT_PATH, sizes[key])
+        return self.grids[key]
+
+    def set_grid(self, key):
+        """Set active grid (legacy). Prefer get_grid() for multi-grid scenes."""
+        self.g = self.get_grid(key)
+        return self.g
+```
+
+**Key difference from v1**: scenes call `r.get_grid("sm")`, `r.get_grid("lg")`, etc. to access multiple grids. Each grid is lazy-initialized and cached. The `set_grid()` method still works for single-grid scenes.
+
+### Minimal Scene (Single Grid)
+
+```python
+def fx_simple_rings(r, f, t, S):
+    """Single-grid scene: rings with distance-mapped hue."""
+    canvas = _render_vf(r, "md",
+        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=8, spacing_base=3),
+        hf_distance(0.3, 0.02), PAL_STARS, f, t, S, sat=0.85)
+    return canvas
+```
+
+### Standard Scene (Two Grids + Blend)
+
+```python
+def fx_tunnel_ripple(r, f, t, S):
+    """Two-grid scene: tunnel depth exclusion-blended with ripple."""
+    canvas_a = _render_vf(r, "md",
+        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=5.0, complexity=10) * 1.3,
+        hf_distance(0.55, 0.02), PAL_GREEK, f, t, S, sat=0.7)
+
+    canvas_b = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_ripple(g, f, t, S,
+            sources=[(0.3,0.3), (0.7,0.7), (0.5,0.2)], freq=0.5, damping=0.012) * 1.4,
+        hf_angle(0.1), PAL_STARS, f, t, S, sat=0.8)
+
+    return blend_canvas(canvas_a, canvas_b, "exclusion", 0.8)
+```
+
+### Complex Scene (Three Grids + Conditional + Custom Rendering)
+
+```python
+def fx_rings_explosion(r, f, t, S):
+    """Three-grid scene with particles and conditional kaleidoscope."""
+    # Layer 1: rings
+    canvas_a = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=10, spacing_base=2) * 1.4,
+        lambda g, f, t, S: (g.angle / (2*np.pi) + t * 0.15) % 1.0,
+        PAL_STARS, f, t, S, sat=0.9)
+
+    # Layer 2: vortex on different grid
+    canvas_b = _render_vf(r, "md",
+        lambda g, f, t, S: vf_vortex(g, f, t, S, twist=6.0) * 1.2,
+        hf_time_cycle(0.15), PAL_BLOCKS, f, t, S, sat=0.8)
+
+    result = blend_canvas(canvas_b, canvas_a, "screen", 0.7)
+
+    # Layer 3: particles (custom rendering, not _render_vf)
+    g = r.get_grid("sm")
+    if "px" not in S:
+        S["px"], S["py"], S["vx"], S["vy"], S["life"], S["pch"] = (
+            [], [], [], [], [], [])
+    if f.get("beat", 0) > 0.5:
+        chars = list("\u2605\u2736\u2733\u2738\u2726\u2728*+")
+        for _ in range(int(80 + f.get("rms", 0.3) * 120)):
+            ang = random.uniform(0, 2 * math.pi)
+            sp = random.uniform(1, 10) * (0.5 + f.get("sub_r", 0.3) * 2)
+            S["px"].append(float(g.cols // 2))
+            S["py"].append(float(g.rows // 2))
+            S["vx"].append(math.cos(ang) * sp * 2.5)
+            S["vy"].append(math.sin(ang) * sp)
+            S["life"].append(1.0)
+            S["pch"].append(random.choice(chars))
+
+    # Update + draw particles
+    ch_p = np.full((g.rows, g.cols), " ", dtype="U1")
+    co_p = np.zeros((g.rows, g.cols, 3), dtype=np.uint8)
+    i = 0
+    while i < len(S["px"]):
+        S["px"][i] += S["vx"][i]; S["py"][i] += S["vy"][i]
+        S["vy"][i] += 0.03; S["life"][i] -= 0.02
+        if S["life"][i] <= 0:
+            for k in ("px","py","vx","vy","life","pch"): S[k].pop(i)
+        else:
+            pr, pc = int(S["py"][i]), int(S["px"][i])
+            if 0 <= pr < g.rows and 0 <= pc < g.cols:
+                ch_p[pr, pc] = S["pch"][i]
+                co_p[pr, pc] = hsv2rgb_scalar(
+                    0.08 + (1-S["life"][i])*0.15, 0.95, S["life"][i])
+            i += 1
+
+    canvas_p = g.render(ch_p, co_p)
+    result = blend_canvas(result, canvas_p, "add", 0.8)
+
+    # Conditional kaleidoscope on strong beats
+    if f.get("bdecay", 0) > 0.4:
+        result = sh_kaleidoscope(result.copy(), folds=6)
+
+    return result
+```
+
+### Scene with Custom Character Rendering (Matrix Rain)
+
+When you need per-cell control beyond what `_render_vf()` provides:
+
+```python
+def fx_matrix_layered(r, f, t, S):
+    """Matrix rain blended with tunnel — two grids, screen blend."""
+    # Layer 1: Matrix rain (custom per-column rendering)
+    g = r.get_grid("md")
+    rows, cols = g.rows, g.cols
+    pal = PAL_KATA
+
+    if "ry" not in S or len(S["ry"]) != cols:
+        S["ry"] = np.random.uniform(-rows, rows, cols).astype(np.float32)
+        S["rsp"] = np.random.uniform(0.3, 2.0, cols).astype(np.float32)
+        S["rln"] = np.random.randint(8, 35, cols)
+        S["rch"] = np.random.randint(1, len(pal), (rows, cols))
+
+    speed = 0.6 + f.get("bass", 0.3) * 3
+    if f.get("beat", 0) > 0.5: speed *= 2.5
+    S["ry"] += S["rsp"] * speed
+
+    ch = np.full((rows, cols), " ", dtype="U1")
+    co = np.zeros((rows, cols, 3), dtype=np.uint8)
+    heads = S["ry"].astype(int)
+    for c in range(cols):
+        head = heads[c]
+        for i in range(S["rln"][c]):
+            row = head - i
+            if 0 <= row < rows:
+                fade = 1.0 - i / S["rln"][c]
+                ch[row, c] = pal[S["rch"][row, c] % len(pal)]
+                if i == 0:
+                    v = int(min(255, fade * 300))
+                    co[row, c] = (int(v*0.9), v, int(v*0.9))
+                else:
+                    v = int(fade * 240)
+                    co[row, c] = (int(v*0.1), v, int(v*0.4))
+    canvas_a = g.render(ch, co)
+
+    # Layer 2: Tunnel on sm grid for depth texture
+    canvas_b = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=5.0, complexity=10),
+        hf_distance(0.3, 0.02), PAL_BLOCKS, f, t, S, sat=0.6)
+
+    return blend_canvas(canvas_a, canvas_b, "screen", 0.5)
+```
+
+---
+
+## Scene Table
+
+The scene table defines the timeline: which scene plays when, with what configuration.
+
+### Structure
+
+```python
+SCENES = [
+    {
+        "start": 0.0,           # start time in seconds
+        "end": 3.96,            # end time in seconds
+        "name": "starfield",    # identifier (used for clip filenames)
+        "grid": "sm",           # default grid (for render_clip setup)
+        "fx": fx_starfield,     # scene function reference (must be module-level)
+        "gamma": 0.75,          # tonemap gamma override (default 0.75)
+        "shaders": [            # shader chain (applied after tonemap + feedback)
+            ("bloom", {"thr": 120}),
+            ("vignette", {"s": 0.2}),
+            ("grain", {"amt": 8}),
+        ],
+        "feedback": None,       # feedback buffer config (None = disabled)
+        # "feedback": {"decay": 0.8, "blend": "screen", "opacity": 0.3,
+        #              "transform": "zoom", "transform_amt": 0.02, "hue_shift": 0.02},
+    },
+    {
+        "start": 3.96,
+        "end": 6.58,
+        "name": "matrix_layered",
+        "grid": "md",
+        "fx": fx_matrix_layered,
+        "shaders": [
+            ("crt", {"strength": 0.05}),
+            ("scanlines", {"intensity": 0.12}),
+            ("color_grade", {"tint": (0.7, 1.2, 0.7)}),
+            ("bloom", {"thr": 100}),
+        ],
+        "feedback": {"decay": 0.5, "blend": "add", "opacity": 0.2},
+    },
+    # ... more scenes ...
+]
+```
+
+### Beat-Synced Scene Cutting
+
+Derive cut points from audio analysis:
+
+```python
+# Get beat timestamps
+beats = [fi / FPS for fi in range(N_FRAMES) if features["beat"][fi] > 0.5]
+
+# Group beats into phrase boundaries (every 4-8 beats)
+cuts = [0.0]
+for i in range(0, len(beats), 4):  # cut every 4 beats
+    cuts.append(beats[i])
+cuts.append(DURATION)
+
+# Or use the music's structure: silence gaps, energy changes
+energy = features["rms"]
+# Find timestamps where energy drops significantly -> natural break points
+```
+
+### `render_clip()` — The Render Loop
+
+This function renders one scene to a clip file:
+
+```python
+def render_clip(seg, features, clip_path):
+    r = Renderer()
+    r.set_grid(seg["grid"])
+    S = r.S
+    import hashlib
+    seed = int.from_bytes(hashlib.sha256(str(seg["id"]).encode()).digest()[:4], "big")
+    random.seed(seed)
+    np.random.seed(seed)
+
+    # Build shader chain from config
+    chain = ShaderChain()
+    for shader_name, kwargs in seg.get("shaders", []):
+        chain.add(shader_name, **kwargs)
+
+    # Setup feedback buffer
+    fb = None
+    fb_cfg = seg.get("feedback", None)
+    if fb_cfg:
+        fb = FeedbackBuffer()
+
+    fx_fn = seg["fx"]
+
+    # Open ffmpeg pipe
+    cmd = ["ffmpeg", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
+           "-s", f"{VW}x{VH}", "-r", str(FPS), "-i", "pipe:0",
+           "-c:v", "libx264", "-preset", "fast", "-crf", "20",
+           "-pix_fmt", "yuv420p", clip_path]
+    stderr_fh = open(clip_path.replace(".mp4", ".log"), "w")
+    pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE,
+                            stdout=subprocess.DEVNULL, stderr=stderr_fh)
+
+    for fi in range(seg["frame_start"], seg["frame_end"]):
+        t = (fi - seg["frame_start"]) / FPS
+        feat = {k: float(features[k][fi]) for k in features}
+
+        # 1. Scene renders canvas
+        canvas = fx_fn(r, feat, t, S)
+
+        # 2. Tonemap normalizes brightness
+        canvas = tonemap(canvas, gamma=seg.get("gamma", 0.75))
+
+        # 3. Feedback adds temporal recursion
+        if fb and fb_cfg:
+            canvas = fb.apply(canvas, **{k: fb_cfg[k] for k in fb_cfg})
+
+        # 4. Shader chain adds post-processing
+        canvas = chain.apply(canvas, f=feat, t=t)
+
+        pipe.stdin.write(canvas.tobytes())
+
+    pipe.stdin.close()
+    status = pipe.wait()
+    stderr_fh.close()
+    if status != 0:
+        raise RuntimeError(f"ffmpeg failed: {status}")
+```
+
+### Building Segments from Scene Table
+
+```python
+segments = []
+for i, scene in enumerate(SCENES):
+    segments.append({
+        "id": f"s{i:02d}_{scene['name']}",
+        "name": scene["name"],
+        "grid": scene["grid"],
+        "fx": scene["fx"],
+        "shaders": scene.get("shaders", []),
+        "feedback": scene.get("feedback", None),
+        "gamma": scene.get("gamma", 0.75),
+        "frame_start": int(scene["start"] * FPS),
+        "frame_end": int(scene["end"] * FPS),
+    })
+```
+
+### Parallel Rendering
+
+Scenes are independent units dispatched to a process pool:
+
+```python
+from concurrent.futures import ProcessPoolExecutor, as_completed
+
+with ProcessPoolExecutor(max_workers=N_WORKERS) as pool:
+    futures = {
+        pool.submit(render_clip, seg, features, clip_path): seg["id"]
+        for seg, clip_path in zip(segments, clip_paths)
+    }
+    for fut in as_completed(futures):
+        try:
+            fut.result()
+        except Exception as e:
+            log(f"ERROR {futures[fut]}: {e}")
+```
+
+**Pickling constraint**: `ProcessPoolExecutor` serializes arguments via pickle. Module-level functions can be pickled; lambdas and closures cannot. All `fx_*` scene functions MUST be defined at module level, not as closures or class methods.
+
+### Test-Frame Mode
+
+Render a single frame at a specific timestamp to verify visuals without a full render:
+
+```python
+if args.test_frame >= 0:
+    fi = min(int(args.test_frame * FPS), N_FRAMES - 1)
+    t = fi / FPS
+    feat = {k: float(features[k][fi]) for k in features}
+    scene = next(sc for sc in reversed(SCENES) if t >= sc["start"])
+    r = Renderer()
+    r.set_grid(scene["grid"])
+    canvas = scene["fx"](r, feat, t, r.S)
+    canvas = tonemap(canvas, gamma=scene.get("gamma", 0.75))
+    chain = ShaderChain()
+    for sn, kw in scene.get("shaders", []):
+        chain.add(sn, **kw)
+    canvas = chain.apply(canvas, f=feat, t=t)
+    Image.fromarray(canvas).save(f"test_{args.test_frame:.1f}s.png")
+    print(f"Mean brightness: {canvas.astype(float).mean():.1f}")
+```
+
+CLI: `python reel.py --test-frame 10.0`
+
+---
+
+## Scene Design Checklist
+
+For each scene:
+
+1. **Choose 2-3 grid sizes** — different scales create interference
+2. **Choose different value fields** per layer — don't use the same effect on every grid
+3. **Choose different hue fields** per layer — or at minimum different hue offsets
+4. **Choose different palettes** per layer — mixing PAL_RUNE with PAL_BLOCKS looks different from PAL_RUNE with PAL_DENSE
+5. **Choose a blend mode** that matches the energy — screen for bright, difference for psychedelic, exclusion for subtle
+6. **Add conditional effects** on beat — kaleidoscope, mirror, glitch
+7. **Configure feedback** for trailing/recursive looks — or None for clean cuts
+8. **Set gamma** if using destructive shaders (solarize, posterize)
+9. **Test with --test-frame** at the scene's midpoint before full render
+
+---
+
+## Scene Examples
+
+Copy-paste-ready scene functions at increasing complexity. Each is a complete, working v2 scene function that returns a pixel canvas. See the Scene Protocol section above for the scene protocol and `composition.md` for blend modes and tonemap.
+
+---
+
+### Minimal — Single Grid, Single Effect
+
+### Breathing Plasma
+
+One grid, one value field, one hue field. The simplest possible scene.
+
+```python
+def fx_breathing_plasma(r, f, t, S):
+    """Plasma field with time-cycling hue. Audio modulates brightness."""
+    canvas = _render_vf(r, "md",
+        lambda g, f, t, S: vf_plasma(g, f, t, S) * 1.3,
+        hf_time_cycle(0.08), PAL_DENSE, f, t, S, sat=0.8)
+    return canvas
+```
+
+### Reaction-Diffusion Coral
+
+Single grid, simulation-based field. Evolves organically over time.
+
+```python
+def fx_coral(r, f, t, S):
+    """Gray-Scott reaction-diffusion — coral branching pattern.
+    Slow-evolving, organic. Best for ambient/chill sections."""
+    canvas = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_reaction_diffusion(g, f, t, S,
+            feed=0.037, kill=0.060, steps_per_frame=6, init_mode="center"),
+        hf_distance(0.55, 0.015), PAL_DOTS, f, t, S, sat=0.7)
+    return canvas
+```
+
+### SDF Geometry
+
+Geometric shapes from SDFs. Clean, precise, graphic.
+
+```python
+def fx_sdf_rings(r, f, t, S):
+    """Concentric SDF rings with smooth pulsing."""
+    def val_fn(g, f, t, S):
+        d1 = sdf_ring(g, radius=0.15 + f.get("bass", 0.3) * 0.05, thickness=0.015)
+        d2 = sdf_ring(g, radius=0.25 + f.get("mid", 0.3) * 0.05, thickness=0.012)
+        d3 = sdf_ring(g, radius=0.35 + f.get("hi", 0.3) * 0.04, thickness=0.010)
+        combined = sdf_smooth_union(sdf_smooth_union(d1, d2, 0.05), d3, 0.05)
+        return sdf_glow(combined, falloff=0.08) * (0.5 + f.get("rms", 0.3) * 0.8)
+    canvas = _render_vf(r, "md", val_fn, hf_angle(0.0), PAL_STARS, f, t, S, sat=0.85)
+    return canvas
+```
+
+---
+
+### Standard — Two Grids + Blend
+
+### Tunnel Through Noise
+
+Two grids at different densities, screen blended. The fine noise texture shows through the coarser tunnel characters.
+
+```python
+def fx_tunnel_noise(r, f, t, S):
+    """Tunnel depth on md grid + fBM noise on sm grid, screen blended."""
+    canvas_a = _render_vf(r, "md",
+        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=4.0, complexity=8) * 1.2,
+        hf_distance(0.5, 0.02), PAL_BLOCKS, f, t, S, sat=0.7)
+
+    canvas_b = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_fbm(g, f, t, S, octaves=4, freq=0.05, speed=0.15) * 1.3,
+        hf_time_cycle(0.06), PAL_RUNE, f, t, S, sat=0.6)
+
+    return blend_canvas(canvas_a, canvas_b, "screen", 0.7)
+```
+
+### Voronoi Cells + Spiral Overlay
+
+Voronoi cell edges with a spiral arm pattern overlaid.
+
+```python
+def fx_voronoi_spiral(r, f, t, S):
+    """Voronoi edge detection on md + logarithmic spiral on lg."""
+    canvas_a = _render_vf(r, "md",
+        lambda g, f, t, S: vf_voronoi(g, f, t, S,
+            n_cells=15, mode="edge", edge_width=2.0, speed=0.4),
+        hf_angle(0.2), PAL_CIRCUIT, f, t, S, sat=0.75)
+
+    canvas_b = _render_vf(r, "lg",
+        lambda g, f, t, S: vf_spiral(g, f, t, S, n_arms=4, tightness=3.0) * 1.2,
+        hf_distance(0.1, 0.03), PAL_BLOCKS, f, t, S, sat=0.9)
+
+    return blend_canvas(canvas_a, canvas_b, "exclusion", 0.6)
+```
+
+### Domain-Warped fBM
+
+Two layers of the same fBM, one domain-warped, difference-blended for psychedelic organic texture.
+
+```python
+def fx_organic_warp(r, f, t, S):
+    """Clean fBM vs domain-warped fBM, difference blended."""
+    canvas_a = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_fbm(g, f, t, S, octaves=5, freq=0.04, speed=0.1),
+        hf_plasma(0.2), PAL_DENSE, f, t, S, sat=0.6)
+
+    canvas_b = _render_vf(r, "md",
+        lambda g, f, t, S: vf_domain_warp(g, f, t, S,
+            warp_strength=20.0, freq=0.05, speed=0.15),
+        hf_time_cycle(0.05), PAL_BRAILLE, f, t, S, sat=0.7)
+
+    return blend_canvas(canvas_a, canvas_b, "difference", 0.7)
+```
+
+---
+
+### Complex — Three Grids + Conditional + Feedback
+
+### Psychedelic Cathedral
+
+Three-grid composition with beat-triggered kaleidoscope and feedback zoom tunnel. The most visually complex pattern.
+
+```python
+def fx_cathedral(r, f, t, S):
+    """Three-layer cathedral: interference + rings + noise, kaleidoscope on beat,
+    feedback zoom tunnel."""
+    # Layer 1: interference pattern on sm grid
+    canvas_a = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_interference(g, f, t, S, n_waves=7) * 1.3,
+        hf_angle(0.0), PAL_MATH, f, t, S, sat=0.8)
+
+    # Layer 2: pulsing rings on md grid
+    canvas_b = _render_vf(r, "md",
+        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=10, spacing_base=3) * 1.4,
+        hf_distance(0.3, 0.02), PAL_STARS, f, t, S, sat=0.9)
+
+    # Layer 3: temporal noise on lg grid (slow morph)
+    canvas_c = _render_vf(r, "lg",
+        lambda g, f, t, S: vf_temporal_noise(g, f, t, S,
+            freq=0.04, t_freq=0.2, octaves=3),
+        hf_time_cycle(0.12), PAL_BLOCKS, f, t, S, sat=0.7)
+
+    # Blend: A screen B, then difference with C
+    result = blend_canvas(canvas_a, canvas_b, "screen", 0.8)
+    result = blend_canvas(result, canvas_c, "difference", 0.5)
+
+    # Beat-triggered kaleidoscope
+    if f.get("bdecay", 0) > 0.3:
+        folds = 6 if f.get("sub_r", 0.3) > 0.4 else 8
+        result = sh_kaleidoscope(result.copy(), folds=folds)
+
+    return result
+
+# Scene table entry with feedback:
+# {"start": 30.0, "end": 50.0, "name": "cathedral", "fx": fx_cathedral,
+#  "gamma": 0.65, "shaders": [("bloom", {"thr": 110}), ("chromatic", {"amt": 4}),
+#                              ("vignette", {"s": 0.2}), ("grain", {"amt": 8})],
+#  "feedback": {"decay": 0.75, "blend": "screen", "opacity": 0.35,
+#               "transform": "zoom", "transform_amt": 0.012, "hue_shift": 0.015}}
+```
+
+### Masked Reaction-Diffusion with Attractor Overlay
+
+Reaction-diffusion visible only through an animated iris mask, with a strange attractor density field underneath.
+
+```python
+def fx_masked_life(r, f, t, S):
+    """Attractor base + reaction-diffusion visible through iris mask + particles."""
+    g_sm = r.get_grid("sm")
+    g_md = r.get_grid("md")
+
+    # Layer 1: strange attractor density field (background)
+    canvas_bg = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_strange_attractor(g, f, t, S,
+            attractor="clifford", n_points=30000),
+        hf_time_cycle(0.04), PAL_DOTS, f, t, S, sat=0.5)
+
+    # Layer 2: reaction-diffusion (foreground, will be masked)
+    canvas_rd = _render_vf(r, "md",
+        lambda g, f, t, S: vf_reaction_diffusion(g, f, t, S,
+            feed=0.046, kill=0.063, steps_per_frame=4, init_mode="ring"),
+        hf_angle(0.15), PAL_HALFFILL, f, t, S, sat=0.85)
+
+    # Animated iris mask — opens over first 5 seconds of scene
+    scene_start = S.get("_scene_start", t)
+    if "_scene_start" not in S:
+        S["_scene_start"] = t
+    mask = mask_iris(g_md, t, scene_start, scene_start + 5.0,
+                     max_radius=0.6)
+    canvas_rd = apply_mask_canvas(canvas_rd, mask, bg_canvas=canvas_bg)
+
+    # Layer 3: flow-field particles following the R-D gradient
+    rd_field = vf_reaction_diffusion(g_sm, f, t, S,
+        feed=0.046, kill=0.063, steps_per_frame=0)  # read without stepping
+    ch_p, co_p = update_flow_particles(S, g_sm, f, rd_field,
+        n=300, speed=0.8, char_set=list("·•◦∘°"))
+    canvas_p = g_sm.render(ch_p, co_p)
+
+    result = blend_canvas(canvas_rd, canvas_p, "add", 0.7)
+    return result
+```
+
+### Morphing Field Sequence with Eased Keyframes
+
+Demonstrates temporal coherence: smooth morphing between effects with keyframed parameters.
+
+```python
+def fx_morphing_journey(r, f, t, S):
+    """Morphs through 4 value fields over 20 seconds with eased transitions.
+    Parameters (twist, arm count) also keyframed."""
+    # Keyframed twist parameter
+    twist = keyframe(t, [(0, 1.0), (5, 5.0), (10, 2.0), (15, 8.0), (20, 1.0)],
+                     ease_fn=ease_in_out_cubic, loop=True)
+
+    # Sequence of value fields with 2s crossfade
+    fields = [
+        lambda g, f, t, S: vf_plasma(g, f, t, S),
+        lambda g, f, t, S: vf_vortex(g, f, t, S, twist=twist),
+        lambda g, f, t, S: vf_fbm(g, f, t, S, octaves=5, freq=0.04),
+        lambda g, f, t, S: vf_domain_warp(g, f, t, S, warp_strength=15),
+    ]
+    durations = [5.0, 5.0, 5.0, 5.0]
+
+    val_fn = lambda g, f, t, S: vf_sequence(g, f, t, S, fields, durations,
+                                             crossfade=2.0)
+
+    # Render with slowly rotating hue
+    canvas = _render_vf(r, "md", val_fn, hf_time_cycle(0.06),
+                        PAL_DENSE, f, t, S, sat=0.8)
+
+    # Second layer: tiled version of same sequence at smaller grid
+    tiled_fn = lambda g, f, t, S: vf_sequence(
+        make_tgrid(g, *uv_tile(g, 3, 3, mirror=True)),
+        f, t, S, fields, durations, crossfade=2.0)
+    canvas_b = _render_vf(r, "sm", tiled_fn, hf_angle(0.1),
+                          PAL_RUNE, f, t, S, sat=0.6)
+
+    return blend_canvas(canvas, canvas_b, "screen", 0.5)
+```
+
+---
+
+### Specialized — Unique State Patterns
+
+### Game of Life with Ghost Trails
+
+Cellular automaton with analog fade trails. Beat injects random cells.
+
+```python
+def fx_life(r, f, t, S):
+    """Conway's Game of Life with fading ghost trails.
+    Beat events inject random live cells for disruption."""
+    canvas = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_game_of_life(g, f, t, S,
+            rule="life", steps_per_frame=1, fade=0.92, density=0.25),
+        hf_fixed(0.33), PAL_BLOCKS, f, t, S, sat=0.8)
+
+    # Overlay: coral automaton on lg grid for chunky texture
+    canvas_b = _render_vf(r, "lg",
+        lambda g, f, t, S: vf_game_of_life(g, f, t, S,
+            rule="coral", steps_per_frame=1, fade=0.85, density=0.15, seed=99),
+        hf_time_cycle(0.1), PAL_HATCH, f, t, S, sat=0.6)
+
+    return blend_canvas(canvas, canvas_b, "screen", 0.5)
+```
+
+### Boids Flock Over Voronoi
+
+Emergent swarm movement over a cellular background.
+
+```python
+def fx_boid_swarm(r, f, t, S):
+    """Flocking boids over animated voronoi cells."""
+    # Background: voronoi cells
+    canvas_bg = _render_vf(r, "md",
+        lambda g, f, t, S: vf_voronoi(g, f, t, S,
+            n_cells=20, mode="distance", speed=0.2),
+        hf_distance(0.4, 0.02), PAL_CIRCUIT, f, t, S, sat=0.5)
+
+    # Foreground: boids
+    g = r.get_grid("md")
+    ch_b, co_b = update_boids(S, g, f, n_boids=150, perception=6.0,
+                              max_speed=1.5, char_set=list("▸▹►▻→⟶"))
+    canvas_boids = g.render(ch_b, co_b)
+
+    # Trails for the boids
+    # (boid positions are stored in S["boid_x"], S["boid_y"])
+    S["px"] = list(S.get("boid_x", []))
+    S["py"] = list(S.get("boid_y", []))
+    ch_t, co_t = draw_particle_trails(S, g, max_trail=6, fade=0.6)
+    canvas_trails = g.render(ch_t, co_t)
+
+    result = blend_canvas(canvas_bg, canvas_trails, "add", 0.3)
+    result = blend_canvas(result, canvas_boids, "add", 0.9)
+    return result
+```
+
+### Fire Rising Through SDF Text Stencil
+
+Fire effect visible only through text letterforms.
+
+```python
+def fx_fire_text(r, f, t, S):
+    """Fire columns visible through text stencil. Text acts as window."""
+    g = r.get_grid("lg")
+
+    # Full-screen fire (will be masked)
+    canvas_fire = _render_vf(r, "sm",
+        lambda g, f, t, S: np.clip(
+            vf_fbm(g, f, t, S, octaves=4, freq=0.08, speed=0.8) *
+            (1.0 - g.rr / g.rows) *  # fade toward top
+            (0.6 + f.get("bass", 0.3) * 0.8), 0, 1),
+        hf_fixed(0.05), PAL_BLOCKS, f, t, S, sat=0.9)  # fire hue
+
+    # Background: dark domain warp
+    canvas_bg = _render_vf(r, "md",
+        lambda g, f, t, S: vf_domain_warp(g, f, t, S,
+            warp_strength=8, freq=0.03, speed=0.05) * 0.3,
+        hf_fixed(0.6), PAL_DENSE, f, t, S, sat=0.4)
+
+    # Text stencil mask
+    mask = mask_text(g, "FIRE", row_frac=0.45)
+    # Expand vertically for multi-row coverage
+    for offset in range(-2, 3):
+        shifted = mask_text(g, "FIRE", row_frac=0.45 + offset / g.rows)
+        mask = mask_union(mask, shifted)
+
+    canvas_masked = apply_mask_canvas(canvas_fire, mask, bg_canvas=canvas_bg)
+    return canvas_masked
+```
+
+### Portrait Mode: Vertical Rain + Quote
+
+Optimized for 9:16. Uses vertical space for long rain trails and stacked text.
+
+```python
+def fx_portrait_rain_quote(r, f, t, S):
+    """Portrait-optimized: matrix rain (long vertical trails) with stacked quote.
+    Designed for 1080x1920 (9:16)."""
+    g = r.get_grid("md")  # ~112x100 in portrait
+
+    # Matrix rain — long trails benefit from portrait's extra rows
+    ch, co, S = eff_matrix_rain(g, f, t, S,
+        hue=0.33, bri=0.6, pal=PAL_KATA, speed_base=0.4, speed_beat=2.5)
+    canvas_rain = g.render(ch, co)
+
+    # Tunnel depth underneath for texture
+    canvas_tunnel = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=3.0, complexity=6) * 0.8,
+        hf_fixed(0.33), PAL_BLOCKS, f, t, S, sat=0.5)
+
+    result = blend_canvas(canvas_tunnel, canvas_rain, "screen", 0.8)
+
+    # Quote text — portrait layout: short lines, many of them
+    g_text = r.get_grid("lg")  # ~90x80 in portrait
+    quote_lines = layout_text_portrait(
+        "The code is the art and the art is the code",
+        max_chars_per_line=20)
+    # Center vertically
+    block_start = (g_text.rows - len(quote_lines)) // 2
+    ch_t = np.full((g_text.rows, g_text.cols), " ", dtype="U1")
+    co_t = np.zeros((g_text.rows, g_text.cols, 3), dtype=np.uint8)
+    total_chars = sum(len(l) for l in quote_lines)
+    progress = min(1.0, (t - S.get("_scene_start", t)) / 3.0)
+    if "_scene_start" not in S: S["_scene_start"] = t
+    render_typewriter(ch_t, co_t, quote_lines, block_start, g_text.cols,
+                      progress, total_chars, (200, 255, 220), t)
+    canvas_text = g_text.render(ch_t, co_t)
+
+    result = blend_canvas(result, canvas_text, "add", 0.9)
+    return result
+```
+
+---
+
+### Scene Table Template
+
+Wire scenes into a complete video:
+
+```python
+SCENES = [
+    {"start": 0.0,  "end": 5.0,  "name": "coral",
+     "fx": fx_coral, "grid": "sm", "gamma": 0.70,
+     "shaders": [("bloom", {"thr": 110}), ("vignette", {"s": 0.2})],
+     "feedback": {"decay": 0.8, "blend": "screen", "opacity": 0.3,
+                  "transform": "zoom", "transform_amt": 0.01}},
+
+    {"start": 5.0,  "end": 15.0, "name": "tunnel_noise",
+     "fx": fx_tunnel_noise, "grid": "md", "gamma": 0.75,
+     "shaders": [("chromatic", {"amt": 3}), ("bloom", {"thr": 120}),
+                 ("scanlines", {"intensity": 0.06}), ("grain", {"amt": 8})],
+     "feedback": None},
+
+    {"start": 15.0, "end": 35.0, "name": "cathedral",
+     "fx": fx_cathedral, "grid": "sm", "gamma": 0.65,
+     "shaders": [("bloom", {"thr": 100}), ("chromatic", {"amt": 5}),
+                 ("color_wobble", {"amt": 0.2}), ("vignette", {"s": 0.18})],
+     "feedback": {"decay": 0.75, "blend": "screen", "opacity": 0.35,
+                  "transform": "zoom", "transform_amt": 0.012, "hue_shift": 0.015}},
+
+    {"start": 35.0, "end": 50.0, "name": "morphing",
+     "fx": fx_morphing_journey, "grid": "md", "gamma": 0.70,
+     "shaders": [("bloom", {"thr": 110}), ("grain", {"amt": 6})],
+     "feedback": {"decay": 0.7, "blend": "screen", "opacity": 0.25,
+                  "transform": "rotate_cw", "transform_amt": 0.003}},
+]
+```