@tensordoc/prism 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Penberthy and Prism contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @tensordoc/prism
+
+Two-line embed for audio-reactive visualizations. Drop a `<div>`,
+call `new PrismPlayer({ container })`, get a Milkdrop preset or
+Shadertoy fragment shader playing in the browser — reacting to
+whatever audio you connect.
+
+```bash
+npm install @tensordoc/prism
+```
+
+```html
+<div id="viz" style="width:100vw;height:100vh"></div>
+<script type="module">
+  import { PrismPlayer } from "@tensordoc/prism";
+  new PrismPlayer({ container: "viz" });
+</script>
+```
+
+That's it. The visualization runs against a built-in synthetic signal
+until you connect real audio.
+
+## Live demo
+
+[**prism.scott.ai**](https://prism.scott.ai) — the deployed site uses this
+exact package. The "Two-line embed" preview at
+[prism.scott.ai/examples/embed.html](https://prism.scott.ai/examples/embed.html)
+is the smallest possible HTML page using it.
+
+## What you get
+
+**Two rendering backends** that swap automatically based on the
+graph you load:
+
+- **Milkdrop** via [butterchurn](https://github.com/jberg/butterchurn) —
+  ~80 named presets ship in the bundle
+- **Shadertoy** — any GLSL fragment shader following Shadertoy's
+  `mainImage()` convention; loaded from a URL
+
+**Six audio sources** the player accepts:
+
+```js
+new PrismPlayer({
+  container: "viz",
+  audio: "mic",                       // getUserMedia
+  audio: "tab",                       // getDisplayMedia
+  audio: someAudioNode,               // your Web Audio graph
+  audio: someMediaStream,             // anything with audio tracks
+  // audio: undefined (default)       → built-in synthetic signal
+});
+```
+
+**Six image sources** for shader inputs (`iChannel1`):
+
+```js
+new PrismPlayer({
+  container: "viz",
+  image: "https://example.com/a.jpg",        // single URL
+  image: ["a.jpg", "b.jpg", "c.jpg"],        // built-in crossfading slideshow
+  image: "webcam",                            // getUserMedia({video: true})
+  image: "tab",                               // getDisplayMedia({video: true})
+  image: someVideoElement,                    // <video>
+  image: someCanvas,                          // your own renderer
+});
+
+// Tune slideshow timing
+new PrismPlayer({ container, image: ["a.jpg","b.jpg"], holdSeconds: 6 });
+```
+
+**Methods** for runtime control:
+
+```js
+player.load(graphOrShortId);     // swap visualization
+player.connectAudio("mic");      // change audio source
+player.disconnectAudio();        // revert to synthetic signal
+player.connectImage("webcam");   // change image feed
+player.disconnectImage();        // release webcam track, etc.
+player.destroy();                // clean up everything
+```
+
+**Readonly handles** for power users (the underlying primitives are
+exposed; you can call them directly):
+
+```js
+player.audioCtx        // AudioContext
+player.activeBackend   // "milkdrop" | "shadertoy"
+player.milkdrop        // butterchurn handle
+player.shadertoy       // shader runtime
+player.synth           // synthetic signal driver
+player.runtime         // graph executor
+```
+
+## Share-by-URL with short IDs
+
+Every curated catalog entry has a permanent **6-character base62
+share token**. Same idea as YouTube video IDs:
+
+```js
+new PrismPlayer({ container: "viz", graph: "7Hq3pK" });
+```
+
+The lookup happens against the bundled registry — no network call. The
+companion site exposes `prism.scott.ai/?g=<id>` as a one-click shareable URL.
+
+```js
+import { lookup, shortIdToGraph } from "@tensordoc/prism";
+lookup("7Hq3pK");          // { name, source_type, source_url, ... }
+shortIdToGraph("7Hq3pK");  // ready-to-use PrismGraph
+```
+
+## Constructor options (full)
+
+```ts
+new PrismPlayer({
+  container: HTMLElement | string,          // required — DOM id or element
+  graph?: PrismGraph | string,              // short_id or full graph
+  audio?: "mic" | "tab" | MediaStream | AudioNode,
+  audioCtx?: AudioContext,                  // bring your own
+  image?: ImageSource,                      // see "image sources" above
+  holdSeconds?: number,                     // slideshow timing, default 6
+  defaultImage?: string,                    // static fallback URL
+  initialPresetName?: string,               // cold-open Milkdrop preset
+  onReady?: () => void,                     // first-frame callback
+  onError?: (err: Error) => void,
+});
+```
+
+## Optional: draggable picture-in-picture overlay
+
+If you want a Picture-in-Picture viewer for the slideshow, ship with
+`ImageOverlay` — a separate export that gives you a draggable,
+resizable, collapsible card. The player stays headless; you compose:
+
+```js
+import { ImageOverlay } from "@tensordoc/prism";
+const overlay = new ImageOverlay({ mount: document.body });
+// overlay.element is a DOM div you can position or style;
+// overlay.rect is the current rectangle, updated on drag/resize
+```
+
+## Use from a CDN (no install)
+
+```html
+<script type="module">
+  import { PrismPlayer } from "https://esm.sh/@tensordoc/prism";
+  new PrismPlayer({ container: "viz" });
+</script>
+```
+
+## Audio context note
+
+Browsers require a user gesture before audio starts. The player
+creates an AudioContext but leaves it suspended; resume it on the
+first interaction:
+
+```js
+const resume = () => player.audioCtx.resume();
+window.addEventListener("pointerdown", resume, { once: true });
+window.addEventListener("keydown", resume, { once: true });
+```
+
+## Bundle size
+
+ESM ~25 KB gzipped (excluding butterchurn). Butterchurn itself ships
+in the bundle as a regular dependency (~500 KB). If you don't need
+Milkdrop and only want shader visualizations, you can tree-shake
+butterchurn out by importing only what you use:
+
+```js
+import { createShadertoyBackground } from "@tensordoc/prism";
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/backends/milkdrop.d.ts

@@ -0,0 +1,28 @@
+export interface MilkdropBg {
+    /** Pretty name of the currently-loaded preset (live; updates on rotation). */
+    readonly presetName: string;
+    /** Raw preset key (matches catalog `preset_id`). Stable for share / API use. */
+    readonly currentPresetId: string;
+    /** Swap the audio source — call when real tab-audio comes in. */
+    connectAudio: (node: AudioNode) => void;
+    /** Load a new random preset (with a blend transition). Returns the
+     *  pretty name of the newly-loaded preset. */
+    loadRandom: (blendSeconds?: number) => string;
+    /** Load a specific preset by its raw key (matches catalog `preset_id`).
+     *  Returns the pretty name on success; `null` if no preset with that key
+     *  exists in the bundled library. */
+    loadByName: (name: string, blendSeconds?: number) => string | null;
+    /** Load a .milk preset from a URL: fetch text → convertPreset → loadPreset.
+     *  Used for the 526 favorites and future contributor uploads which live
+     *  at public/presets/milkdrop/<slug>.milk. Returns the pretty name on
+     *  success; throws on fetch / parse error so callers can surface it. */
+    loadFromUrl: (url: string, blendSeconds?: number) => Promise<string>;
+    destroy: () => void;
+}
+export interface MilkdropBgOptions {
+    /** Preset key to load on cold open. Falls back to a random pick if the
+     *  name doesn't exist in the bundle. Lets the landing pin a curated
+     *  "atelier" default instead of getting random_$$$ Royal Mashup. */
+    initialPresetName?: string;
+}
+export declare function createMilkdropBackground(audioCtx: AudioContext, canvas: HTMLCanvasElement, silentSource: AudioNode, onReady?: () => void, options?: MilkdropBgOptions): MilkdropBg;

package/dist/backends/shadertoy.d.ts

@@ -0,0 +1,22 @@
+export interface ShadertoyBg {
+    /** Pretty name from the source URL, useful for SKILL readout. */
+    readonly presetName: string;
+    /** URL of the currently-loaded shader. */
+    readonly currentUrl: string | null;
+    /** Connect a Web Audio source — Shadertoy's iChannel0 sees its FFT. */
+    connectAudio: (node: AudioNode) => void;
+    /** Fetch + compile + render a new shader. Resolves once first frame
+     *  paints. Throws on compile error. */
+    loadFromUrl: (url: string) => Promise<string>;
+    /** Bind an image URL as iChannel1. Resolves once decoded + uploaded.
+     *  Pass null to clear (resets to the 1x1 placeholder). */
+    bindImage: (url: string | null) => Promise<void>;
+    /** Pipe a live source (e.g. a slideshow's canvas) into iChannel1 — its
+     *  contents are uploaded to the GPU every frame, so when the slideshow
+     *  advances to the next image, the shader sees it immediately. Pass
+     *  null to disable + revert to whatever was last bound via bindImage. */
+    setLiveSource: (source: HTMLCanvasElement | HTMLVideoElement | null) => void;
+    /** Pause the render loop + free GL resources. */
+    destroy: () => void;
+}
+export declare function createShadertoyBackground(audioCtx: AudioContext, canvas: HTMLCanvasElement, silentSource: AudioNode): ShadertoyBg;

package/dist/image-feed.d.ts

@@ -0,0 +1,32 @@
+export interface SlideshowOptions {
+    /** How long (seconds) each image is held on-screen before the
+     *  crossfade to the next begins. Defaults to 6. */
+    holdSeconds?: number;
+}
+export declare class HeadlessSlideshow {
+    /** The output canvas — bind this to the shader via setLiveSource. */
+    readonly canvas: HTMLCanvasElement;
+    private readonly ctx;
+    private readonly urls;
+    private readonly holdMs;
+    private readonly images;
+    private currentIndex;
+    private nextIndex;
+    /** Wall-clock time the current crossfade started, or null if we're
+     *  in the steady-hold portion of the cycle. */
+    private crossfadeStartMs;
+    private holdTimer;
+    private rafHandle;
+    private destroyed;
+    constructor(urls: string[], opts?: SlideshowOptions);
+    destroy(): void;
+    private preload;
+    private start;
+    private scheduleNext;
+    private advance;
+    private tickCrossfade;
+    /** Draw the current image fully opaque. */
+    private drawFrame;
+    /** Draw the current image, then the next one at alpha=t on top. */
+    private drawCrossfade;
+}

package/dist/image-overlay.d.ts

@@ -0,0 +1,84 @@
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface OverlayState {
+    rect: Rect;
+    collapsed: boolean;
+}
+export interface ImageOverlayOptions {
+    /** Element to mount the card div in. Defaults to document.body. */
+    mount?: HTMLElement;
+    /** Initial card rect in CSS pixels. Defaults to a centered card sized
+     *  to ~58% of viewport width. */
+    initialRect?: Rect;
+    /** BEM class prefix for the card and its parts. Defaults to
+     *  "prism-overlay" — produces classes `.prism-overlay`,
+     *  `.prism-overlay__handle`, `.prism-overlay__collapse`. */
+    className?: string;
+    /** Thumbnail (collapsed) width in CSS pixels. Defaults to 200. */
+    thumbWidth?: number;
+    /** Min visible margin in pixels — drag is clamped so this much of
+     *  the card always stays in the viewport. Defaults to 60. */
+    minVisible?: number;
+    /** Min top edge (pixels from viewport top), e.g. to clear a status
+     *  bar. Defaults to 36. */
+    topMargin?: number;
+    /** Minimum card dimensions while resizing. Defaults to 80×45 (16:9). */
+    minWidth?: number;
+    minHeight?: number;
+    /** Called whenever the rect or collapsed state changes (drag, resize,
+     *  collapse, expand, window resize re-anchor). */
+    onChange?: (state: OverlayState) => void;
+}
+export declare class ImageOverlay {
+    readonly element: HTMLElement;
+    private readonly mount;
+    private readonly className;
+    private readonly thumbW;
+    private readonly thumbH;
+    private readonly thumbMargin;
+    private readonly statusBarH;
+    private readonly minVisible;
+    private readonly minWidth;
+    private readonly minHeight;
+    private readonly onChange?;
+    private _rect;
+    private _collapsed;
+    private uncollapsedRect;
+    private drag;
+    private destroyed;
+    constructor(opts?: ImageOverlayOptions);
+    /** Current card rect (live; do not mutate — call setRect instead). */
+    get rect(): Rect;
+    isCollapsed(): boolean;
+    /** Programmatically set the rect. Silent: does NOT call onChange.
+     *  Use this to push externally-managed state into the overlay
+     *  without echoing back into your own change handler. The internal
+     *  drag/resize handlers emit onChange themselves — that's the only
+     *  source of change notifications. */
+    setRect(next: Rect): void;
+    /** Programmatically collapse. Silent — see setRect. */
+    collapse(): void;
+    /** Programmatically expand. Silent — see setRect. */
+    expand(): void;
+    show(): void;
+    hide(): void;
+    /** Whether the card is currently visible (DOM attribute is the
+     *  source of truth, so this stays accurate if anyone toggles it
+     *  externally for testing). */
+    isVisible(): boolean;
+    destroy(): void;
+    private buildDom;
+    private applyRectToDom;
+    private emit;
+    private defaultRect;
+    private thumbRect;
+    private clampRect;
+    private readonly onWindowResize;
+    private readonly onPointerDown;
+    private readonly onPointerMove;
+    private readonly onPointerEnd;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { PrismPlayer, type PrismPlayerOptions, type GraphInput, type ImageSource, } from './player';
+export { HeadlessSlideshow, type SlideshowOptions } from './image-feed';
+export { ImageOverlay, type ImageOverlayOptions, type OverlayState, type Rect, } from './image-overlay';
+export { GraphRuntime, type ApplyResult, type RuntimeContext } from './runtime';
+export { SyntheticSignal } from './synth';
+export { createMilkdropBackground, type MilkdropBg, type MilkdropBgOptions, } from './backends/milkdrop';
+export { createShadertoyBackground, type ShadertoyBg, } from './backends/shadertoy';
+export { lookup, shortIds, shortIdToGraph, type RegistryEntry } from './registry';
+export * from './types';

package/dist/player.d.ts

@@ -0,0 +1,150 @@
+import { MilkdropBg } from './backends/milkdrop';
+import { ShadertoyBg } from './backends/shadertoy';
+import { GraphRuntime, ApplyResult } from './runtime';
+import { SyntheticSignal } from './synth';
+import { PrismGraph } from './types';
+/** Anything `load()` and the `graph` option accept. A string is treated
+ *  as a catalog short_id (6-char base62) and resolved against the
+ *  bundled registry. */
+export type GraphInput = PrismGraph | string;
+/** Anything the `image` option / `connectImage()` accepts. Strings
+ *  beyond the "webcam" / "tab" sentinels are treated as static URLs. */
+export type ImageSource = "webcam" | "tab" | string | string[] | HTMLCanvasElement | HTMLVideoElement | MediaStream;
+export interface PrismPlayerOptions {
+    /** Where to mount the visualization canvases. Pass either an element
+     *  (preferred from frameworks — React refs, Vue template refs, etc.)
+     *  or a DOM id string for hand-written HTML embeds. The player
+     *  creates its own canvases inside; it does not touch any children
+     *  that already exist there. */
+    container: HTMLElement | string;
+    /** Optional initial graph. Pass a PrismGraph object directly, or a
+     *  6-char short_id string (e.g. "7Hq3pK") to look up an entry from
+     *  the bundled catalog. Without it, cold-opens on a curated milkdrop
+     *  preset; you can call load() later. */
+    graph?: GraphInput;
+    /** Audio source. An AudioNode is connected directly; "mic" and "tab"
+     *  request the matching media stream via getUserMedia /
+     *  getDisplayMedia and connect that. Undefined → the built-in
+     *  SyntheticSignal drives both backends. */
+    audio?: "mic" | "tab" | MediaStream | AudioNode;
+    /** Bring your own AudioContext (useful when the embedder already has
+     *  one; web pages can only have a small number of them). */
+    audioCtx?: AudioContext;
+    /** iChannel1 fallback used by shader backends until something more
+     *  specific is bound by the graph or setLiveSource(). */
+    defaultImage?: string;
+    /** Image feed for shader backends (bound to iChannel1). Accepts:
+     *    - A single URL                          → static image
+     *    - An array of URLs                      → built-in crossfading slideshow
+     *    - "webcam" / "tab"                      → getUserMedia / getDisplayMedia
+     *    - a MediaStream / HTMLVideoElement      → live video
+     *    - an HTMLCanvasElement                  → live canvas (e.g. your own
+     *                                              renderer; the player just
+     *                                              re-uploads its contents every
+     *                                              frame)
+     *  Use this for "I want pictures showing through the shader" without
+     *  thinking about iChannel1 or setLiveSource. */
+    image?: ImageSource;
+    /** Seconds each image is held on-screen before the crossfade to the
+     *  next begins. Only used when `image` is a URL array. Defaults to 6. */
+    holdSeconds?: number;
+    /** Milkdrop preset to load on cold-open. Falls back to a random preset
+     *  from the bundled library if the name isn't found. */
+    initialPresetName?: string;
+    /** Called once the first frame has painted. */
+    onReady?: () => void;
+    /** Async failures (audio capture rejection, graph load errors that
+     *  cannot be surfaced from a synchronous call) land here. */
+    onError?: (err: Error) => void;
+}
+export declare class PrismPlayer {
+    /** AudioContext driving both backends + the default synthetic signal.
+     *  Created on construction unless one was passed in `opts.audioCtx`. */
+    readonly audioCtx: AudioContext;
+    /** Default audio driver: a silent "pink-noise-ish" pad that keeps the
+     *  visualization animated when no real audio is connected. Kept alive
+     *  for the lifetime of the player — call `player.synth.stop()` if you
+     *  want to free it after switching to a real audio source. */
+    readonly synth: SyntheticSignal;
+    /** Milkdrop (butterchurn) backend handle. Cold-opens on a random
+     *  preset (or `initialPresetName` if you passed one). */
+    readonly milkdrop: MilkdropBg;
+    /** Shadertoy backend handle. Idle until a graph with `lf.shadertoy` is
+     *  loaded (or you call `shadertoy.loadFromUrl` directly). */
+    readonly shadertoy: ShadertoyBg;
+    /** Graph executor — dispatches to the right backend based on the
+     *  graph's light-field generator node. */
+    readonly runtime: GraphRuntime;
+    /** Tracks which backend's canvas is currently visible. */
+    activeBackend: "milkdrop" | "shadertoy";
+    private readonly milkdropCanvas;
+    private readonly shadertoyCanvas;
+    private readonly ownsAudioCtx;
+    /** Default hold per image when `image` is a URL list; set in ctor. */
+    private readonly defaultHoldSeconds;
+    /** Owned media resources (MediaStreams we started, <video> elements
+     *  we created internally, headless slideshow). Cleaned up by
+     *  connectImage() before re-binding and by destroy() on teardown. */
+    private currentSlideshow;
+    private currentVideo;
+    private currentStream;
+    /** Audio MediaStream the player started itself ("mic" / "tab"). Held
+     *  so disconnectAudio() can stop the tracks. Null if the caller
+     *  passed in their own stream/node (we never stop tracks we don't own). */
+    private currentAudioOwnedStream;
+    constructor(opts: PrismPlayerOptions);
+    /** Swap to a new graph. Accepts either a full PrismGraph object or a
+     *  6-char short_id string from the bundled registry. Returns the
+     *  ApplyResult the runtime emits so the caller can react to backend
+     *  switches / errors. An unknown short_id returns
+     *  `{ ok: false, error: "unknown short_id ..." }` without touching
+     *  the running visualization. */
+    load(graph: GraphInput, blendSeconds?: number): ApplyResult;
+    /** Connect a new audio source. Accepts:
+     *    - "mic"        — getUserMedia({ audio: true })
+     *    - "tab"        — getDisplayMedia({ audio: true })
+     *    - MediaStream  — wrapped in a MediaStreamAudioSourceNode
+     *    - AudioNode    — connected directly
+     *  Routes the source to both backends so whichever one is active sees
+     *  reactivity. Tracks any MediaStream the player started itself so
+     *  disconnectAudio() can stop the tracks (mic indicator off, etc.). */
+    connectAudio(source: "mic" | "tab" | MediaStream | AudioNode): Promise<AudioNode>;
+    /** Disconnect the current audio source and revert both backends to
+     *  the built-in SyntheticSignal. Stops any MediaStream tracks the
+     *  player started itself (mic / tab capture indicator goes off).
+     *  Streams or AudioNodes the caller passed in are left untouched —
+     *  the caller owns their lifetime. Idempotent. */
+    disconnectAudio(): void;
+    /** Pipe a live source (e.g. a slideshow's canvas) into iChannel1 — its
+     *  contents are re-uploaded each frame. Pass null to disable.
+     *  Most embedders should prefer connectImage(), which handles
+     *  webcam/tab/slideshow plumbing for you. */
+    setLiveSource(source: HTMLCanvasElement | HTMLVideoElement | null): void;
+    /** Connect an image source for the shader's iChannel1. Symmetric to
+     *  connectAudio. Replaces any prior image feed; old MediaStream
+     *  tracks are stopped and internal slideshow timers are cleared.
+     *  See ImageSource for the accepted shapes. */
+    connectImage(source: ImageSource): Promise<void>;
+    /** Stop the current image feed and unbind from the shader. Releases
+     *  resources the player owned: slideshow timer cleared, MediaStream
+     *  tracks stopped (webcam light off), internal <video> detached.
+     *  Canvas/video elements the caller passed in are left untouched.
+     *  After this, the shader reverts to whatever was last bound via
+     *  `defaultImage` or `shadertoy.bindImage()` (or the 1×1 placeholder).
+     *  Idempotent. */
+    disconnectImage(): void;
+    /** Toggle which backend's canvas is visible. Called by GraphRuntime;
+     *  callers can flip it manually too (rare). */
+    setActiveBackend(which: "milkdrop" | "shadertoy"): void;
+    /** Stop animation, free GL resources, detach canvases, close the
+     *  AudioContext (only if the player created it itself). */
+    destroy(): void;
+    /** Wrap a MediaStream in an autoplaying <video> and bind that as the
+     *  live source. The video element is held internally; teardown is
+     *  handled by teardownImageFeed(). */
+    private bindStream;
+    /** Stop the current image feed (slideshow timer, MediaStream tracks,
+     *  internal <video>) and unbind from the shader. Idempotent. */
+    private teardownImageFeed;
+    private resolveAudioNode;
+}