@dopaminefx/core 0.1.0

package/src/index.ts

@@ -0,0 +1,227 @@
+/**
+ * @dopaminefx/core — the EFFECT-FREE runtime + public API.
+ *
+ * This is the slim runtime: the conductor (overlay + shared program-cached GL
+ * contexts + RAF loop), the registry, the mood registry, the `.dope` loader +
+ * `loadEffect`, the generic runners (pass + panel), the shared engine bits
+ * (color, sdf, shadow, seed, context, gl, the `look/` GLSL chunks, tempo
+ * PRIMITIVES) and the generic `play(name, …)` / `prepare(name, …)` API.
+ *
+ * Core imports + registers NO effect. Each effect ships as its own
+ * `@dopaminefx/effect-<name>` package that depends on this and self-registers on
+ * import; the `@dopaminefx/effects` umbrella bundles all nine + the `celebrate*`
+ * conveniences + the `<dopamine-success>` element.
+ */
+
+import {
+  play as conductorPlay,
+  prepare as conductorPrepare,
+  type CompositeMode,
+  type PlayHandle,
+} from "./framework/conductor.js";
+import { getEffect } from "./framework/registry.js";
+import type { Anchor, FeelingInput } from "./framework/effect.js";
+import { parseBackdrop } from "./engine/color.js";
+import { randomSeed } from "./engine/seed.js";
+import { isBrowser } from "./framework/runtime.js";
+import type { DopamineSuccessOptions } from "./types.js";
+
+export type { DopamineMood, DopamineSuccessOptions } from "./types.js";
+export type { RGB, OKLCH } from "./engine/color.js";
+export { buildPalette, oklchToLinearSrgb, wrapHue, GOLDEN_ANGLE_DEG, type PaletteParams } from "./engine/color.js";
+export { mulberry32, randomSeed, type Rng } from "./engine/seed.js";
+
+// Framework surface — for adding new effects / moods and lower-level control.
+export type {
+  Effect,
+  EffectFactory,
+  EffectInstance,
+  EffectContext,
+  FeelingInput,
+  Anchor,
+} from "./framework/effect.js";
+export { registerEffect, getEffect, hasEffect, effectNames } from "./framework/registry.js";
+export {
+  registerMood,
+  resolveMood,
+  hasMood,
+  moodNames,
+  type MoodSpec,
+  type ResolvedMood,
+} from "./framework/mood-registry.js";
+export { teardown, type PreparedHandle, type PlayHandle } from "./framework/conductor.js";
+export {
+  loadEffect,
+  loadEffectSync,
+  type LoadEffectOptions,
+  type LoadOverrides,
+  type LoadedEffect,
+} from "./framework/load-effect.js";
+export { registerProgram, getProgram, programNames, type RenderProgram } from "./framework/programs.js";
+export {
+  parseDope,
+  resolveDopeParams,
+  getOutline,
+  type DopeDoc,
+  type DopeOutline,
+  type DopeBinding,
+  type DopeSampler,
+  type DopeFrameSpec,
+  type DopeLoopSpec,
+} from "./framework/loader.js";
+export {
+  dopePassConfig,
+  dopePanelConfig,
+  registerDopeEffect,
+  registerDopePanelEffect,
+  type DopePassHooks,
+  type DopeShader,
+  type RegisterDopeEffectOptions,
+} from "./framework/dope-pass.js";
+export {
+  evalFrameExpr,
+  evalParamExpr,
+  evalPassExpr,
+  type FrameExprNode,
+  type FrameExprCtx,
+  type PassExprInputs,
+} from "./framework/frame-expr.js";
+export {
+  pickFromList,
+  pickBand,
+  resolveTypography,
+  type DopeTypography,
+} from "./framework/content.js";
+export { bakeSdf, decodeSdf, parseSvgPath, type BakedSdf, type DecodedSdf } from "./engine/sdf.js";
+// The generic runners — for authoring new pure-shader / Canvas2D-panel effects.
+export {
+  createPassInstance,
+  type PassConfig,
+  type PassParams,
+  type AuxTextureSpec,
+  type FrameInfo,
+} from "./framework/pass-runner.js";
+export {
+  createPanelInstance,
+  type PanelConfig,
+  type PanelDraw,
+  type PanelFrameInfo,
+} from "./framework/panel-runner.js";
+
+// Tempo PRIMITIVES — the generic easing/envelope building blocks effects build
+// their bespoke timing on top of (each effect's bespoke envelope lives in its
+// own package's `<name>-tempo.ts`).
+export {
+  clamp01,
+  easeOutCubic,
+  easeOutBack,
+  envelope,
+  NPR_TIME_STEP_MS,
+} from "./engine/tempo.js";
+
+// The shared GLSL "look" chunks — reusable shader fragments (hash, fbm, palette
+// mix, tonemap, dither, halftone, …) an effect's shader composes into its source.
+export * from "./engine/look/glsl.js";
+export { GLSL_PARTICLES } from "./engine/look/particles.glsl.js";
+
+const DEFAULTS = { mood: "celebratory", intensity: 0.7, whimsy: 0.5 } as const;
+
+/**
+ * Resolve the shared options into a target, a feeling, and an overlay-local
+ * anchor. Effects that aren't anchored (Verdict, Comic) simply ignore the anchor.
+ */
+function resolveRequest(
+  effect: string,
+  options: DopamineSuccessOptions,
+): {
+  factory: ReturnType<typeof getEffect>;
+  target: HTMLElement;
+  anchor: Anchor;
+  targetSize: { width: number; height: number };
+  feeling: FeelingInput;
+  composite: CompositeMode | null;
+} | null {
+  const factory = getEffect(effect);
+  if (!factory) throw new Error(`dopamine: unknown effect "${effect}"`);
+  const target = options.target ?? document.body;
+  const seed = options.seed ?? randomSeed();
+  const feeling: FeelingInput = {
+    mood: options.mood ?? DEFAULTS.mood,
+    intensity: options.intensity ?? DEFAULTS.intensity,
+    whimsy: options.whimsy ?? DEFAULTS.whimsy,
+    seed,
+  };
+  const rect = target.getBoundingClientRect();
+  const origin = options.origin ?? {
+    x: rect.left + rect.width / 2,
+    y: rect.top + rect.height / 2,
+  };
+  const anchor: Anchor =
+    target === document.body || target === document.documentElement
+      ? origin
+      : { x: origin.x - rect.left, y: origin.y - rect.top };
+  // The element box the centrepiece is sized to (CSS px). Defaults to the target's
+  // own rect, so the centrepiece matches whatever element was fired on; an explicit
+  // `targetSize` lets a caller match a child element under a full-page overlay.
+  const targetSize = options.targetSize ?? { width: rect.width, height: rect.height };
+  // A `backdrop` colour opts into surface-aware compositing (visible on light /
+  // arbitrary surfaces); we keep only its luminance — the colour itself isn't a
+  // shader input (the light layer composites source-over against the live page).
+  const bd = options.backdrop ? parseBackdrop(options.backdrop) : null;
+  const composite: CompositeMode | null = bd ? { luminance: bd.luminance } : null;
+  return { factory, target, anchor, targetSize, feeling, composite };
+}
+
+/**
+ * Generic real-time fire: play a registered effect by name. Resolves when the
+ * animation has fully played out. A CONTINUOUS effect (one whose `.dope`
+ * declares `tempo.loop`, e.g. halo) loops seamlessly until the host calls the
+ * returned handle's `stop()`. The handle's `pause()`/`resume()` freeze and
+ * resume the timeline drift-free (parking a perpetual loop so it costs no
+ * battery; the conductor also auto-pauses on a hidden tab). SSR-safe (resolves
+ * immediately off-DOM). The effect must already be registered (import
+ * `@dopaminefx/effect-<name>` or the `@dopaminefx/effects` umbrella, or load one
+ * via `loadEffect`).
+ */
+export function play(effect: string, options: DopamineSuccessOptions = {}): PlayHandle {
+  const noop: PlayHandle = Object.assign(Promise.resolve(), { stop() {}, pause() {}, resume() {} });
+  if (!isBrowser()) return noop;
+  const req = resolveRequest(effect, options);
+  if (!req || !req.factory) return noop;
+  return conductorPlay({
+    factory: req.factory,
+    target: req.target,
+    anchor: req.anchor,
+    targetSize: req.targetSize,
+    feeling: req.feeling,
+    composite: req.composite,
+  });
+}
+
+/** A prepared, manually-driven effect handle (offline capture / external clock). */
+export interface PreparedEffect {
+  readonly durationMs: number;
+  /** Draw the frame at `elapsedMs` since the start. */
+  renderAt(elapsedMs: number): void;
+  /** Dispose the renderer *and* release the overlay. */
+  dispose(): void;
+}
+
+/**
+ * Generic prepared effect: mount the overlay and return a renderer you drive
+ * yourself via `renderAt(elapsedMs)`. Call `dispose()` when finished. Returns
+ * `null` in non-DOM environments.
+ */
+export function prepare(effect: string, options: DopamineSuccessOptions = {}): PreparedEffect | null {
+  if (!isBrowser()) return null;
+  const req = resolveRequest(effect, options);
+  if (!req || !req.factory) return null;
+  return conductorPrepare({
+    factory: req.factory,
+    target: req.target,
+    anchor: req.anchor,
+    targetSize: req.targetSize,
+    feeling: req.feeling,
+    composite: req.composite,
+  });
+}

package/src/overlay.ts

@@ -0,0 +1,109 @@
+/**
+ * Full-bleed overlay host. Creates fixed, click-through canvases layered over
+ * the target.
+ *
+ * Two stacked compositing layers give the effect real physical presence:
+ *
+ *   - LIGHT layer (`mix-blend-mode: screen`): black pixels leave content
+ *     untouched, bright pixels lighten it — this is what makes the effect cast
+ *     coloured light onto the UI beneath.
+ *   - SHADOW layer (`mix-blend-mode: multiply`): white pixels leave content
+ *     untouched, dark pixels darken it — a soft, offset occlusion silhouette of
+ *     the effect's bright forms, so the effect reads as floating ABOVE the page
+ *     and throwing shadow into it, not just glowing on top of it.
+ *
+ * The shadow layer sits BENEATH the light layer in z-order, so the bright core
+ * always wins where the two overlap (the shadow is pushed out to the edges /
+ * away from the light, which is physically what an offset penumbra does).
+ *
+ * Back-compat: `createOverlay(target)` still returns an object whose `.canvas`
+ * is the single light canvas and `.destroy()` tears everything down — existing
+ * single-canvas callers are unaffected. Pass `{ shadow: true }` to additionally
+ * get a `shadow` canvas (`overlay.shadow`).
+ */
+
+export interface Overlay {
+  /** The light-casting canvas (`mix-blend-mode: screen`). */
+  canvas: HTMLCanvasElement;
+  /**
+   * The shadow-casting canvas (`mix-blend-mode: multiply`), present only when
+   * the overlay was created with `{ shadow: true }`.
+   */
+  shadow?: HTMLCanvasElement;
+  /**
+   * Lazily create (or return the existing) shadow canvas, inserting it beneath
+   * the light layer. Lets a persistent overlay gain a shadow layer when a later
+   * effect needs one without recreating the whole overlay.
+   */
+  ensureShadow: () => HTMLCanvasElement;
+  /** Remove the overlay (all layers) from the DOM. */
+  destroy: () => void;
+}
+
+export interface OverlayOptions {
+  /** Also create a multiply "shadow" layer beneath the light layer. */
+  shadow?: boolean;
+}
+
+const LIGHT_Z = "2147483646";
+// One below the light layer so the bright core composites over the shadow.
+const SHADOW_Z = "2147483645";
+
+function styleCanvas(
+  canvas: HTMLCanvasElement,
+  blend: "screen" | "multiply",
+  zIndex: string,
+  scoped: boolean,
+): void {
+  const s = canvas.style;
+  s.position = scoped ? "absolute" : "fixed";
+  s.inset = "0";
+  s.width = "100%";
+  s.height = "100%";
+  s.pointerEvents = "none";
+  s.zIndex = zIndex;
+  s.mixBlendMode = blend;
+  s.display = "block";
+  canvas.setAttribute("aria-hidden", "true");
+}
+
+export function createOverlay(target: HTMLElement, options: OverlayOptions = {}): Overlay {
+  const scoped = target !== document.body && target !== document.documentElement;
+  if (scoped) {
+    const cs = getComputedStyle(target);
+    if (cs.position === "static") target.style.position = "relative";
+  }
+
+  // Shadow layer is created (and appended) first so it sits beneath the light
+  // layer both in z-index and DOM order.
+  let shadow: HTMLCanvasElement | undefined;
+  const makeShadow = (): HTMLCanvasElement => {
+    const s = document.createElement("canvas");
+    styleCanvas(s, "multiply", SHADOW_Z, scoped);
+    s.dataset.dopamine = "shadow";
+    // Insert at the front so it sits beneath the (later-appended) light canvas.
+    target.insertBefore(s, target.firstChild);
+    return s;
+  };
+  if (options.shadow) shadow = makeShadow();
+
+  const canvas = document.createElement("canvas");
+  styleCanvas(canvas, "screen", LIGHT_Z, scoped);
+  canvas.dataset.dopamine = "solarbloom";
+  target.appendChild(canvas);
+
+  return {
+    canvas,
+    get shadow() {
+      return shadow;
+    },
+    ensureShadow(): HTMLCanvasElement {
+      if (!shadow) shadow = makeShadow();
+      return shadow;
+    },
+    destroy: () => {
+      canvas.remove();
+      shadow?.remove();
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Public types for Dopamine's success effect.
+ *
+ * The whole point of the API is that callers choose a *feeling* — a mood, how
+ * intense it should be, and how much whimsy — rather than tuning low-level
+ * particle counts and easing curves. Those get derived internally (see
+ * `engine/mood.ts`).
+ */
+
+/** Emotional register of the celebration. */
+export type DopamineMood = "serene" | "celebratory" | "electric";
+
+export interface DopamineSuccessOptions {
+  /**
+   * Emotional register. Default `"celebratory"`. A built-in success mood, or any
+   * mood registered via `registerMood` (e.g. the fail effect's `try-again` /
+   * `error` / `denied`).
+   */
+  mood?: DopamineMood | (string & {});
+  /**
+   * How strong the reward feels, 0..1. Drives saturation, brightness, bloom
+   * size, mote count and overshoot — grounded in the finding that saturated,
+   * bright color raises both arousal and positive valence. Default `0.7`.
+   */
+  intensity?: number;
+  /**
+   * How playful/organic the motion is, 0..1. Widens the hue spread and the
+   * turbulence of the drifting motes. Default `0.5`.
+   */
+  whimsy?: number;
+  /**
+   * Seed for the algorithmic color + motion. Omit to get a fresh, unique
+   * palette every fire (the variable-reward / novelty lever). Provide a fixed
+   * value for reproducible output (e.g. tests, snapshots).
+   */
+  seed?: number;
+  /** Origin of the bloom in viewport pixels. Default: center of `target`. */
+  origin?: { x: number; y: number };
+  /**
+   * Size (CSS px) of the element the effect's centrepiece (checkmark, ✗, comic
+   * word, hero heart, ink gesture) is sized to. Default: the `target`'s own box.
+   * Set this to match a CHILD element while the overlay still covers the page.
+   */
+  targetSize?: { width: number; height: number };
+  /**
+   * Element the full-bleed overlay is mounted over. Default `document.body`,
+   * i.e. the whole page. Light is cast (via `mix-blend-mode`) onto whatever
+   * sits beneath the overlay.
+   */
+  target?: HTMLElement;
+  /**
+   * The page colour the effect composites against, as any CSS colour string
+   * (e.g. `"#ffffff"`, `"rgb(20 24 37)"`, a named colour). Omit (the default)
+   * for the classic dark compositing: the light layer uses
+   * `mix-blend-mode: screen`, which is rich on a dark UI but mathematically
+   * invisible on white. Pass the actual surface colour and the runtime switches
+   * the light layer to PREMULTIPLIED source-over light — visible on ANY surface,
+   * white included — and strengthens the multiply shadow as the surface
+   * lightens. Use this whenever the effect plays over a light or unknown-colour
+   * background.
+   */
+  backdrop?: string;
+}