@dopaminefx/core 0.1.0

package/dist/index.js

@@ -0,0 +1,126 @@
+/**
+ * @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, } from "./framework/conductor.js";
+import { getEffect } from "./framework/registry.js";
+import { parseBackdrop } from "./engine/color.js";
+import { randomSeed } from "./engine/seed.js";
+import { isBrowser } from "./framework/runtime.js";
+export { buildPalette, oklchToLinearSrgb, wrapHue, GOLDEN_ANGLE_DEG } from "./engine/color.js";
+export { mulberry32, randomSeed } from "./engine/seed.js";
+export { registerEffect, getEffect, hasEffect, effectNames } from "./framework/registry.js";
+export { registerMood, resolveMood, hasMood, moodNames, } from "./framework/mood-registry.js";
+export { teardown } from "./framework/conductor.js";
+export { loadEffect, loadEffectSync, } from "./framework/load-effect.js";
+export { registerProgram, getProgram, programNames } from "./framework/programs.js";
+export { parseDope, resolveDopeParams, getOutline, } from "./framework/loader.js";
+export { dopePassConfig, dopePanelConfig, registerDopeEffect, registerDopePanelEffect, } from "./framework/dope-pass.js";
+export { evalFrameExpr, evalParamExpr, evalPassExpr, } from "./framework/frame-expr.js";
+export { pickFromList, pickBand, resolveTypography, } from "./framework/content.js";
+export { bakeSdf, decodeSdf, parseSvgPath } from "./engine/sdf.js";
+// The generic runners — for authoring new pure-shader / Canvas2D-panel effects.
+export { createPassInstance, } from "./framework/pass-runner.js";
+export { createPanelInstance, } 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 };
+/**
+ * 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, options) {
+    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 = {
+        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 = 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 = 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, options = {}) {
+    const noop = 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,
+    });
+}
+/**
+ * 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, options = {}) {
+    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,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,IAAI,IAAI,aAAa,EACrB,OAAO,IAAI,gBAAgB,GAG5B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAKnD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,OAAO,EAAE,gBAAgB,EAAsB,MAAM,mBAAmB,CAAC;AACnH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAY,MAAM,kBAAkB,CAAC;AAWpE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC5F,OAAO,EACL,YAAY,EACZ,WAAW,EACX,OAAO,EACP,SAAS,GAGV,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAwC,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EACL,UAAU,EACV,cAAc,GAIf,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAsB,MAAM,yBAAyB,CAAC;AACxG,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,UAAU,GAOX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,uBAAuB,GAIxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,GAIb,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,iBAAiB,GAElB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAkC,MAAM,iBAAiB,CAAC;AACnG,gFAAgF;AAChF,OAAO,EACL,kBAAkB,GAKnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,GAIpB,MAAM,6BAA6B,CAAC;AAErC,+EAA+E;AAC/E,8EAA8E;AAC9E,oCAAoC;AACpC,OAAO,EACL,OAAO,EACP,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,kFAAkF;AAClF,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAW,CAAC;AAE/E;;;GAGG;AACH,SAAS,cAAc,CACrB,MAAc,EACd,OAA+B;IAS/B,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,GAAG,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC;IAC/C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,UAAU,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAiB;QAC5B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI;QACnC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS;QAClD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM;QACzC,IAAI;KACL,CAAC;IACF,MAAM,IAAI,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI;QAC/B,CAAC,EAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC;QAC7B,CAAC,EAAE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC;KAC9B,CAAC;IACF,MAAM,MAAM,GACV,MAAM,KAAK,QAAQ,CAAC,IAAI,IAAI,MAAM,KAAK,QAAQ,CAAC,eAAe;QAC7D,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC1D,iFAAiF;IACjF,kFAAkF;IAClF,8EAA8E;IAC9E,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACpF,8EAA8E;IAC9E,8EAA8E;IAC9E,+EAA+E;IAC/E,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,MAAM,SAAS,GAAyB,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAChF,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,IAAI,CAAC,MAAc,EAAE,UAAkC,EAAE;IACvE,MAAM,IAAI,GAAe,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,KAAI,CAAC,EAAE,KAAK,KAAI,CAAC,EAAE,MAAM,KAAI,CAAC,EAAE,CAAC,CAAC;IAClG,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,aAAa,CAAC;QACnB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAC,CAAC;AACL,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,MAAc,EAAE,UAAkC,EAAE;IAC1E,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,gBAAgB,CAAC;QACtB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAC,CAAC;AACL,CAAC"}

package/dist/overlay.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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;
+}
+export declare function createOverlay(target: HTMLElement, options?: OverlayOptions): Overlay;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,OAAO;IACtB,2DAA2D;IAC3D,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;OAIG;IACH,YAAY,EAAE,MAAM,iBAAiB,CAAC;IACtC,oDAAoD;IACpD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAwBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAuCxF"}

package/dist/overlay.js

@@ -0,0 +1,79 @@
+/**
+ * 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`).
+ */
+const LIGHT_Z = "2147483646";
+// One below the light layer so the bright core composites over the shadow.
+const SHADOW_Z = "2147483645";
+function styleCanvas(canvas, blend, zIndex, scoped) {
+    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, options = {}) {
+    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;
+    const makeShadow = () => {
+        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() {
+            if (!shadow)
+                shadow = makeShadow();
+            return shadow;
+        },
+        destroy: () => {
+            canvas.remove();
+            shadow?.remove();
+        },
+    };
+}
+//# sourceMappingURL=overlay.js.map

package/dist/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyBH,MAAM,OAAO,GAAG,YAAY,CAAC;AAC7B,2EAA2E;AAC3E,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B,SAAS,WAAW,CAClB,MAAyB,EACzB,KAA4B,EAC5B,MAAc,EACd,MAAe;IAEf,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;IACvB,CAAC,CAAC,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;IAC3C,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC;IACd,CAAC,CAAC,KAAK,GAAG,MAAM,CAAC;IACjB,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC,CAAC,aAAa,GAAG,MAAM,CAAC;IACzB,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC,CAAC,YAAY,GAAG,KAAK,CAAC;IACvB,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC;IACpB,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAmB,EAAE,UAA0B,EAAE;IAC7E,MAAM,MAAM,GAAG,MAAM,KAAK,QAAQ,CAAC,IAAI,IAAI,MAAM,KAAK,QAAQ,CAAC,eAAe,CAAC;IAC/E,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,EAAE,CAAC,QAAQ,KAAK,QAAQ;YAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,UAAU,CAAC;IACnE,CAAC;IAED,4EAA4E;IAC5E,uCAAuC;IACvC,IAAI,MAAqC,CAAC;IAC1C,MAAM,UAAU,GAAG,GAAsB,EAAE;QACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC3C,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC,CAAC,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC9B,4EAA4E;QAC5E,MAAM,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAC1C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IACF,IAAI,OAAO,CAAC,MAAM;QAAE,MAAM,GAAG,UAAU,EAAE,CAAC;IAE1C,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,CAAC,OAAO,CAAC,QAAQ,GAAG,YAAY,CAAC;IACvC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAE3B,OAAO;QACL,MAAM;QACN,IAAI,MAAM;YACR,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,YAAY;YACV,IAAI,CAAC,MAAM;gBAAE,MAAM,GAAG,UAAU,EAAE,CAAC;YACnC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE;YACZ,MAAM,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,EAAE,MAAM,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,UAAU,CAAC;AAEjE,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,CAAC,EAAE,YAAY,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACpC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * 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`).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@dopaminefx/core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic slim runtime + shared engine for Dopamine visual effects (vanilla TS + WebGL2). Effects ship as separate @dopaminefx/effect-* packages.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "license": "MIT",
+  "author": "10in30",
+  "homepage": "https://github.com/10in30/dopamine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/10in30/dopamine.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/10in30/dopamine/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/engine/color.ts

@@ -0,0 +1,154 @@
+/**
+ * Algorithmic color in OKLCH.
+ *
+ * OKLCH is perceptually uniform, so walking hue by the golden angle (137.5°)
+ * yields palettes that are always harmonious yet never repeat — the novelty
+ * that keeps a reward from habituating. Lightness/chroma come from the mood
+ * (saturated + bright == higher arousal *and* positive valence).
+ *
+ * We hand the shader *linear* sRGB, because light should be summed in linear
+ * space; sRGB gamma is only for talking to CSS.
+ */
+
+import type { Rng } from "./seed.js";
+
+/** Linear sRGB, nominally 0..1 (may exceed before clamping). */
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export interface OKLCH {
+  /** Perceptual lightness, 0..1. */
+  L: number;
+  /** Chroma (colorfulness), ~0..0.4. */
+  C: number;
+  /** Hue in degrees, 0..360. */
+  h: number;
+}
+
+export const GOLDEN_ANGLE_DEG = 137.50776405003785;
+
+const clamp01 = (x: number): number => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+/** Positive modulo into [0, 360). */
+export const wrapHue = (h: number): number => ((h % 360) + 360) % 360;
+
+/**
+ * OKLCH → linear sRGB (Björn Ottosson's OKLab matrices). Result is gamut-clamped
+ * to [0, 1] per channel.
+ */
+export function oklchToLinearSrgb({ L, C, h }: OKLCH): RGB {
+  const hr = (h * Math.PI) / 180;
+  const a = C * Math.cos(hr);
+  const b = C * Math.sin(hr);
+
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+
+  return {
+    r: clamp01(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+    g: clamp01(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+    b: clamp01(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+  };
+}
+
+export interface PaletteParams {
+  /** Base lightness for the stops. */
+  lightness: number;
+  /** Base chroma for the stops. */
+  chroma: number;
+  /** Center of the hue range this mood prefers, in degrees. */
+  hueCenter: number;
+  /** Width of the random hue range around the center, in degrees. */
+  hueRange: number;
+  /** 0..1 — how far the golden-angle stops fan out from the base hue. */
+  hueSpread: number;
+}
+
+/**
+ * Build a 3-stop linear-RGB palette. The base hue is drawn from `rng` (so an
+ * un-pinned seed gives a unique palette each fire), biased toward the mood's
+ * preferred range. Successive stops step by the golden angle, scaled by whimsy.
+ * Lightness and chroma breathe slightly across the stops for depth.
+ */
+export function buildPalette(rng: Rng, p: PaletteParams): RGB[] {
+  const baseHue = wrapHue(p.hueCenter + (rng() - 0.5) * p.hueRange);
+  const step = GOLDEN_ANGLE_DEG * (0.35 + 0.65 * p.hueSpread);
+  const lightSteps = [0.0, 0.06, -0.05];
+  const chromaSteps = [0.0, 0.02, -0.01];
+
+  return [0, 1, 2].map((i) =>
+    oklchToLinearSrgb({
+      L: clamp01(p.lightness + lightSteps[i]!),
+      C: Math.max(0, p.chroma + chromaSteps[i]!),
+      h: wrapHue(baseHue + step * i),
+    }),
+  );
+}
+
+/** A parsed backdrop colour the overlay composites against. */
+export interface Backdrop {
+  /** sRGB 0..1 (the value as authored — NOT linearised). */
+  rgb: RGB;
+  /** Rec.709 relative luminance in sRGB space, 0 (black) .. 1 (white). */
+  luminance: number;
+}
+
+/** Parse `#rgb[a]` / `#rrggbb[aa]` hex (3/4/6/8 digits) into sRGB 0..1, or null. */
+function parseHex(s: string): RGB | null {
+  const m = /^#([0-9a-f]{3,8})$/i.exec(s);
+  if (!m) return null;
+  const h = m[1]!;
+  const dup = (c: string): number => parseInt(c + c, 16) / 255;
+  if (h.length === 3 || h.length === 4) return { r: dup(h[0]!), g: dup(h[1]!), b: dup(h[2]!) };
+  if (h.length === 6 || h.length === 8) {
+    const at = (i: number): number => parseInt(h.slice(i, i + 2), 16) / 255;
+    return { r: at(0), g: at(2), b: at(4) };
+  }
+  return null;
+}
+
+/** Parse `rgb()/rgba()` (comma- or space-separated, 0–255 or %), or null. */
+function parseRgbFunc(s: string): RGB | null {
+  const m = /^rgba?\(([^)]+)\)$/i.exec(s.trim());
+  if (!m) return null;
+  const parts = m[1]!.split(/[\s,/]+/).filter(Boolean).slice(0, 3);
+  if (parts.length < 3) return null;
+  const chan = (p: string): number =>
+    p.endsWith("%") ? clamp01(parseFloat(p) / 100) : clamp01(parseFloat(p) / 255);
+  return { r: chan(parts[0]!), g: chan(parts[1]!), b: chan(parts[2]!) };
+}
+
+/**
+ * Parse any CSS colour string into a {@link Backdrop} (sRGB 0..1 + luminance),
+ * or `null` if it can't be understood. Handles hex and `rgb()/rgba()` directly;
+ * for everything else (named colours, `hsl()`, `color()`) it falls back to the
+ * browser's own normaliser via a throwaway 2D canvas when a DOM is present. The
+ * runtime uses the luminance to decide how strongly to cast shadow as a surface
+ * lightens; the colour itself isn't sent to the shader (the light layer
+ * composites source-over against the live page).
+ */
+export function parseBackdrop(css: string): Backdrop | null {
+  let rgb = parseHex(css) ?? parseRgbFunc(css);
+  if (!rgb && typeof document !== "undefined") {
+    try {
+      const ctx = document.createElement("canvas").getContext("2d");
+      if (ctx) {
+        ctx.fillStyle = "#000";
+        ctx.fillStyle = css; // the browser normalises to #rrggbb or rgb(a)(...)
+        rgb = parseHex(ctx.fillStyle) ?? parseRgbFunc(ctx.fillStyle);
+      }
+    } catch {
+      /* no canvas — fall through to null */
+    }
+  }
+  if (!rgb) return null;
+  return { rgb, luminance: 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b };
+}

package/src/engine/gl.ts

@@ -0,0 +1,46 @@
+/**
+ * Low-level WebGL2 helpers: shader compilation + program linking. Kept separate
+ * from any particular effect so every effect (and the shared context's program
+ * cache) reuses the exact same, well-tested path. This is the single place a
+ * GLSL program is compiled in the whole library.
+ */
+
+function compileShader(
+  gl: WebGL2RenderingContext,
+  type: number,
+  src: string,
+): WebGLShader {
+  const sh = gl.createShader(type);
+  if (!sh) throw new Error("dopamine: failed to create shader");
+  gl.shaderSource(sh, src);
+  gl.compileShader(sh);
+  if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(sh);
+    gl.deleteShader(sh);
+    throw new Error(`dopamine: shader compile error\n${log ?? ""}`);
+  }
+  return sh;
+}
+
+/** Compile + link a vertex/fragment pair into a program. */
+export function linkProgram(
+  gl: WebGL2RenderingContext,
+  vertexSrc: string,
+  fragmentSrc: string,
+): WebGLProgram {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, vertexSrc);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, fragmentSrc);
+  const program = gl.createProgram();
+  if (!program) throw new Error("dopamine: failed to create program");
+  gl.attachShader(program, vs);
+  gl.attachShader(program, fs);
+  gl.linkProgram(program);
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    const log = gl.getProgramInfoLog(program);
+    gl.deleteProgram(program);
+    throw new Error(`dopamine: program link error\n${log ?? ""}`);
+  }
+  return program;
+}