@dopaminefx/core 0.1.0

package/src/framework/effect.ts

@@ -0,0 +1,127 @@
+/**
+ * The Dopamine effect framework — the backbone every visual effect plugs into.
+ *
+ * An *effect* (Solarbloom, Calligraphic Verdict, Comic Impact, and future
+ * progress / error / attention effects) is a self-contained module that knows
+ * two things:
+ *
+ *  1. how to turn the human-facing "feeling" knobs (mood / intensity / whimsy)
+ *     plus a seed into its own concrete, deterministic render parameters, and
+ *  2. how to draw a single frame at an arbitrary `elapsedMs` into a shared GPU
+ *     surface — both the light pass and (if present) the multiply shadow pass.
+ *
+ * Effects never create the DOM overlay, the GL context, or the RAF loop — the
+ * runtime (the conductor) owns all of that. That separation is what lets a new
+ * effect be a small file that self-registers, and keeps the library
+ * tree-shakeable: importing one effect pulls in nothing from the others.
+ */
+
+import type { GLContext } from "../engine/context.js";
+import type { ResolvedMood } from "./mood-registry.js";
+
+/** Origin/anchor in CSS pixels, relative to the render surface's top-left. */
+export interface Anchor {
+  x: number;
+  y: number;
+}
+
+/**
+ * The "feeling" API, shared by every effect. Individual effects map these onto
+ * their own low-level parameters via {@link EffectFactory.resolve}. This is the
+ * deliberate seam between *what a developer expresses* (a feeling) and *what the
+ * shader consumes* (numbers).
+ */
+export interface FeelingInput {
+  /** Emotional register — a registered mood name. */
+  mood: string;
+  /** 0..1 — arousal/valence: saturation, brightness, scale, overshoot. */
+  intensity: number;
+  /** 0..1 — stylization: photoreal (0) ↔ cel / hand-drawn "animate on twos" (1). */
+  whimsy: number;
+  /** Deterministic seed for the algorithmic color + motion. */
+  seed: number;
+}
+
+/**
+ * Everything an effect instance needs to draw, supplied by the runtime. The
+ * effect draws its light pass into `light` and, when `shadow` is non-null, its
+ * occlusion silhouette into `shadow` (a separate `mix-blend-mode: multiply`
+ * canvas + context). Both contexts are persistent + program-cached.
+ */
+export interface EffectContext {
+  /** Shared WebGL2 light context (`screen` blend) + program cache. */
+  readonly light: GLContext;
+  /** Shared WebGL2 shadow context (`multiply` blend), or null if disabled. */
+  readonly shadow: GLContext | null;
+  /** Where the effect is anchored, in CSS px relative to the surface. */
+  readonly anchor: Anchor;
+  /**
+   * Size (CSS px) of the underlying element the effect targets, centred on
+   * {@link anchor}. The centrepiece (checkmark, ✗, comic word, hero heart, ink
+   * gesture) is sized to THIS box so it matches the page element. Omitted ⇒ the
+   * full render surface (the centrepiece fills the canvas, as before).
+   */
+  readonly targetSize?: { width: number; height: number };
+  /** Device-pixel ratio to render at (already capped by the runtime). */
+  readonly dpr: number;
+  /**
+   * Present when the host composites against a known backdrop colour rather than
+   * the default `mix-blend-mode: screen`. The runners then emit PREMULTIPLIED
+   * light (alpha = brightness) on the light pass so the effect stays visible on
+   * any surface — white included — composited source-over. Absent ⇒ the classic
+   * screen/opaque path (byte-identical to before).
+   */
+  readonly composite?: { premultiplied: boolean };
+}
+
+/** A live, drawable effect. Pure function of time: same `elapsedMs` → same frame. */
+export interface EffectInstance {
+  /** Total length in ms after which the effect has fully played out. */
+  readonly durationMs: number;
+  /** Draw the frame at `elapsedMs` since the effect started. */
+  renderAt(elapsedMs: number): void;
+  /** Release any per-instance GPU resources (not shared/cached ones). */
+  dispose(): void;
+}
+
+/**
+ * The contract a new effect implements. `Params` is the effect's private,
+ * fully-resolved parameter shape — opaque to the runtime.
+ */
+export interface EffectFactory<Params = unknown> {
+  /** Stable, unique id, e.g. `"solarbloom"`. Used by the registry + API. */
+  readonly name: string;
+  /**
+   * Map the shared feeling knobs + a resolved mood into this effect's own
+   * deterministic params. Pure — no DOM, no GL, no randomness beyond the seed.
+   */
+  resolve(feeling: FeelingInput, mood: ResolvedMood): Params;
+  /** Build a drawable instance for the given resolved params + context. */
+  create(params: Params, ctx: EffectContext): EffectInstance;
+  /**
+   * Whether this effect wants a shadow (multiply) companion canvas. Defaults to
+   * true; an effect that casts no shadow can opt out to skip the second context.
+   */
+  readonly castsShadow?: boolean;
+  /**
+   * Optional reduced-motion handling: which `elapsedMs` of the timeline best
+   * represents a calm peak, and how long to hold that single static frame
+   * instead of animating. Sensible defaults are used if omitted.
+   */
+  readonly reducedMotion?: {
+    /** How long to hold the minimal frame, ms. Default 360. */
+    holdMs?: number;
+    /** Which `elapsedMs` of the full timeline best represents a calm peak. */
+    peakMs?: number;
+  };
+  /**
+   * CONTINUOUS-loop contract (from `tempo.loop`): the effect repeats seamlessly
+   * with this period and `durationMs` is a whole number of periods. The
+   * conductor re-arms it at `durationMs` instead of tearing down — the host
+   * stops it via the handle `play()` returns. Absent for one-shot effects.
+   */
+  readonly loop?: { periodMs: number };
+}
+
+/** Public alias: an `Effect` is what you register and play by name. */
+export type Effect<Params = unknown> = EffectFactory<Params>;

package/src/framework/frame-expr.ts

@@ -0,0 +1,217 @@
+/**
+ * Per-FRAME expression evaluator — the datafied form of an effect's `frame()` /
+ * `shadowHeightFrac` logic hooks.
+ *
+ * The resolve-time grammar (`loader.ts` `evalExpr`) maps a feeling into the
+ * resolved param bag ONCE per fire. This module is its per-frame sibling: it
+ * evaluates the `.dope` `tempo.frame` / `render.shadowHeightFrac` expression
+ * trees EVERY frame against the live clocks (`animMs` / `life` / `elapsedMs`,
+ * plus the `loopS` / `phase` loop clocks for effects with `tempo.loop`) and
+ * the resolved params — so the per-frame logic, like the resolve mapping,
+ * is authored once in the `.dope` and interpreted identically on every
+ * platform. The same grammar also powers the PER-PASS `render.pass`
+ * expressions ({@link evalPassExpr}): params plus the pass-geometry inputs
+ * (`targetMinDimPx` / `sdfRange` / `sdfViewBoxW`), with the frame clocks
+ * rejected — pass values are computed once per pass, not per frame.
+ *
+ * Like `evalExpr`, nodes are evaluated RAW (no decode step) and anything
+ * outside the grammar THROWS. The tempo primitives (`envelope`, `easeOutBack`,
+ * `easeOutCubic`, `clamp01`) are the SAME functions the hand-written hooks
+ * called (imported from `engine/tempo.ts`), so a datafied effect's output is
+ * bit-identical to the code it replaced.
+ */
+
+import { clamp01, easeOutBack, easeOutCubic, envelope } from "../engine/tempo.js";
+
+/** The per-frame expression grammar — an expression tree over the frame ctx. */
+export type FrameExprNode =
+  | number
+  | { const: number }
+  | { param: string }
+  | {
+      input:
+        | "animMs"
+        | "life"
+        | "elapsedMs"
+        | "loopS"
+        | "phase"
+        // Pass-geometry inputs — only valid in a `render.pass` expression
+        // (evalPassExpr); the frame/params modes reject them.
+        | "targetMinDimPx"
+        | "sdfRange"
+        | "sdfViewBoxW"
+        | "dpr";
+    }
+  | { add: FrameExprNode[] }
+  | { sub: FrameExprNode[] }
+  | { mul: FrameExprNode[] }
+  | { div: FrameExprNode[] }
+  | { min: FrameExprNode[] }
+  | { max: FrameExprNode[] }
+  | { pow: [FrameExprNode, FrameExprNode] }
+  | { sin: FrameExprNode }
+  | { cos: FrameExprNode }
+  | { exp: FrameExprNode }
+  | { clamp01: FrameExprNode }
+  | { lt: [FrameExprNode, FrameExprNode, FrameExprNode, FrameExprNode] }
+  | { envelope: [FrameExprNode, FrameExprNode] }
+  | { easeOutCubic: FrameExprNode }
+  | { easeOutBack: [FrameExprNode, FrameExprNode] };
+
+/** Evaluation context for a per-frame expression. */
+export interface FrameExprCtx {
+  /** The "on twos"-snapped animation clock in ms (stepping already applied). */
+  animMs: number;
+  /** Normalized life 0..1 (animMs / durationMs, clamped). */
+  life: number;
+  /** The REAL un-stepped wall clock in ms (mirrors the Swift/Android runners). */
+  elapsedMs: number;
+  /** The resolved render-param bag (numeric entries are addressable). */
+  params: Record<string, unknown>;
+  /**
+   * Seconds within the current loop (`(animMs % tempo.loop.periodMs) / 1000`).
+   * 0 for an effect with no `tempo.loop` — the caller (the dope-pass frame
+   * derivation) fills these from the doc's loop contract.
+   */
+  loopS?: number;
+  /** Normalized loop phase in [0, 1) (`animMs % periodMs / periodMs`); 0 without a loop. */
+  phase?: number;
+  /** Pass-geometry inputs (see {@link PassExprInputs}); only read in "pass" mode. */
+  pass?: PassExprInputs;
+}
+
+/**
+ * The pass-geometry inputs a `render.pass` expression may read (evaluated ONCE
+ * per pass by the runners, never per resolve or per frame).
+ */
+export interface PassExprInputs {
+  /**
+   * Min dimension of the TARGETED element box in device px, falling back to
+   * the full canvas when untargeted — the same target-fallback the standard
+   * `uTarget` uniform uses, so a pass-sized centrepiece tracks the element.
+   */
+  targetMinDimPx: number;
+  /**
+   * The declared `range` of the SDF behind the first `binding.samplers` entry
+   * with an `outline` source (author units → the full byte range); 0 when no
+   * sampler declares one.
+   */
+  sdfRange: number;
+  /** That SDF's `viewBox[2]` (author-units width); 0 when absent. */
+  sdfViewBoxW: number;
+  /**
+   * The device-pixel ratio (web `devicePixelRatio` / Android `density` / the
+   * Metal layer's content scale) the surface renders at — so a pass value can
+   * be expressed in CSS-ish units and scaled to device px (e.g. heartburst's
+   * halftone cell `uDotSize = dotSize · dpr`).
+   */
+  dpr: number;
+}
+
+/** Which inputs an expression may read: the three evaluation entry points. */
+type ExprMode = "frame" | "params" | "pass";
+
+const FRAME_INPUTS = ["animMs", "life", "elapsedMs", "loopS", "phase"] as const;
+const PASS_INPUTS = ["targetMinDimPx", "sdfRange", "sdfViewBoxW", "dpr"] as const;
+
+function evalInput(name: string, ctx: FrameExprCtx, mode: ExprMode): number {
+  const isFrame = (FRAME_INPUTS as readonly string[]).includes(name);
+  const isPass = (PASS_INPUTS as readonly string[]).includes(name);
+  if (mode === "pass") {
+    if (isFrame) {
+      throw new Error(
+        `dope: frame input "${name}" is not allowed in a render.pass expression (pass expressions are not frame-clocked)`,
+      );
+    }
+    if (isPass) return ctx.pass?.[name as keyof PassExprInputs] ?? 0;
+    throw new Error(`dope: unknown frame input "${name}"`);
+  }
+  if (isPass) {
+    throw new Error(`dope: pass input "${name}" is only allowed in a render.pass expression`);
+  }
+  if (mode === "params") {
+    throw new Error(`dope: {input} is not allowed in a params-only expression (got "${name}")`);
+  }
+  if (name === "animMs") return ctx.animMs;
+  if (name === "life") return ctx.life;
+  if (name === "elapsedMs") return ctx.elapsedMs;
+  if (name === "loopS") return ctx.loopS ?? 0;
+  if (name === "phase") return ctx.phase ?? 0;
+  throw new Error(`dope: unknown frame input "${name}"`);
+}
+
+function evalNode(node: FrameExprNode, ctx: FrameExprCtx, mode: ExprMode): number {
+  if (typeof node === "number") return node;
+  if ("const" in node) return node.const;
+  if ("param" in node) {
+    const raw = ctx.params[node.param];
+    if (typeof raw !== "number") {
+      throw new Error(`dope: frame expr references missing/non-numeric param "${node.param}"`);
+    }
+    return Number(raw);
+  }
+  if ("input" in node) return evalInput(String(node.input), ctx, mode);
+  if ("add" in node) return node.add.reduce((p: number, n) => p + evalNode(n, ctx, mode), 0);
+  if ("sub" in node) {
+    const parts: number[] = node.sub.map((n) => evalNode(n, ctx, mode));
+    return parts.slice(1).reduce((p: number, n: number) => p - n, parts[0] ?? 0);
+  }
+  if ("mul" in node) return node.mul.reduce((p: number, n) => p * evalNode(n, ctx, mode), 1);
+  if ("div" in node) {
+    const parts: number[] = node.div.map((n) => evalNode(n, ctx, mode));
+    return parts.slice(1).reduce((p: number, n: number) => p / n, parts[0] ?? 0);
+  }
+  if ("min" in node) return Math.min(...node.min.map((n) => evalNode(n, ctx, mode)));
+  if ("max" in node) return Math.max(...node.max.map((n) => evalNode(n, ctx, mode)));
+  if ("pow" in node) {
+    return Math.pow(evalNode(node.pow[0], ctx, mode), evalNode(node.pow[1], ctx, mode));
+  }
+  if ("sin" in node) return Math.sin(evalNode(node.sin, ctx, mode));
+  if ("cos" in node) return Math.cos(evalNode(node.cos, ctx, mode));
+  if ("exp" in node) return Math.exp(evalNode(node.exp, ctx, mode));
+  if ("clamp01" in node) return clamp01(evalNode(node.clamp01, ctx, mode));
+  if ("lt" in node) {
+    // Branches are evaluated LAZILY (only the taken branch), so a guard like
+    // `0 < elapsedMs ? f(elapsedMs) : 0` never evaluates f outside its domain.
+    const [a, b, then, otherwise] = node.lt;
+    return evalNode(a, ctx, mode) < evalNode(b, ctx, mode)
+      ? evalNode(then, ctx, mode)
+      : evalNode(otherwise, ctx, mode);
+  }
+  if ("envelope" in node) {
+    return envelope(evalNode(node.envelope[0], ctx, mode), evalNode(node.envelope[1], ctx, mode));
+  }
+  if ("easeOutCubic" in node) return easeOutCubic(evalNode(node.easeOutCubic, ctx, mode));
+  if ("easeOutBack" in node) {
+    return easeOutBack(evalNode(node.easeOutBack[0], ctx, mode), evalNode(node.easeOutBack[1], ctx, mode));
+  }
+  throw new Error(`dope: unknown frame expr node ${JSON.stringify(node)}`);
+}
+
+/** Evaluate a per-frame grammar node to a number. Pure; throws outside the grammar. */
+export function evalFrameExpr(node: FrameExprNode, ctx: FrameExprCtx): number {
+  return evalNode(node, ctx, "frame");
+}
+
+/**
+ * Evaluate a PARAMS-ONLY expression (e.g. `render.shadowHeightFrac`): the same
+ * grammar, but `{input}` nodes THROW — a shadow-geometry expression must be a
+ * pure function of the resolved params, never of the frame clock.
+ */
+export function evalParamExpr(node: FrameExprNode, params: Record<string, unknown>): number {
+  return evalNode(node, { animMs: 0, life: 0, elapsedMs: 0, params }, "params");
+}
+
+/**
+ * Evaluate a PER-PASS expression (`render.pass`): the same grammar over the
+ * resolved params plus the pass-geometry inputs (`targetMinDimPx` / `sdfRange`
+ * / `sdfViewBoxW`). Frame clocks (`animMs` / `life` / …) THROW — a pass
+ * expression is evaluated once per pass, not per frame.
+ */
+export function evalPassExpr(
+  node: FrameExprNode,
+  params: Record<string, unknown>,
+  pass: PassExprInputs,
+): number {
+  return evalNode(node, { animMs: 0, life: 0, elapsedMs: 0, params, pass }, "pass");
+}

package/src/framework/load-effect.ts

@@ -0,0 +1,204 @@
+/**
+ * `loadEffect()` — the public, no-code entry point for arbitrary `.dope` effects.
+ *
+ * A host drops in a `.dope` (a parsed object, a JSON string, or a `.dope` zip),
+ * optionally patches it (clamp control ranges, pin a brand palette, swap an
+ * outline path), and gets back a registered `EffectFactory` playable via
+ * `play()` / `prepare()`. The effect binds to a BUNDLED render program
+ * (framework/programs.ts) referenced by the doc's
+ * `render.backends.webgl2.shader.program` key — the format carries data + a
+ * program key; the runtime owns the GLSL. No new shader/renderer code is needed
+ * to ship a recolored / re-iconed / retimed variant of a bundled effect.
+ *
+ * Overrides are a shallow JSON-pointer-style patch applied to the parsed doc,
+ * then the merged doc is RE-VALIDATED (parseDope: magic/version + the
+ * standalone guard) so a host can't push the effect into an invalid or
+ * non-self-contained state. Swapped outline paths are re-baked to an SDF here so
+ * the runtime still only samples.
+ */
+
+import { parseDope, type DopeDoc, type DopeOutline } from "./loader.js";
+import type { OKLCH } from "../engine/color.js";
+import { bakeSdf } from "../engine/sdf.js";
+import { getProgram, programNames } from "./programs.js";
+import { registerEffect } from "./registry.js";
+import { resolveDopeParams } from "./loader.js";
+import type { EffectContext, EffectFactory, FeelingInput } from "./effect.js";
+
+/** A control descriptor as it appears in a `.dope` `controls` block. */
+interface ControlDesc {
+  type?: string;
+  min?: number;
+  max?: number;
+  default?: number | null;
+  [k: string]: unknown;
+}
+
+/** Host customization patch — all no-code from the host's POV (docs §9.1). */
+export interface LoadOverrides {
+  /**
+   * Clamp/retune a control's range or default, by control name. The loader
+   * re-validates that default ∈ [min, max] after merging.
+   * e.g. `{ intensity: { max: 0.8, default: 0.6 } }`.
+   */
+  controls?: Record<string, { min?: number; max?: number; default?: number | null }>;
+  /**
+   * THEME: replace the generated palette with three explicit OKLCH brand stops
+   * (the base-hue rng is still consumed, so per-fire scatter is unchanged), OR
+   * pin `seed` to lock the generated palette. `palette` wins over `seed`.
+   */
+  palette?: [OKLCH, OKLCH, OKLCH];
+  /** THEME: pin the seed so the generated palette reproduces every fire. */
+  seed?: number;
+  /**
+   * RESKIN: swap an outline's SVG path by outline name; re-baked to an SDF here.
+   * e.g. `{ checkmark: "M5 55 L40 88 L95 8" }`.
+   */
+  outlines?: Record<string, string>;
+}
+
+export interface LoadEffectOptions {
+  /** Register the effect under this name (default: the doc's `id`). */
+  name?: string;
+  /** Host customization patch (§9.1). */
+  overrides?: LoadOverrides;
+  /** SDF bake resolution for swapped outlines (default 64). */
+  sdfSize?: number;
+  /** SDF bake distance range in author units for swapped outlines (default 18). */
+  sdfRange?: number;
+}
+
+/** A loaded, registered effect ready to fire. */
+export interface LoadedEffect {
+  /** The registered name (use with `play(name, …)`). */
+  readonly name: string;
+  /** The registered factory. */
+  readonly factory: EffectFactory;
+  /** The merged, validated `.dope` document. */
+  readonly doc: DopeDoc;
+}
+
+const REMOTE_RE = /^(?:[a-z][a-z0-9+.-]*:)?\/\//i;
+
+/** Apply control range/default overrides, validating default ∈ [min, max]. */
+function applyControlOverrides(doc: DopeDoc, overrides: NonNullable<LoadOverrides["controls"]>): void {
+  const controls = (doc as { controls?: Record<string, ControlDesc> }).controls;
+  if (!controls) throw new Error("dope: cannot override controls — doc has no `controls` block");
+  for (const [name, patch] of Object.entries(overrides)) {
+    const c = controls[name];
+    if (!c) throw new Error(`dope: cannot override unknown control "${name}"`);
+    if (patch.min !== undefined) c.min = patch.min;
+    if (patch.max !== undefined) c.max = patch.max;
+    if (patch.default !== undefined) c.default = patch.default;
+    const lo = typeof c.min === "number" ? c.min : -Infinity;
+    const hi = typeof c.max === "number" ? c.max : Infinity;
+    if (typeof c.min === "number" && typeof c.max === "number" && c.min > c.max) {
+      throw new Error(`dope: control "${name}" override has min > max`);
+    }
+    if (typeof c.default === "number" && (c.default < lo || c.default > hi)) {
+      throw new Error(`dope: control "${name}" default ${c.default} out of range [${lo}, ${hi}]`);
+    }
+  }
+}
+
+/** Swap outline svgPaths and re-bake their SDFs (the runtime still only samples). */
+function applyOutlineOverrides(
+  doc: DopeDoc,
+  outlines: NonNullable<LoadOverrides["outlines"]>,
+  size: number,
+  range: number,
+): void {
+  const geo = doc.geometry;
+  if (!geo?.outlines) throw new Error("dope: cannot swap outline — doc has no `geometry.outlines`");
+  const viewBox = geo.viewBox ?? [0, 0, 100, 100];
+  for (const [name, svgPath] of Object.entries(outlines)) {
+    const o: DopeOutline | undefined = geo.outlines[name];
+    if (!o) throw new Error(`dope: cannot swap unknown outline "${name}"`);
+    if (REMOTE_RE.test(svgPath) || svgPath.trim().startsWith("/")) {
+      throw new Error(`dope: swapped outline path must be a self-contained svgPath, not a ref`);
+    }
+    o.svgPath = svgPath;
+    o.sdf = bakeSdf(svgPath, viewBox, size, range);
+    o.source = "baked-sdf";
+  }
+}
+
+/**
+ * Parse + (optionally) patch a `.dope`, bind it to its bundled render program,
+ * register it, and return a playable factory. The merged doc is re-validated.
+ */
+export function loadEffectSync(
+  src: string | object,
+  opts: LoadEffectOptions = {},
+): LoadedEffect {
+  // Parse + validate the base doc first (rejects remote/absolute refs).
+  let doc = parseDope(src);
+  // Deep-clone so overrides never mutate a caller's object (and so re-bakes land
+  // on a private copy).
+  doc = JSON.parse(JSON.stringify(doc)) as DopeDoc;
+
+  const ov = opts.overrides ?? {};
+  if (ov.controls) applyControlOverrides(doc, ov.controls);
+  if (ov.outlines) {
+    applyOutlineOverrides(doc, ov.outlines, opts.sdfSize ?? 64, opts.sdfRange ?? 18);
+  }
+
+  // Re-validate the merged doc (magic/version + standalone guard). A swapped
+  // outline that smuggled a remote/absolute ref is rejected here.
+  doc = parseDope(doc);
+
+  // Resolve the bundled render program the doc references.
+  const backends = (doc.render.backends ?? {}) as Record<string, { shader?: { program?: string } }>;
+  const programKey = backends.webgl2?.shader?.program;
+  if (!programKey) {
+    throw new Error("dope: render.backends.webgl2.shader.program is required for loadEffect");
+  }
+  const program = getProgram(programKey);
+  if (!program) {
+    throw new Error(
+      `dope: unknown render program "${programKey}". Known: ${programNames().join(", ") || "import the effect that registers it"}`,
+    );
+  }
+
+  const name = opts.name ?? doc.id;
+  const seed = ov.seed;
+  const paletteOverride = ov.palette;
+
+  const factory: EffectFactory = {
+    name,
+    castsShadow: program.castsShadow,
+    reducedMotion: program.reducedMotion,
+    resolve(feeling: FeelingInput) {
+      // A pinned override seed wins over the per-fire seed (locks the palette).
+      const f = { ...feeling, seed: seed ?? feeling.seed };
+      const numeric = resolveDopeParams(doc, f, program.consts, program.scatterKey, paletteOverride);
+      return program.composeParams
+        ? program.composeParams(numeric as Record<string, unknown>, f)
+        : numeric;
+    },
+    create(params, ctx: EffectContext) {
+      return program.create(params as Record<string, unknown>, ctx);
+    },
+  };
+
+  registerEffect(factory);
+  return { name, factory, doc };
+}
+
+/**
+ * Public async `loadEffect`. Accepts a parsed doc, a JSON string, or a `.dope`
+ * zip (Uint8Array/ArrayBuffer/Blob). Resolves to the registered, playable effect.
+ */
+export async function loadEffect(
+  src: string | object | Uint8Array | ArrayBuffer | Blob,
+  opts: LoadEffectOptions = {},
+): Promise<LoadedEffect> {
+  if (src instanceof Blob) src = new Uint8Array(await src.arrayBuffer());
+  if (src instanceof ArrayBuffer) src = new Uint8Array(src);
+  if (src instanceof Uint8Array) {
+    const { readDopeZip } = await import("./dope-zip.js");
+    const json = await readDopeZip(src);
+    return loadEffectSync(json, opts);
+  }
+  return loadEffectSync(src, opts);
+}