reze-engine 0.50.12 → 0.52.0

package/dist/engine.js

@@ -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 { MATERIAL_MORPH_MULTIPLY } from "./model";
+import { Model, MATERIAL_MORPH_MULTIPLY } from "./model";
 import { MORPH_COMPUTE_WGSL } from "./shaders/passes/morph";
 import { CULL_COMPUTE_WGSL } from "./shaders/passes/cull";
 import { buildAnchorTable, anchorAliasWgsl, EMPTY_ANCHOR_TABLE } from "./shaders/anchor-table";
@@ -19,13 +19,14 @@ 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 } from "./param-track";
+import { effectState } from "./effect-schedule";
 import { SHADOW_CASCADES, buildShadowVP } from "./shadow-cascades";
 import { REFLECTION_DEBUG_WGSL, buildMirrorCamera } from "./reflection";
 import { packHalf } from "./hdr";
 import { evalIrradianceSH, projectIrradianceSH } from "./ibl";
 import { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, LYRICS_FLOATS, packLyrics } from "./shaders/lyrics-api";
 import { sceneTargets as sceneTargetsFor, sceneColorFormats, setMrtIds, mrtIdsEnabled, SCENE_ID_FORMAT, } from "./shaders/passes/scene-contract";
-import { LIGHT_HEADER, LIGHT_STRIDE, LIGHTS_FLOATS, MAX_LIGHTS, buildLightEmitShader, hasLightEmit, parseLightCount, } from "./shaders/lights";
+import { LIGHT_HEADER, LIGHT_STRIDE, LIGHTS_FLOATS, MAX_LIGHTS, buildLightEmitShader, hasLightEmit, } from "./shaders/lights";
 import { groundShaderWgsl, GROUND_NOISE_BAKE_WGSL, GROUND_NOISE_SIZE } from "./shaders/passes/ground";
 import { outlineShaderWgsl } from "./shaders/passes/outline";
 import { transparentDepthPrepassWgsl } from "./shaders/passes/depth-prepass";
@@ -33,14 +34,16 @@ import { SELECTION_MASK_SHADER_WGSL, SELECTION_EDGE_SHADER_WGSL } from "./shader
 import { GIZMO_SHADER_WGSL } from "./shaders/passes/gizmo";
 import { BLOOM_BLIT_SHADER_WGSL, BLOOM_DOWNSAMPLE_SHADER_WGSL, BLOOM_UPSAMPLE_SHADER_WGSL, } from "./shaders/passes/bloom";
 import { AGX_LUT_GZ, AGX_LUT_SIZE } from "./shaders/agx-lut";
-import { buildCompositeShader, EFFECT_SCENE_API, buildFieldShader, parseEffectAnchors, EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES, } from "./shaders/passes/composite";
-import { buildParticleComputeShader, buildParticleRenderShader, parseParticleBlend, parseParticleBloom, parseParticleCount, particleEntryPoints, PARTICLE_STRIDE, } from "./shaders/passes/particles";
-import { SIM_FORMAT, GRID_MAX, buildSimShader, parseGridSize, gridEntryPoint, } from "./shaders/passes/grid";
+import { buildCompositeShader, EFFECT_SCENE_API, buildFieldShader, EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES, } from "./shaders/passes/composite";
+import { buildParticleComputeShader, buildParticleRenderShader, particleEntryPoints, PARTICLE_STRIDE, } from "./shaders/passes/particles";
+import { SIM_FORMAT, GRID_MAX, buildSimShader, gridEntryPoint, } from "./shaders/passes/grid";
 import { buildTrailShader, trailEntryPoints, TRAIL_SUBDIVISIONS } from "./shaders/passes/trails";
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick";
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap";
 import { compileGraph } from "./graph/compile";
 import { DEFAULT_GRAPH } from "./graph/presets/default";
+import { parseDirectives, stripDirectives } 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";
@@ -596,13 +599,13 @@ const FIELD_LAYER_BLEND = {
     alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
 };
 /**
- * `// @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
@@ -983,6 +986,8 @@ export class Engine {
         this.framePhysicsMsRaw = 0;
         /** 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. */
+        this.planeTextures = new Map();
         this.casterSphere = new Float32Array(4);
         /** The ground's uniform block, kept so the caster sphere can be refreshed in
          *  it every frame rather than rebuilding the buffer (addGround allocates). */
@@ -2075,7 +2080,9 @@ export class Engine {
      * is KEPT and diagnostics are returned with line numbers relative to the
      * user's WGSL. Pass null to remove the effect.
      */
-    async compileEffect(wgsl, params, 
+    async compileEffect(
+    /** The author's file, directives included — parsed here and nowhere else. */
+    authored, params, 
     /** This effect's own declarations, already parsed by the caller — which had
      *  to read them anyway to build the scene table. */
     anchors, 
@@ -2083,7 +2090,22 @@ export class Engine {
     alias) {
         const noMounts = { background: false, foreground: false };
         if (!this.device)
-            return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts };
+            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
         // `fn` keyword is enough to be safe against a `foreground` LOCAL or a call
@@ -2099,14 +2121,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 = [
@@ -2114,7 +2132,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.
         //
@@ -2129,35 +2147,27 @@ 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
@@ -2170,8 +2180,8 @@ export class Engine {
         // pinning an effect that declares this has to keep installing; saying so is
         // all that was ever missing.
         const warnings = [];
-        if (parseParticleBloom(wgsl) && !wantsParticles && !wantsTrails) {
-            warnings.push("// @bloom does nothing here. A field effect (background/foreground) composites after tone " +
+        if (d.bloom && !wantsParticles && !wantsTrails) {
+            warnings.push("#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.");
         }
@@ -2191,7 +2201,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;
@@ -2220,7 +2230,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 = hasBackground || hasForeground ? { wgsl, paramsDecl, hasBackground, hasForeground, gridSize, alias, trailCount: anchors.filter((a) => a.trail).length } : null;
@@ -2229,10 +2239,10 @@ export class Engine {
         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 };
+            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 = null;
@@ -2249,7 +2259,7 @@ export class Engine {
             if (diagnostics.length === 0 && fieldScopeErr)
                 diagnostics.push(fieldScopeErr.message);
             if (diagnostics.length > 0)
-                return { ok: false, diagnostics, mounts };
+                return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration };
             try {
                 fieldPipeline = await this.device.createRenderPipelineAsync({
                     label: "field layer pipeline",
@@ -2276,7 +2286,7 @@ export class Engine {
                 });
             }
             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;
@@ -2300,7 +2310,7 @@ export class Engine {
             ]);
         }
         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
         // the previously installed effect running, exactly as a bad composite does.
@@ -2315,18 +2325,18 @@ 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 = 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 = 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;
@@ -2337,13 +2347,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;
@@ -2356,13 +2362,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 = 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) {
@@ -2390,6 +2396,8 @@ export class Engine {
         }
         const instance = {
             wgsl,
+            paramDecls: d.params,
+            duration: d.duration,
             paramLayout: layout,
             paramsBuffer,
             paramsData,
@@ -2404,9 +2412,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
@@ -2446,7 +2475,7 @@ export class Engine {
     async setEffects(list) {
         const noMounts = { background: false, foreground: false };
         if (!this.device)
-            return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts }];
+            return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts, params: [], duration: 0 }];
         const requested = list ?? [];
         if (requested.length === 0) {
             for (const e of this.effects) {
@@ -2470,7 +2499,12 @@ 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 = [];
         const instances = [];
@@ -2484,6 +2518,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,
@@ -2543,7 +2579,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.
@@ -2560,20 +2596,25 @@ 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 };
-    }
-    async buildParticles(wgsl, anchors, 
+        return result ?? { ok: false, diagnostics: ["effect failed to install"], mounts: noMounts, params: [], duration: 0 };
+    }
+    async buildParticles(
+    /** Already stripped of directives — see compileEffect. */
+    wgsl, 
+    /** 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, anchors, 
     /** 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) {
         // 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 = {
@@ -2611,10 +2652,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
         // visible to the vertex stage at all (WebGPU forbids it — a vertex shader
@@ -2820,6 +2864,11 @@ export class Engine {
     emitLights(encoder) {
         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
@@ -2827,6 +2876,7 @@ export class Engine {
             // 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);
             const cp = encoder.beginComputePass({ label: "light emit" });
             cp.setPipeline(l.pipeline);
@@ -2841,6 +2891,11 @@ export class Engine {
             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));
@@ -2858,7 +2913,7 @@ export class Engine {
     renderParticles(pass, view) {
         for (const e of this.effects) {
             const p = e.particles;
-            if (!p)
+            if (!p || e.weight === 0)
                 continue;
             pass.setPipeline(p.render);
             pass.setBindGroup(0, view === "mirror" ? p.mirrorRenderBind : p.renderBind);
@@ -2872,7 +2927,12 @@ export class Engine {
      * and several declared bones is still one draw and nothing is computed per
      * frame on the CPU.
      */
-    async buildTrails(wgsl, anchors, 
+    async buildTrails(
+    /** Already stripped of directives — see compileEffect. */
+    wgsl, 
+    /** 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, anchors, 
     /** 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. */
@@ -2886,7 +2946,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,
@@ -3023,7 +3083,7 @@ export class Engine {
      * Takes the pass rather than opening one: that IS the change.
      */
     drawTrails(pass, view) {
-        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) {
@@ -3047,6 +3107,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);
             }
             pass.setPipeline(t.pipeline);
@@ -3058,9 +3119,25 @@ 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. */
     renderFieldPass(encoder) {
-        const drawn = this.effects.filter((e) => e.fieldPipeline && e.fieldBindGroups);
-        if (drawn.length === 0)
+        // 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.
@@ -3068,6 +3145,7 @@ export class Engine {
             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);
         }
         // ONE PASS PER RESOLUTION, N draws each, in document order — a pair is
@@ -3082,7 +3160,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];
@@ -3096,7 +3174,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"),
@@ -3160,12 +3238,17 @@ export class Engine {
      * against: rzGridFrame() is 0 on the first step and every value it reads is
      * zero, so seeding is just "if frame is 0, return the initial state".
      */
-    async buildSim(wgsl, anchors, 
+    async buildSim(
+    /** Already stripped of directives — see compileEffect. */
+    wgsl, 
+    /** 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, anchors, 
     /** 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) {
-        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,
@@ -3300,10 +3383,19 @@ export class Engine {
     getEffectMounts() {
         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, value) {
-        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, name, value) {
+        const fx = this.effects[index];
         if (!fx || !fx.paramsBuffer)
             return;
         const slot = fx.paramLayout.get(name);
@@ -3318,6 +3410,114 @@ 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, influence) {
+        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) {
+        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, windows) {
+        const fx = this.effects[index];
+        if (!fx)
+            return;
+        fx.window = windows && windows.length ? windows : null;
+    }
+    getEffectSchedule(index) {
+        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.
+     */
+    evaluateEffectSchedules() {
+        // 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, time) {
+        const fx = this.effects[index];
+        if (!fx)
+            return;
+        fx.epochScene = this.sceneClock - time;
+    }
+    getEffectTime(index) {
+        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. */
@@ -3345,7 +3545,9 @@ export class Engine {
             return null;
         const view = this.camera.getViewMatrix().values;
         for (const inst of this.modelInstances.values()) {
-            if (!inst.model.visible || inst.isStage)
+            // 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();
@@ -4866,7 +5068,7 @@ export class Engine {
                 format: this.hdrFormat,
                 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();
@@ -5701,10 +5903,24 @@ export class Engine {
         this.cameraAnimation = null;
         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).
-    cameraClockTime() {
+    /**
+     * 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.
+     */
+    transportTime() {
         let fallback = null;
         for (const inst of this.modelInstances.values()) {
             // Stages are skipped outright. Scenery carries no motion, and it is added
@@ -5712,7 +5928,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)
+            if (inst.isStage || inst.isPlane)
                 continue;
             const p = inst.model.getAnimationProgress();
             if (p.playing || p.paused)
@@ -6054,7 +6270,7 @@ 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;
     }
     /**
@@ -6082,6 +6298,163 @@ export class Engine {
             this.setModelTransform(key, options.transform);
         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) {
+        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 = {
+            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 = {
+            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 = { 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, source, width, height) {
+        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). */
@@ -6100,6 +6473,9 @@ export class Engine {
         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);
@@ -6352,10 +6728,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;
@@ -7305,7 +7681,7 @@ export class Engine {
                 });
         }
     }
-    async setupModelInstance(name, model, basePath, assetReader, isStage = false) {
+    async setupModelInstance(name, model, basePath, assetReader, isStage = false, isPlane = false, dynamicTexture = false) {
         const vertices = model.getVertices();
         const skinning = model.getSkinning();
         const skeleton = model.getSkeleton();
@@ -7348,7 +7724,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 —
@@ -7420,6 +7796,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(),
@@ -7841,7 +8219,21 @@ export class Engine {
             bounds[3] += grow;
             bounds[4] += grow;
             bounds[5] += grow;
-            const type = 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 = inst.isPlane ? "opaque" : isTransparent ? "transparent" : "opaque";
             inst.drawCalls.push({
                 type,
                 count: indexCount,
@@ -8134,7 +8526,13 @@ export class Engine {
                 `so sheer fabric will not blend. The canvas 2D readback is what failed.`);
         }
         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],
@@ -8623,7 +9021,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);
         }
@@ -8757,6 +9155,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,
@@ -8819,7 +9223,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
@@ -10261,14 +10665,14 @@ Engine.JIGGLE_DAMPING_SCALE = 0.5;
  * 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. */
 Engine.MAX_PARTICLES = 65536;
 /**
  * The field layer: user background/foreground mounts, ONE TARGET PAIR PER
  * 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
@@ -10292,7 +10696,7 @@ Engine.FIELD_SCALES = [1, 2];
  *
  *  `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