reze-engine 0.50.12 → 0.52.0

package/src/engine.ts

@@ -2,7 +2,7 @@ import { Camera } from "./camera"
 import { decodeDds, isDds } from "./dds-loader"
 import { Mat4, Quat, Vec3 } from "./math"
 import { decodePsd, isPsd } from "./psd-loader"
-import { Model, MATERIAL_MORPH_MULTIPLY, type Material } from "./model"
+import { Model, MATERIAL_MORPH_MULTIPLY, type Material, type Skeleton } from "./model"
 import { MORPH_COMPUTE_WGSL } from "./shaders/passes/morph"
 import { CULL_COMPUTE_WGSL } from "./shaders/passes/cull"
 import { buildAnchorTable, anchorAliasWgsl, EMPTY_ANCHOR_TABLE, type AnchorTable } from "./shaders/anchor-table"
@@ -29,6 +29,7 @@ import { LTC_MAG_LUT_SIZE, LTC_MAG_LUT_DATA } from "./shaders/ltc_mag_lut"
 import { SHADOW_DEPTH_SHADER_WGSL } from "./shaders/passes/shadow"
 import { ID_DEBUG_SHADER_WGSL } from "./shaders/passes/id-debug"
 import { paramChanged, sampleParamTrack, type ParamKey, type ParamValue } from "./param-track"
+import { effectState, type EffectWindow } from "./effect-schedule"
 import { SHADOW_CASCADES, buildShadowVP } from "./shadow-cascades"
 import { REFLECTION_DEBUG_WGSL, buildMirrorCamera } from "./reflection"
 import { packHalf, type HdrImage } from "./hdr"
@@ -49,7 +50,6 @@ import {
   MAX_LIGHTS,
   buildLightEmitShader,
   hasLightEmit,
-  parseLightCount,
 } from "./shaders/lights"
 import { groundShaderWgsl, GROUND_NOISE_BAKE_WGSL, GROUND_NOISE_SIZE } from "./shaders/passes/ground"
 import { outlineShaderWgsl } from "./shaders/passes/outline"
@@ -66,7 +66,6 @@ import {
   buildCompositeShader,
   EFFECT_SCENE_API,
   buildFieldShader,
-  parseEffectAnchors,
   EFFECT_ANCHORS,
   EFFECT_SUBJECTS,
   EFFECT_TRAIL_BASE,
@@ -75,9 +74,6 @@ import {
 import {
   buildParticleComputeShader,
   buildParticleRenderShader,
-  parseParticleBlend,
-  parseParticleBloom,
-  parseParticleCount,
   particleEntryPoints,
   PARTICLE_STRIDE,
 } from "./shaders/passes/particles"
@@ -85,7 +81,6 @@ import {
   SIM_FORMAT,
   GRID_MAX,
   buildSimShader,
-  parseGridSize,
   gridEntryPoint,
 } from "./shaders/passes/grid"
 import { buildTrailShader, trailEntryPoints, TRAIL_SUBDIVISIONS } from "./shaders/passes/trails"
@@ -101,6 +96,8 @@ import type {
   StyleGroup,
 } from "./graph/style-group"
 import { DEFAULT_GRAPH } from "./graph/presets/default"
+import { parseDirectives, stripDirectives, type EffectDirectives, type EffectParamDecl } from "./shaders/directives"
+import { UNLIT_GRAPH } from "./graph/presets/unlit"
 import { FACE_GRAPH } from "./graph/presets/face"
 import { HAIR_GRAPH } from "./graph/presets/hair"
 import { BODY_GRAPH } from "./graph/presets/body"
@@ -378,6 +375,18 @@ export type EffectResult = {
   /** Which mounts the WGSL declared — `fn background` / `fn foreground`. Both
    *  false only on a failed compile, since defining neither IS the failure. */
   mounts: { background: boolean; foreground: boolean }
+  /** The knobs this effect exposes, from its own `#param` lines — name, type,
+   *  default and any range. A host builds controls from THIS rather than from
+   *  a second parse of the source, so what the panel offers and what the shader
+   *  reads cannot come apart. Empty when the effect declares none. */
+  params: EffectParamDecl[]
+  /** How long ONE firing lasts, seconds, from `#duration`. 0 = the effect
+   *  declared none and is AMBIENT — a condition the scene is in rather than
+   *  something that happens at a moment. A host places a hit at its own length
+   *  and spans an ambient one, which is the same reason `params` is here: what
+   *  the host does with an effect should come from the effect, not from a
+   *  second parse that can drift from it. */
+  duration: number
 }
 
 type CameraOptions = {
@@ -719,6 +728,21 @@ interface ModelInstance {
   /** Environment geometry added via addStage — no physics, no IK, and it
    *  suppresses the built-in ground. See addStage for why each of those. */
   isStage: boolean
+  /**
+   * A media plane: a flat card carrying a picture.
+   *
+   * Its OWN flag rather than a shade of isStage. The two overlap in what they
+   * skip — neither performs, so neither wants physics, IK, the cast buffer or
+   * the camera clock — but they disagree on the thing a stage exists for: a
+   * stage IS the floor and suppresses the built-in ground, while a card is
+   * scenery standing in the scene and must leave the floor alone. Folding a
+   * plane into isStage would have made adding a title graphic delete the ground.
+   */
+  isPlane: boolean
+  /** This card's texture is rewritten every frame, so it is allocated with no
+   *  mip chain — rebuilding one per frame is a pass per level per card, and is
+   *  what a moving card was mostly costing. See setPlaneFrame. */
+  dynamicTexture: boolean
   /** A pose pass ran since the last skin-matrix upload. Always true for cast
    *  members; false for an idle stage, which is the point. */
   skinMatricesDirty: boolean
@@ -1244,13 +1268,13 @@ const FIELD_LAYER_BLEND: GPUBlendState = {
 }
 
 /**
- * `// @layer additive` — for LIGHT rather than matter.
+ * `#layer additive` — for LIGHT rather than matter.
  *
  * Alpha-over is right for anything with mass: smoke, fog, a backdrop. It is
  * wrong for a glow, and visibly so the moment two of them cross — the later
  * bolt occludes the earlier one in proportion to its own brightness, when what
  * light does is get brighter. Unity and Unreal both ship exactly this split,
- * and the particle path here already has it as `@blend additive`.
+ * and the particle path here already has it as `#blend additive`.
  *
  * Colour still scales by the author's alpha, so alpha keeps meaning "how much
  * of this is here" and an effect fades out the way it always did. What changes
@@ -1279,6 +1303,12 @@ const FIELD_LAYER_BLEND_ADDITIVE: GPUBlendState = {
  */
 interface EffectInstance {
   wgsl: string
+  /** What this instance's source declared — kept so setEffectParam can refuse a
+   *  name the effect never offered instead of writing nowhere. */
+  paramDecls: EffectParamDecl[]
+  /** One firing's length in seconds, from `#duration`. 0 = ambient. Reported
+   *  back at install so a host can place the effect at its own length. */
+  duration: number
   paramLayout: Map<string, { offset: number; comps: 1 | 3 }>
   paramsBuffer: GPUBuffer | null
   paramsData: Float32Array<ArrayBuffer>
@@ -1305,6 +1335,26 @@ interface EffectInstance {
   anchors: { bone: string; trail: boolean }[]
   /** Where this effect's own clock started, in scene seconds. */
   epochScene: number
+  /**
+   * The level this effect reaches, 0..1 — Blender's `influence`, and its
+   * meaning: a strip's blends ramp toward THIS rather than toward 1, so a
+   * permanently half-strength effect and a scheduled one are the same dial.
+   */
+  influence: number
+  /** Its strips, in scene seconds — a LANE, so one effect can fire more than
+   *  once. Null or empty = on for the whole scene, which is what applying an
+   *  effect does until someone places it. */
+  window: readonly EffectWindow[] | null
+  /**
+   * What the mounts actually read this frame: `influence` shaped by the strip.
+   *
+   * Applied by ENGINE-GENERATED code at each mount's one output site, never by
+   * the author's — an effect that had to honour its own weight would be an
+   * effect that could forget to, and a scheduler cannot be built on a promise
+   * every author has to keep. At 0 the mount's draw is skipped outright, which
+   * is what makes a scheduled effect cost nothing outside its window.
+   */
+  weight: number
   /** This effect's OWN clock, as a uniform the field shader reads. Per effect
    *  because the shared one (viewU[6].x) is measured from the first installed
    *  effect's epoch, so everything later started mid-stream. Null when the
@@ -1312,7 +1362,7 @@ interface EffectInstance {
   fieldClock: GPUBuffer | null
   /** The lightEmit mount: a compute stage that writes this effect's own slots
    *  in the shared lights buffer, once per light per frame. Null unless the
-   *  source declares `// @lights n` AND defines fn lightEmit. */
+   *  source declares `#lights n` AND defines fn lightEmit. */
   lights: {
     pipeline: GPUComputePipeline
     bind: GPUBindGroup
@@ -1584,7 +1634,7 @@ export class Engine {
    * cost a degenerate quad the rasteriser rejects, which is cheaper than the
    * prefix sum and readback a compacted draw list would need every frame.
    */
-  /** Ceiling for `// @particles`. Past this an author is asking for a stall. */
+  /** Ceiling for `#particles`. Past this an author is asking for a stall. */
   private static readonly MAX_PARTICLES = 65536
   private particleFrame = 0
   /**
@@ -1604,7 +1654,7 @@ export class Engine {
    * RESOLUTION. Index 0 is full, index 1 is half — coarsest last, so the
    * composite reads them full-over-half.
    *
-   * `@fullres` used to be a property of the shared targets: one effect
+   * `#fullres` used to be a property of the shared targets: one effect
    * declaring it promoted the pass for every effect installed, so a starfield
    * that upsamples perfectly paid four times the pixels because a keyboard
    * beside it needed crisp edges. Measured, that was the largest avoidable cost
@@ -1726,7 +1776,7 @@ export class Engine {
    *
    *  `field` earns its place now that a scene runs SEVERAL field effects at
    *  once: it is one pass with N draws, its resolution is a property of the
-   *  shared targets rather than of any one effect — so a single `@fullres`
+   *  shared targets rather than of any one effect — so a single `#fullres`
    *  effect quadruples the pixel count for all of them — and it is the pass the
    *  field restructure moves. Restructuring it while it was the only untimed
    *  pass in the frame would have meant reasoning about the cost instead of
@@ -2994,8 +3044,10 @@ export class Engine {
    * is KEPT and diagnostics are returned with line numbers relative to the
    * user's WGSL. Pass null to remove the effect.
    */
+
   private async compileEffect(
-    wgsl: string,
+    /** The author's file, directives included — parsed here and nowhere else. */
+    authored: string,
     params: Record<string, EffectParamValue> | undefined,
     /** This effect's own declarations, already parsed by the caller — which had
      *  to read them anyway to build the scene table. */
@@ -3004,7 +3056,22 @@ export class Engine {
     alias: number[],
   ): Promise<{ ok: true; instance: EffectInstance; warnings: string[] } | EffectResult> {
     const noMounts = { background: false, foreground: false }
-    if (!this.device) return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts }
+    if (!this.device) return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts, params: [], duration: 0 }
+
+    // WHAT THE FILE DECLARES, read once. Everything below takes it from `d`
+    // rather than running a regex of its own — eight parsers over one file was
+    // eight chances to disagree about what it said, and they did.
+    //
+    // An unrecognised or malformed directive is an ERROR. `#` is not WGSL
+    // syntax, so a line starting with one is unambiguously ours and there is
+    // nothing to be lenient about; the old spelling lived in comments, where a
+    // typo was indistinguishable from prose and could only ever be warned about.
+    const parsed = parseDirectives(authored)
+    if (parsed.errors.length) return { ok: false, diagnostics: parsed.errors, mounts: noMounts, params: [], duration: 0 }
+    const d = parsed.directives
+    // The compiler sees the file with its directive lines BLANKED, so every
+    // diagnostic below still names the line the author is looking at.
+    const wgsl = stripDirectives(authored)
 
     // ── Which mounts did the author ask for? A declaration, not a setting: the
     // entry points present in the source are the ones compiled in. Matching the
@@ -3021,14 +3088,10 @@ export class Engine {
     const te = trailEntryPoints(wgsl)
     const wantsTrails = te.width || te.shade
     if (wantsTrails && !(te.width && te.shade)) {
-      return {
-        ok: false,
-        diagnostics: [
+      return { ok: false, diagnostics: [
           `a ribbon effect needs both fn trailWidth(u: f32, age: f32) -> f32 and ` +
             `fn trailShade(u: f32, v: f32, age: f32, weight: f32, slot: i32) -> vec4f`,
-        ],
-        mounts: noMounts,
-      }
+        ], mounts: noMounts, params: [], duration: 0 }
     }
     if (wantsParticles && !(pe.init && pe.step && pe.shade)) {
       const missing = [
@@ -3036,7 +3099,7 @@ export class Engine {
         pe.step ? null : "fn particleStep(p: Particle, dt: f32) -> Particle",
         pe.shade ? null : "fn particleShade(p: Particle, uv: vec2f) -> vec4f",
       ].filter(Boolean)
-      return { ok: false, diagnostics: [`a particle effect also needs ${missing.join(" and ")}`], mounts: noMounts }
+      return { ok: false, diagnostics: [`a particle effect also needs ${missing.join(" and ")}`], mounts: noMounts, params: [], duration: 0 }
     }
     // One file, one kind — for now.
     //
@@ -3051,36 +3114,28 @@ export class Engine {
     // says so plainly instead of failing with "unresolved type Particle" from a
     // pass they did not know they were compiling into.
     if ((wantsParticles || wantsTrails) && (hasBackground || hasForeground)) {
-      return {
-        ok: false,
-        diagnostics: [
+      return { ok: false, diagnostics: [
           "an effect declares field mounts (background/foreground) or particles, not both — " +
             "split them into two effects",
-        ],
-        mounts: noMounts,
-      }
+        ], mounts: noMounts, params: [], duration: 0 }
     }
     // lightEmit counts as a mount on its own: a pure lighting rig draws nothing
     // and is still an effect — it is how a scene gets stage lights without also
     // getting geometry it did not ask for.
     if (!hasBackground && !hasForeground && !wantsParticles && !wantsTrails && !hasLightEmit(wgsl)) {
-      return {
-        ok: false,
-        diagnostics: [
+      return { ok: false, diagnostics: [
           "an effect must define fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f, " +
             "fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f, " +
             "the particle trio (particleInit/particleStep/particleShade), " +
             "the ribbon pair (trailWidth/trailShade), " +
-            "or fn lightEmit(i: u32) -> RzLight with // @lights <n>",
-        ],
-        mounts: noMounts,
-      }
+            "or fn lightEmit(i: u32) -> RzLight with #lights <n>",
+        ], mounts: noMounts, params: [], duration: 0 }
     }
     const mounts = { background: hasBackground, foreground: hasForeground }
 
     // ── Directives only some mounts honour ──
     //
-    // @bloom sets the aux mask, and only the particle and ribbon modules write
+    // #bloom sets the aux mask, and only the particle and ribbon modules write
     // that mask: they draw inside the scene pass, in HDR, while the bloom
     // pyramid can still see them. A field effect composites in DISPLAY space
     // after tone mapping, so there is nothing left to pick it up and the
@@ -3093,9 +3148,9 @@ export class Engine {
     // pinning an effect that declares this has to keep installing; saying so is
     // all that was ever missing.
     const warnings: string[] = []
-    if (parseParticleBloom(wgsl) && !wantsParticles && !wantsTrails) {
+    if (d.bloom && !wantsParticles && !wantsTrails) {
       warnings.push(
-        "// @bloom does nothing here. A field effect (background/foreground) composites after tone " +
+        "#bloom does nothing here. A field effect (background/foreground) composites after tone " +
           "mapping, past the bloom pyramid — the directive applies to particles and ribbons, which draw " +
           "in HDR inside the scene pass. Make the effect's own falloff brighter instead.",
       )
@@ -3118,7 +3173,7 @@ export class Engine {
     let cursor = 0
     for (const [name, value] of entries) {
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
-        return { ok: false, diagnostics: [`invalid param name "${name}" (must be a WGSL identifier)`], mounts }
+        return { ok: false, diagnostics: [`invalid param name "${name}" (must be a WGSL identifier)`], mounts, params: d.params, duration: d.duration }
       }
       const isVec = typeof value !== "number"
       const align = isVec ? 16 : 4
@@ -3147,7 +3202,7 @@ export class Engine {
     // module (buildFieldShader), so a bad effect can no longer produce errors at
     // line numbers in a shader the author never wrote — and installing one no
     // longer recompiles the composite's tone-mapping half at all.
-    const gridSize = gridEntryPoint(wgsl) ? parseGridSize(wgsl, GRID_MAX) || 256 : 0
+    const gridSize = gridEntryPoint(wgsl) ? Math.min(d.grid || 256, GRID_MAX) : 0
     // `alias` goes in: a field effect reads bones through _rzSlot exactly as a
     // particle one does, and it was the only module never handed the mapping.
     const fieldEffect =
@@ -3156,11 +3211,11 @@ export class Engine {
     this.device.pushErrorScope("validation")
     const module = this.device.createShaderModule({ label: "composite shader (effect)", code: source })
     const scopeErr = await this.device.popErrorScope()
-    if (scopeErr) return { ok: false, diagnostics: [scopeErr.message], mounts }
+    if (scopeErr) return { ok: false, diagnostics: [scopeErr.message], mounts, params: d.params, duration: d.duration }
 
     // Declared like every other mount property: by what the source says, not by
     // a setting somewhere else that an author cannot see from the file.
-    const layerBlend = /^\s*\/\/\s*@layer\s+additive\s*$/m.test(wgsl)
+    const layerBlend = d.additiveLayer
       ? FIELD_LAYER_BLEND_ADDITIVE
       : FIELD_LAYER_BLEND
     let fieldPipeline: GPURenderPipeline | null = null
@@ -3175,7 +3230,7 @@ export class Engine {
         .filter((m) => m.type === "error")
         .map((m) => `${Math.max(0, m.lineNum - userLineOffset)}:${m.linePos} ${m.message}`)
       if (diagnostics.length === 0 && fieldScopeErr) diagnostics.push(fieldScopeErr.message)
-      if (diagnostics.length > 0) return { ok: false, diagnostics, mounts }
+      if (diagnostics.length > 0) return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration }
       try {
         fieldPipeline = await this.device.createRenderPipelineAsync({
           label: "field layer pipeline",
@@ -3201,7 +3256,7 @@ export class Engine {
           multisample: { count: 1 },
         })
       } catch (e) {
-        return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts }
+        return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts, params: d.params, duration: d.duration }
       }
     }
     let identity: GPURenderPipeline
@@ -3225,7 +3280,7 @@ export class Engine {
         make(true, "composite pipeline (effect, gamma!=1)"),
       ])
     } catch (e) {
-      return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts }
+      return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts, params: d.params, duration: d.duration }
     }
 
     // Built BEFORE the swap: a particle stage that fails to compile has to leave
@@ -3241,17 +3296,17 @@ export class Engine {
       grid?.textures[1].destroy()
       grid?.uniform.destroy()
       trails?.uniform.destroy()
-      return { ok: false, diagnostics, mounts }
+      return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration }
     }
     let particles: EffectParticles | null = null
     if (wantsParticles) {
-      const built = await this.buildParticles(wgsl, anchors, alias)
+      const built = await this.buildParticles(wgsl, d, anchors, alias)
       if (!built.ok) return abandon(built.diagnostics)
       particles = built.state
     }
     let grid: EffectGrid | null = null
     if (gridEntryPoint(wgsl)) {
-      const built = await this.buildSim(wgsl, anchors, alias)
+      const built = await this.buildSim(wgsl, d, anchors, alias)
       if (!built.ok) return abandon(built.diagnostics)
       grid = built.state
     }
@@ -3261,13 +3316,9 @@ export class Engine {
       // bone recorded without one would read zeroes and paint a line to the origin.
       const trailSlots = anchors.filter((a) => a.trail).length
       if (trailSlots === 0) {
-        return {
-          ok: false,
-          diagnostics: ["a ribbon effect needs at least one // @anchor <bone> trail"],
-          mounts,
-        }
+        return { ok: false, diagnostics: ["a ribbon effect needs at least one #anchor <bone> trail"], mounts, params: d.params, duration: d.duration }
       }
-      const built = await this.buildTrails(wgsl, anchors, alias)
+      const built = await this.buildTrails(wgsl, d, anchors, alias)
       if (!built.ok) return abandon(built.diagnostics)
       trails = built.state
     }
@@ -3280,13 +3331,13 @@ export class Engine {
     // count is a function nothing calls. Either alone is a silent blank, which
     // is the worst way for an effect to fail.
     let lights: EffectInstance["lights"] = null
-    const declaredLights = parseLightCount(wgsl, MAX_LIGHTS)
+    const declaredLights = Math.min(d.lights, MAX_LIGHTS)
     const emits = hasLightEmit(wgsl)
     if (declaredLights > 0 !== emits) {
       return abandon([
         emits
-          ? "an effect defining fn lightEmit(i: u32) -> RzLight must also declare how many with // @lights <n>"
-          : "// @lights <n> needs fn lightEmit(i: u32) -> RzLight to fill those slots",
+          ? "an effect defining fn lightEmit(i: u32) -> RzLight must also declare how many with #lights <n>"
+          : "#lights <n> needs fn lightEmit(i: u32) -> RzLight to fill those slots",
       ])
     }
     if (declaredLights > 0) {
@@ -3315,6 +3366,8 @@ export class Engine {
     }
     const instance: EffectInstance = {
         wgsl,
+        paramDecls: d.params,
+        duration: d.duration,
         paramLayout: layout,
         paramsBuffer,
         paramsData,
@@ -3329,9 +3382,30 @@ export class Engine {
         // The effect's own clock starts now. Per effect so that one installed
         // later still gets a frame where rzGridFrame() is 0 and can seed.
         epochScene: this.sceneClock,
+        // Fully on, unscheduled. An effect that is installed is showing;
+        // scheduling it is something a caller does afterwards, and an install
+        // that silently began at zero would look like a compile that failed.
+        influence: 1,
+        window: null,
+        weight: 1,
         // Its OWN resolution, no longer the scene's: an effect that never asked
         // for full res is not promoted because a neighbour did.
-        fieldLayer: /^\s*\/\/\s*@fullres\s*$/m.test(wgsl) ? 0 : 1,
+        // FULL RESOLUTION UNLESS TOLD OTHERWISE.
+        //
+        // It was the other way round, and the default was the bug. An author
+        // who has never heard of the flag writes an effect with an edge in it
+        // and gets a soft one — nothing fails, nothing warns, because nothing
+        // was declared to fail. Three shipped effects DID declare it and were
+        // half-res anyway on a parsing technicality, which is the same bug
+        // wearing a different hat: the safe answer has to be the one you get
+        // for saying nothing.
+        //
+        // The cost is real and is why the half layer stays: `#halfres` is worth
+        // about 3.7x on a full-screen effect (Footprints, measured, 1.2ms
+        // against 4.5ms). It is the right call for a soft additive glow, which
+        // upsamples invisibly — and it is now a claim an author makes about
+        // their own effect rather than a fate that befalls one.
+        fieldLayer: d.fieldLayer,
         fieldPipeline,
         fieldClock,
         // Filled by rebuildFieldBindGroup below, which needs the instance to
@@ -3373,7 +3447,7 @@ export class Engine {
     list: { wgsl: string; params?: Record<string, EffectParamValue> }[] | null,
   ): Promise<EffectResult[]> {
     const noMounts = { background: false, foreground: false }
-    if (!this.device) return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts }]
+    if (!this.device) return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts, params: [], duration: 0 }]
 
     const requested = list ?? []
     if (requested.length === 0) {
@@ -3399,7 +3473,14 @@ export class Engine {
 
     // One table for the whole scene, built before anything compiles: an effect's
     // alias is its row, and a bone two effects both name is allocated once.
-    const perEffectAnchors = requested.map((e) => parseEffectAnchors(e.wgsl, MAX_EFFECT_ANCHORS))
+    // The table needs every effect's anchors before any of them compiles, so
+    // this is the one place a source is read twice — compileEffect parses it
+    // again for everything else. A malformed file yields no anchors here and
+    // fails with its real diagnostics there, which is the right order: the
+    // error names the line, not the table.
+    const perEffectAnchors = requested.map((e) =>
+      parseDirectives(e.wgsl).directives.anchors.slice(0, MAX_EFFECT_ANCHORS),
+    )
     const table = buildAnchorTable(perEffectAnchors, MAX_EFFECT_ANCHORS)
 
     const results: EffectResult[] = []
@@ -3419,6 +3500,8 @@ export class Engine {
       instances.push(built.instance)
       results.push({
         ok: true,
+        params: built.instance.paramDecls,
+        duration: built.instance.duration,
         // Installed, and still with something to say — a directive that parsed
         // but will never fire. Same channel as the dropped-anchor note below.
         diagnostics: built.warnings,
@@ -3483,7 +3566,7 @@ export class Engine {
     this.compositePipelineIdentity = this.makeCompositePipeline(compositeModule, false, "composite pipeline (gamma=1)")
     this.compositePipelineGamma = this.makeCompositePipeline(compositeModule, true, "composite pipeline (gamma!=1)")
 
-    // Nothing to promote any more: `@fullres` is per effect, read into
+    // Nothing to promote any more: `#fullres` is per effect, read into
     // fieldLayer when the instance is built, and both target pairs exist for
     // the life of the surface. What used to be a scene-wide decision made here
     // is now each effect's own.
@@ -3501,14 +3584,18 @@ export class Engine {
     const noMounts = { background: false, foreground: false }
     if (wgsl === null) {
       await this.setEffects(null)
-      return { ok: true, diagnostics: [], mounts: noMounts }
+      return { ok: true, diagnostics: [], mounts: noMounts, params: [], duration: 0 }
     }
     const [result] = await this.setEffects([{ wgsl, params }])
-    return result ?? { ok: false, diagnostics: ["effect failed to install"], mounts: noMounts }
+    return result ?? { ok: false, diagnostics: ["effect failed to install"], mounts: noMounts, params: [], duration: 0 }
   }
 
   private async buildParticles(
+    /** Already stripped of directives — see compileEffect. */
     wgsl: string,
+    /** What the file declared. Read here rather than re-parsed: the source no
+     *  longer carries the lines, and two readers is how they drift. */
+    d: EffectDirectives,
     anchors: { bone: string; trail: boolean }[],
     /** This effect's local→scene slot map. Passed rather than read off the
      *  engine: the builders run BEFORE the swap, so this.anchorTable still
@@ -3517,8 +3604,8 @@ export class Engine {
   ): Promise<{ ok: true; state: EffectParticles } | { ok: false; diagnostics: string[] }> {
     // No pragma means "some": an author who wrote the trio clearly wants
     // particles, and failing over a missing comment would be pedantry.
-    const count = parseParticleCount(wgsl, Engine.MAX_PARTICLES) || 1024
-    const src = { wgsl, count, blend: parseParticleBlend(wgsl), bloom: parseParticleBloom(wgsl) }
+    const count = Math.min(d.particles || 1024, Engine.MAX_PARTICLES)
+    const src = { wgsl, count, blend: d.particleBlend, bloom: d.bloom }
     // Sparks want to spawn where a trail is, so the particle stages see the same
     // cast buffer the trail draw reads.
     const cast = {
@@ -3556,10 +3643,13 @@ export class Engine {
     })
     const uniform = this.device.createBuffer({
       label: "particle uniforms",
-      size: 16,
+      // Two vec4-sized rows: (time, dt, count, frame) and (weight, _, _, _).
+      // The first was exactly full, and weight has to live in the same buffer
+      // as the clock or a frame could draw one without the other.
+      size: 32,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
-    const uniformBytes = new ArrayBuffer(16)
+    const uniformBytes = new ArrayBuffer(32)
     const uniformView = { floats: new Float32Array(uniformBytes), uints: new Uint32Array(uniformBytes) }
 
     // Visibility is per LAYOUT, not shared: a read_write storage buffer may not be
@@ -3776,12 +3866,18 @@ export class Engine {
   private emitLights(encoder: GPUCommandEncoder): void {
     for (const e of this.effects) {
       const l = e.lights
+      // NOT skipped at weight 0, unlike every other mount. Each effect writes
+      // its OWN slots in a shared buffer that is never cleared, so a skipped
+      // dispatch leaves last frame's lights burning — the one place where not
+      // running is the wrong answer. The shader zeroes them instead, and the
+      // dispatch it costs is a single workgroup.
       if (!l || l.data[2] === 0) continue
       // The effect's OWN epoch — the same one its field, particle, ribbon and
       // grid halves now read. This was briefly conditional, to match a field
       // clock that was shared from the first installed effect; that clock is
       // per effect now, so every mount in one file agrees by construction.
       l.data[0] = this.sceneClock - e.epochScene
+      l.data[3] = e.weight
       this.device.queue.writeBuffer(l.uniform, 0, l.data.buffer as ArrayBuffer)
       const cp = encoder.beginComputePass({ label: "light emit" })
       cp.setPipeline(l.pipeline)
@@ -3796,6 +3892,11 @@ export class Engine {
       const p = e.particles
       if (!p) continue
       p.data[0] = this.sceneClock - e.epochScene
+      // The SIMULATION runs at every weight, 0 included — only the draw stops.
+      // A scheduled effect that froze while faded out would resume from the
+      // state it left rather than the one it would have reached, so fading one
+      // back in would rewind it.
+      p.data[4] = e.weight
       // Clamped: a backgrounded tab returns with a delta of whole seconds, and an
       // unclamped step flings every particle out of the scene in one frame.
       p.data[1] = Math.min(0.1, Math.max(0, deltaTime))
@@ -3814,7 +3915,7 @@ export class Engine {
   private renderParticles(pass: GPURenderPassEncoder, view: "camera" | "mirror"): void {
     for (const e of this.effects) {
       const p = e.particles
-      if (!p) continue
+      if (!p || e.weight === 0) continue
       pass.setPipeline(p.render)
       pass.setBindGroup(0, view === "mirror" ? p.mirrorRenderBind : p.renderBind)
       pass.draw(6, p.count)
@@ -3829,7 +3930,11 @@ export class Engine {
    * frame on the CPU.
    */
   private async buildTrails(
+    /** Already stripped of directives — see compileEffect. */
     wgsl: string,
+    /** What the file declared. Read here rather than re-parsed: the source no
+     *  longer carries the lines, and two readers is how they drift. */
+    d: EffectDirectives,
     anchors: { bone: string; trail: boolean }[],
     /** This effect's local→scene slot map. Passed rather than read off the
      *  engine: the builders run BEFORE the swap, so this.anchorTable still
@@ -3845,7 +3950,7 @@ export class Engine {
     // nothing before: ribbon i was read as anchor slot i.
     const ribbonSlots = anchors.map((a, i) => (a.trail ? i : -1)).filter((i) => i >= 0)
     const slots = ribbonSlots.length
-    const src = { wgsl, slots, ribbonSlots, blend: parseParticleBlend(wgsl), bloom: parseParticleBloom(wgsl) }
+    const src = { wgsl, slots, ribbonSlots, blend: d.particleBlend, bloom: d.bloom }
     const code = buildTrailShader(src, {
       subjects: MAX_EFFECT_SUBJECTS,
       samples: TRAIL_SAMPLES,
@@ -3982,7 +4087,7 @@ export class Engine {
    * Takes the pass rather than opening one: that IS the change.
    */
   private drawTrails(pass: GPURenderPassEncoder, view: "camera" | "mirror"): void {
-    const drawn = this.effects.filter((e) => e.trails)
+    const drawn = this.effects.filter((e) => e.trails && e.weight > 0)
     if (drawn.length === 0) return
     for (const e of drawn) {
       const t = e.trails!
@@ -4005,6 +4110,7 @@ export class Engine {
       if (view === "camera") {
         t.data[0] = this.sceneClock - e.epochScene
         t.data[1] = live
+        t.data[2] = e.weight
         this.device.queue.writeBuffer(t.uniform, 0, t.data.buffer as ArrayBuffer)
       }
       pass.setPipeline(t.pipeline)
@@ -4017,14 +4123,31 @@ export class Engine {
    *  upsample. Runs the whole quad — uniform control flow, so effects may use
    *  derivatives freely, which the old inline path had to forbid. */
   private renderFieldPass(encoder: GPUCommandEncoder): void {
-    const drawn = this.effects.filter((e) => e.fieldPipeline && e.fieldBindGroups)
-    if (drawn.length === 0) return
+    // TWO PREDICATES, deliberately, and they are not interchangeable.
+    //
+    // MOUNTED decides whether the pass runs, and it must agree exactly with
+    // fieldPairUsed — that is what the composite's bind group was built against,
+    // at install, and it is not rebuilt per frame. A pass skipped under a
+    // binding that still points at its target leaves the last frame it drew
+    // sitting there, so an effect faded to nothing would freeze on screen
+    // instead of disappearing.
+    //
+    // DRAWN decides what is drawn into it, and this is where weight is worth
+    // something: a field mount is a full-screen quad however little of the frame
+    // it ends up touching, so an effect that is scheduled off would otherwise
+    // shade every pixel to multiply it out to nothing. The pass still clears —
+    // which is what makes the layer transparent rather than stale — and shades
+    // nothing.
+    const mounted = this.effects.filter((e) => e.fieldPipeline && e.fieldBindGroups)
+    if (mounted.length === 0) return
+    const drawn = mounted.filter((e) => e.weight > 0)
     // Each effect's own clock, before the pass that reads it. Seconds since
     // THIS effect was installed — so an effect added to a running scene starts
     // at zero and can seed, rather than joining whatever the first one is up to.
     for (const e of drawn) {
       if (!e.fieldClock) continue
       this.fieldClockScratch[0] = this.sceneClock - e.epochScene
+      this.fieldClockScratch[1] = e.weight
       this.device.queue.writeBuffer(e.fieldClock, 0, this.fieldClockScratch.buffer as ArrayBuffer)
     }
     // ONE PASS PER RESOLUTION, N draws each, in document order — a pair is
@@ -4039,7 +4162,7 @@ export class Engine {
     // (fieldLayerView). Clearing and storing an empty full-res rgba16f pair is
     // two 16MB writes a frame to produce the transparent black the fallback
     // already is. Most scenes leave the full-res pair empty, since an effect only
-    // lands there by declaring @fullres.
+    // lands there by declaring #fullres.
     let stamped = false
     for (let i = 0; i < Engine.FIELD_SCALES.length; i++) {
       const bg = this.fieldBgViews[i]
@@ -4052,7 +4175,7 @@ export class Engine {
           { view: fg, clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: "clear", storeOp: "store" },
         ],
         // One query pair is reserved for "field", and it goes to the first pair
-        // that actually runs — full res when something declared @fullres, half
+        // that actually runs — full res when something declared #fullres, half
         // otherwise. Pinning it to i === 0 would have measured a pass that, now
         // that empty pairs are skipped, usually does not happen.
         timestampWrites: stamped ? undefined : this.stamps("field"),
@@ -4117,14 +4240,18 @@ export class Engine {
    * zero, so seeding is just "if frame is 0, return the initial state".
    */
   private async buildSim(
+    /** Already stripped of directives — see compileEffect. */
     wgsl: string,
+    /** What the file declared. Read here rather than re-parsed: the source no
+     *  longer carries the lines, and two readers is how they drift. */
+    d: EffectDirectives,
     anchors: { bone: string; trail: boolean }[],
     /** This effect's local→scene slot map. Passed rather than read off the
      *  engine: the builders run BEFORE the swap, so this.anchorTable still
      *  describes the effect that is still on screen. */
     alias: number[],
   ): Promise<{ ok: true; state: EffectGrid } | { ok: false; diagnostics: string[] }> {
-    const size = parseGridSize(wgsl, GRID_MAX) || 256
+    const size = Math.min(d.grid || 256, GRID_MAX)
     const cast = {
       subjects: MAX_EFFECT_SUBJECTS,
       samples: TRAIL_SAMPLES,
@@ -4263,10 +4390,19 @@ export class Engine {
     return { background: this.effect?.hasBackground ?? false, foreground: this.effect?.hasForeground ?? false }
   }
 
-  /** Write one effect param (declared at setEffect) — a uniform write, no
-   *  recompile; the instant tier, like setStyleParam. */
-  setEffectParam(name: string, value: EffectParamValue): void {
-    const fx = this.effect
+  /**
+   * Set one parameter on one INSTANCE.
+   *
+   * By index, because the scene holds a list and the same effect may appear in
+   * it twice with different values — which is the whole point of an instance
+   * and was impossible while this addressed `this.effect`, a singular left over
+   * from when a scene could wear exactly one.
+   *
+   * A write, not a recompile: parameters live in their own uniform buffer, so
+   * dragging a slider costs a 16-byte upload rather than a shader build.
+   */
+  setEffectParam(index: number, name: string, value: EffectParamValue): void {
+    const fx = this.effects[index]
     if (!fx || !fx.paramsBuffer) return
     const slot = fx.paramLayout.get(name)
     if (!slot) return
@@ -4279,6 +4415,119 @@ export class Engine {
     this.device.queue.writeBuffer(fx.paramsBuffer, 0, fx.paramsData)
   }
 
+  /**
+   * How much of one instance is showing, 0..1.
+   *
+   * The third of the three things an instance has — parameters, weight, time —
+   * and the one a scheduler drives. Weight is not a parameter: a parameter is
+   * whatever the author decided to expose and means only what their source
+   * makes it mean, while weight means the same thing for every effect ever
+   * written, including one whose author never heard of it. That is why it is
+   * applied by engine-generated code at each mount's output rather than handed
+   * to the source as a uniform to respect.
+   *
+   * At 0 nothing is drawn: no field quad, no particle draw, no ribbon, no light
+   * dispatch. A scheduled effect outside its window costs its simulation and
+   * nothing else — and a particle effect keeps simulating on purpose, so that
+   * fading one back in continues rather than rewinds.
+   *
+   * Instant, and free: a float in a uniform every mount already uploads once a
+   * frame. Nothing recompiles, so this is safe to drive per frame from a
+   * timeline.
+   */
+  setEffectInfluence(index: number, influence: number): void {
+    const fx = this.effects[index]
+    if (!fx) return
+    // Clamped rather than trusted: above 1 the field's own clamp would swallow
+    // it while an additive particle would happily keep getting brighter, so the
+    // same number would mean two things.
+    fx.influence = Math.min(1, Math.max(0, influence))
+  }
+
+  getEffectInfluence(index: number): number {
+    return this.effects[index]?.influence ?? 0
+  }
+
+  /**
+   * Schedule one instance: when it is alive, and how it enters and leaves.
+   *
+   * Null is the unscheduled case — on for the whole scene, on the scene's own
+   * clock — and is what an effect starts as.
+   *
+   * The engine evaluates this every frame rather than taking a weight from a
+   * caller, because every loop that renders would otherwise have to remember to
+   * drive it. The offline export loop already carries a scar about exactly that
+   * shape of bug. Evaluating where the scene clock advances means playback and
+   * export cannot disagree, and neither can forget.
+   *
+   * A caller that wants to drive an effect from something OTHER than the scene
+   * clock — an animation's progress, a skill firing — leaves this null and
+   * writes setEffectInfluence and setEffectTime itself, per frame. Both paths
+   * exist on purpose; this one is what a timeline wants.
+   */
+  setEffectSchedule(index: number, windows: readonly EffectWindow[] | null): void {
+    const fx = this.effects[index]
+    if (!fx) return
+    fx.window = windows && windows.length ? windows : null
+  }
+
+  getEffectSchedule(index: number): readonly EffectWindow[] | null {
+    return this.effects[index]?.window ?? null
+  }
+
+  /**
+   * Every scheduled effect, at the current scene clock.
+   *
+   * Called once a frame, BEFORE anything reads a weight or a clock. An effect
+   * with no window keeps whatever a caller last set, which is what makes the
+   * manual path above work — evaluating it would fight the caller for the field
+   * every frame.
+   */
+  private evaluateEffectSchedules(): void {
+    // Read ONCE: it walks the cast, and every effect wants the same answer.
+    const transport = this.transportTime()
+    for (const fx of this.effects) {
+      if (!fx.window || fx.window.length === 0) {
+        fx.weight = fx.influence
+        continue
+      }
+      const at = effectState(fx.window, fx.influence, transport)
+      fx.weight = at.weight
+      // Its own clock, expressed the way the mounts read it. Every mount
+      // derives time from the epoch against sceneClock, so this one write moves
+      // the field, the particles, the ribbons, lightEmit and the grid together
+      // — and hands them the STRIP's local time while they keep running on the
+      // smooth monotonic clock a particle integrator needs.
+      fx.epochScene = this.sceneClock - at.time
+    }
+  }
+
+  /**
+   * Move one instance's own clock to a given second.
+   *
+   * Everything an effect can animate is derived from its epoch — the field
+   * clock, the particle and ribbon clocks, lightEmit's time argument, the grid's
+   * frame counter — so moving the epoch moves all of them together and there is
+   * no mount that can be left reading last frame's time.
+   *
+   * This is what lets an effect be SCHEDULED rather than merely switched on: an
+   * instance that enters at bar 33 is handed a time that starts at zero there,
+   * so it plays its own opening instead of joining whatever the scene clock had
+   * reached. Feeding it the transport's time instead gives the other reading —
+   * an effect that runs in lockstep with the music — and both are one call.
+   */
+  setEffectTime(index: number, time: number): void {
+    const fx = this.effects[index]
+    if (!fx) return
+    fx.epochScene = this.sceneClock - time
+  }
+
+
+  getEffectTime(index: number): number {
+    const fx = this.effects[index]
+    return fx ? this.sceneClock - fx.epochScene : 0
+  }
+
   /** Patch bloom; GPU uniforms update immediately if `init()` has run. */
   /** Camera depth of field (see DepthOfFieldOptions). Free while disabled —
    *  the scene pass only stores its depth buffer on frames the gather reads. */
@@ -4305,7 +4554,9 @@ export class Engine {
     if (!this.camera) return null
     const view = this.camera.getViewMatrix().values
     for (const inst of this.modelInstances.values()) {
-      if (!inst.model.visible || inst.isStage) continue
+      // Neither a stage nor a plane is a performer, so neither is a subject an
+      // effect can follow.
+      if (!inst.model.visible || inst.isStage || inst.isPlane) continue
       const model = inst.model
       const matrices = model.getWorldMatrices()
       if (matrices.length === 0) continue
@@ -5938,7 +6189,7 @@ export class Engine {
         usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
       })
 
-      // The field layer — half resolution by default, full for @fullres effects.
+      // The field layer — half resolution by default, full for #fullres effects.
       this.fieldFullW = width
       this.fieldFullH = height
       this.createFieldTargets()
@@ -6822,10 +7073,24 @@ export class Engine {
     this.camera.setVmdDriven(false)
   }
 
-  // Clock the camera VMD runs on: the first model with an active clip (playing or scrubbed),
-  // so a static stage in the scene never freezes the shot at frame 0. Falls back to the first
-  // model, then to 0 (empty scene).
-  private cameraClockTime(): number {
+  /**
+   * THE TRANSPORT'S CLOCK — where the scene is in its own playback.
+   *
+   * The first model with an active clip (playing or scrubbed), so a static stage
+   * never freezes it at frame 0. Falls back to the first model with a clip, then
+   * to 0 for an empty scene.
+   *
+   * NOT `sceneClock`, and the difference is the whole reason this has a name.
+   * `sceneClock` only ever accumulates delta — it is how long the engine has
+   * been running, it does not move when you scrub, and it does not stop when you
+   * pause. Anything that should line up with what the transport shows has to
+   * read THIS. An effect scheduled to frame 100 against sceneClock fires once,
+   * a hundred frames after the page loaded, and never again.
+   *
+   * Deterministic offline: the export loop advances model animation by an exact
+   * per-frame delta, so this reproduces frame for frame.
+   */
+  private transportTime(): number {
     let fallback: number | null = null
     for (const inst of this.modelInstances.values()) {
       // Stages are skipped outright. Scenery carries no motion, and it is added
@@ -6833,7 +7098,7 @@ export class Engine {
       // is first in insertion order and was seeding this clock with its own
       // permanent zero. In a scene with a stage, a camera VMD therefore sampled
       // frame 0 forever and the shot never moved.
-      if (inst.isStage) continue
+      if (inst.isStage || inst.isPlane) continue
       const p = inst.model.getAnimationProgress()
       if (p.playing || p.paused) return p.current
       // Otherwise the first cast member that actually HAS a clip: one still at
@@ -7223,7 +7488,7 @@ export class Engine {
     pmxPath: string,
     name?: string,
     assetReader?: AssetReader,
-    options?: { stage?: boolean },
+    options?: { stage?: boolean; plane?: boolean; dynamic?: boolean },
   ): Promise<string> {
     const requested = name ?? model.name
     let key = requested
@@ -7234,7 +7499,15 @@ export class Engine {
     const reader = assetReader ?? createFetchAssetReader()
     const basePath = deriveBasePathFromPmxPath(pmxPath)
     model.setAssetContext(reader, basePath)
-    await this.setupModelInstance(key, model, basePath, reader, options?.stage ?? false)
+    await this.setupModelInstance(
+      key,
+      model,
+      basePath,
+      reader,
+      options?.stage ?? false,
+      options?.plane ?? false,
+      options?.dynamic ?? false,
+    )
     return key
   }
 
@@ -7267,6 +7540,191 @@ export class Engine {
     return key
   }
 
+  /**
+   * Put a picture in the scene as a flat card.
+   *
+   * The thing compositors arrange in a post tool's fake 3D space — Nuke calls
+   * it a Card, After Effects a 3D layer, MMD 板ポリ — except the space here is
+   * the real one. A card is occluded by anything in front of it, occludes what
+   * is behind it, takes perspective when turned, and is caught by depth of
+   * field like everything else, because it is ordinary geometry rather than a
+   * layer composited afterwards.
+   *
+   * It is a MODEL, deliberately. Not a new kind of scene object with its own
+   * list, its own persistence and its own selection: a card wants a position,
+   * a rotation and a size, which is exactly what a model already has, and
+   * everything built around models — the transform, the shadow settings, the
+   * material editor, the asset bundle — works on it the day it exists. It is
+   * not a STAGE, though: it skips the same machinery for the same reasons, and
+   * leaves the floor alone. See ModelInstance.isPlane.
+   *
+   * @returns the model key, for setModelTransform and removeModel.
+   */
+  async addPlane(options: {
+    /** The picture's own bytes, exactly as uploaded. The name's extension picks
+     *  the decoder, so this never re-encodes anything. */
+    image: ArrayBuffer
+    /** File name — decides the decoder, names the model and keys its texture. */
+    name: string
+    /** World size of the card. The caller owns the aspect: it knows the
+     *  picture's own proportions, and a card is free to disagree with them. */
+    width: number
+    height: number
+    transform?: Partial<ModelTransform>
+    /** Drawn from behind as well. Off by default — a card turned away from the
+     *  camera vanishing is the same thing a sheet of paper does. */
+    doubleSided?: boolean
+    /** The picture will be replaced every frame (see setPlaneFrame). Allocates
+     *  the texture without a mip chain, which is what makes that affordable. */
+    dynamic?: boolean
+  }): Promise<string> {
+    const { image, name, width, height } = options
+    const hw = Math.max(width, 1e-4) / 2
+    const hh = Math.max(height, 1e-4) / 2
+
+    // A quad on the XY plane, facing +Z, centred on its own origin — so a
+    // rotation turns it about its middle and a position places its centre,
+    // which is what a handle in the viewport implies.
+    //
+    // V IS FLIPPED, and this is the whole of it: a picture's rows run downward
+    // from its top-left, a UV runs upward from the bottom-left, and a card that
+    // renders its image upside down looks like a bug in everything else.
+    // prettier-ignore
+    const vertexData = new Float32Array([
+      // x     y     z    nx   ny   nz   u    v
+      -hw,  -hh,  0.0,  0.0, 0.0, 1.0,  0.0, 1.0,
+       hw,  -hh,  0.0,  0.0, 0.0, 1.0,  1.0, 1.0,
+       hw,   hh,  0.0,  0.0, 0.0, 1.0,  1.0, 0.0,
+      -hw,   hh,  0.0,  0.0, 0.0, 1.0,  0.0, 0.0,
+    ])
+    // Two triangles, counter-clockwise seen from +Z. A second pair wound the
+    // other way is how "visible from behind" is done here, rather than a
+    // per-material cull flag the rest of the engine has no concept of.
+    const indices = options.doubleSided ? [0, 1, 2, 0, 2, 3, 0, 2, 1, 0, 3, 2] : [0, 1, 2, 0, 2, 3]
+    const indexData = new Uint32Array(indices)
+
+    // The texture table's one entry. The path is a key, not a location — the
+    // reader below answers it from memory, so nothing is fetched and nothing is
+    // written to disk.
+    //
+    // A PLAIN RELATIVE NAME under a plain directory, because the loader treats
+    // this exactly as it treats a PMX's: it takes the model path's directory
+    // and JOINS the texture entry onto it. A scheme-looking path went through
+    // that as `plane://` + `plane://name` and matched nothing, so every card
+    // came out with the untextured fallback. `plane/<name>` joins to
+    // `plane/<name>` and stays unique per card, which the engine-wide texture
+    // cache needs it to be.
+    const texturePath = `plane/${name}`
+    const material: Material = {
+      name,
+      diffuse: [1, 1, 1, 1],
+      specular: [0, 0, 0],
+      ambient: [0, 0, 0],
+      shininess: 0,
+      diffuseTextureIndex: 0,
+      normalTextureIndex: -1,
+      sphereTextureIndex: -1,
+      sphereMode: 0,
+      toonTextureIndex: -1,
+      sharedToon: false,
+      // 0 CARRIES TWO DECISIONS, both wanted, and both silent if changed.
+      //
+      // No inverted-hull outline (bit 0x10): a card is not a character, and a
+      // black rim around a light leak is the opposite of what it is for.
+      //
+      // AND NO SHADOW (bit 0x04, which is what castsShadow reads). A card is
+      // usually light or artwork rather than an object, and a rectangle of hard
+      // shadow thrown across the stage by a gradient reads as the renderer
+      // being broken. Set geometry that SHOULD cast one is the rarer case, and
+      // it can say so.
+      edgeFlag: 0,
+      edgeColor: [0, 0, 0, 1],
+      edgeSize: 0,
+      vertexCount: indices.length,
+    }
+
+    // ONE BONE, because Model requires one — it throws on an empty skeleton,
+    // every vertex has to be skinned to something, and a card has nothing to
+    // articulate. It is never posed; the model transform is what moves a card.
+    const skeleton: Skeleton = {
+      bones: [{ name: "全ての親", parentIndex: -1, bindTranslation: [0, 0, 0], children: [] }],
+      inverseBindMatrices: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+    }
+    const vertexCount = 4
+    const joints = new Uint16Array(vertexCount * 4)
+    const weights = new Uint8Array(vertexCount * 4)
+    for (let i = 0; i < vertexCount; i++) weights[i * 4] = 255
+
+    const model = new Model(
+      vertexData,
+      indexData,
+      [{ path: name, name }],
+      [material],
+      skeleton,
+      { joints, weights },
+      { morphs: [] },
+    )
+
+    // ITS OWN PATH, not addStage's. A plane and a stage skip the same machinery
+    // and mean different things, and routing one through the other is how the
+    // ground came to be suppressed by adding a picture.
+    // The picture answers from memory, whatever it is asked for: a card has
+    // exactly ONE texture, so there is nothing to disambiguate and no way for a
+    // path to be wrong. Matching the string instead is what silently produced
+    // untextured cards, because the loader composes that string itself.
+    const reader: AssetReader = { readBinary: async () => image }
+    const key = await this.addModel(model, texturePath, name, reader, { plane: true, dynamic: options.dynamic })
+
+    // UNLIT, because a card is FOOTAGE and not a surface.
+    //
+    // Its pixels were finished somewhere else — a gradient painted in
+    // Photoshop, a title, a rendered element — so its brightness is the artwork
+    // rather than a response to anything. Shading it means the sun dimming one
+    // side of a thing that has no sides, and the world colour tinting a picture
+    // whose colour was the point. Left ungrouped it would take the neutral
+    // Principled base, which is exactly that mistake.
+    //
+    // A group, not a hard-coded pipeline: a card used as SET geometry — a photo
+    // of a wall, a poster standing in the room — genuinely does want the light,
+    // and this is the same control every other material is changed through, so
+    // that case is a graph swap rather than a feature request.
+    await this.applyStyleGroups(key, [
+      { id: "plane", label: "Plane", materials: [name], graph: UNLIT_GRAPH, alphaMode: "hashed" },
+    ])
+
+    if (options.transform) this.setModelTransform(key, options.transform)
+    // Kept so a moving card can push frames into it. The cache is keyed by the
+    // texture's logical path, which is derived rather than stored anywhere the
+    // caller can see — and deriving it twice is how the two would drift.
+    const tex = this.textureCache.get(texturePath)
+    if (tex) this.planeTextures.set(key, tex)
+    return key
+  }
+
+  /**
+   * Replace what a card is showing, in place.
+   *
+   * For a moving card: a video element, a decoded frame, a canvas — anything
+   * copyExternalImageToTexture accepts. Nothing is reallocated and no bind group
+   * is rebuilt, so this is a per-frame call rather than a per-clip one; the
+   * texture is written where it stands and the material keeps pointing at it.
+   *
+   * The frame must be the size the card was created at. A card is a fixed
+   * rectangle of texels and resizing one mid-clip would mean rebuilding the
+   * material behind it — so the caller allocates the card at its video's size
+   * and this refuses anything else rather than stretching it silently.
+   */
+  setPlaneFrame(id: string, source: GPUCopyExternalImageSource, width: number, height: number): boolean {
+    const tex = this.planeTextures.get(id)
+    if (!tex || !this.device) return false
+    if (tex.width !== width || tex.height !== height) return false
+    this.device.queue.copyExternalImageToTexture({ source }, { texture: tex }, [width, height])
+    // A moving card is allocated with one level precisely so this is never
+    // reached: rebuilding a mip pyramid per frame is a pass per level per card.
+    if (tex.mipLevelCount > 1) this.generateMipmaps(tex, tex.mipLevelCount)
+    return true
+  }
+
   /** True while a stage is in the scene. Two things turn on it: the built-in
    *  ground plane must not draw, and the far shadow cascade has nothing to
    *  cover without one (see the cascade loop). */
@@ -7289,6 +7747,9 @@ export class Engine {
   removeModel(name: string): void {
     const inst = this.modelInstances.get(name)
     if (!inst) return
+    // Before the texture cache below frees it: a stale entry here would hand a
+    // destroyed texture to the next setPlaneFrame.
+    this.planeTextures.delete(name)
     inst.model.stop()
     for (const path of inst.textureCacheKeys) {
       const tex = this.textureCache.get(path)
@@ -7563,10 +8024,10 @@ export class Engine {
       // A stage never solves IK — nothing drives its chains — and skips the pose
       // pass entirely while it is idle. Morph changes still come through, since
       // that is the one thing a stage's controls do move.
-      const stageIdle = inst.isStage && inst.model.isIdle()
+      const stageIdle = (inst.isStage || inst.isPlane) && inst.model.isIdle()
       let verticesChanged = false
       if (!stageIdle) {
-        verticesChanged = inst.model.update(deltaTime, inst.isStage ? false : this.ikEnabled)
+        verticesChanged = inst.model.update(deltaTime, inst.isStage || inst.isPlane ? false : this.ikEnabled)
         inst.skinMatricesDirty = true
       }
       animMs += performance.now() - tAnim
@@ -7989,6 +8450,8 @@ export class Engine {
 
   /** Every shadow caster in one sphere: (x, y, z, radius). radius 0 = nothing
    *  casts, -1 = do not use (a rigid caster has no sphere). See updateCasterSphere. */
+  /** A card's own texture, by model key — see setPlaneFrame. */
+  private planeTextures = new Map<string, GPUTexture>()
   private casterSphere = new Float32Array(4)
 
   /** The ground's uniform block, kept so the caster sphere can be refreshed in
@@ -8560,6 +9023,8 @@ export class Engine {
     basePath: string,
     assetReader: AssetReader,
     isStage = false,
+    isPlane = false,
+    dynamicTexture = false,
   ): Promise<void> {
     const vertices = model.getVertices()
     const skinning = model.getSkinning()
@@ -8620,7 +9085,7 @@ export class Engine {
     // A stage never simulates, so its bodies are never built — constructing the
     // solver for the heaviest mesh in the scene and dropping it afterwards was
     // both wasted work and an invariant maintained in the wrong place.
-    const physics = !isStage && rbs.length > 0 ? new RezePhysics(rbs, model.getJoints()) : null
+    const physics = !isStage && !isPlane && rbs.length > 0 ? new RezePhysics(rbs, model.getJoints()) : null
     // Which bones the simulation will overwrite, handed to the pose pipeline so
     // the append (付与) pass can consume the simulated result instead of the
     // animated one. Precomputed here, once, because the answer is topology —
@@ -8700,6 +9165,8 @@ export class Engine {
       pickPerInstanceBindGroup,
       pickDrawCalls: [],
       isStage,
+      isPlane,
+      dynamicTexture,
       // Seeded true: the bind pose has to reach the GPU once before any frame.
       skinMatricesDirty: true,
       hiddenMaterials: new Set(),
@@ -9200,7 +9667,21 @@ export class Engine {
       bounds[4] += grow
       bounds[5] += grow
 
-      const type: DrawCallType = isTransparent ? "transparent" : "opaque"
+      // A CARD IS ALWAYS OPAQUE-PHASE, whatever its alpha says.
+      //
+      // The scene pass runs opaque -> ground -> transparent, and the ground
+      // writes depth at every opacity (effects locate the floor by it). Every
+      // card qualifies as transparent — a cutout has translucent texels, and a
+      // video card starts from a blank sheet that is nothing but — so cards
+      // drew after the ground and an INVISIBLE floor rejected them. Turning the
+      // ground down for the shadow catcher made pictures disappear into it.
+      //
+      // Not a workaround: alphaMode "hashed" is alpha-to-coverage, which is the
+      // transparency technique built for this phase, and addPlane already sets
+      // it. The cost is dithering on a large soft gradient, where MSAA has four
+      // coverage levels to spend — a cutout edge, which is what a card usually
+      // has, resolves exactly.
+      const type: DrawCallType = inst.isPlane ? "opaque" : isTransparent ? "transparent" : "opaque"
       inst.drawCalls.push({
         type,
         count: indexCount,
@@ -9516,7 +9997,13 @@ export class Engine {
     }
     this.textureAlphaCache.set(cacheKey, alphaPlane)
 
-    const mipLevelCount = Math.floor(Math.log2(Math.max(width, height))) + 1
+    // NO MIPS FOR A MOVING CARD. The chain would have to be rebuilt on every
+    // frame written into it — a full pyramid of render passes per video plane
+    // per frame, which is most of what a moving card was costing. Level 0 is
+    // the only level a card in frame reads anyway; the price is aliasing on one
+    // shrunk far into the distance, which is the case a video card is least
+    // often in.
+    const mipLevelCount = inst.dynamicTexture ? 1 : Math.floor(Math.log2(Math.max(width, height))) + 1
     const texture = this.device.createTexture({
       label: `texture: ${cacheKey}`,
       size: [width, height],
@@ -10254,7 +10741,7 @@ export class Engine {
 
     // Drive the shot from the camera VMD (synced to the animated model's clock).
     if (this.camera.vmdDriven && this.cameraAnimation) {
-      const pose = this.cameraAnimation.sample(this.cameraClockTime())
+      const pose = this.cameraAnimation.sample(this.transportTime())
       if (pose) this.camera.setVmdPose(pose)
     }
 
@@ -10389,6 +10876,12 @@ export class Engine {
     // uniforms this frame.
     this.evaluateDissolveCycles()
     this.evaluateParamTracks()
+    // FIRST among the things that read an effect, because every one of them
+    // reads what this writes: the sim's clock, the particle uniform's weight,
+    // the light dispatch, the field draw. Evaluated here rather than by a
+    // caller so that playback, the export loop and a warm-up pass cannot
+    // disagree about when an effect is alive — none of them has to remember it.
+    this.evaluateEffectSchedules()
     this.stepSim(encoder, deltaTime)
     this.stepParticles(encoder, deltaTime)
     // Before the scene pass, which READS the slots this writes. Same buffer,
@@ -10450,7 +10943,7 @@ export class Engine {
     this.forEachInstance((inst) => this.renderModelTransparentPhase(pass, inst, camView))
     // Last in the pass: depth-tested against everything drawn above, so a
     // particle behind the character is simply hidden, and still inside the HDR
-    // target so an `@bloom` effect reaches the pyramid below.
+    // target so an `#bloom` effect reaches the pyramid below.
     this.renderParticles(pass, "camera")
     // Ribbons, in the same pass and after the particles: both are additive
     // light in HDR, and both reach the bloom pyramid because of it. This used