shardlight 0.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,901 @@
+import { E as EffectConfig, a as ShardLightConfig, P as Preset, S as ShardInput, R as ResolvedLight, B as Baker, L as LayerSource, d as ResolvedLayer, e as BaseShardKinds, f as BaseShardPresets } from '../baker-BmlWqsXG.js';
+export { g as BakeOptions, h as BlobParams, i as BuiltInPresetName, C as ClusterParams, F as FanParams, H as HaloParams, N as NullContextError, j as ResolvedCollapse, k as ResolvedHover, l as ResolvedShard, m as ResolvedSpin, c as ShardBase, n as ShardBlend, o as ShardCollapse, b as ShardConfig, p as ShardHover, q as ShardSpin } from '../baker-BmlWqsXG.js';
+
+/**
+ * Param schemas. One schema per kind or effect drives types, defaults,
+ * validation and (later) shader backends.
+ */
+interface NumberParam {
+    type: 'number';
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** `'px'` costs and widths scale with the bake resolution. */
+    unit?: string;
+    /** Multiplied by the `rayScale` render option. */
+    ray?: boolean;
+    label?: string;
+}
+interface AngleParam {
+    type: 'angle';
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    label?: string;
+}
+interface ColorParam {
+    type: 'color';
+    default: string;
+    label?: string;
+}
+interface BooleanParam {
+    type: 'boolean';
+    default: boolean;
+    label?: string;
+}
+interface EnumParam {
+    type: 'enum';
+    default: string;
+    values: readonly string[];
+    label?: string;
+}
+interface ChannelsParam {
+    type: 'channels';
+    default: readonly string[];
+    label?: string;
+}
+type ParamSchema = NumberParam | AngleParam | ColorParam | BooleanParam | EnumParam | ChannelsParam;
+type ParamMap = Record<string, ParamSchema>;
+/** The runtime value type a schema describes. */
+type ValueOfParam<P> = P extends {
+    type: 'number' | 'angle';
+} ? number : P extends {
+    type: 'color';
+} ? string : P extends {
+    type: 'boolean';
+} ? boolean : P extends {
+    type: 'channels';
+} ? string[] : P extends {
+    type: 'enum';
+    values: readonly (infer V)[];
+} ? V : unknown;
+/** Derive the param value type from a schema map: `ParamsOf<typeof dots>`. */
+type ParamsFromSchema<P extends ParamMap> = {
+    [K in keyof P]: ValueOfParam<P[K]>;
+};
+type ParamsOf<D> = D extends {
+    params: infer P extends ParamMap;
+} ? ParamsFromSchema<P> : Record<string, unknown>;
+
+type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/**
+ * Everything a draw function needs besides the context and its params. The
+ * context is already centred and rotated for the shard; draw functions work in
+ * local coordinates with the origin at the light's centre.
+ */
+interface DrawEnv {
+    /** Half-edge of the bake canvas, in px (`resolution / 2`). */
+    unit: number;
+    /** Base-pixel scale (`resolution / 1024`), for px-valued parameters. */
+    px: number;
+    /** The shard's resolved colour. */
+    color: string;
+    /** Render option that thins every ray on lights shown much larger than tuned. */
+    rayScale: number;
+    /** Bake canvas edge, in px. */
+    size: number;
+    /** The shard's own PRNG. Consume it in a fixed order for determinism. */
+    rng: () => number;
+    /** Format the shard's colour at a given alpha. */
+    rgba: (alpha: number) => string;
+}
+/**
+ * A shard kind: a param schema plus a draw function. The four built-ins are
+ * written the same way and go through the same registry, so nothing in core
+ * switches on kind names.
+ */
+interface ShardKindDefinition<K extends string = string, P extends ParamMap = ParamMap> {
+    kind: K;
+    label?: string;
+    params: P;
+    draw: (ctx: Ctx2D, params: ParamsFromSchema<P>, env: DrawEnv) => void;
+    /**
+     * Optional composite blur for this shard, in px. Defaults to the shard's
+     * `softness` param when present.
+     */
+    blur?: (params: ParamsFromSchema<P>, env: DrawEnv) => number;
+    /**
+     * Optional mask applied to the shard's scratch canvas after drawing (e.g. the
+     * variance mask for blob/halo). Receives an untransformed context.
+     */
+    mask?: (ctx: Ctx2D, params: ParamsFromSchema<P>, env: DrawEnv, size: number) => void;
+}
+
+/** `blob`: a soft round glow. A radial gradient from the centre out to `size`. */
+declare const blob: ShardKindDefinition<"blob", {
+    readonly strength: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly size: {
+        readonly type: "number";
+        readonly default: 0.5;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly hardness: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 0.999;
+    };
+    readonly falloff: {
+        readonly type: "number";
+        readonly default: 2;
+        readonly min: 0.1;
+        readonly max: 8;
+    };
+    readonly aspect: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0.1;
+        readonly max: 10;
+    };
+    readonly angle: {
+        readonly type: "angle";
+        readonly default: 0;
+    };
+    readonly softness: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 50;
+        readonly unit: "px";
+    };
+    readonly variance: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 1;
+    };
+}>;
+
+/**
+ * `fan`: `count` rays spread evenly round the centre. Each ray is a quad
+ * tapering from root to tip, filled with a linear gradient along its length.
+ */
+declare const fan: ShardKindDefinition<"fan", {
+    readonly strength: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly size: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly count: {
+        readonly type: "number";
+        readonly default: 4;
+        readonly min: 1;
+        readonly max: 256;
+        readonly step: 1;
+    };
+    readonly angle: {
+        readonly type: "angle";
+        readonly default: 0;
+    };
+    readonly jitter: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly inner: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly variance: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly width: {
+        readonly type: "number";
+        readonly default: 4;
+        readonly min: 0;
+        readonly max: 100;
+        readonly unit: "px";
+        readonly ray: true;
+    };
+    readonly taper: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly falloff: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 8;
+    };
+    readonly fadeIn: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly softness: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 50;
+        readonly unit: "px";
+        readonly ray: true;
+    };
+}>;
+
+/**
+ * `clusters`: `clusters` bundles, spread evenly round the centre, of
+ * `perCluster` fine rays each. Rays are drawn like `fan` rays.
+ */
+declare const clusters: ShardKindDefinition<"clusters", {
+    readonly clusters: {
+        readonly type: "number";
+        readonly default: 4;
+        readonly min: 1;
+        readonly max: 64;
+        readonly step: 1;
+    };
+    readonly perCluster: {
+        readonly type: "number";
+        readonly default: 5;
+        readonly min: 1;
+        readonly max: 64;
+        readonly step: 1;
+    };
+    readonly spread: {
+        readonly type: "number";
+        readonly default: 20;
+        readonly min: 0;
+        readonly max: 360;
+    };
+    readonly inner: {
+        readonly type: "number";
+        readonly default: 0.1;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly strength: {
+        readonly type: "number";
+        readonly default: 0.5;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly size: {
+        readonly type: "number";
+        readonly default: 0.5;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly angle: {
+        readonly type: "angle";
+        readonly default: 0;
+    };
+    readonly variance: {
+        readonly type: "number";
+        readonly default: 0.5;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly width: {
+        readonly type: "number";
+        readonly default: 2;
+        readonly min: 0;
+        readonly max: 100;
+        readonly unit: "px";
+        readonly ray: true;
+    };
+    readonly taper: {
+        readonly type: "number";
+        readonly default: 0.5;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly falloff: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 8;
+    };
+    readonly fadeIn: {
+        readonly type: "number";
+        readonly default: 0.1;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly softness: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 50;
+        readonly unit: "px";
+        readonly ray: true;
+    };
+}>;
+
+/**
+ * `halo`: a ring. A radial gradient between `size − width/2` and
+ * `size + width/2`, brightest at `size`.
+ */
+declare const halo: ShardKindDefinition<"halo", {
+    readonly strength: {
+        readonly type: "number";
+        readonly default: 0.1;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly size: {
+        readonly type: "number";
+        readonly default: 0.5;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly width: {
+        readonly type: "number";
+        readonly default: 0.05;
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly falloff: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 8;
+    };
+    readonly softness: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 50;
+        readonly unit: "px";
+    };
+    readonly variance: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 1;
+    };
+}>;
+
+/** Register the built-in kinds as ordinary definitions. */
+declare function registerBuiltInKinds(): void;
+
+/**
+ * A frame's animation values. Effects start from scale 1, opacity 1, rotation 0
+ * and compose by multiplying scale/opacity and adding to rotation.
+ */
+interface FrameValues {
+    /** The values for a channel, created on first access at scale 1 / opacity 1. */
+    channel(name: string): ChannelValues;
+    /** The whole light's opacity. */
+    opacity: number;
+    /** Light-wide hover amount, 0..1, eased by the model. */
+    hover: number;
+    /** Seconds accumulated while hovered; lets effects spin up on hover. */
+    hoverTime: number;
+    /** Light-wide collapsed amount, 0..1, eased by the model. */
+    collapse: number;
+    /** Channel names currently present (built-in effects use this for `channels: 'all'`). */
+    channels(): string[];
+}
+interface EffectDefinition<N extends string = string, P extends ParamMap = ParamMap> {
+    name: N;
+    label?: string;
+    params: P;
+    /** Pure: advance the frame values for time `t` (seconds). */
+    apply: (t: number, params: ParamsFromSchema<P>, out: FrameValues) => void;
+    /**
+     * Optional CSS-keyframes form the DOM adapter can use instead of one JS call
+     * per frame. Reserved for a later release.
+     */
+    css?: (params: ParamsFromSchema<P>) => string;
+    /** Pause under `prefers-reduced-motion` unless this is `'keep'`. */
+    reducedMotion?: 'keep';
+}
+
+/**
+ * `pulse`: multiplies each channel's scale by `1 + amount·sin(2π·speed·t)`.
+ */
+declare const pulse: EffectDefinition<"pulse", {
+    readonly channels: {
+        readonly type: "channels";
+        readonly default: readonly ["main"];
+    };
+    readonly speed: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 10;
+        readonly step: 0.01;
+    };
+    readonly amount: {
+        readonly type: "number";
+        readonly default: 0.1;
+        readonly min: 0;
+        readonly max: 1;
+    };
+}>;
+
+/**
+ * `flicker`: a two-sine brightness wobble, applied to each channel's opacity.
+ * `channels: ['*']` (the default) means every channel.
+ */
+declare const flicker: EffectDefinition<"flicker", {
+    readonly amount: {
+        readonly type: "number";
+        readonly default: 0.15;
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly speed: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 10;
+        readonly step: 0.01;
+    };
+    readonly channels: {
+        readonly type: "channels";
+        readonly default: readonly ["*"];
+    };
+}>;
+
+/**
+ * `spin`: adds `phase + speed · 360 · t` degrees to each target channel's
+ * rotation. Several spin effects on one channel add up, so a shard can turn at
+ * the sum of their speeds.
+ */
+declare const spin: EffectDefinition<"spin", {
+    readonly channels: {
+        readonly type: "channels";
+        readonly default: readonly ["main"];
+    };
+    readonly speed: {
+        readonly type: "number";
+        readonly default: 0.1;
+        readonly min: -10;
+        readonly max: 10;
+        readonly step: 0.01;
+        readonly unit: "turns/s";
+    };
+    readonly phase: {
+        readonly type: "angle";
+        readonly default: 0;
+    };
+}>;
+
+/**
+ * `hover`: eases each target channel toward `scale` / `opacity` / `rotate` as
+ * the pointer sits over the light, and keeps turning at `spin` turns/s while it
+ * is there. `out.hover` is the light-wide hover amount (0..1) and
+ * `out.hoverTime` is the seconds accumulated while hovered, both eased by the
+ * model, so the response is the same shape everywhere.
+ *
+ * Hover is user-driven, so it keeps running under `prefers-reduced-motion`.
+ */
+declare const hover: EffectDefinition<"hover", {
+    readonly channels: {
+        readonly type: "channels";
+        readonly default: readonly ["main"];
+    };
+    readonly scale: {
+        readonly type: "number";
+        readonly default: 1.15;
+        readonly min: 0;
+        readonly max: 4;
+        readonly step: 0.01;
+    };
+    readonly opacity: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 4;
+        readonly step: 0.01;
+    };
+    readonly rotate: {
+        readonly type: "angle";
+        readonly default: 0;
+    };
+    readonly spin: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: -10;
+        readonly max: 10;
+        readonly step: 0.01;
+        readonly unit: "turns/s";
+    };
+}>;
+
+/** How a light reacts to a click when it has a `collapse` effect. */
+type CollapseTrigger = 'click' | 'once' | 'none';
+/**
+ * `collapse`: shrinks (`scale`) and fades (`opacity`) each target channel as the
+ * light is clicked. `out.collapse` is the light-wide collapsed amount (0..1),
+ * eased by the model.
+ *
+ * `trigger` decides the built-in click behavior: `'click'` toggles, `'once'`
+ * collapses and stays, `'none'` leaves the click alone so you can drive
+ * `setCollapsed()` yourself.
+ *
+ * Click is user-driven, so it keeps running under `prefers-reduced-motion`.
+ */
+declare const collapse: EffectDefinition<"collapse", {
+    readonly channels: {
+        readonly type: "channels";
+        readonly default: readonly ["*"];
+    };
+    readonly scale: {
+        readonly type: "number";
+        readonly default: 0;
+        readonly min: 0;
+        readonly max: 4;
+        readonly step: 0.01;
+    };
+    readonly opacity: {
+        readonly type: "number";
+        readonly default: 1;
+        readonly min: 0;
+        readonly max: 4;
+        readonly step: 0.01;
+    };
+    readonly trigger: {
+        readonly type: "enum";
+        readonly default: "click";
+        readonly values: readonly ["click", "once", "none"];
+    };
+}>;
+/**
+ * The built-in click behavior for a light's `collapse` effects. `'none'` wins
+ * when set (an explicit opt-out), then `'once'`, otherwise `'click'`.
+ */
+declare function collapseTrigger(effects: readonly EffectConfig[]): CollapseTrigger;
+
+/** Register the built-in effects as ordinary definitions. */
+declare function registerBuiltInEffects(): void;
+
+/** `star` (default): a warm 4-point star with a soft bloom and a faint ring. */
+declare const star: ShardLightConfig;
+
+/** `sun`: a big soft sun with many faint, slightly jittered rays. */
+declare const sun: ShardLightConfig;
+
+/** `sparkle`: a small crisp glint — a tight core with two crossed fans. */
+declare const sparkle: ShardLightConfig;
+
+/** `starburst`: a bright core throwing many long, fine, uneven rays. */
+declare const starburst: ShardLightConfig;
+
+/** `ember`: a warm, low glow with a few short, uneven sparks. */
+declare const ember: ShardLightConfig;
+
+/** Register the built-in presets by name. */
+declare function registerBuiltInPresets(): void;
+
+interface ResolveInput {
+    /** Starting config. Omitted or `null` = start empty (only the shards you give). */
+    preset?: Preset | null;
+    /** Data-driven config merged over the preset. */
+    config?: Partial<ShardLightConfig> | null;
+    /** Per-shard overrides (`<Shard>` children / the `shards` option). */
+    shards?: readonly ShardInput[] | null;
+    /** Effects; overrides `config.effects` when provided. */
+    effects?: readonly EffectConfig[] | null;
+    color?: string;
+    rotation?: number;
+    seed?: number;
+}
+interface ResolveOptions {
+    /** Force development warnings on/off. Defaults to NODE_ENV !== 'production'. */
+    warn?: boolean;
+    /** Preset used when `preset` is omitted. Defaults to none. */
+    defaultPreset?: string | null;
+}
+/**
+ * The single place that decides what gets drawn. Every adapter calls
+ * it. Order: preset → config → shard overrides, merged per shard by `id`; then
+ * kind defaults are filled in; then values are clamped.
+ */
+declare function resolveConfig(input?: ResolveInput, options?: ResolveOptions): ResolvedLight;
+
+declare const CURRENT_VERSION = 1;
+/**
+ * Upgrade older config JSON to the current schema version, step by step
+ *. Adapters run this on every config they're given, so old saves
+ * keep working. Unknown fields are preserved so a config from a newer version
+ * degrades gracefully rather than throwing.
+ */
+declare function migrateConfig(input: unknown): ShardLightConfig;
+
+/** Define a kind object. Does not register it. */
+declare function defineShardKind<K extends string, const P extends ParamMap>(def: ShardKindDefinition<K, P>): ShardKindDefinition<K, P>;
+declare function registerShardKind(def: ShardKindDefinition<string, ParamMap>): void;
+declare function getShardKind(kind: string): ShardKindDefinition<string, ParamMap> | undefined;
+declare function listShardKinds(): ShardKindDefinition<string, ParamMap>[];
+declare function unregisterShardKind(kind: string): void;
+
+/** Define an effect object. Does not register it. */
+declare function defineEffect<N extends string, const P extends ParamMap>(def: EffectDefinition<N, P>): EffectDefinition<N, P>;
+declare function registerEffect(def: EffectDefinition<string, ParamMap>): void;
+declare function getEffect(name: string): EffectDefinition<string, ParamMap> | undefined;
+declare function listEffects(): EffectDefinition<string, ParamMap>[];
+declare function unregisterEffect(name: string): void;
+
+/** Values set by hand through `set()`; effects compose on top of these. */
+interface FrameBase {
+    channels?: Record<string, {
+        scale?: number;
+        opacity?: number;
+        rotation?: number;
+    }>;
+    opacity?: number;
+    /** Light-wide hover amount, 0..1. Default 0. */
+    hover?: number;
+    /** Seconds accumulated while hovered. Default 0. */
+    hoverTime?: number;
+    /** Light-wide collapsed amount, 0..1. Default 0. */
+    collapse?: number;
+}
+/**
+ * Compute a frame: start from the manual base (scale 1 / opacity 1 / rotation 0),
+ * seed every known channel, then let each effect multiply scale and opacity and
+ * add to rotation.
+ */
+declare function computeFrame(base: FrameBase, effects: readonly EffectConfig[], t: number, channelNames?: readonly string[]): FrameValues;
+
+/** Define a preset object. Does not register it, so it can be passed directly. */
+declare function definePreset(config: ShardLightConfig): ShardLightConfig;
+declare function registerPreset(name: string, config: ShardLightConfig): void;
+declare function getPreset(name: string): ShardLightConfig | undefined;
+declare function listPresets(): string[];
+declare function unregisterPreset(name: string): void;
+
+/**
+ * The default baker. Draws each shard to its own scratch canvas with
+ * the kind's `draw`, applies its variance mask, then composites it onto the
+ * layer canvas with `lighter` and a per-shard blur.
+ */
+declare const canvas2dBaker: Baker;
+
+declare function acquireSource(key: string, start: (signal: AbortSignal) => Promise<LayerSource>): Promise<LayerSource>;
+declare function releaseSource(key: string): void;
+declare function disposeSource(source: LayerSource): void;
+/** Number of live entries; used by the memory tests. */
+declare function cacheSize(): number;
+declare function clearCache(): void;
+
+/**
+ * Runs bakes one layer per task, yielding between them, so a big light never
+ * blocks a frame and stale bakes never finish.
+ */
+interface Scheduler {
+    run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Drop everything still queued (does not cancel the running task). */
+    clear(): void;
+}
+interface SchedulerOptions {
+    /** Delay between tasks, in ms. 0 (a macrotask) still yields. */
+    yieldDelay?: number;
+}
+declare function createScheduler(options?: SchedulerOptions): Scheduler;
+declare function abortError(): Error;
+declare function isAbortError(error: unknown): boolean;
+
+interface PrewarmOptions extends ResolveInput {
+    resolution?: number;
+    rayScale?: number;
+    baker?: Baker;
+    accepts?: LayerSource['type'][];
+    warn?: boolean;
+}
+/**
+ * Bake a config into the shared cache ahead of time, so a light that appears on
+ * a key moment (a reveal, an entrance) is ready before it's needed.
+ * Holds a cache reference until `releasePrewarm()` is called.
+ */
+declare function prewarm(options?: PrewarmOptions): Promise<void>;
+/** Release the cache references held by `prewarm()`. */
+declare function releasePrewarm(): void;
+
+/** One host unit: one baked image, one `<img>` or plane. */
+interface Layer {
+    /** Stable while the layer exists: `${channel}|${blend}`. */
+    id: string;
+    /** Content hash; changes when the layer needs re-baking. */
+    key: string;
+    channel: string;
+    blend: 'add' | 'screen';
+    source: LayerSource | null;
+}
+interface SetValues {
+    channels?: Record<string, {
+        scale?: number;
+        opacity?: number;
+        rotation?: number;
+    }>;
+    /** The whole light's opacity. */
+    opacity?: number;
+    /** Direct hover amount 0..1; also snaps the eased hover target. */
+    hover?: number;
+    /** Direct collapsed amount 0..1; also snaps the eased collapse target. */
+    collapse?: number;
+}
+interface LightModelOptions extends ResolveInput {
+    resolution?: number;
+    rayScale?: number;
+    baker?: Baker;
+    accepts?: LayerSource['type'][];
+    /** Pause effects under `prefers-reduced-motion`. */
+    reducedMotion?: boolean;
+    /** Seconds for hover to ease in/out. Default 0.25; 0 snaps. */
+    hoverEase?: number;
+    /** Seconds for the click collapse to ease in/out. Default 0.3; 0 snaps. */
+    collapseEase?: number;
+    warn?: boolean;
+    onError?: (error: unknown) => void;
+}
+interface LightModel {
+    subscribe(listener: (layers: Layer[]) => void): () => void;
+    onFrame(listener: (values: FrameValues) => void): () => void;
+    update(patch: Partial<LightModelOptions>): void;
+    set(values: SetValues): void;
+    setChannel(channel: string, values: {
+        scale?: number;
+        opacity?: number;
+        rotation?: number;
+    }): void;
+    /** Ease the light-wide hover amount toward 0 or 1. */
+    setHover(hovered: boolean): void;
+    /** Ease the light-wide collapse toward 0 (expanded) or 1 (collapsed). */
+    setCollapsed(collapsed: boolean): void;
+    /** Flip between expanded and collapsed. */
+    toggleCollapsed(): void;
+    tick(dt: number): void;
+    dispose(): void;
+    readonly layers: readonly Layer[];
+    readonly resolved: ResolvedLight;
+    /** Resolves once every currently-known layer has a baked source. */
+    readonly ready: Promise<void>;
+}
+/**
+ * The headless controller every target wraps. It owns everything that
+ * isn't drawing to a host: resolving, grouping, baking, caching, diffing and
+ * effects.
+ */
+declare function createLightModel(options?: LightModelOptions): LightModel;
+
+interface BakeInputs {
+    resolution: number;
+    rayScale: number;
+    baker: string;
+    accept: string[];
+}
+/**
+ * Group shards into layers: shards that share `channel` + `blend` are baked
+ * baked together into one image. The layer `key` is a stable content
+ * hash (resolved shards + light-wide bake inputs) used for caching and sharing.
+ */
+declare function buildLayers(light: ResolvedLight, inputs: BakeInputs): ResolvedLayer[];
+declare function layerId(channel: string, blend: string): string;
+
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Parse the common CSS colour forms used by lights: #rgb, #rgba, #rrggbb,
+ * #rrggbbaa, rgb()/rgba(). Falls back to opaque white for anything unknown so a
+ * malformed colour never blanks a whole light.
+ */
+declare function parseColor(input: string): RGB;
+/** A function that formats a colour at a given alpha, for a draw env. */
+type RgbaFormatter = (alpha: number) => string;
+declare function makeRgba(color: string): RgbaFormatter;
+/** Loose validity check for names used in CSS custom properties. */
+declare function isCssIdentifier(name: string): boolean;
+
+/**
+ * FNV-1a string hash. Deterministic across runs and platforms.
+ * Used to seed a shard's PRNG from its `id`, so reordering or inserting
+ * shards never reshuffles the other shards' randomness.
+ */
+declare function hashString(input: string): number;
+
+/** mulberry32: a tiny, fast, seedable PRNG. */
+declare function mulberry32(seed: number): () => number;
+/**
+ * A shard's PRNG seed: `hash(id) ^ (shard.seed ?? light.seed)`.
+ * Seeding by id (not position) keeps each shard's randomness stable.
+ */
+declare function shardSeed(id: string, seed: number): number;
+
+/**
+ * Stable, deterministic serialisation used for cache keys and diffing.
+ * Key order never affects the output.
+ */
+declare function stableStringify(value: unknown): string;
+
+/** Environment helpers shared by the bakers and adapters. */
+type AnyCanvas = HTMLCanvasElement | OffscreenCanvas;
+type AnyCanvasContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+declare function isBrowser(): boolean;
+/** Create a canvas of the best available flavour for the current host. */
+declare function createCanvas(width: number, height: number): AnyCanvas;
+declare function get2dContext(canvas: AnyCanvas): AnyCanvasContext | null;
+/**
+ * Free a scratch canvas immediately rather than waiting for the GC.
+ * Setting both dimensions to 0 releases the backing store in browsers.
+ */
+declare function freeCanvas(canvas: AnyCanvas): void;
+declare function canvasToBlob(canvas: AnyCanvas): Promise<Blob>;
+declare function isLowMemoryDevice(): boolean;
+
+/**
+ * Copy only the own properties whose value is not `undefined`.
+ *
+ * Used when merging options over defaults: a caller that spreads an optional
+ * prop (e.g. `{ baker }` where `baker` is undefined) must not wipe out the
+ * default. `null` is kept, since it is a meaningful value for `preset`.
+ */
+declare function definedOnly<T extends object>(value: T): Partial<T>;
+
+/**
+ * **shardlight** — core (headless).
+ *
+ * Framework-free: no React, no three. Config model, shard kinds, presets,
+ * effects, baking and cache. Adapters (`shardlight/react`, `shardlight/three`,
+ * `shardlight/r3f`) wrap `createLightModel()` and draw its layers to a host.
+ *
+ * Importing this module registers the built-in kinds, effects and presets, so
+ * `preset="sun"` works with no setup. That is the package's only side effect.
+ */
+
+/**
+ * Built-in shard kinds, plus any added by downstream code:
+ *
+ * ```ts
+ * declare module 'shardlight' {
+ *   interface ShardKinds { dots: ParamsOf<typeof dots> }
+ * }
+ * ```
+ */
+interface ShardKinds extends BaseShardKinds {
+}
+/** Built-in presets, plus any registered by name via `registerPreset()`. */
+interface ShardPresets extends BaseShardPresets {
+}
+/**
+ * Per-channel animation values. Augmentable so a later release can add fields;
+ * v1 ships scale, opacity and rotation.
+ */
+interface ChannelValues {
+    scale: number;
+    opacity: number;
+    /** Degrees; turns this channel's layer around the light's centre. */
+    rotation: number;
+}
+
+export { type AngleParam, type AnyCanvas, type AnyCanvasContext, type BakeInputs, Baker, BaseShardKinds, BaseShardPresets, type BooleanParam, CURRENT_VERSION, type ChannelValues, type ChannelsParam, type CollapseTrigger, type ColorParam, type Ctx2D, type DrawEnv, EffectConfig, type EffectDefinition, type EnumParam, type FrameBase, type FrameValues, type Layer, LayerSource, type LightModel, type LightModelOptions, type NumberParam, type ParamMap, type ParamSchema, type ParamsFromSchema, type ParamsOf, Preset, type PrewarmOptions, type RGB, type ResolveInput, type ResolveOptions, ResolvedLayer, ResolvedLight, type RgbaFormatter, type Scheduler, type SchedulerOptions, type SetValues, ShardInput, type ShardKindDefinition, type ShardKinds, ShardLightConfig, type ShardPresets, type ValueOfParam, abortError, acquireSource, blob, buildLayers, cacheSize, canvas2dBaker, canvasToBlob, clearCache, clusters, collapse, collapseTrigger, computeFrame, createCanvas, createLightModel, createScheduler, defineEffect, definePreset, defineShardKind, definedOnly, disposeSource, ember, fan, flicker, freeCanvas, get2dContext, getEffect, getPreset, getShardKind, halo, hashString, hover, isAbortError, isBrowser, isCssIdentifier, isLowMemoryDevice, layerId, listEffects, listPresets, listShardKinds, makeRgba, migrateConfig, mulberry32, parseColor, prewarm, pulse, registerBuiltInEffects, registerBuiltInKinds, registerBuiltInPresets, registerEffect, registerPreset, registerShardKind, releasePrewarm, releaseSource, resolveConfig, shardSeed, sparkle, spin, stableStringify, star, starburst, sun, unregisterEffect, unregisterPreset, unregisterShardKind };