@dopaminefx/core 0.1.0

package/dist/framework/loader.js

@@ -0,0 +1,266 @@
+/**
+ * `.dope` effect loader.
+ *
+ * Parses a `.dope` JSON document (per docs/effect-format.md) and evaluates its
+ * `controls → render.params` mapping grammar, the OKLCH golden-angle palette,
+ * and the per-mood baseline table into the SAME flat render-param bag the engine
+ * consumes. Shader bodies stay referenced GLSL (the format references them); the
+ * loader is NOT a GLSL transpiler.
+ *
+ * The single load-bearing invariant (the correctness anchor): the PRNG is
+ * consumed in the SAME order as the legacy `resolve*Params` — `buildPalette`
+ * draws the base hue first (one `rng()` inside it), then the per-fire scatter
+ * (`rng() * 1000`). So a pinned seed reproduces the legacy output byte-for-byte;
+ * a vitest asserts this across a mood × intensity × whimsy × seed grid.
+ *
+ * The grammar is intentionally tiny + non-Turing-complete (no loops, no user
+ * functions) so it is safe to evaluate from an untrusted file and trivial to
+ * port to Swift for the Metal backend.
+ */
+import { buildPalette, oklchToLinearSrgb } from "../engine/color.js";
+import { mulberry32 } from "../engine/seed.js";
+import { NPR_TIME_STEP_MS } from "../engine/tempo.js";
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+const lerp = (a, b, t) => a + (b - a) * clamp01(t);
+/** Read a named outline from a doc's geometry, or undefined. */
+export function getOutline(doc, name) {
+    return doc.geometry?.outlines?.[name];
+}
+/**
+ * The mood a doc degrades to when asked for one it doesn't declare.
+ *
+ * Each effect declares its OWN moods (the success trio declares
+ * serene/celebratory/electric; the fail effect declares try-again/error/denied),
+ * so there is no single hardcoded fallback mood that exists for every effect.
+ * An effect's own default is, in order of preference:
+ *   1. its `controls.mood.default`, if that mood actually has a baseline, else
+ *   2. the first mood key in its `baselines` table.
+ * This keeps EVERY declared mood resolvable and makes an unknown mood degrade to
+ * the effect's own sensible default instead of throwing on a missing baseline.
+ */
+export function defaultMoodKey(doc) {
+    const controls = doc.controls;
+    const declared = controls?.mood?.default;
+    if (typeof declared === "string" && doc.baselines[declared])
+        return declared;
+    const first = Object.keys(doc.baselines)[0];
+    if (!first)
+        throw new Error("dope: document has no baselines to resolve a mood against");
+    return first;
+}
+/**
+ * Resolve a requested mood name against a doc to a key the doc actually declares:
+ * the requested mood if it has a baseline, otherwise the doc's own default mood
+ * ({@link defaultMoodKey}). Returned key is used for BOTH the baseline table and
+ * the palette `perMood` register, so they always agree.
+ */
+function resolveMoodKey(doc, mood) {
+    return doc.baselines[mood] ? mood : defaultMoodKey(doc);
+}
+/** Evaluate a grammar node to a number. Pure; matches mood.ts arithmetic. */
+export function evalExpr(node, ctx) {
+    if (typeof node === "number")
+        return node;
+    if ("const" in node)
+        return node.const;
+    if ("control" in node)
+        return clamp01(ctx.controls[node.control] ?? 0);
+    if ("baseline" in node) {
+        const v = ctx.baseline[node.baseline];
+        if (v === undefined)
+            throw new Error(`dope: unknown baseline "${node.baseline}"`);
+        return v;
+    }
+    if ("lerp" in node) {
+        const [c, a, b] = node.lerp;
+        return lerp(a, b, ctx.controls[c] ?? 0);
+    }
+    if ("mul" in node)
+        return node.mul.reduce((p, n) => p * evalExpr(n, ctx), 1);
+    if ("add" in node)
+        return node.add.reduce((p, n) => p + evalExpr(n, ctx), 0);
+    if ("sub" in node) {
+        const parts = node.sub.map((n) => evalExpr(n, ctx));
+        return parts.slice(1).reduce((p, n) => p - n, parts[0] ?? 0);
+    }
+    if ("round" in node)
+        return Math.round(evalExpr(node.round, ctx));
+    if ("floor" in node)
+        return Math.floor(evalExpr(node.floor, ctx));
+    if ("mix" in node) {
+        const [a, b, c] = node.mix;
+        const va = evalExpr(a, ctx);
+        const vb = evalExpr(b, ctx);
+        return va + (vb - va) * clamp01(ctx.controls[c] ?? 0);
+    }
+    if ("max" in node)
+        return Math.max(...node.max.map((n) => evalExpr(n, ctx)));
+    if ("min" in node)
+        return Math.min(...node.min.map((n) => evalExpr(n, ctx)));
+    throw new Error(`dope: unknown expr node ${JSON.stringify(node)}`);
+}
+/** Apply a param spec's post-clamp flags. */
+function applyFlags(v, spec, consts) {
+    if (spec.clamp01)
+        v = clamp01(v);
+    if (spec.clampMax)
+        v = Math.min(v, consts[spec.clampMax] ?? Infinity);
+    if (spec.clampMin)
+        v = Math.max(v, consts[spec.clampMin] ?? -Infinity);
+    return v;
+}
+/**
+ * Resolve a `.dope` doc + a feeling into the flat render-param bag (palette,
+ * style, durationMs, seed, scatter seed, and every `render.params` entry). The
+ * `scatterKey` is the name the legacy code gave the per-fire scatter offset
+ * (`moteSeed` / `inkSeed` / `comicSeed`) so the output keys match exactly.
+ *
+ * RNG order (the parity anchor): baseHue via buildPalette FIRST, then the
+ * scatter `rng()*1000` — identical to `resolve*Params`.
+ */
+export function resolveDopeParams(doc, input, consts, scatterKey, 
+/**
+ * Host theme override: three explicit OKLCH stops that REPLACE the generated
+ * golden-angle palette (a pinned brand palette). The base-hue rng() is still
+ * consumed first, so the per-fire scatter offset stays identical to the
+ * generated path — pinning the palette never shifts the mote/spray layout.
+ */
+paletteOverride) {
+    const i = clamp01(input.intensity);
+    const w = clamp01(input.whimsy);
+    // Degrade an undeclared mood to THIS effect's own default mood (not a hardcoded
+    // "celebratory", which the fail effect — and any non-success effect — has no
+    // baseline for). Declared moods always resolve to themselves, so parity holds.
+    const moodKey = resolveMoodKey(doc, input.mood);
+    const baseline = doc.baselines[moodKey];
+    const rng = mulberry32(input.seed);
+    const ctx = {
+        controls: { intensity: i, whimsy: w },
+        baseline,
+        consts,
+    };
+    const out = {
+        seed: input.seed,
+        style: w,
+    };
+    // durationMs (tempo)
+    if (doc.tempo.durationMs) {
+        out.durationMs = applyFlags(evalExpr(doc.tempo.durationMs.from, ctx), doc.tempo.durationMs, consts);
+    }
+    // render.params
+    for (const [name, spec] of Object.entries(doc.render.params)) {
+        if (name === "style")
+            continue; // style is the raw whimsy control, set above
+        out[name] = applyFlags(evalExpr(spec.from, ctx), spec, consts);
+    }
+    // Palette FIRST (consumes one rng() for the base hue inside buildPalette),
+    // matching the engine's call order exactly.
+    // Same resolved key as the baseline lookup, so palette + baselines always agree
+    // (an undeclared mood uses the effect's own default for both).
+    const reg = doc.palette.perMood[moodKey] ?? doc.palette.perMood[defaultMoodKey(doc)];
+    const chroma = evalExpr(doc.palette.chroma.from, { ...ctx, baseline: reg });
+    const generated = buildPalette(rng, {
+        lightness: reg.lightness,
+        chroma,
+        hueCenter: reg.hueCenter,
+        hueRange: reg.hueRange,
+        hueSpread: doc.palette.hueSpread,
+    });
+    // A host palette override REPLACES the generated stops (the base-hue rng() above
+    // was still consumed, so scatter parity holds), pinning a brand palette.
+    out.palette = paletteOverride ? paletteOverride.map(oklchToLinearSrgb) : generated;
+    // THEN the per-fire scatter offset (same rng() * 1000 as the engine).
+    out[scatterKey] = rng() * 1000;
+    return out;
+}
+// A `.dope` must be SELF-CONTAINED — it may inline assets (e.g. `data:` URIs) or
+// reference bundled programs/assets by key or by a path RELATIVE to the package
+// (resolved inside a `.dope` zip), but it must never point at the network or an
+// absolute filesystem path. This keeps every effect portable and offline.
+const REMOTE_REF_RE = /^(?:[a-z][a-z0-9+.-]*:)?\/\//i; // http(s)://, ftp://, //host
+const ABS_PATH_RE = /^(?:\/|[A-Za-z]:[\\/])/; // /etc/..., C:\...
+function assertStandalone(node, path = "$") {
+    if (typeof node === "string") {
+        if (REMOTE_REF_RE.test(node) || ABS_PATH_RE.test(node)) {
+            throw new Error(`dope: external asset reference is not allowed — a .dope must be ` +
+                `self-contained (inline or bundle assets). Offending value at ${path}: "${node}"`);
+        }
+        return;
+    }
+    if (Array.isArray(node)) {
+        node.forEach((v, i) => assertStandalone(v, `${path}[${i}]`));
+    }
+    else if (node && typeof node === "object") {
+        for (const [k, v] of Object.entries(node))
+            assertStandalone(v, `${path}.${k}`);
+    }
+}
+// Tolerance for the loop whole-multiple checks (the step 1000/12 is not exactly
+// representable, so an exact `% === 0` would be float-fragile).
+const LOOP_EPS = 1e-6;
+const isWhole = (x) => Math.abs(x - Math.round(x)) < LOOP_EPS;
+/**
+ * Validate a `tempo.loop` block against the doc's baselines: the period must be
+ * positive, must tile the "animate on twos" grid (unless `snapAligned` is
+ * false), and every per-mood baseline `durationMs` must be a whole number of
+ * periods — the seam guarantee, moved from per-effect convention into the
+ * parser (identical on every platform).
+ */
+function assertValidLoop(loop, baselines) {
+    const p = loop.periodMs;
+    if (typeof p !== "number" || !Number.isFinite(p) || p <= 0) {
+        throw new Error(`dope: tempo.loop.periodMs must be a positive number (got ${JSON.stringify(p)})`);
+    }
+    if (loop.snapAligned !== false && !isWhole(p / NPR_TIME_STEP_MS)) {
+        throw new Error(`dope: tempo.loop.periodMs (${p}) is not a whole number of animate-on-twos steps (1000/12 ms)`);
+    }
+    for (const [mood, row] of Object.entries(baselines)) {
+        const d = row.durationMs;
+        if (d !== undefined && !isWhole(d / p)) {
+            throw new Error(`dope: baselines.${mood}.durationMs (${d}) is not a whole number of tempo.loop periods (${p} ms)`);
+        }
+    }
+}
+/**
+ * Parse + validate a `.dope` document from a JSON string or already-parsed
+ * object. Rejects a wrong/absent magic or major version, any external
+ * (remote / absolute-path) asset reference — a `.dope` must be self-contained —
+ * and a `tempo.loop` that breaks the seam invariants.
+ * (A fuller JSON-Schema validation lives in CI against effect-format.schema.json.)
+ */
+export function parseDope(src) {
+    const doc = (typeof src === "string" ? JSON.parse(src) : src);
+    if (doc.fmt !== "dopamine-effect") {
+        throw new Error(`dope: not a Dopamine effect document (fmt="${doc.fmt}")`);
+    }
+    const major = Number(doc.v?.split(".")[0]);
+    if (!Number.isFinite(major) || major > 1) {
+        throw new Error(`dope: unsupported format version "${doc.v}"`);
+    }
+    if (!doc.render?.params || !doc.palette?.perMood || !doc.baselines) {
+        throw new Error("dope: document missing render.params / palette.perMood / baselines");
+    }
+    if (doc.tempo?.loop)
+        assertValidLoop(doc.tempo.loop, doc.baselines);
+    if (doc.render?.panel)
+        assertValidPanel(doc.render.panel, doc.binding);
+    assertStandalone(doc);
+    return doc;
+}
+/**
+ * `render.panel` invariants: the panel sampler must be one of the declared
+ * `binding.samplers` (the panel is a texture binding like any other — one
+ * source of truth for the uniform list), and the unit must be a non-negative
+ * integer.
+ */
+function assertValidPanel(panel, binding) {
+    const samplers = (binding?.samplers ?? []).map((s) => (typeof s === "string" ? s : s.web));
+    if (!panel.sampler || !samplers.includes(panel.sampler)) {
+        throw new Error(`dope: render.panel.sampler "${panel.sampler}" is not a declared binding.samplers entry`);
+    }
+    const unit = panel.texture ?? 0;
+    if (!Number.isInteger(unit) || unit < 0) {
+        throw new Error(`dope: render.panel.texture must be a non-negative integer (got ${unit})`);
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/framework/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/framework/loader.ts"],"names":[],"mappings":"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"}

package/dist/framework/mood-registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Mood registry — the shared, effect-agnostic "emotional register" layer.
+ *
+ * A mood describes a *feeling baseline* (how warm, how energetic, how bright) in
+ * effect-neutral terms. Every effect reads the same resolved mood, so adding a
+ * mood ("triumphant", "focused", a brand mood) lights up across *all* effects at
+ * once — no per-effect edits.
+ *
+ * Why a register, not a full param table: the three built-in effects share their
+ * *color identity* per mood (the same `hueCenter`/`hueRange` — a serene blue, a
+ * celebratory roam, a hot electric band) but each effect has its own spatial /
+ * motion / typographic baselines (a bloom radius means nothing to a comic word).
+ * So the registry owns the shared register + a normalized `energy`, and each
+ * effect's `mood.ts` baseline table keys off the mood name (built-ins keep their
+ * exact tuned values; an unfamiliar mood is derived from the register + energy
+ * so it still renders sensibly everywhere). This keeps built-in output
+ * byte-identical to the legacy `resolve*Params` while making moods extensible.
+ */
+/** Effect-neutral description of a mood's shared color register + energy. */
+export interface MoodSpec {
+    /** Preferred hue center in degrees (arousal rises blue→green→red). */
+    hueCenter: number;
+    /** Width of the random hue band around the center, in degrees. */
+    hueRange: number;
+    /** Perceptual lightness reference for palettes, 0..1. */
+    lightness: number;
+    /** Base chroma (colorfulness) reference for palettes, ~0..0.4. */
+    chroma: number;
+    /**
+     * Normalized energy 0..1 (serene → electric). Effects use this to derive a
+     * baseline for a mood they have no tuned table entry for (faster, denser,
+     * harder slams toward 1). Built-in effects ignore it for their built-in moods.
+     */
+    energy: number;
+}
+/** A mood resolved for use: its spec plus the name it was registered under. */
+export interface ResolvedMood extends MoodSpec {
+    readonly name: string;
+}
+/** The mood used when none is given or an unknown one is requested. */
+export declare const DEFAULT_MOOD = "celebratory";
+/**
+ * Register (or override) a mood. Returns the name so it can be used inline.
+ *
+ * ```ts
+ * registerMood("triumphant", { hueCenter: 280, hueRange: 160,
+ *                              lightness: 0.8, chroma: 0.22, energy: 0.9 });
+ * await celebrate({ mood: "triumphant" });   // now works for ALL effects
+ * ```
+ */
+export declare function registerMood(name: string, spec: MoodSpec): string;
+/** Look up a mood, falling back to the default. Always returns a usable mood. */
+export declare function resolveMood(name: string | undefined): ResolvedMood;
+/** Whether a mood name is currently registered. */
+export declare function hasMood(name: string): boolean;
+/** Names of all registered moods (built-in + custom). */
+export declare function moodNames(): string[];
+//# sourceMappingURL=mood-registry.d.ts.map

package/dist/framework/mood-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mood-registry.d.ts","sourceRoot":"","sources":["../../src/framework/mood-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAeD,uEAAuE;AACvE,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAGjE;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAGlE;AAED,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED,yDAAyD;AACzD,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC"}

package/dist/framework/mood-registry.js

@@ -0,0 +1,58 @@
+/**
+ * Mood registry — the shared, effect-agnostic "emotional register" layer.
+ *
+ * A mood describes a *feeling baseline* (how warm, how energetic, how bright) in
+ * effect-neutral terms. Every effect reads the same resolved mood, so adding a
+ * mood ("triumphant", "focused", a brand mood) lights up across *all* effects at
+ * once — no per-effect edits.
+ *
+ * Why a register, not a full param table: the three built-in effects share their
+ * *color identity* per mood (the same `hueCenter`/`hueRange` — a serene blue, a
+ * celebratory roam, a hot electric band) but each effect has its own spatial /
+ * motion / typographic baselines (a bloom radius means nothing to a comic word).
+ * So the registry owns the shared register + a normalized `energy`, and each
+ * effect's `mood.ts` baseline table keys off the mood name (built-ins keep their
+ * exact tuned values; an unfamiliar mood is derived from the register + energy
+ * so it still renders sensibly everywhere). This keeps built-in output
+ * byte-identical to the legacy `resolve*Params` while making moods extensible.
+ */
+/**
+ * The three built-in moods. The register values mirror the per-mood columns
+ * shared by all three effects' baseline tables in `mood.ts`; `energy` orders
+ * them serene(0) → celebratory(0.5) → electric(1).
+ */
+const BUILTIN_MOODS = {
+    serene: { hueCenter: 230, hueRange: 120, lightness: 0.83, chroma: 0.1, energy: 0.0 },
+    celebratory: { hueCenter: 50, hueRange: 320, lightness: 0.81, chroma: 0.17, energy: 0.5 },
+    electric: { hueCenter: 35, hueRange: 150, lightness: 0.79, chroma: 0.24, energy: 1.0 },
+};
+const moods = new Map(Object.entries(BUILTIN_MOODS));
+/** The mood used when none is given or an unknown one is requested. */
+export const DEFAULT_MOOD = "celebratory";
+/**
+ * Register (or override) a mood. Returns the name so it can be used inline.
+ *
+ * ```ts
+ * registerMood("triumphant", { hueCenter: 280, hueRange: 160,
+ *                              lightness: 0.8, chroma: 0.22, energy: 0.9 });
+ * await celebrate({ mood: "triumphant" });   // now works for ALL effects
+ * ```
+ */
+export function registerMood(name, spec) {
+    moods.set(name, spec);
+    return name;
+}
+/** Look up a mood, falling back to the default. Always returns a usable mood. */
+export function resolveMood(name) {
+    const key = name && moods.has(name) ? name : DEFAULT_MOOD;
+    return { name: key, ...moods.get(key) };
+}
+/** Whether a mood name is currently registered. */
+export function hasMood(name) {
+    return moods.has(name);
+}
+/** Names of all registered moods (built-in + custom). */
+export function moodNames() {
+    return [...moods.keys()];
+}
+//# sourceMappingURL=mood-registry.js.map

package/dist/framework/mood-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mood-registry.js","sourceRoot":"","sources":["../../src/framework/mood-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAyBH;;;;GAIG;AACH,MAAM,aAAa,GAA6B;IAC9C,MAAM,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IACpF,WAAW,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IACzF,QAAQ,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;CACvF,CAAC;AAEF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAmB,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;AAEvE,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAc;IACvD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAC,IAAwB;IAClD,MAAM,GAAG,GAAG,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC;IAC1D,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,EAAE,CAAC;AAC3C,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3B,CAAC"}

package/dist/framework/panel-runner.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Generic Canvas2D "panel" runner — the shared backbone for HYBRID effects whose
+ * per-frame content is drawn with Canvas2D (vector / text / shape) and then lit
+ * by a fragment shader (Comic Impact's hand-lettered word + jagged starburst +
+ * ink, lit into Ben-Day halftone + action lines + flash).
+ *
+ * It owns ALL the renderer/texture/upload/shadow plumbing that a Canvas2D-panel
+ * effect would otherwise hand-wire:
+ *   • the single offscreen panel canvas + its 2D context,
+ *   • resizing the panel to track the live GL canvas each frame,
+ *   • the per-frame draw → `texImage2D` UPLOAD into BOTH the light + shadow
+ *     contexts (the panel pixels change every frame, so — unlike a static SDF
+ *     aux — they are re-uploaded each frame), with the FLIP_Y + non-premultiplied
+ *     channel-encoding convention the panel shaders expect,
+ *   • the standard shader uniforms (resolution, center, life, time, style,
+ *     palette, the shadow-pass uniforms via shadowGeometry) + scalar render.params
+ *     auto-bound by name convention,
+ *   • the light + (optional) shadow pass via the program-cached contexts, and
+ *   • disposing the per-fire panel textures.
+ *
+ * What stays per-effect (the honest boundary): the GLSL, a small `draw()` panel
+ * program (the Canvas2D draw — genuinely code-shaped vector/text logic stays JS),
+ * and a tiny config naming the shader's uniforms + the per-frame timing.
+ */
+import type { EffectContext, EffectInstance } from "./effect.js";
+import type { PassParams } from "./pass-runner.js";
+/** Per-frame timing context for a panel effect's draw + frame hooks. */
+export interface PanelFrameInfo {
+    /** Raw elapsed time since start, ms (panels don't snap "on twos"). */
+    elapsedMs: number;
+    /** Normalized life 0..1 (elapsedMs / durationMs, clamped). */
+    life: number;
+    /** Device-pixel ratio the panel is rendered at. */
+    dpr: number;
+    /**
+     * Targeted element CENTRE in panel device px (canvas space, y-down). The
+     * centrepiece is drawn here instead of the canvas centre. Defaults to the
+     * canvas centre.
+     */
+    centerPx: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Targeted element SIZE in device px. The centrepiece is sized to this box.
+     * Defaults to the full canvas.
+     */
+    targetPx: {
+        width: number;
+        height: number;
+    };
+}
+/** A registered "panel program": the Canvas2D draw for one frame. */
+export type PanelDraw<P extends PassParams = PassParams> = (panelCtx: CanvasRenderingContext2D, width: number, height: number, params: P, info: PanelFrameInfo) => void;
+/** Config for one Canvas2D-panel effect. */
+export interface PanelConfig<P extends PassParams = PassParams> {
+    /** Vertex + fragment GLSL (the per-effect look). */
+    vertex: string;
+    fragment: string;
+    /** Every uniform name the shader reads. */
+    uniforms: readonly string[];
+    /** Sampler uniform for the uploaded panel (bound to TEXTURE0). Default "uPanel". */
+    panelSampler?: string;
+    /**
+     * Explicit `param name → uniform name` overrides for the scalar auto-binding;
+     * map to `null` to skip a param that isn't a uniform (e.g. a scatter seed).
+     */
+    bindings?: Record<string, string | null>;
+    /** The shadow occluder "height" as a fraction of min canvas dim. */
+    shadowHeightFrac: number | ((params: P) => number);
+    /** The Canvas2D panel program (draws one frame). */
+    draw: PanelDraw<P>;
+    /**
+     * Compute the genuinely effect-specific TIME-VARYING uniforms for a frame
+     * (presence, flash, …). Returns a map of uniform name → float; `amp` (a
+     * well-known key) feeds shadowGeometry.
+     */
+    frame(info: PanelFrameInfo, params: P): {
+        amp: number;
+    } & Record<string, number>;
+    /**
+     * Extra per-pass scalar uniforms that depend on the live canvas / dpr but are
+     * not plain params (e.g. `uDotSize = dotSize * dpr`, `uInkBoost`). Computed per
+     * pass.
+     */
+    passUniforms?(canvas: HTMLCanvasElement, params: P, dpr: number, targetPx: {
+        width: number;
+        height: number;
+    }): Record<string, number>;
+}
+/**
+ * Build a drawable {@link EffectInstance} for a Canvas2D-panel effect from its
+ * config + resolved params + the runtime context.
+ */
+export declare function createPanelInstance<P extends PassParams>(config: PanelConfig<P>, params: P, ctx: EffectContext): EffectInstance;
+//# sourceMappingURL=panel-runner.d.ts.map

package/dist/framework/panel-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel-runner.d.ts","sourceRoot":"","sources":["../../src/framework/panel-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAcnD,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,qEAAqE;AACrE,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,CACzD,QAAQ,EAAE,wBAAwB,EAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,cAAc,KACjB,IAAI,CAAC;AAEV,4CAA4C;AAC5C,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAC5D,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC;IACnD,oDAAoD;IACpD,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjF;;;;OAIG;IACH,YAAY,CAAC,CACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAC1C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3B;AAQD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,UAAU,EACtD,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,aAAa,GACjB,cAAc,CA6GhB"}

package/dist/framework/panel-runner.js

@@ -0,0 +1,137 @@
+/**
+ * Generic Canvas2D "panel" runner — the shared backbone for HYBRID effects whose
+ * per-frame content is drawn with Canvas2D (vector / text / shape) and then lit
+ * by a fragment shader (Comic Impact's hand-lettered word + jagged starburst +
+ * ink, lit into Ben-Day halftone + action lines + flash).
+ *
+ * It owns ALL the renderer/texture/upload/shadow plumbing that a Canvas2D-panel
+ * effect would otherwise hand-wire:
+ *   • the single offscreen panel canvas + its 2D context,
+ *   • resizing the panel to track the live GL canvas each frame,
+ *   • the per-frame draw → `texImage2D` UPLOAD into BOTH the light + shadow
+ *     contexts (the panel pixels change every frame, so — unlike a static SDF
+ *     aux — they are re-uploaded each frame), with the FLIP_Y + non-premultiplied
+ *     channel-encoding convention the panel shaders expect,
+ *   • the standard shader uniforms (resolution, center, life, time, style,
+ *     palette, the shadow-pass uniforms via shadowGeometry) + scalar render.params
+ *     auto-bound by name convention,
+ *   • the light + (optional) shadow pass via the program-cached contexts, and
+ *   • disposing the per-fire panel textures.
+ *
+ * What stays per-effect (the honest boundary): the GLSL, a small `draw()` panel
+ * program (the Canvas2D draw — genuinely code-shaped vector/text logic stays JS),
+ * and a tiny config naming the shader's uniforms + the per-frame timing.
+ */
+import { STANDARD_COMMON, applyFloatMap, beginProgram, bindFrameUniforms, bindPalette, bindScalars, bindShadowGeometry, bindTarget, compositeLightFragment, computeScalarBinds, } from "./pass-common.js";
+// The panel runner adds `uCenter` (the panel composites around screen center)
+// to the shared standard set — and binds the SAME anchor under the pass-runner's
+// `uOrigin` name, so a panel shader may use either spelling (the single-source
+// GLSL→MSL path maps `uOrigin` onto the packed struct's `origin` field).
+const STANDARD = ["uCenter", "uOrigin", ...STANDARD_COMMON];
+/**
+ * Build a drawable {@link EffectInstance} for a Canvas2D-panel effect from its
+ * config + resolved params + the runtime context.
+ */
+export function createPanelInstance(config, params, ctx) {
+    const pal = params.palette;
+    const dpr = ctx.dpr;
+    const sampler = config.panelSampler ?? "uPanel";
+    const allUniforms = [...new Set([...STANDARD, sampler, ...config.uniforms])];
+    // Backdrop-aware mode: the light pass emits premultiplied light (source-over,
+    // visible on any surface); the shadow pass keeps the opaque multiply fragment.
+    const lightFragment = ctx.composite?.premultiplied
+        ? compositeLightFragment(config.fragment)
+        : config.fragment;
+    // The numeric params that auto-bind to a uniform.
+    const scalarBinds = computeScalarBinds(params, config.bindings ?? {});
+    // One offscreen Canvas2D panel, shared by both passes (drawn once per frame).
+    const panel = document.createElement("canvas");
+    const pctx = panel.getContext("2d", { alpha: true });
+    const lightTex = ctx.light.gl.createTexture();
+    const shadowTex = ctx.shadow ? ctx.shadow.gl.createTexture() : null;
+    for (const glc of [ctx.light, ctx.shadow]) {
+        if (!glc)
+            continue;
+        const { gl } = glc;
+        gl.bindTexture(gl.TEXTURE_2D, glc === ctx.light ? lightTex : shadowTex);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    }
+    const heightFrac = () => typeof config.shadowHeightFrac === "function" ? config.shadowHeightFrac(params) : config.shadowHeightFrac;
+    const drawPass = (glc, tex, info, frameUniforms, isShadow) => {
+        const { gl } = glc;
+        const c = glc.canvas;
+        const { u } = beginProgram(glc, config.vertex, isShadow ? config.fragment : lightFragment, allUniforms);
+        // Upload the freshly-drawn panel (changes every frame).
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+        gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, panel);
+        if (u[sampler])
+            gl.uniform1i(u[sampler], 0);
+        // Extra per-pass scalar uniforms (dpr-scaled etc.).
+        applyFloatMap(gl, u, config.passUniforms?.(c, params, dpr, info.targetPx));
+        // Standard uniforms.
+        gl.uniform2f(u.uResolution, c.width, c.height);
+        bindTarget(gl, u, c, ctx.targetSize, dpr);
+        // uCenter is the impact/heart centre the PROCEDURAL parts radiate from (comic's
+        // action lines, heartburst's bloom). It must match where the panel centrepiece
+        // lands — the anchor — NOT the canvas centre, or they split (centrepiece on the
+        // target, lines/glow stuck at screen centre). `frag` here is vUv*uResolution
+        // (y-up, matching the flipped panel texture), so flip the anchor's y exactly as
+        // the pure-shader runner does for uOrigin.
+        gl.uniform2f(u.uCenter, ctx.anchor.x * dpr, c.height - ctx.anchor.y * dpr);
+        if (u.uOrigin)
+            gl.uniform2f(u.uOrigin, ctx.anchor.x * dpr, c.height - ctx.anchor.y * dpr);
+        gl.uniform1f(u.uLife, info.life);
+        gl.uniform1f(u.uTimeS, info.elapsedMs / 1000);
+        gl.uniform1f(u.uStyle, params.style);
+        bindPalette(gl, u, pal);
+        bindScalars(gl, u, params, scalarBinds);
+        bindFrameUniforms(gl, u, frameUniforms);
+        gl.uniform1f(u.uShadow, isShadow ? 1 : 0);
+        if (isShadow)
+            bindShadowGeometry(gl, u, c, heightFrac(), frameUniforms.amp, params.style);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+    };
+    let disposed = false;
+    return {
+        durationMs: params.durationMs,
+        renderAt(elapsedMs) {
+            if (disposed)
+                return;
+            const c = ctx.light.canvas;
+            if (panel.width !== c.width || panel.height !== c.height) {
+                panel.width = c.width;
+                panel.height = c.height;
+            }
+            const life = Math.min(Math.max(elapsedMs, 0) / params.durationMs, 1);
+            // The targeted element box → panel device px (y-down canvas space). Defaults
+            // to the canvas centre + full canvas, reproducing the old screen-centred pose.
+            const centerPx = { x: ctx.anchor.x * dpr, y: ctx.anchor.y * dpr };
+            const targetPx = ctx.targetSize
+                ? { width: ctx.targetSize.width * dpr, height: ctx.targetSize.height * dpr }
+                : { width: c.width, height: c.height };
+            const info = { elapsedMs, life, dpr, centerPx, targetPx };
+            const frameUniforms = config.frame(info, params);
+            // Draw the shared offscreen panel once, then composite into each pass.
+            config.draw(pctx, c.width, c.height, params, info);
+            if (ctx.shadow && shadowTex)
+                drawPass(ctx.shadow, shadowTex, info, frameUniforms, true);
+            drawPass(ctx.light, lightTex, info, frameUniforms, false);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (lightTex)
+                ctx.light.gl.deleteTexture(lightTex);
+            if (shadowTex && ctx.shadow)
+                ctx.shadow.gl.deleteTexture(shadowTex);
+        },
+    };
+}
+//# sourceMappingURL=panel-runner.js.map