kuinetic 0.1.4 → 0.2.0

package/dist/types/3d/angles.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An authored `<angle>` as a number of degrees.
+ *
+ * Copied from `degreesOf` in `src/effects/carousel/index.ts:523` rather than imported: that file is
+ * part of the default catalog, and a value import from it would pull the catalog into this tier's
+ * bundle to save nine lines. See `src/3d/register.ts` for the same argument at length.
+ *
+ * It has to exist at all because `core/js-params.ts`'s `toNumber` (js-params.ts:165) returns its
+ * *fallback* for any unit other than `''` and `%` — `params.num('spin')` on a validated `"360deg"`
+ * reads back as `0`. `core/params.ts` accepts every CSS angle unit and normalises only the bare and
+ * `d`-suffixed spellings to `deg`, so a value reaching here can legitimately be `0.05turn` or
+ * `1.2rad`, and `Number('0.05turn')` is `NaN`.
+ *
+ * Falls back rather than throwing on an unrecognised unit, for the reason every reader in this
+ * library does: the value has already been validated, so an unfamiliar spelling here means this
+ * function is behind `params.ts`, and a model that does not spin is a better answer than one that
+ * throws during `prepare`.
+ *
+ * @param value - A validated CSS angle.
+ * @param fallbackDeg - Used when the value is not an angle this function converts.
+ * @returns Degrees.
+ * @complexity O(n) time in value length; O(1) space.
+ */
+export declare function degreesOf(value: string, fallbackDeg: number): number;
+/**
+ * Clamp to an inclusive range.
+ *
+ * @complexity O(1).
+ */
+export declare function clamp(val: number, min: number, max: number): number;

package/dist/types/3d/flattening.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dev-mode diagnostic: which ancestor is clipping the scene.
+ *
+ * Adapted from `warnFlatteningAncestor` in `src/effects/carousel/index.ts:129-175` — copied rather
+ * than imported, for the bundle reason `src/3d/register.ts` sets out.
+ *
+ * **Why this tier needs one at all.** A canvas is a canvas: an ancestor cannot flatten what it
+ * renders the way it flattens a CSS `preserve-3d` subtree. But the *host* is an ordinary element,
+ * and an ancestor that clips it clips the render with it. The symptom — "the 3D scene is cut in
+ * half, or gone" — points squarely at this effect while the cause is three levels up, and that gap
+ * is the whole value of naming the element. So: yes, its own copy.
+ *
+ * **But a narrower table than the carousel's.** The original tests five properties, because all
+ * five defeat `transform-style: preserve-3d`. Only two of them clip a canvas. `opacity` below 1, a
+ * `filter` and a `backdrop-filter` are ordinary compositing on an ordinary element here — a dimmed
+ * or blurred 3D hero is a design, not a bug, and warning about it would be a false positive on a
+ * deliberate choice. Firing on things that are fine is how a diagnostic teaches people to ignore
+ * it, which is the same reason the original stops at `<body>`.
+ */
+/**
+ * The slice of `PrepareContext` this needs. A real one satisfies it structurally.
+ *
+ * Declared narrow rather than importing `PrepareContext` so a test can drive the walk with a fake
+ * `getComputedStyle` and no realm, which is the only way to reach the guilty-ancestor branches
+ * under jsdom.
+ */
+export interface FlatteningContext {
+    win: {
+        getComputedStyle?: (el: Element) => CSSStyleDeclaration | null;
+    };
+    warn(message: string): void;
+}
+/**
+ * Walk the ancestors and warn about the first one that clips the scene.
+ *
+ * A diagnostic, not a fix: there is nothing this library can safely do about an ancestor it does
+ * not own — removing an `overflow: hidden` a page relies on to clip something else would trade a
+ * cropped model for a broken layout. Naming the element is the whole value.
+ *
+ * Stops at the first offender rather than listing all of them: the first one already clips
+ * everything below it, so the rest are consequences of a page the author has yet to change. Stops
+ * at `<body>` because a page-level `overflow-x: hidden` on `<html>`/`<body>` — which is on a large
+ * fraction of all sites — would otherwise fire on every model ever authored.
+ *
+ * @param el - The model host.
+ * @param ctx - Effect context, for the window (`getComputedStyle`) and the warning sink.
+ * @complexity O(d) time in tree depth, once per instance; O(1) space.
+ */
+export declare function warnClippingAncestor(el: Element, ctx: FlatteningContext): void;

package/dist/types/3d/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * kUInetic 3D — real geometry, opt-in.
+ *
+ * Tier 2. A `<div data-kui="model-3d src:…">` becomes a glTF model on a canvas the library inserts
+ * and owns, with the div's own children painting over it. One div, all settings: there is no child
+ * element per mesh, per light or per camera, because those would be DOM as bookkeeping rather than
+ * content. See `docs/3d-tier-grammar.md`.
+ *
+ * Reached only by subpath, exactly like `kuinetic/advanced`: the default entry never imports this,
+ * so a page that does not ask for 3D does not pay a byte for it. It also does not depend on
+ * `kuinetic/advanced` — the two are siblings, and either ships without the other.
+ *
+ * **The renderer is not here yet.** This tier currently mounts the canvas, claims the host's
+ * properties, resolves the `target:`/`poster:` fallback and tears all of it back down. It imports
+ * no three.js and requests no GL context.
+ */
+import type { Registry } from '../core/registry.js';
+import type { Animator } from '../core/animator.js';
+export { registerModel3D, prepareModel3D, resolveModelOptions, MODEL_3D_PARAMETERS, MODEL_3D_PRIMITIVE, MODEL_3D_PRIMITIVES, MODEL_3D_PRESETS, type ModelOptions, type ModelAxis, type LightRig, } from './model-3d.js';
+export { registerInto } from './register.js';
+export { degreesOf, clamp } from './angles.js';
+export { detectWebGL } from './webgl.js';
+export { warnClippingAncestor, type FlatteningContext } from './flattening.js';
+/**
+ * Register every 3D module into a kUInetic `Registry` or `Animator`.
+ *
+ * Named `register3D`, not `registerThreeD`: `registerThreeD` is already taken by
+ * `src/effects/three-d/` — the CSS-transform catalog that ships `card-flip-x`, `cube-rotate` and
+ * `fold-panel` in the default entry. The two are unrelated and confusingly close in name; this one
+ * is the WebGL tier.
+ *
+ * @param target - A `Registry`, an `Animator`, or anything carrying either shape.
+ * @returns The registry that was written to, so callers can chain.
+ * @complexity O(n) in primitives plus presets.
+ */
+export declare function register3D(target: unknown): Registry | Animator;

package/dist/types/3d/model-3d.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `model-3d` — one div, one glTF model, one canvas.
+ *
+ * The grammar is `docs/3d-tier-grammar.md`; this file is the half of it that does not draw.
+ * It owns the canvas, the host's two claimed properties, the `target:`/`poster:` fallback and the
+ * teardown. It imports no renderer, requests no GL context and paints nothing. Everything here is
+ * exercisable in jsdom, which is deliberate: a skeleton that stubbed `prepare()` into an inert
+ * no-op would make `channels` a lie — declaring properties it never writes — and would prove only
+ * that a name registers.
+ *
+ * ```html
+ * <div data-kui="model-3d src:/models/robot.glb spin:360deg light:studio target:img">
+ *   <h2>Meet the robot</h2>
+ *   <img src="/img/robot.jpg" alt="A red toy robot" />
+ * </div>
+ * ```
+ */
+import type { EffectInstance, EffectParams, ParameterSchema, PrepareContext, Preset, Primitive } from '../core/types.js';
+import type { Registry } from '../core/registry.js';
+import type { Animator } from '../core/animator.js';
+declare const AXES: readonly ["x", "y", "z"];
+declare const LIGHT_RIGS: readonly ["studio", "key", "rim", "flat"];
+export type ModelAxis = (typeof AXES)[number];
+export type LightRig = (typeof LIGHT_RIGS)[number];
+/**
+ * Everything `prepare()` decided, in the form the controller consumes.
+ *
+ * Split from the controller so the reading of the attribute and the writing to the DOM are two
+ * testable halves: a suite can assert what `src:`/`spin:`/`target:` resolved to without a document,
+ * and assert what got mounted without re-deriving the parameters.
+ */
+export interface ModelOptions {
+    /** The glTF/GLB URL. Empty means there is nothing to render, whatever else was authored. */
+    src: string;
+    /** Total turn across the element's scroll pass, in degrees. Not a rate. */
+    spinDeg: number;
+    axis: ModelAxis;
+    /** Camera elevation in degrees, clamped to ±{@link MAX_TILT_DEG}. Positive is above. */
+    tiltDeg: number;
+    light: LightRig;
+    /**
+     * The element `target:` named, already inside the host. Shown when nothing renders, hidden when
+     * something does. The library never creates this one.
+     */
+    fallbackEl: Element | null;
+    /** A still-image URL. Used only when `target:` named nothing — see the grammar doc's §4. */
+    posterUrl: string;
+    /** Whether to mount a canvas at all. False under reduced motion, no WebGL, or no `src:`. */
+    render: boolean;
+}
+/**
+ * Turn the validated attribute into the decisions the controller acts on.
+ *
+ * `render` is the whole point of the function: three unrelated reasons collapse into one boolean,
+ * so the controller has one branch instead of three and every caller agrees on what "nothing is
+ * going to draw" means. Nothing renders without a `src:`, nothing renders under reduced motion
+ * (the grammar's §4 — a spin's end is a camera position, not a design, so the fallback is a still
+ * image and never the end state), and nothing renders without WebGL 2.
+ *
+ * @complexity O(n) in matches for the `target:` query; O(1) otherwise.
+ */
+export declare function resolveModelOptions(el: Element, params: EffectParams, ctx: PrepareContext): ModelOptions;
+/**
+ * Wire up one `model-3d` host.
+ *
+ * `ctx` is required, unlike `camera-3d.ts`'s `prepareCameraScene`, which takes it optional to be
+ * defensive about direct construction. `Primitive.prepare`'s own signature already says the
+ * animator passes a real one, and every `ctx?.` arm underneath an optional parameter is a branch
+ * that only a test can reach — under this repo's 100% branch threshold that is a branch written to
+ * be covered rather than to be right. A suite constructs a context object instead.
+ *
+ * @param el - The authored host.
+ * @param params - Validated parameters; a primitive never sees a raw author string.
+ * @param ctx - The prepare context, for the document, the host's ledger, and the warning sink.
+ * @returns A lifecycle handle. Nothing has started — the animator decides when.
+ * @complexity O(d) in tree depth for the clipping diagnostic; O(1) otherwise.
+ */
+export declare function prepareModel3D(el: Element, params: EffectParams, ctx: PrepareContext): EffectInstance;
+/**
+ * `model-3d`'s parameters.
+ *
+ * Every custom property is namespaced `--kui-model-*`, and that is not tidiness. A custom property
+ * published on a host inherits into its entire subtree, and three of these names are already taken:
+ * `--kui-tilt` is read by `src/css/carousel.css:77`, so a model containing a carousel would tilt
+ * the ring; `--kui-axis` is read by `src/css/text.css:360` as a `font-variation-settings` tag, so
+ * `axis:y` would hand every variable-font descendant `font-variation-settings: y 100`; and
+ * `--kui-poster` belongs to `effects/catalog/media.ts:325`. `--kui-progress` was lost this way once
+ * already. `target:` keeps the shared `--kui-target` spelling on purpose — it is one convention
+ * across the library (`advanced/audio.ts:828`, `scroll-mechanics/primitives.ts:727`) and, being
+ * `text`, it is dropped before the stylesheet and can collide with nothing.
+ */
+export declare const MODEL_3D_PARAMETERS: ParameterSchema;
+/**
+ * The primitive.
+ *
+ * `channels` names both properties this writes to the host — see {@link HOST_STYLE} for why there
+ * are two. It deliberately does *not* name `display`, which goes to a `target:`-named descendant
+ * and never to the host: `findConflicts` (`core/channels.ts:223`) groups claims per compiled host
+ * element, so declaring it would make `model-3d` falsely conflict with any host-level effect that
+ * claims `display`, over a write that never lands on the host.
+ *
+ * `reducedMotion: 'disable'` is what makes the animator refuse to activate this instance, and the
+ * still image is therefore mounted in `prepare` precisely because nothing else runs — the same
+ * arrangement `camera-scene` and `shaders` use.
+ */
+export declare const MODEL_3D_PRIMITIVE: Primitive;
+export declare const MODEL_3D_PRIMITIVES: Primitive[];
+export declare const MODEL_3D_PRESETS: Preset[];
+/**
+ * Register `model-3d` onto a `Registry`, an `Animator`, or anything carrying either shape.
+ *
+ * @complexity O(1).
+ */
+export declare function registerModel3D(target: unknown): Registry | Animator;
+export {};

package/dist/types/3d/register.d.ts

@@ -0,0 +1,26 @@
+/**
+ * How this tier is handed a registry.
+ *
+ * A near-copy of `registerInto`/`asRegistry`/`hasRegistrarShape` from `src/advanced/base.ts:519-568`
+ * — deliberately copied rather than imported. `kuinetic/3d` ships as its own `<script>` bundle and
+ * its own subpath, and importing a sibling tier's helper would mean you cannot ship 3D without also
+ * shipping advanced. The originals stay the reference implementation; if the shape gate's rule ever
+ * changes, both move, and `test/3d-register-gate.test.ts` mirrors
+ * `src/advanced/__tests__/register-gate.test.ts` case for case so a drift shows up as a failure
+ * rather than as a browser bug.
+ */
+import type { Preset, Primitive } from '../core/types.js';
+import type { Registry } from '../core/registry.js';
+import type { Animator } from '../core/animator.js';
+/**
+ * Register one module's primitives and presets onto a `Registry`, an `Animator`, or anything
+ * carrying either shape.
+ *
+ * @param target - The registry, the animator, or a host exposing one as `.registry`.
+ * @param primitives - One primitive or a list of them.
+ * @param presets - One preset or a list of them.
+ * @param name - Spelled into the thrown message, so it names the function the consumer called.
+ * @returns `target`, so callers can chain.
+ * @complexity O(n) in primitives plus presets.
+ */
+export declare function registerInto(target: unknown, primitives: Primitive | Primitive[], presets: Preset | Preset[], name?: string): Registry | Animator;

package/dist/types/3d/webgl.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Does this environment have WebGL 2 at all?
+ *
+ * **This deliberately does not request a context.** `getContext('webgl2')` is the only answer that
+ * is true in every sense, and it is also an allocation: on a machine at its context limit it evicts
+ * a live one, and in a browser with a blocklisted GPU it can take tens of milliseconds. A presence
+ * check is cheap, synchronous, and wrong only in the direction that is safe — an environment that
+ * has the constructor but refuses a context falls through to the renderer's own failure path, which
+ * shows the same still image this one does.
+ *
+ * It is also the only probe that works before there is a renderer to fail. The skeleton has to
+ * decide canvas-or-fallback in `prepare()`, and it has no GL code to ask.
+ *
+ * Not a field on `core/capabilities.ts`'s `Capabilities`, and not added to it: that record is the
+ * *core* feature-detection surface, every entry of which gates something core renders. A tier that
+ * is opt-in by subpath should not widen core's public type to hold a flag core never reads.
+ *
+ * @param win - The window to interrogate. Injected rather than read off the global so a test can
+ *   drive both answers; jsdom defines no `WebGL2RenderingContext`, so the real one is always
+ *   `false` there and the mounted-canvas path would otherwise be unreachable.
+ * @returns Whether WebGL 2 is present.
+ * @complexity O(1).
+ */
+export declare function detectWebGL(win: object | null | undefined): boolean;

package/dist/types/advanced/audio.d.ts

@@ -0,0 +1,322 @@
+/**
+ * kUInetic Audio - Web Audio Reactive Source Module
+ *
+ * Exposes audio frequency bands (bass, mid, treble, overall level)
+ * as CSS custom properties on scoped elements:
+ * - --kui-audio-bass (0..1)
+ * - --kui-audio-mid (0..1)
+ * - --kui-audio-treble (0..1)
+ * - --kui-audio-level (0..1)
+ * - --kui-audio (alias to level)
+ *
+ * Supports page audio/video elements by default, with opt-in mic streaming.
+ */
+import type { EffectInstance, EffectParams, PrepareContext, Preset, Primitive } from '../core/types.js';
+import type { Registry } from '../core/registry.js';
+import type { Animator } from '../core/animator.js';
+import { type AdvancedEnv, type AnyWindow, type AnyDocument, type RafFunction, type CafFunction } from './base.js';
+/** The host custom properties this module owns. Also the primitive's declared channels. */
+export declare const AUDIO_CHANNELS: readonly ["--kui-audio-bass", "--kui-audio-mid", "--kui-audio-treble", "--kui-audio-level", "--kui-audio"];
+export interface AudioBands {
+    bass: number;
+    mid: number;
+    treble: number;
+    level: number;
+}
+/**
+ * The bands a *consumer* can subscribe to, and the custom property each one reads.
+ *
+ * The same names {@link AUDIO_CHANNELS} declares, minus the `--kui-audio` alias — an alias is a
+ * second spelling of `level`, not a fifth band, and offering both as separate choices would make
+ * two authored values mean exactly the same thing. `__tests__/audio.test.ts` asserts every
+ * property here is one this module actually writes, so the two cannot drift apart.
+ */
+export declare const AUDIO_BAND_PROPERTIES: {
+    readonly bass: "--kui-audio-bass";
+    readonly mid: "--kui-audio-mid";
+    readonly treble: "--kui-audio-treble";
+    readonly level: "--kui-audio-level";
+};
+export type AudioBand = keyof typeof AUDIO_BAND_PROPERTIES;
+/** Band names, for a consumer's `keywords` list. */
+export declare const AUDIO_BANDS: readonly AudioBand[];
+/**
+ * The band an authored keyword names, or `null` for "no band" — including `off` and any word that
+ * is not a band at all.
+ *
+ * `Object.hasOwn`, not `AUDIO_BANDS.includes`, for the same reason `readParams` uses it: a plain
+ * property read answers for `__proto__`/`constructor` too, and would report those as bands whose
+ * property is a function.
+ */
+export declare function parseAudioBand(raw: string | null | undefined): AudioBand | null;
+/**
+ * One band's current value for this element, as a consumer sees it.
+ *
+ * Inline first, then computed — the same two-step `shaders.ts`'s `readElementProgress` uses, and
+ * for the same reason: `--kui-audio-*` are ordinary unregistered custom properties (nothing in
+ * this codebase declares them with `@property`), so they inherit, and an `audio-source` on an
+ * *ancestor* is already visible through `getComputedStyle` without this module doing anything
+ * special. The inline read is the fast path for the common case — the driver on the element
+ * itself, where its own per-frame write lands.
+ *
+ * `0` when nothing has declared a value, which is also what a silent driver writes: a consumer
+ * that reads 0 behaves as if there were no audio, rather than having to distinguish the two.
+ *
+ * Callers on a shared render loop must read every element before any of them writes style; see
+ * `SharedShaderRenderer`'s `inputReaders` pass for why the ordering matters.
+ *
+ * @complexity O(1) time (one inline read, at most one computed-style read); O(1) space.
+ */
+export declare function readAudioBand(el: HTMLElement, band: AudioBand): number;
+export interface AudioSourceOptions {
+    /** Where the samples come from, not which element: the page's own media, or the microphone. */
+    source?: 'media' | 'mic';
+    /** The author's `target:` selector for the media element to analyse. */
+    target?: string;
+    fftSize?: number;
+    smoothing?: number;
+}
+export declare function computeFrequencyBands(data: Uint8Array, sampleRate: number): AudioBands;
+/**
+ * The nearest legal `fftSize`.
+ *
+ * `AnalyserNode.fftSize` must be a power of two and throws `IndexSizeError` for anything else. The
+ * parameter schema bounds the range but `clamp` cannot snap, so an authored `fft:300` threw inside
+ * initialisation, left an open `AudioContext` with no analyser behind it, and then wrote `0.000`
+ * for all five properties every frame — a silent dead effect with a running audio thread.
+ */
+export declare function snapFftSize(requested: number): number;
+export declare class AudioSourceController {
+    element: HTMLElement;
+    options: AudioSourceOptions;
+    env: AdvancedEnv;
+    window: AnyWindow;
+    document: AnyDocument;
+    raf: RafFunction;
+    caf: CafFunction;
+    audioCtx: AudioContext | null;
+    analyser: AnalyserNode | null;
+    sourceNode: MediaElementAudioSourceNode | MediaStreamAudioSourceNode | null;
+    stream: MediaStream | null;
+    freqData: Uint8Array<ArrayBuffer> | null;
+    rafId: number | null;
+    isActive: boolean;
+    /** The window-wide graph this instance is currently counted against. */
+    private graph;
+    /**
+     * Whether `sourceNode` belongs to the shared graph rather than to this instance.
+     *
+     * True for `source: media` — the node feeds the page's speakers as well as this analyser, so
+     * teardown may only cut its edge to *this* analyser. False for `source: mic`, where the node and
+     * its stream are this instance's alone and must be released in full.
+     */
+    private sourceIsShared;
+    /**
+     * The author's inline custom properties, and what this module replaced them with.
+     *
+     * Not a snapshot taken here: the ledger for `element` is opened at the first write in
+     * `updateFrame`, so what it restores is whatever the author had at that instant. The field it
+     * replaced captured all five properties in this constructor and restored them on destroy, which
+     * meant an author who wrote `--kui-audio-bass` any time after `prepare` had that write silently
+     * reverted to a value from before their own.
+     *
+     * Shared with every other controller writing to this element — see `createAdvancedLedgers`. Two
+     * `audio-source` effects on one element (`audio-reactive` plus `audio-mic`, say) would otherwise
+     * open a ledger each, and the second would capture the first's `0.000` as the author's value.
+     */
+    private ledgers;
+    /**
+     * Which microphone request is the live one.
+     *
+     * `getUserMedia` cannot be cancelled — the permission prompt belongs to the browser, and the
+     * promise settles whenever the visitor answers it. Every `stop()` bumps this, so a request the
+     * visitor grants *after* the effect was cancelled resolves into a handler that no longer
+     * recognises its own generation and stops the tracks instead of connecting them. Without it,
+     * cancelling while the prompt is open and then granting leaves the microphone recording until
+     * the element is eventually destroyed.
+     */
+    private micRequestToken;
+    /** Detaches the one-shot gesture listeners armed by {@link armGestureResume}. */
+    private releaseGestureResume;
+    constructor(element: HTMLElement, options?: AudioSourceOptions, env?: AdvancedEnv);
+    private connectMicSource;
+    private connectMediaSource;
+    /**
+     * This instance's analyser, already on a live path to the destination.
+     *
+     * @returns The analyser, or `null` when the context refused to build one.
+     */
+    private buildAnalyser;
+    /**
+     * Join the window's audio graph and give this instance an analyser on it.
+     *
+     * `this.analyser`, not `this.audioCtx`, is the "already initialised" test, and nothing is
+     * recorded on `this` until the analyser exists. Assigning the context first is what left a
+     * half-built instance behind — an open context, no analyser, and a loop writing zeros — whenever
+     * `createAnalyser` or `fftSize` threw.
+     */
+    initAudio(): boolean;
+    /**
+     * Go live — but only run a frame loop once there is something for it to read.
+     *
+     * The loop used to start unconditionally, and both ways that can be wrong were reachable:
+     *
+     * - **Initialisation failed.** No Web Audio, or an `AudioContext` the browser refused to build.
+     *   `initAudio()` is only ever called from here and here early-returns on `isActive`, so there is
+     *   no retry path at all — the loop sampled nothing, wrote the same `0.000` forever and could
+     *   never recover.
+     * - **The context is suspended.** `defaultActivation` is `'load'`, so this normally runs before
+     *   the visitor has touched anything and the context starts suspended. The gesture retry below
+     *   is the fix for *that*, but the loop does not have to run while it waits: a suspended context
+     *   fills zeros, and {@link GESTURE_EVENTS} is `pointerdown`/`keydown`/`touchend` — a visitor who
+     *   only ever scrolls with a wheel fires none of them, so "while it waits" was the rest of the
+     *   session at 60fps.
+     *
+     * - **There is nothing to read.** `initAudio()` answers `true` as soon as the analyser exists,
+     *   and the analyser can exist with nothing connected to it: `audio-source target:#missing`, or a
+     *   page with no media under the element, leaves `connectMediaSource` with no node to attach;
+     *   `audio-mic` leaves `connectMicSource` waiting on a permission prompt the visitor may close,
+     *   refuse, or never answer. A loop over a disconnected analyser is the first case again — the
+     *   same `0.000` at 60fps, for the life of the page, with nothing coming to change it.
+     *
+     * One frame of silence covers all three, and it is all any of them needs: nothing is going to
+     * change these five values until a resume or a stream lands, and writing them once still says
+     * "there is a driver on this element and it is silent" to a consumer that would otherwise inherit
+     * an ancestor's live band. The loop is then started by whichever arrives last — the `resume()`
+     * that succeeds, or the microphone the visitor grants — see {@link startLoopIfReady}.
+     */
+    start(): void;
+    /**
+     * Wake a context the browser suspended for autoplay policy.
+     *
+     * `defaultActivation` is `'load'`, so the context is very often constructed before the visitor
+     * has touched anything, and a context built outside a user gesture starts `suspended`. A bare
+     * `resume()` there is rejected or left pending — WebKit is strict about it, and iOS is this
+     * repo's main audience — after which `getByteFrequencyData` fills zeros and all five properties
+     * sit at `0.000` for the rest of the session. `on:click` only worked by luck, because it happens
+     * to run inside a gesture.
+     *
+     * So: try immediately, and arm a one-shot retry on the visitor's first gesture. The `on:click`
+     * path still succeeds on the first attempt and the listeners are never needed.
+     *
+     * @returns `true` when the context is already live and {@link start} may run its loop now,
+     *   `false` when a resume has been arranged and the loop is that resume's job to start.
+     */
+    private resumeContext;
+    /**
+     * Start the loop, unless the effect was torn down while the context was still waking up — or
+     * there is still nothing connected for it to read.
+     *
+     * `resume()` settles whenever the browser gets to it, which can be long after a `cancel()` — the
+     * same race {@link micRequestToken} closes for `getUserMedia`, and with the same consequence if
+     * it is left open: a resume landing after teardown would start a frame loop on a stopped
+     * instance, and nothing would ever come back to stop it.
+     *
+     * The source check is the other half of the gate {@link start} applies: a resume that lands
+     * before the microphone is granted, or on an element with no media to bind, has nothing to start
+     * a loop over. When the stream does arrive, `connectMicSource` comes back through here.
+     */
+    private startLoopIfReady;
+    private armGestureResume;
+    startLoop(): void;
+    updateFrame(): void;
+    /**
+     * One channel, written only when it would actually change anything.
+     *
+     * These are unregistered custom properties, so they inherit: five unconditional `setProperty`
+     * calls per frame per instance dirty the whole subtree's style 60 times a second even on a page
+     * whose audio is silent or whose context never resumed, where all five values are the identical
+     * `0.000`.
+     *
+     * The comparison reads the live inline value rather than a remembered one on purpose. A cache
+     * would go stale the moment the author wrote the property themselves — this module would agree
+     * with its own record, skip the write, and look dead. Reading the CSSOM's own map is a lookup,
+     * not a style resolution, so it costs nothing a `setProperty` would not already cost.
+     *
+     * `claim()` first and unconditionally, because the very first frame can legitimately skip its
+     * write (the author happened to have written the same string), and the ledger still has to have
+     * captured what was there to restore it.
+     *
+     * @complexity O(1).
+     */
+    private writeChannel;
+    /**
+     * Give back everything this instance owns: the frame loop, its analyser, the microphone.
+     *
+     * This is what `cancel()` and `finish()` reach, and it is deliberately a full release of the
+     * *instance's* half of the graph. A cancelled `audio-mic` that only stopped its loop left the
+     * stream connected and the recording indicator lit until the element was eventually destroyed —
+     * the visitor stopped the effect and the microphone stayed on.
+     *
+     * What it deliberately does **not** do is touch the page's own audio or the author's styles.
+     * The shared media source keeps its edge to the destination (see {@link SharedAudioGraph}), and
+     * the ledger is left as it is because `EffectInstance.cancel` means "stop where it is, leaving
+     * the element mid-effect" — unwinding the five custom properties here would snap every rule
+     * reading `var(--kui-audio-bass, 0)` back to its fallback on a pause, which is not what the
+     * other five modules in this directory do. `destroy()` is where the styles go back.
+     *
+     * Idempotent, and safe on a controller that was never started — every step below no-ops on an
+     * empty graph. It runs unguarded for that reason: the old `isActive` early-return meant a
+     * controller cancelled twice, or destroyed without ever activating, skipped the parts that had
+     * nothing to do with the loop.
+     */
+    stop(): void;
+    private disconnectAudioNodes;
+    /**
+     * Everything `stop()` gives back, plus the author's inline styles.
+     *
+     * `try`/`finally` because the restore must not be hostage to the graph teardown: the animator
+     * swallows a throwing `instance.destroy()` (`runQuietly`), and an element this module reached on
+     * its own — a `camera-layer`, a `scene-step` — is in no ledger the animator will ever restore.
+     * A single throw on the way out would otherwise leave the library's values on it permanently.
+     */
+    destroy(): void;
+}
+export declare function prepareAudioSource(el: Element, params: EffectParams, ctx?: PrepareContext | null): EffectInstance;
+export declare const AUDIO_PARAMETERS: {
+    source: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+    /**
+     * Which media element to analyse — the library's one spelling for "this effect names another
+     * element", declared exactly as every other primitive that owns the key declares it — see
+     * `compile.ts`'s `liftTarget` for the current set — down to the shared `--kui-target`.
+     *
+     * It was `media:`, which was both a second word for `target:`'s job and a live footgun:
+     * `compile.ts`'s `liftTarget` only leaves `target:` in a primitive's own parameters when that
+     * primitive declares it, and otherwise *relocates the whole effect* onto the elements the
+     * selector matched. So `audio-source target:#track` used to move the analyser onto the `<audio>`
+     * element itself — which happens to work, silently writing the five custom properties on the
+     * wrong element. Declaring the key here claims it and closes that.
+     *
+     * No `scope: SCOPE_PARAM` alongside it, unlike its peers: this resolves its own two-step search
+     * (`findMediaElement` — the host's own subtree first, the document only for an authored
+     * selector), and importing core's shared declaration would be a value import from `src/effects`
+     * into a tier whose bundle weight is measured (see `base.ts`'s `asRegistry`).
+     */
+    target: {
+        type: "text";
+        default: string;
+        cssProperty: string;
+    };
+    smoothing: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    fft: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+};
+export declare const AUDIO_PRIMITIVES: Primitive[];
+export declare const AUDIO_PRESETS: Preset[];
+export declare function registerAudio(target: unknown): Registry | Animator;