@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/ascii-video/references/composition.md

@@ -0,0 +1,662 @@
+# 混合与亮度参考
+
+可组合系统是视觉复杂性的核心。它在三个层面上运作：像素级混合模式、多网格合成以及自适应亮度管理。本文档涵盖了这三个层面，以及用于空间控制的遮罩/Stencil 系统。
+
+> **另见:** architecture.md · effects.md · scenes.md · shaders.md · troubleshooting.md
+
+## 像素级混合模式
+
+### `blend_canvas()` 函数
+
+所有混合操作都在完整的像素画布（`uint8 H,W,3`）上进行。内部会将其转换为 float32 [0,1] 以保证精度，完成混合后，根据不透明度进行线性插值，最后转换回原格式。
+
+```python
+def blend_canvas(base, top, mode="normal", opacity=1.0):
+    af = base.astype(np.float32) / 255.0
+    bf = top.astype(np.float32) / 255.0
+    fn = BLEND_MODES.get(mode, BLEND_MODES["normal"])
+    result = fn(af, bf)
+    if opacity < 1.0:
+        result = af * (1 - opacity) + result * opacity
+    return np.clip(result * 255, 0, 255).astype(np.uint8)
+```
+
+### 20 种混合模式
+
+```python
+BLEND_MODES = {
+    # Basic arithmetic
+    "normal":       lambda a, b: b,
+    "add":          lambda a, b: np.clip(a + b, 0, 1),
+    "subtract":     lambda a, b: np.clip(a - b, 0, 1),
+    "multiply":     lambda a, b: a * b,
+    "screen":       lambda a, b: 1 - (1 - a) * (1 - b),
+
+    # Contrast
+    "overlay":      lambda a, b: np.where(a < 0.5, 2*a*b, 1 - 2*(1-a)*(1-b)),
+    "softlight":    lambda a, b: (1 - 2*b)*a*a + 2*b*a,
+    "hardlight":    lambda a, b: np.where(b < 0.5, 2*a*b, 1 - 2*(1-a)*(1-b)),
+
+    # Difference
+    "difference":   lambda a, b: np.abs(a - b),
+    "exclusion":    lambda a, b: a + b - 2*a*b,
+
+    # Dodge / burn
+    "colordodge":   lambda a, b: np.clip(a / (1 - b + 1e-6), 0, 1),
+    "colorburn":    lambda a, b: np.clip(1 - (1 - a) / (b + 1e-6), 0, 1),
+
+    # Light
+    "linearlight":  lambda a, b: np.clip(a + 2*b - 1, 0, 1),
+    "vividlight":   lambda a, b: np.where(b < 0.5,
+                        np.clip(1 - (1-a)/(2*b + 1e-6), 0, 1),
+                        np.clip(a / (2*(1-b) + 1e-6), 0, 1)),
+    "pin_light":    lambda a, b: np.where(b < 0.5,
+                        np.minimum(a, 2*b), np.maximum(a, 2*b - 1)),
+    "hard_mix":     lambda a, b: np.where(a + b >= 1.0, 1.0, 0.0),
+
+    # Compare
+    "lighten":      lambda a, b: np.maximum(a, b),
+    "darken":       lambda a, b: np.minimum(a, b),
+
+    # Grain
+    "grain_extract": lambda a, b: np.clip(a - b + 0.5, 0, 1),
+    "grain_merge":  lambda a, b: np.clip(a + b - 0.5, 0, 1),
+}
+```
+
+### 混合模式选择指南
+
+**提亮模式**（对暗色输入安全）：
+- `screen` — 始终提亮。两个 50% 灰度的图层 screen 混合后得到 75%。是首选的安全混合方式。
+- `add` — 简单相加，超出部分会显示为纯白。适合火花、辉光、粒子叠加。
+- `colordodge` — 在重叠区域产生极致的提亮。容易过曝。建议使用低不透明度（0.3-0.5）。
+- `linearlight` — 强烈的提亮效果。类似于 add，但带有偏移量。
+
+**压暗模式**（避免用于暗色输入）：
+- `multiply` — 使所有内容变暗。仅当两个图层本身都比较亮时才使用。
+- `overlay` — 基底 < 0.5 时变暗，基底 > 0.5 时变亮。会严重压碎暗色输入：`2 * 0.12 * 0.12 = 0.03`。对于暗色素材，请改用 `screen`。
+- `colorburn` — 在重叠区域产生极致的变暗效果。
+
+**增加对比度的模式**：
+- `softlight` — 柔和的对比度。适合微妙的纹理叠加。
+- `hardlight` — 强烈的对比度。类似于 overlay，但取决于顶部图层。
+- `vividlight` — 极其强烈的对比度。请谨慎使用。
+
+**产生色彩效果的模式**：
+- `difference` — 类似异或（XOR）的图案。两个相同的图层 difference 混合会得到纯黑；偏移的图层会产生狂野的色彩。非常适合迷幻风格。
+- `exclusion` — 较柔和的 difference 版本。产生互补色的图案。
+- `hard_mix` — 在相交处色调分离为纯黑/纯白/饱和色。
+
+**用于纹理混合的模式**：
+- `grain_extract` / `grain_merge` — 从一个图层提取纹理，并将其应用到另一个图层。
+
+### 多层链接
+
+```python
+# Pattern: render layers -> blend sequentially
+canvas_a = _render_vf(r, "md", vf_plasma, hf_angle(0.0), PAL_DENSE, f, t, S)
+canvas_b = _render_vf(r, "sm", vf_vortex, hf_time_cycle(0.1), PAL_RUNE, f, t, S)
+canvas_c = _render_vf(r, "lg", vf_rings, hf_distance(), PAL_BLOCKS, f, t, S)
+
+result = blend_canvas(canvas_a, canvas_b, "screen", 0.8)
+result = blend_canvas(result, canvas_c, "difference", 0.6)
+```
+
+顺序很重要：`screen(A, B)` 是可交换的，但 `difference(screen(A,B), C)` 不同于 `difference(A, screen(B,C))`。
+
+### 线性光混合模式
+
+标准的 `blend_canvas()` 在 sRGB 空间中运行——即原始的字节值。这对于大多数用途来说已经足够，但 sRGB 在感知上是非线性的：在 sRGB 空间中进行混合会使中间调变暗，并导致色调发生轻微偏移。为了获得物理上准确的混合效果（匹配光线实际组合的方式），需要先转换到线性光空间。
+
+使用来自 `architecture.md` § OKLAB Color System 的 `srgb_to_linear()` / `linear_to_srgb()`。
+
+```python
+def blend_canvas_linear(base, top, mode="normal", opacity=1.0):
+    """Blend in linear light space for physically accurate results.
+    
+    Identical API to blend_canvas(), but converts sRGB → linear before
+    blending and linear → sRGB after. More expensive (~2x) due to the
+    gamma conversions, but produces correct results for additive blending,
+    screen, and any mode where brightness matters.
+    """
+    af = srgb_to_linear(base.astype(np.float32) / 255.0)
+    bf = srgb_to_linear(top.astype(np.float32) / 255.0)
+    fn = BLEND_MODES.get(mode, BLEND_MODES["normal"])
+    result = fn(af, bf)
+    if opacity < 1.0:
+        result = af * (1 - opacity) + result * opacity
+    result = linear_to_srgb(np.clip(result, 0, 1))
+    return np.clip(result * 255, 0, 255).astype(np.uint8)
+```
+
+**何时使用 `blend_canvas_linear()` 与 `blend_canvas()`：**
+
+| 场景 | Use | Why |
+|----------|-----|-----|
+| Screen-blending two bright layers | `linear` | sRGB screen over-brightens highlights |
+| Add mode for glow/bloom effects | `linear` | Additive light follows linear physics |
+| Blending text overlay at low opacity | `srgb` | Perceptual blending looks more natural for text |
+| Multiply for shadow/darkening | `srgb` | Differences are minimal for darken ops |
+| Color-critical work (matching reference) | `linear` | Avoids sRGB hue shifts in midtones |
+| Performance-critical inner loop | `srgb` | ~2x faster, good enough for most ASCII art |
+
+**批量版本** 用于合成多个图层（一次转换，多次混合，最后转换回去）：
+
+```python
+def blend_many_linear(layers, modes, opacities):
+    """Blend a stack of layers in linear light space.
+    
+    Args:
+        layers: list of uint8 (H,W,3) canvases
+        modes: list of blend mode strings (len = len(layers) - 1)
+        opacities: list of floats (len = len(layers) - 1)
+    Returns:
+        uint8 (H,W,3) canvas
+    """
+    # Convert all to linear at once
+    linear = [srgb_to_linear(l.astype(np.float32) / 255.0) for l in layers]
+    result = linear[0]
+    for i in range(1, len(linear)):
+        fn = BLEND_MODES.get(modes[i-1], BLEND_MODES["normal"])
+        blended = fn(result, linear[i])
+        op = opacities[i-1]
+        if op < 1.0:
+            blended = result * (1 - op) + blended * op
+        result = np.clip(blended, 0, 1)
+    result = linear_to_srgb(result)
+    return np.clip(result * 255, 0, 255).astype(np.uint8)
+```
+
+---
+
+## 多网格合成
+
+这是核心的视觉技术。在不同的网格密度（字符大小）下渲染同一个概念场景，会产生自然的纹理干涉，因为不同尺度的字符会在不同的空间频率上发生重叠。
+
+### 为什么有效
+
+- `sm` 网格（10pt 字体）：320x83 个字符。细节精细，纹理密集。
+- `md` 网格（16pt）：192x56 个字符。中等密度。
+- `lg` 网格（20pt）：160x45 个字符。粗犷，厚实的字符。
+
+当你在 `sm` 网格上渲染一个 plasma 场，并在 `lg` 网格上渲染一个 vortex，然后将它们进行 screen 混合时，精细的 plasma 纹理就会从粗糙的 vortex 字符间隙中显露出来。其结果比单独任何一个图层都具有更高的视觉复杂性。
+
+### `_render_vf()` 助手函数
+
+这是一个主力函数。它接收一个 value field + hue field + palette + grid，并将其渲染为完整的像素画布：
+
+```python
+def _render_vf(r, grid_key, val_fn, hue_fn, pal, f, t, S, sat=0.8, threshold=0.03):
+    """Render a value field + hue field to a pixel canvas via a named grid.
+
+    Args:
+        r: Renderer instance (has .get_grid())
+        grid_key: "xs", "sm", "md", "lg", "xl", "xxl"
+        val_fn: (g, f, t, S) -> float32 [0,1] array (rows, cols)
+        hue_fn: callable (g, f, t, S) -> float32 hue array, OR float scalar
+        pal: character palette string
+        f: feature dict
+        t: time in seconds
+        S: persistent state dict
+        sat: HSV saturation (0-1)
+        threshold: minimum value to render (below = space)
+
+    Returns:
+        uint8 array (VH, VW, 3) — full pixel canvas
+    """
+    g = r.get_grid(grid_key)
+    val = np.clip(val_fn(g, f, t, S), 0, 1)
+    mask = val > threshold
+    ch = val2char(val, mask, pal)
+
+    # Hue: either a callable or a fixed float
+    if callable(hue_fn):
+        h = hue_fn(g, f, t, S) % 1.0
+    else:
+        h = np.full((g.rows, g.cols), float(hue_fn), dtype=np.float32)
+
+    # CRITICAL: broadcast to full shape and copy (see Troubleshooting)
+    h = np.broadcast_to(h, (g.rows, g.cols)).copy()
+
+    R, G, B = hsv2rgb(h, np.full_like(val, sat), val)
+    co = mkc(R, G, B, g.rows, g.cols)
+    return g.render(ch, co)
+```
+
+### 网格组合策略
+
+| Combination | Effect | Good For |
+|-------------|--------|----------|
+| `sm` + `lg` | Maximum contrast between fine detail and chunky blocks | Bold, graphic looks |
+| `sm` + `md` | Subtle texture layering, similar scales | Organic, flowing looks |
+| `md` + `lg` + `xs` | Three-scale interference, maximum complexity | Psychedelic, dense |
+| `sm` + `sm` (different effects) | Same scale, pattern interference only | Moire, interference |
+
+### 完整的多网格场景示例
+
+```python
+def fx_psychedelic(r, f, t, S):
+    """Three-layer multi-grid scene with beat-reactive kaleidoscope."""
+    # Layer A: plasma on medium grid with rainbow hue
+    canvas_a = _render_vf(r, "md",
+        lambda g, f, t, S: vf_plasma(g, f, t, S) * 1.3,
+        hf_angle(0.0), PAL_DENSE, f, t, S, sat=0.8)
+
+    # Layer B: vortex on small grid with cycling hue
+    canvas_b = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_vortex(g, f, t, S, twist=5.0) * 1.2,
+        hf_time_cycle(0.1), PAL_RUNE, f, t, S, sat=0.7)
+
+    # Layer C: rings on large grid with distance hue
+    canvas_c = _render_vf(r, "lg",
+        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=8, spacing_base=3) * 1.4,
+        hf_distance(0.3, 0.02), PAL_BLOCKS, f, t, S, sat=0.9)
+
+    # Blend: A screened with B, then difference with C
+    result = blend_canvas(canvas_a, canvas_b, "screen", 0.8)
+    result = blend_canvas(result, canvas_c, "difference", 0.6)
+
+    # Beat-triggered kaleidoscope
+    if f.get("bdecay", 0) > 0.3:
+        result = sh_kaleidoscope(result.copy(), folds=6)
+
+    return result
+```
+
+---
+
+## 自适应色调映射
+
+### 亮度问题
+
+ASCII 字符是黑色背景上的微小亮点。任意一帧中的大多数像素都是背景（黑色）。这意味着：
+- 平均帧亮度天生较低（通常在 255 中只占 5-30）
+- 不同的效果组合会产生差异巨大的亮度水平
+- 一个螺旋场景的平均亮度可能是 50，而火焰场景可能是 9
+- 线性乘数（例如 `canvas * 2.0`）要么让暗场景依然很暗，要么让亮场景严重过曝
+
+### `tonemap()` 函数
+
+使用自适应逐帧归一化 + gamma 校正来取代线性亮度乘数：
+
+```python
+def tonemap(canvas, target_mean=90, gamma=0.75, black_point=2, white_point=253):
+    """Adaptive tone-mapping: normalizes + gamma-corrects so no frame is
+    fully dark or washed out.
+
+    1. Compute 1st and 99.5th percentile on 4x subsample (16x fewer values,
+       negligible accuracy loss, major speedup at 1080p+)
+    2. Stretch that range to [0, 1]
+    3. Apply gamma curve (< 1 lifts shadows, > 1 darkens)
+    4. Rescale to [black_point, white_point]
+    """
+    f = canvas.astype(np.float32)
+    sub = f[::4, ::4]  # 4x subsample: ~390K values vs ~6.2M at 1080p
+    lo = np.percentile(sub, 1)
+    hi = np.percentile(sub, 99.5)
+    if hi - lo < 10:
+        hi = max(hi, lo + 10)  # near-uniform frame fallback
+    f = np.clip((f - lo) / (hi - lo), 0.0, 1.0)
+    np.power(f, gamma, out=f)          # in-place: avoids allocation
+    np.multiply(f, (white_point - black_point), out=f)
+    np.add(f, black_point, out=f)
+    return np.clip(f, 0, 255).astype(np.uint8)
+```
+
+### 为什么使用 Gamma，而不是线性
+
+线性乘数 `* 2.0`：
+```
+input 10  -> output 20   (still dark)
+input 100 -> output 200  (ok)
+input 200 -> output 255  (clipped, lost detail)
+```
+
+归一化后 Gamma 0.75：
+```
+input 0.04 -> output 0.08 (lifted from invisible to visible)
+input 0.39 -> output 0.50 (moderate lift)
+input 0.78 -> output 0.84 (gentle lift, no clipping)
+```
+
+小于 1 的 Gamma 会压缩高光并扩展阴影。这正是我们所需要的：将暗淡的 ASCII 内容提升到可见状态，同时又不会使明亮的部分过曝。
+
+### 管线顺序
+
+`render_clip()` 中的管线流程如下：
+
+```
+scene_fn(r, f, t, S)  ->  canvas
+         |
+    tonemap(canvas, gamma=scene_gamma)
+         |
+    FeedbackBuffer.apply(canvas, ...)
+         |
+    ShaderChain.apply(canvas, f=f, t=t)
+         |
+    ffmpeg pipe
+```
+
+Tonemap 在 feedback 和 shaders 之前运行。这意味着：
+- Feedback 在归一化后的数据上运行（无论场景亮度如何，行为都保持一致）
+- 像 solarize、posterize、contrast 这样的 shader 在数据范围恰当的情况下运行
+- 链条中不再需要亮度 shader（由 tonemap 负责处理）
+
+### 逐场景 Gamma 调优
+
+默认 gamma 为 0.75。应用了破坏性后处理的场景需要更大幅度的提升，因为破坏发生在 tonemap 之后：
+
+| Scene Type | Recommended Gamma | Why |
+|------------|-------------------|-----|
+| Standard effects | 0.75 | Default, works for most scenes |
+| Solarize post-process | 0.50-0.60 | Solarize inverts bright pixels, reducing overall brightness |
+| Posterize post-process | 0.50-0.55 | Posterize quantizes, often crushing mid-values to black |
+| Heavy difference blending | 0.60-0.70 | Difference mode creates many near-zero pixels |
+| Already bright scenes | 0.85-1.0 | Don't over-boost scenes that are naturally bright |
+
+通过场景表进行配置：
+
+```python
+SCENES = [
+    {"start": 9.17, "end": 11.25, "name": "fire", "gamma": 0.55,
+     "fx": fx_fire, "shaders": [("solarize", {"threshold": 200}), ...]},
+    {"start": 25.96, "end": 27.29, "name": "diamond", "gamma": 0.5,
+     "fx": fx_diamond, "shaders": [("bloom", {"thr": 90}), ...]},
+]
+```
+
+### 亮度验证
+
+渲染后，抽查帧亮度：
+
+```python
+# In test-frame mode
+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)
+print(f"Mean brightness: {canvas.astype(float).mean():.1f}, max: {canvas.max()}")
+```
+
+Tonemap + shaders 后的目标范围：
+- Quiet/ambient scenes: mean 30-60
+- Active scenes: mean 40-100
+- Climax/peak scenes: mean 60-150
+- If mean < 20: gamma is too high or a shader is destroying brightness
+- If mean > 180: gamma is too low or add is stacking too much
+
+---
+
+## FeedbackBuffer 空间变换
+
+Feedback buffer 会存储前一帧，并利用衰减将其混合到当前帧中。在混合之前对 buffer 应用空间变换，能够在 feedback 拖尾中产生运动的错觉。
+
+### 实现
+
+```python
+class FeedbackBuffer:
+    def __init__(self):
+        self.buf = None
+
+    def apply(self, canvas, decay=0.85, blend="screen", opacity=0.5,
+              transform=None, transform_amt=0.02, hue_shift=0.0):
+        if self.buf is None:
+            self.buf = canvas.astype(np.float32) / 255.0
+            return canvas
+
+        # Decay old buffer
+        self.buf *= decay
+
+        # Spatial transform
+        if transform:
+            self.buf = self._transform(self.buf, transform, transform_amt)
+
+        # Hue shift the feedback for rainbow trails
+        if hue_shift > 0:
+            self.buf = self._hue_shift(self.buf, hue_shift)
+
+        # Blend feedback into current frame
+        result = blend_canvas(canvas,
+                              np.clip(self.buf * 255, 0, 255).astype(np.uint8),
+                              blend, opacity)
+
+        # Update buffer with current frame
+        self.buf = result.astype(np.float32) / 255.0
+        return result
+
+    def _transform(self, buf, transform, amt):
+        h, w = buf.shape[:2]
+        if transform == "zoom":
+            # Zoom in: sample from slightly inside (creates expanding tunnel)
+            m = int(h * amt); n = int(w * amt)
+            if m > 0 and n > 0:
+                cropped = buf[m:-m or None, n:-n or None]
+                # Resize back to full (nearest-neighbor for speed)
+                buf = np.array(Image.fromarray(
+                    np.clip(cropped * 255, 0, 255).astype(np.uint8)
+                ).resize((w, h), Image.NEAREST)).astype(np.float32) / 255.0
+        elif transform == "shrink":
+            # Zoom out: pad edges, shrink center
+            m = int(h * amt); n = int(w * amt)
+            small = np.array(Image.fromarray(
+                np.clip(buf * 255, 0, 255).astype(np.uint8)
+            ).resize((w - 2*n, h - 2*m), Image.NEAREST))
+            new = np.zeros((h, w, 3), dtype=np.uint8)
+            new[m:m+small.shape[0], n:n+small.shape[1]] = small
+            buf = new.astype(np.float32) / 255.0
+        elif transform == "rotate_cw":
+            # Small clockwise rotation via affine
+            angle = amt * 10  # amt=0.005 -> 0.05 degrees per frame
+            cy, cx = h / 2, w / 2
+            Y = np.arange(h, dtype=np.float32)[:, None]
+            X = np.arange(w, dtype=np.float32)[None, :]
+            cos_a, sin_a = np.cos(angle), np.sin(angle)
+            sx = (X - cx) * cos_a + (Y - cy) * sin_a + cx
+            sy = -(X - cx) * sin_a + (Y - cy) * cos_a + cy
+            sx = np.clip(sx.astype(int), 0, w - 1)
+            sy = np.clip(sy.astype(int), 0, h - 1)
+            buf = buf[sy, sx]
+        elif transform == "rotate_ccw":
+            angle = -amt * 10
+            cy, cx = h / 2, w / 2
+            Y = np.arange(h, dtype=np.float32)[:, None]
+            X = np.arange(w, dtype=np.float32)[None, :]
+            cos_a, sin_a = np.cos(angle), np.sin(angle)
+            sx = (X - cx) * cos_a + (Y - cy) * sin_a + cx
+            sy = -(X - cx) * sin_a + (Y - cy) * cos_a + cy
+            sx = np.clip(sx.astype(int), 0, w - 1)
+            sy = np.clip(sy.astype(int), 0, h - 1)
+            buf = buf[sy, sx]
+        elif transform == "shift_up":
+            pixels = max(1, int(h * amt))
+            buf = np.roll(buf, -pixels, axis=0)
+            buf[-pixels:] = 0  # black fill at bottom
+        elif transform == "shift_down":
+            pixels = max(1, int(h * amt))
+            buf = np.roll(buf, pixels, axis=0)
+            buf[:pixels] = 0
+        elif transform == "mirror_h":
+            buf = buf[:, ::-1]
+        return buf
+
+    def _hue_shift(self, buf, amount):
+        """Rotate hues of the feedback buffer. Operates on float32 [0,1]."""
+        rgb = np.clip(buf * 255, 0, 255).astype(np.uint8)
+        hsv = np.zeros_like(buf)
+        # Simple approximate RGB->HSV->shift->RGB
+        r, g, b = buf[:,:,0], buf[:,:,1], buf[:,:,2]
+        mx = np.maximum(np.maximum(r, g), b)
+        mn = np.minimum(np.minimum(r, g), b)
+        delta = mx - mn + 1e-10
+        # Hue
+        h = np.where(mx == r, ((g - b) / delta) % 6,
+            np.where(mx == g, (b - r) / delta + 2, (r - g) / delta + 4))
+        h = (h / 6 + amount) % 1.0
+        # Reconstruct with shifted hue (simplified)
+        s = delta / (mx + 1e-10)
+        v = mx
+        c = v * s; x = c * (1 - np.abs((h * 6) % 2 - 1)); m = v - c
+        ro = np.zeros_like(h); go = np.zeros_like(h); bo = np.zeros_like(h)
+        for lo, hi, rv, gv, bv in [(0,1,c,x,0),(1,2,x,c,0),(2,3,0,c,x),
+                                     (3,4,0,x,c),(4,5,x,0,c),(5,6,c,0,x)]:
+            mask = ((h*6) >= lo) & ((h*6) < hi)
+            ro[mask] = rv[mask] if not isinstance(rv, (int,float)) else rv
+            go[mask] = gv[mask] if not isinstance(gv, (int,float)) else gv
+            bo[mask] = bv[mask] if not isinstance(bv, (int,float)) else bv
+        return np.stack([ro+m, go+m, bo+m], axis=2)
+```
+
+### Feedback 预设
+
+| Preset | Config | Visual Effect |
+|--------|--------|---------------|
+| Infinite zoom tunnel | `decay=0.8, blend="screen", transform="zoom", transform_amt=0.015` | Expanding ring patterns |
+| Rainbow trails | `decay=0.7, blend="screen", transform="zoom", transform_amt=0.01, hue_shift=0.02` | Psychedelic color trails |
+| Ghostly echo | `decay=0.9, blend="add", opacity=0.15, transform="shift_up", transform_amt=0.01` | Faint upward smearing |
+| Kaleidoscopic recursion | `decay=0.75, blend="screen", transform="rotate_cw", transform_amt=0.005, hue_shift=0.01` | Rotating mandala feedback |
+| Color evolution | `decay=0.8, blend="difference", opacity=0.4, hue_shift=0.03` | Frame-to-frame color XOR |
+| Rising heat haze | `decay=0.5, blend="add", opacity=0.2, transform="shift_up", transform_amt=0.02` | Hot air shimmer |
+
+---
+
+## 遮罩 / Stencil 系统
+
+遮罩是范围在 [0, 1] 之间的 float32 数组 `(rows, cols)` 或 `(VH, VW)`。它们控制效果在何处可见：1.0 = 完全可见，0.0 = 完全隐藏。使用遮罩可以创建图底关系、视觉焦点以及特定形状的显示区域。
+
+### 形状遮罩
+
+```python
+def mask_circle(g, cx_frac=0.5, cy_frac=0.5, radius=0.3, feather=0.05):
+    """Circular mask centered at (cx_frac, cy_frac) in normalized coords.
+    feather: width of soft edge (0 = hard cutoff)."""
+    asp = g.cw / g.ch if hasattr(g, 'cw') else 1.0
+    dx = (g.cc / g.cols - cx_frac)
+    dy = (g.rr / g.rows - cy_frac) * asp
+    d = np.sqrt(dx**2 + dy**2)
+    if feather > 0:
+        return np.clip(1.0 - (d - radius) / feather, 0, 1)
+    return (d <= radius).astype(np.float32)
+
+def mask_rect(g, x0=0.2, y0=0.2, x1=0.8, y1=0.8, feather=0.03):
+    """Rectangular mask. Coordinates in [0,1] normalized."""
+    dx = np.maximum(x0 - g.cc / g.cols, g.cc / g.cols - x1)
+    dy = np.maximum(y0 - g.rr / g.rows, g.rr / g.rows - y1)
+    d = np.maximum(dx, dy)
+    if feather > 0:
+        return np.clip(1.0 - d / feather, 0, 1)
+    return (d <= 0).astype(np.float32)
+
+def mask_ring(g, cx_frac=0.5, cy_frac=0.5, inner_r=0.15, outer_r=0.35,
+              feather=0.03):
+    """Ring / annulus mask."""
+    inner = mask_circle(g, cx_frac, cy_frac, inner_r, feather)
+    outer = mask_circle(g, cx_frac, cy_frac, outer_r, feather)
+    return outer - inner
+
+def mask_gradient_h(g, start=0.0, end=1.0):
+    """Left-to-right gradient mask."""
+    return np.clip((g.cc / g.cols - start) / (end - start + 1e-10), 0, 1).astype(np.float32)
+
+def mask_gradient_v(g, start=0.0, end=1.0):
+    """Top-to-bottom gradient mask."""
+    return np.clip((g.rr / g.rows - start) / (end - start + 1e-10), 0, 1).astype(np.float32)
+
+def mask_gradient_radial(g, cx_frac=0.5, cy_frac=0.5, inner=0.0, outer=0.5):
+    """Radial gradient mask — bright at center, dark at edges."""
+    d = np.sqrt((g.cc / g.cols - cx_frac)**2 + (g.rr / g.rows - cy_frac)**2)
+    return np.clip(1.0 - (d - inner) / (outer - inner + 1e-10), 0, 1)
+```
+
+### 将 Value Field 作为遮罩
+
+将任何 `vf_*` 函数的输出用作空间遮罩：
+
+```python
+def mask_from_vf(vf_result, threshold=0.5, feather=0.1):
+    """Convert a value field to a mask by thresholding.
+    feather: smooth edge width around threshold."""
+    if feather > 0:
+        return np.clip((vf_result - threshold + feather) / (2 * feather), 0, 1)
+    return (vf_result > threshold).astype(np.float32)
+
+def mask_select(mask, vf_a, vf_b):
+    """Spatial conditional: show vf_a where mask is 1, vf_b where mask is 0.
+    mask: float32 [0,1] array. Intermediate values blend."""
+    return vf_a * mask + vf_b * (1 - mask)
+```
+
+### 文本 Stencil
+
+将文本渲染为遮罩。效果仅透过字符形状显示出来：
+
+```python
+def mask_text(grid, text, row_frac=0.5, font=None, font_size=None):
+    """Render text string as a float32 mask [0,1] at grid resolution.
+    Characters = 1.0, background = 0.0.
+
+    row_frac: vertical position as fraction of grid height.
+    font: PIL ImageFont (defaults to grid's font if None).
+    font_size: override font size for the mask text (for larger stencil text).
+    """
+    from PIL import Image, ImageDraw, ImageFont
+
+    f = font or grid.font
+    if font_size and font != grid.font:
+        f = ImageFont.truetype(font.path, font_size)
+
+    # Render text to image at pixel resolution, then downsample to grid
+    img = Image.new("L", (grid.cols * grid.cw, grid.ch), 0)
+    draw = ImageDraw.Draw(img)
+    bbox = draw.textbbox((0, 0), text, font=f)
+    tw = bbox[2] - bbox[0]
+    x = (grid.cols * grid.cw - tw) // 2
+    draw.text((x, 0), text, fill=255, font=f)
+    row_mask = np.array(img, dtype=np.float32) / 255.0
+
+    # Place in full grid mask
+    mask = np.zeros((grid.rows, grid.cols), dtype=np.float32)
+    target_row = int(grid.rows * row_frac)
+    # Downsample rendered text to grid cells
+    for c in range(grid.cols):
+        px = c * grid.cw
+        if px + grid.cw <= row_mask.shape[1]:
+            cell = row_mask[:, px:px + grid.cw]
+            if cell.mean() > 0.1:
+                mask[target_row, c] = cell.mean()
+    return mask
+
+def mask_text_block(grid, lines, start_row_frac=0.3, font=None):
+    """Multi-line text stencil. Returns full grid mask."""
+    mask = np.zeros((grid.rows, grid.cols), dtype=np.float32)
+    for i, line in enumerate(lines):
+        row_frac = start_row_frac + i / grid.rows
+        line_mask = mask_text(grid, line, row_frac, font)
+        mask = np.maximum(mask, line_mask)
+    return mask
+```
+
+### 动画遮罩
+
+随时间变化以实现显示、擦除和变形的遮罩：
+
+```python
+def mask_iris(g, t, t_start, t_end, cx_frac=0.5, cy_frac=0.5,
+              max_radius=0.7, ease_fn=None):
+    """Iris open/close: circle that grows from 0 to max_radius.
+    ease_fn: easing function (default: ease_in_out_cubic from effects.md)."""
+    if ease_fn is None:
+        ease_fn = lambda x: x * x * (3 - 2 * x)  # smoothstep fallback
+    progress = np.clip((t - t_start) / (t_end - t_start), 0, 1)
+    radius = ease_fn(progress) * max_radius
+    return mask_circle(g, cx_frac, cy_frac, radius, feather=0.03)
+
+def mask_wipe_h(g, t, t_start, t_end, direction="right"):
+    """Horizontal wipe reveal."""
+    progress = np.clip((t - t_start) / (t_end - t_start), 0, 1)
+    if direction == "left":
+        progress = 1 - progress
+    return mask_gradient_h(g, start=progress - 0.05, end=progress + 0.05)
+
+def mask