asciify-engine 4.12.1 → 4.13.0

package/dist/kit.d.ts

@@ -0,0 +1,907 @@
+import { GlyphField, GlyphFieldOptions } from './field.js';
+
+/** Options every kit component takes. */
+interface KitOptions {
+    /** The field's ink: a CSS colour, a custom property name (`--brand`) or `var(--brand, #888)`. Re-read when the theme changes. */
+    ink?: string;
+    /** Raw glyph-field settings layered over the component's own look, such as `charset`, `cellSize` or `font`. */
+    look?: GlyphFieldOptions;
+    /** `true` or `false` overrides the visitor's `prefers-reduced-motion`; leave it unset to follow it. */
+    reducedMotion?: boolean;
+}
+/** The handle every kit component returns. Component handles add their own methods. */
+interface KitHandle<O> {
+    /** False when WebGL2 is missing (or the field failed): the HTML is left as it was and drawing methods do nothing. */
+    readonly supported: boolean;
+    /** The underlying GPU field, for anything the kit does not cover. `null` in the fallback. */
+    readonly field: GlyphField | null;
+    /** Merges options; the next frame draws with them. */
+    update(options: Partial<O>): void;
+    /** Resumes motion after `pause()`. */
+    play(): void;
+    /** Holds the current frame and stops drawing. */
+    pause(): void;
+    /** Removes the canvas, listeners and observers, and restores the element's own markup and styles. */
+    destroy(): void;
+}
+interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface PaintFrame {
+    /** The source canvas, already cleared to black. White is the densest glyph; in source colour mode hue colours the glyph. */
+    pen: CanvasRenderingContext2D;
+    /** Source size in pixels. */
+    width: number;
+    height: number;
+    /** Canvas size in CSS pixels, and source pixels per CSS pixel. */
+    w: number;
+    h: number;
+    scale: number;
+    now: number;
+    /** Reduced motion: paint the settled state; the loop stops after this frame. */
+    still: boolean;
+    /** The page behind the element is dark (judged from the element's text colour). */
+    dark: boolean;
+    /** An element's layout box in the canvas's CSS pixels, unaffected by transforms on an ancestor. */
+    box(element: Element): Box;
+}
+interface SurfaceConfig {
+    host: HTMLElement;
+    /** The field look; ink comes from `ink`, so leave it out here. */
+    look: () => GlyphFieldOptions;
+    /** CSS colour or custom property for the field ink, given whether the ground is dark. */
+    ink: (dark: boolean) => string | undefined;
+    /** `over` draws above the element's content; `under` sits above its background but below its content. */
+    layer?: 'over' | 'under';
+    /** CSS pixels the canvas reaches past the element on every side. */
+    outset?: number;
+    /** Source pixels per CSS pixel (default 1), or a fixed source size from the canvas's CSS size. */
+    resolution?: number | ((w: number, h: number) => [number, number]);
+    /** Paints one frame; return true while more frames are needed. */
+    paint: (frame: PaintFrame) => boolean;
+    reducedMotion: () => boolean | undefined;
+    /** The field failed after mounting; the surface has already removed itself. */
+    onFail?: () => void;
+    /** Called when the theme changes, after the ink is re-read. */
+    onTheme?: () => void;
+}
+interface Surface {
+    readonly field: GlyphField;
+    readonly canvas: HTMLCanvasElement;
+    /** Starts the frame loop if it is not running. */
+    kick(): void;
+    /** Re-reads the look and ink, then kicks. */
+    refresh(): void;
+    still(): boolean;
+    dark(): boolean;
+    box(element: Element): Box;
+    play(): void;
+    pause(): void;
+    destroy(): void;
+}
+/** Any CSS colour as #rrggbb, or null. Custom properties are read from `from`. */
+declare function resolveColor(token: string | undefined, from: Element, fallback?: string): string | null;
+/**
+ * Mounts a field over or inside `host` and feeds it a canvas painted each frame. Returns null without WebGL2 or when
+ * mounting fails, having changed nothing, so the caller can keep its HTML as the fallback.
+ */
+declare function mountSurface(config: SurfaceConfig): Surface | null;
+
+type BeamPalette = 'colorful' | 'mono' | 'ocean' | 'sunset' | readonly string[];
+type BeamMode = 'rotate' | 'pulse' | 'progress';
+interface BeamOptions extends KitOptions {
+    /** A named palette, or your own hex stops looped once round the border. `mono` draws in the ink. Default `colorful`. */
+    palette?: BeamPalette;
+    /** `rotate`: two arcs turn round the border. `pulse`: the whole border breathes. `progress`: all but dark at rest, a progress ring while work runs. */
+    mode?: BeamMode;
+    /** `dots` is a fine halftone; `glyphs` draws the light in small characters. */
+    grain?: 'dots' | 'glyphs';
+    /** Lap speed multiplier. 1 is a 2.6 second lap. */
+    speed?: number;
+    /** Faster and brighter while the pointer is over the element or it holds visible focus. Default true. */
+    hover?: boolean;
+    /** How far the glow reaches inward, in CSS px. It also stops 2px short of the element's padding. Default 18. */
+    depth?: number;
+}
+interface BeamHandle extends KitHandle<BeamOptions> {
+    /** Work is running, 0–1. In `progress` mode the ring grows clockwise from the top to this point; the other modes speed up as it fills. */
+    progress(value: number): void;
+    /** The light closes into a full ring, a flash sweeps once round it, a green fade settles, then the beam goes back to rest. */
+    success(): void;
+    /** Everything stops, flickers red twice and cracks into dim red fragments, which stay until `reset()` or `progress()`. */
+    error(): void;
+    /** Back to rest. */
+    reset(): void;
+}
+declare const BEAM_PALETTES: Record<'colorful' | 'mono' | 'ocean' | 'sunset', readonly string[]>;
+/** 256 steps of a looped palette, each at full value with its luminance, so a pixel is one lookup. */
+declare function beamPalette(palette: BeamPalette): Float32Array<ArrayBuffer>;
+/**
+ * A band of light round an element's border, drawn as fine halftone dots or small characters inside the edge.
+ * The field covers the element exactly and is clipped to its computed corner radii, so nothing lands past its corners.
+ */
+declare function beam(element: HTMLElement, options?: BeamOptions): BeamHandle;
+
+interface DecodeOptions extends KitOptions {
+    /** Text to draw instead of the element's own, centred and as large as fits; `\n` breaks lines. By default the element's text is drawn exactly where the browser lays it out. */
+    text?: string;
+    /** Total length in ms: the first 30% is drift alone, then the words resolve left to right. Default 900. */
+    duration?: number;
+    /** `visible` decodes when the element scrolls into view; `manual` waits for `replay()`. Default `visible`. */
+    trigger?: 'visible' | 'manual';
+    /** Decode again when the pointer enters. Default true. */
+    replayOnHover?: boolean;
+    /** `glyphs` keeps the headline in characters; `text` hands back to the crisp HTML text at the end. Default `glyphs`. */
+    settle?: 'glyphs' | 'text';
+}
+interface DecodeHandle extends KitHandle<DecodeOptions> {
+    /** Plays the decode again from the drift. */
+    replay(): void;
+}
+/** A headline that condenses out of a drifting field of characters, left to right through a flickering band. */
+declare function decode(element: HTMLElement, options?: DecodeOptions): DecodeHandle;
+
+interface OdometerOptions extends KitOptions {
+    /** The starting value. Default 0. */
+    value?: number;
+    /** Turns the value into the text shown. Default `toLocaleString()`. */
+    format?: (value: number) => string;
+    /** Milliseconds the first changed column rolls; each column to its right rolls `stagger` ms longer. Defaults 360 and 60. */
+    duration?: number;
+    stagger?: number;
+    /** Glyphs the columns roll through. Default `#%*+=-:`. */
+    glyphs?: string;
+}
+interface OdometerHandle extends KitHandle<OdometerOptions> {
+    /** Shows a new value; only the changed digits roll, leftmost first. */
+    set(value: number): void;
+    readonly value: number;
+}
+/**
+ * A figure in the page's own font whose changed digits roll through glyphs and land back on the crisp digit.
+ * The element's text becomes one span per character; a visually hidden live copy announces each value.
+ */
+declare function odometer(element: HTMLElement, options?: OdometerOptions): OdometerHandle;
+
+interface ButtonLoadingOptions extends KitOptions {
+    /** The idle label. Default: the label element's text. */
+    text?: string;
+    /** The element holding the label text. Default: the button itself. Pass it when the button also holds an icon. */
+    label?: HTMLElement;
+    /** Put a check before the success label. Default true. */
+    check?: boolean;
+    /** Shake the button on failure (skipped under reduced motion). Default true. */
+    shake?: boolean;
+    /** A live region to announce each state in. Optional. */
+    announce?: HTMLElement;
+}
+type ButtonState = 'idle' | 'loading' | 'success' | 'error';
+interface ButtonLoadingHandle extends KitHandle<ButtonLoadingOptions> {
+    /** Busy: the label decodes in, then a wave cycles each letter through glyphs until the next call. */
+    start(label?: string): void;
+    /** Decodes in the success label (with a check). */
+    succeed(label?: string): void;
+    /** Decodes in the failure label, with a short shake. */
+    fail(label?: string): void;
+    /** Back to the idle label. */
+    reset(label?: string): void;
+    readonly state: ButtonState;
+}
+/**
+ * A button whose label cycles through characters while its request runs, then decodes into the result.
+ * The width never changes: it grows to the widest label it has shown and holds there until `destroy()`.
+ */
+declare function buttonLoading(button: HTMLElement, options?: ButtonLoadingOptions): ButtonLoadingHandle;
+
+type OrbState = 'idle' | 'loading' | 'success' | 'warning' | 'error';
+type Outcome = 'success' | 'warning' | 'error';
+interface StatusOrbOptions extends KitOptions {
+    /** Tint the characters with the outcome's colour. Default true. */
+    colourByState?: boolean;
+    /** Close the orbit into a ring around the mark; false leaves the bare mark. Default true. */
+    ring?: boolean;
+    /** Outcome colours: CSS colours or custom properties. Defaults read `--ascii-success`, `--ascii-warning` and `--ascii-error`. */
+    colors?: Partial<Record<Outcome, string>>;
+}
+interface StatusOrbHandle extends KitHandle<StatusOrbOptions> {
+    idle(): void;
+    loading(): void;
+    success(): void;
+    warning(): void;
+    error(): void;
+    readonly state: OrbState;
+}
+/** An orb of characters: it orbits while work runs, then closes into a ring around a check, '!' or X, tinted by the outcome. */
+declare function statusOrb(element: HTMLElement, options?: StatusOrbOptions): StatusOrbHandle;
+
+type SkeletonBlock = 'text' | 'photo' | 'avatar';
+interface SkeletonOptions extends KitOptions {
+    /** Selector for the placeholder blocks inside the element. `data-block` may name the kind (`text`, `photo`, `avatar`); images default to photo. Default `[data-block]`. */
+    blocks?: string;
+    /** One shimmer sweep, in ms. Default 1250. */
+    shimmer?: number;
+    /** Each block resolves over this many ms. Default 240. */
+    resolve?: number;
+    /** Ms between blocks resolving, unless a block sets `data-delay`. Default 60. */
+    stagger?: number;
+    /** An image block develops in characters over this many ms. Default 560. */
+    develop?: number;
+}
+interface SkeletonHandle extends KitHandle<SkeletonOptions> {
+    /** The data has landed: each block resolves into its content. Resolves when the last one has. */
+    resolve(): Promise<void>;
+    /** Back to the shimmering skeleton, for a reload. */
+    reset(): void;
+    readonly loading: boolean;
+}
+/** Placeholder blocks drawn in characters with a shimmer sweeping across; on `resolve()` each block hands over to its content. */
+declare function skeleton(element: HTMLElement, options?: SkeletonOptions): SkeletonHandle;
+
+type PillTone = 'green' | 'amber' | 'red' | 'neutral' | 'new';
+interface PillOptions extends KitOptions {
+    /** The tone of a pill without `data-tone`. `new` is a solid pill that takes a sheen on hover. Default `neutral`. */
+    tone?: PillTone;
+    /** A live state such as Live or Syncing: the indicator breathes and a sweep crosses the pill every few seconds. `data-live` on a pill wins. Default false. */
+    live?: boolean;
+    /** A three-character indicator on status pills, drawn over the pill's `[data-dot]` element (one is added when missing). Default true. */
+    indicator?: boolean;
+    /** A gradient sheen of characters passes once across a `new` pill when the pointer enters it. Default true. */
+    sheen?: boolean;
+    /** Glyph hues to paint, as `[r, g, b]` 0–255, for the light and dark ground. */
+    tones?: Partial<Record<'light' | 'dark', Partial<Record<PillTone, [number, number, number]>>>>;
+}
+interface PillHandle extends KitHandle<PillOptions> {
+    /** Runs the sheen once across one pill, or every `new` pill. */
+    sheen(pill?: HTMLElement): void;
+    /** Sets a count pill (`data-count`) to `value`; only the changed digits roll. Without `pill`, the first count pill. */
+    count(value: number | string, pill?: HTMLElement): void;
+    /** Re-reads each pill's `data-tone` and `data-live`; tone changes ease over 240ms. `update()` does this too. */
+    refresh(): void;
+}
+/** Glyph hues painted into the source. The field normalises each hue and takes the glyph from its brightness. */
+declare const PILL_TONES: Record<'light' | 'dark', Record<PillTone, [number, number, number]>>;
+/**
+ * Pills and badges with a strip of characters in their tone: a breathing live indicator, a sweep across live states, a sheen on
+ * `new` pills and rolling digits on count pills. One element gets a field under its text; a list shares one field over their common
+ * container (one WebGL context for all), with each pill's labels lifted above it.
+ */
+declare function pill(target: HTMLElement | Iterable<HTMLElement>, options?: PillOptions): PillHandle;
+
+interface TabsOptions extends KitOptions {
+    /** The tab elements. Default: the tablist's `[role="tab"]` children. */
+    tabs?: string;
+    /** The tab shown first. Default: the one with `aria-selected="true"`, else 0. */
+    active?: number;
+    /** How long the indicator streams to a new tab, in ms. Default 280. */
+    duration?: number;
+    /** How the kit shows panels named by `aria-controls`: `hidden` toggles the attribute, `attribute` toggles `data-active`, `none` leaves them. Default `hidden`. */
+    panels?: 'hidden' | 'attribute' | 'none';
+    /** Wire clicks and arrow, Home and End keys, and keep `aria-selected` and roving `tabindex` in step. Default true. */
+    manage?: boolean;
+    /** Called after the active tab changes. */
+    onChange?: (index: number, tab: HTMLElement) => void;
+}
+interface TabsHandle extends KitHandle<TabsOptions> {
+    /** Selects a tab; the indicator streams across to it. `focus` moves keyboard focus too. */
+    select(index: number, focus?: boolean): void;
+    readonly active: number;
+}
+/** Segmented tabs whose active indicator is a pill of characters that streams across and condenses under the new tab. */
+declare function tabs(tablist: HTMLElement, options?: TabsOptions): TabsHandle;
+
+/** One update from an image provider. Either may be a Blob or a URL. */
+interface ImageUpdate {
+    preview?: Blob | string;
+    final?: Blob | string;
+}
+type ImageStream = AsyncIterable<ImageUpdate> | (() => AsyncIterable<ImageUpdate>);
+type GenerateState = 'idle' | 'generating' | 'done' | 'failed';
+interface ImageGenerateOptions extends KitOptions {
+    /** Starts generating straight away. A function is called again by `run()` for each new request. */
+    stream?: ImageStream;
+    /** The photo that crossfades in over the field. Default: the first `<img>` inside the element. */
+    image?: HTMLImageElement | null;
+    /** Writes the elapsed time while generating, such as `4.2s`. */
+    elapsed?: HTMLElement | null;
+    /** Called on every state change. */
+    onState?: (state: GenerateState, error?: unknown) => void;
+}
+interface ImageGenerateHandle extends KitHandle<ImageGenerateOptions> {
+    /** Starts a request (a finished image dissolves back into the ground first). Resolves with the final state. */
+    run(stream?: ImageStream): Promise<GenerateState>;
+    /** Abandons a running request and returns to the idle ground. */
+    reset(): void;
+    readonly state: GenerateState;
+}
+/**
+ * An image being generated: the field drifts with an elapsed clock, each streamed preview develops in a step sharper,
+ * then the final image, and the photo crossfades in. Works with any provider that can be wrapped as an async iterable.
+ */
+declare function imageGenerate(element: HTMLElement, options?: ImageGenerateOptions): ImageGenerateHandle;
+
+type FieldPreset = 'hero' | 'notFound' | 'brand';
+interface FieldBackgroundOptions extends KitOptions {
+    /** `hero`: a drifting ground of characters. `brand`: the same ground, denser, in the brand colour. `notFound`: the page's code set large in characters. Default `hero`. */
+    preset?: FieldPreset;
+    /** The headline block to keep clear: the ground fades out in a soft ellipse round it, so a frosted veil over it reads clean. */
+    clear?: HTMLElement | false;
+    /** The ink, one colour or one per ground. Wins over `ink`. `brand` defaults to `var(--brand)`. */
+    palette?: string | {
+        light?: string;
+        dark?: string;
+    };
+    /** `notFound` only: the characters drawn. Default `404`. */
+    text?: string;
+    /** The pointer drops a soft ring into the ground every so often (`hero` and `brand`). Default true. */
+    ripple?: boolean;
+    /** The canvas's accessible name. `notFound` defaults to its text; the grounds are decorative and hidden. */
+    label?: string;
+}
+interface FieldBackgroundHandle extends KitHandle<FieldBackgroundOptions> {
+    /** Sends a ring through the field from an element, a viewport point or the centre. Ripples hold off for a moment after. */
+    pulse(from?: Element | {
+        x: number;
+        y: number;
+    }, strength?: number): void;
+    /** `notFound`: the characters break apart, hang for a beat and re-form, as the next page would load. Other presets pulse. */
+    scatter(from?: Element): Promise<void>;
+}
+/**
+ * A page background drawn in characters: the hero's drifting ground with a soft clear zone round the headline, the same ground in
+ * the brand colour, or a 404 set large that scatters and re-forms.
+ */
+declare function fieldBackground(element: HTMLElement, options?: FieldBackgroundOptions): FieldBackgroundHandle;
+
+interface WordmarkOptions extends KitOptions {
+    /** The word drawn. Default the element's own text, which stays in the DOM, transparent, for selection and screen readers. */
+    text?: string;
+    /** The face it is set in. Default a serif: `Georgia, "Times New Roman", serif`. */
+    font?: string;
+    /** Default 600. */
+    fontWeight?: number;
+}
+interface WordmarkHandle extends KitHandle<WordmarkOptions> {
+    /** Sets the word again, as large as fits. */
+    setText(text: string): void;
+    readonly text: string;
+}
+/** A name or a word set in characters, with a trail under the pointer. */
+declare function wordmark(element: HTMLElement, options?: WordmarkOptions): WordmarkHandle;
+
+interface AsciiVideoOptions extends KitOptions {
+    /** A video URL, or a `<video>` element. Default the first `<video>` inside the element, which is hidden while the field draws it. */
+    src?: string | HTMLVideoElement;
+    /** Starts playing at once. Default true, or false when the visitor prefers reduced motion, which shows the first frame. */
+    autoplay?: boolean;
+    /** An image URL shown before the first frame is drawn, and in place of the video while it is paused under reduced motion. */
+    poster?: string;
+    /** The canvas's accessible name. Default `Video, drawn in characters`. */
+    label?: string;
+}
+interface AsciiVideoHandle extends KitHandle<AsciiVideoOptions> {
+    /** Plays when paused, pauses when playing; returns whether it now plays. */
+    toggle(): boolean;
+    readonly playing: boolean;
+}
+/**
+ * A video drawn in characters, muted and looping, with play and pause. Without WebGL2 the video itself plays in the element,
+ * with the poster until it starts.
+ */
+declare function asciiVideo(element: HTMLElement, options?: AsciiVideoOptions): AsciiVideoHandle;
+
+interface ArtPanelOptions extends KitOptions {
+    /** An image URL or element. Default the first `<img>` inside the panel, which is hidden while the field draws it. */
+    image?: string | HTMLImageElement;
+    /** A brand mark or caption over the art to keep clear, in a soft rectangle. */
+    clear?: HTMLElement | false;
+    /** Crop focus for the cover fit, 0–1 on each axis. Default `{ x: 0.5, y: 0.4 }`. */
+    focus?: {
+        x: number;
+        y: number;
+    };
+    /** The canvas's accessible name. Default the image's `alt`, else hidden as decoration. */
+    label?: string;
+}
+interface ArtPanelHandle extends KitHandle<ArtPanelOptions> {
+    /** Sends a ring through the art from an element (the submit button), a viewport point or the centre. Default strength 1. */
+    pulse(from?: Element | {
+        x: number;
+        y: number;
+    }, strength?: number): void;
+    /** While on, a lit band crosses the art again and again, characters climbing the ramp as it passes: a request is running. */
+    shimmer(on: boolean): void;
+}
+/** The sign-in page's art panel: an image drawn in characters, with a trail, pulses for form events and a shimmer while it waits. */
+declare function artPanel(element: HTMLElement, options?: ArtPanelOptions): ArtPanelHandle;
+
+interface PricingGlowOptions extends KitOptions {
+    /** A saving, such as `−25%`, set large in dots in the open space above the price. Default none. */
+    saving?: string | null;
+    /** The price element the open space ends at. Default the card's `[data-price]`. */
+    price?: Element | string;
+    /** The face the saving is set in. Default `600 … "Geist", Arial, sans-serif`. */
+    font?: string;
+}
+interface PricingGlowHandle extends KitHandle<PricingGlowOptions> {
+    /** A lit band crosses the card once, the halftone redrawn behind it. */
+    sweep(): Promise<void>;
+    /** Shows a saving (or none) in dots: the band sweeps the old art out and the new one in. */
+    saving(text: string | null): Promise<void>;
+    /** Sends a ring through the halftone from an element, such as the plan's button. Default strength 1.6. */
+    pulse(from?: Element | {
+        x: number;
+        y: number;
+    }, strength?: number): void;
+}
+/** The recommended plan's halftone glow: light from the corner, a lantern under the pointer, and the yearly saving set in dots. */
+declare function pricingGlow(element: HTMLElement, options?: PricingGlowOptions): PricingGlowHandle;
+
+type VoicePalette = 'mono' | 'aurora' | 'brand' | readonly string[];
+type VoiceState = 'idle' | 'listening' | 'thinking' | 'done';
+interface VoiceOrbOptions extends KitOptions {
+    /** `mono` draws in the ink; `aurora`, `brand` or your own hex stops tint the sphere, sliding as the voice gets louder. Default `aurora`. */
+    palette?: VoicePalette;
+    /** The starting level, 0–1. Default 0. */
+    level?: number;
+    /** Swell the element by up to 10% with the level (sets `scale`). It also sets `--ascii-level` either way. Default true. */
+    swell?: boolean;
+}
+interface VoiceOrbHandle extends KitHandle<VoiceOrbOptions> {
+    /** The voice's loudness, 0–1. The orb follows it with a fast attack and a slower release. */
+    level(value: number): void;
+    /** Listening: the orb follows `level()` (or the microphone). */
+    listen(): void;
+    /** Thinking: a slow low hum while the reply is worked out. Stops the microphone. */
+    think(): void;
+    /** Done: the level falls away over 420ms. Stops the microphone. */
+    done(): void;
+    /** Back to rest. Stops the microphone. */
+    idle(): void;
+    /** Asks for the microphone (only now) and listens to it. Resolves false when it is unavailable or refused. */
+    mic(): Promise<boolean>;
+    readonly state: VoiceState;
+    /** The level the orb is drawing now, after smoothing. */
+    readonly current: number;
+}
+declare const VOICE_PALETTES: Record<'aurora' | 'brand', readonly string[]>;
+/** A voice orb of characters that swells with the voice, hums while thinking and settles when done. */
+declare function voiceOrb(element: HTMLElement, options?: VoiceOrbOptions): VoiceOrbHandle;
+
+interface CommandPaletteOptions extends KitOptions {
+    /** The button that opens the palette. Blocks fly out of it on open and back into it on close. */
+    trigger?: HTMLElement | null;
+    /** The search field inside the palette. Default: its first `input`. */
+    input?: string;
+    /** The command rows. Default `[role="option"]`. */
+    rows?: string;
+    /** Start open. Default: open unless the palette has the `hidden` attribute. */
+    open?: boolean;
+    /** ⌘K / Ctrl+K toggles the palette from anywhere on the page; `false` turns it off. Default `'k'`. */
+    hotkey?: string | false;
+    /** Wire arrow keys, Home, End, Enter, Escape, pointer hover, outside clicks and `aria-selected`. Default true. */
+    manage?: boolean;
+    /** Close after a command runs. Default true. */
+    closeOnRun?: boolean;
+    /** Called when a row is chosen with Enter or a click. */
+    onRun?: (index: number, row: HTMLElement) => void;
+    /** Called after the palette opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+}
+interface CommandPaletteHandle extends KitHandle<CommandPaletteOptions> {
+    /** Condenses the palette out of the trigger. `focus` moves focus to the input (default true). */
+    open(focus?: boolean): void;
+    /** Dissolves the palette back into the trigger. */
+    close(): void;
+    toggle(): void;
+    /** Moves the selection; the marker glides to the row. */
+    select(index: number): void;
+    /** Runs a row as if it were clicked. */
+    run(index?: number): void;
+    readonly isOpen: boolean;
+    readonly selected: number;
+}
+/**
+ * A command palette that condenses out of its trigger in blocks of characters and dissolves back into it, with a glyph marker
+ * in the selected row's gutter that glides between rows.
+ */
+declare function commandPalette(panel: HTMLElement, options?: CommandPaletteOptions): CommandPaletteHandle;
+
+interface SlideToConfirmOptions extends KitOptions {
+    /** Called once the slide completes, by drag, fling, Enter, Space, End or `confirm()`. */
+    onConfirm?: () => void;
+    /** The handle. Default: the track's `[role="slider"]`, else its first child element. */
+    thumb?: string;
+    /** Text that fades as the thumb travels. Default `[data-label]`. */
+    label?: string;
+    /** Where the fill condenses into a ring and check. Default: the middle of the track. */
+    mark?: HTMLElement | null;
+    /** How far, 0–1, a release must reach to confirm. Default 0.9. */
+    threshold?: number;
+    /** Ms after confirming before the slider resets itself; 0 keeps it confirmed until `reset()`. Default 0. */
+    resetAfter?: number;
+    /** The ink the field eases to on success: a CSS colour or custom property. Default `--ascii-success`. */
+    color?: string;
+}
+interface SlideToConfirmHandle extends KitHandle<SlideToConfirmOptions> {
+    /** Completes the slide as if dragged to the end. */
+    confirm(): void;
+    /** Springs back to the start, unconfirmed. */
+    reset(): void;
+    readonly confirmed: boolean;
+}
+/**
+ * Slide to confirm: characters fill the track behind the thumb as it travels; on completion the fill condenses into a disc,
+ * opens into a ring and a check draws inside it while the ink eases to the success colour.
+ */
+declare function slideToConfirm(track: HTMLElement, options?: SlideToConfirmOptions): SlideToConfirmHandle;
+
+type LikeMark = 'heart' | 'save';
+interface LikeBurstOptions extends KitOptions {
+    /** The shape that bursts: a heart or a bookmark. Default `heart`. */
+    kind?: LikeMark;
+    /** The icon inside the button the burst grows from and lands back in. Default: its first `svg`. */
+    icon?: string;
+    /** Clicking toggles `aria-pressed`, bursting on and loosening off. `false` leaves clicks to you. Default true. */
+    manage?: boolean;
+    /** Nothing is drawn above this element's bottom edge, so the burst never covers the copy above the button. */
+    limit?: HTMLElement | null;
+    /** CSS pixels the field reaches past the button on every side. Default 40; set at mount. */
+    outset?: number;
+    /** Called after a click toggles the button. */
+    onChange?: (pressed: boolean) => void;
+}
+interface LikeBurstHandle extends KitHandle<LikeBurstOptions> {
+    /** The pop: the mark springs out of the icon in characters, an outline rolls out, sparks fly, and it lands back in the icon. */
+    burst(): void;
+    /** The soft undo: the filled mark loosens, sinks and thins out. */
+    undo(): void;
+    /** Sets `aria-pressed`, bursting when it turns on and loosening when it turns off. */
+    toggle(pressed?: boolean): void;
+    readonly pressed: boolean;
+}
+/** A like or save button that pops its mark in characters on press and loosens it on undo. */
+declare function likeBurst(button: HTMLElement, options?: LikeBurstOptions): LikeBurstHandle;
+
+interface BlockChartOptions extends KitOptions {
+    /** The bars, left to right. */
+    values?: readonly number[];
+    /** A name per bar, read by screen readers and passed to `onHover`. */
+    labels?: readonly string[];
+    /** The value the top of the plot stands for. Default: the largest value plus 4%. */
+    max?: number;
+    /** How long each bar grows, in ms. Default 520. */
+    duration?: number;
+    /** Ms between bars growing. Default 45 for up to 7 bars, else 9. */
+    stagger?: number;
+    /** Formats values for the screen reader table. Default `toLocaleString()`. */
+    format?: (value: number) => string;
+    /** Called as the pointer or arrow keys move onto a bar, and with `null` when they leave. */
+    onHover?: (index: number | null, value: number | null, label: string | null) => void;
+}
+interface BlockChartHandle extends KitHandle<BlockChartOptions> {
+    /** New values (and labels); the bars grow again. */
+    set(values: readonly number[], labels?: readonly string[]): void;
+    /** Lights one bar and dims the rest, or `null` for the resting emphasis on the last bar. */
+    highlight(index: number | null): void;
+    readonly active: number | null;
+    readonly values: readonly number[];
+}
+/** A bar chart drawn in columns of characters: bars grow in staggered, the last is emphasised, and hover lights one and dims the rest. */
+declare function blockChart(element: HTMLElement, options?: BlockChartOptions): BlockChartHandle;
+
+interface PageDissolveOptions extends KitOptions {
+    /** Where the dissolve starts: an element (such as the tab that was clicked) or a point in the container's CSS pixels. Default: top centre. */
+    origin?: HTMLElement | {
+        x: number;
+        y: number;
+    } | null;
+    /** Ms the old view takes to break up. Default 140. */
+    dissolve?: number;
+    /** Ms the new view takes to condense. Default 160. */
+    condense?: number;
+}
+interface PageDissolveHandle extends KitHandle<PageDissolveOptions> {
+    /**
+     * The view breaks into its own characters from `origin`, `render` swaps the content underneath, and the new view condenses
+     * out of characters. Swaps queue; each promise resolves once its view is crisp again.
+     */
+    swap(render: () => void | Promise<void>, origin?: HTMLElement | {
+        x: number;
+        y: number;
+    } | null): Promise<void>;
+    readonly busy: boolean;
+}
+/** A page or panel transition: the view dissolves into characters from where the user clicked and the next view condenses in. */
+declare function pageDissolve(container: HTMLElement, options?: PageDissolveOptions): PageDissolveHandle;
+
+interface SwipeDeckOptions extends KitOptions {
+    /** The cards, in order. Each card's first `img` is drawn in characters. Default `[data-card]`. */
+    cards?: string;
+    /** Start again from the first card after the last. Default true. */
+    loop?: boolean;
+    /** How far, as a share of the card's width, a release must travel to fling it. Default 0.4. */
+    threshold?: number;
+    /** Corner radius of the drawn cards, in CSS px. Default: the deck's own border radius. */
+    radius?: number;
+    /** CSS pixels the field reaches past the deck for the stack and the fling. Default 56; set at mount. */
+    outset?: number;
+    /** Called after a card leaves: `dir` is 1 for right (keep), -1 for left (pass). */
+    onSwipe?: (dir: 1 | -1, index: number, card: HTMLElement) => void;
+}
+interface SwipeDeckHandle extends KitHandle<SwipeDeckOptions> {
+    /** Flings the top card: 1 to the right, -1 to the left. Returns false at the end of a deck that does not loop. */
+    next(dir?: 1 | -1): boolean;
+    /** The index of the top card. */
+    readonly index: number;
+}
+/** A deck of cards drawn in characters: drag or press the arrow keys to fling the top card, which breaks into rows of characters along the swipe. */
+declare function swipeDeck(deck: HTMLElement, options?: SwipeDeckOptions): SwipeDeckHandle;
+
+type CodeState = 'idle' | 'error' | 'success';
+interface CodeInputOptions extends KitOptions {
+    /** How many characters the code has. Default 6. */
+    length?: number;
+    /** `digits` keeps only 0–9; `alphanumeric` keeps letters too, upper-cased. Default `digits`. */
+    accept?: 'digits' | 'alphanumeric';
+    /** The cells. Missing cells are created as `span[data-cell]`. Default `[data-cell]`. */
+    cells?: string;
+    /** Called once every cell is filled and has resolved. Answer with `verify(ok)`. */
+    onComplete?: (code: string) => void;
+}
+interface CodeInputHandle extends KitHandle<CodeInputOptions> {
+    /** `true`: the digits gather into the middle and a check draws in a ring. `false`: they break up, the row shakes, and it clears. */
+    verify(ok: boolean): void;
+    /** Empties the code and returns to idle. */
+    clear(): void;
+    readonly value: string;
+    readonly state: CodeState;
+}
+/**
+ * A one-time-code field: each digit resolves out of scattered characters, the caret is a breathing column of characters,
+ * a wrong code breaks up and shakes, and a right one gathers into a check in a ring.
+ */
+declare function codeInput(element: HTMLElement, options?: CodeInputOptions): CodeInputHandle;
+
+interface Toast {
+    title: string;
+    body?: string;
+    /** A node (such as an inline SVG) or a short text shown in the icon tile. */
+    icon?: Node | string;
+    /** A button beside the text, such as Undo. Clicking it dismisses the toast too. */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    /** Ms before it leaves on its own; 0 keeps it until dismissed. Default: the stack's `duration`. */
+    duration?: number;
+}
+interface ToastStackOptions extends KitOptions {
+    /** Toasts kept at once; the oldest dissolves when another arrives. Default 3. */
+    max?: number;
+    /** Ms a toast stays, unless pointed at or focused. 0 keeps every toast until dismissed. Default 6000. */
+    duration?: number;
+    /** Your own markup for a toast. Mark parts with `data-paint` (`strong`, `text`, `meta`, `tile`, `icon`, `none`) to set how they gather. */
+    render?: (toast: Toast, id: number) => HTMLElement;
+    /** Accessible name of the list. Default `Notifications`. */
+    label?: string;
+}
+interface ToastStackHandle extends KitHandle<ToastStackOptions> {
+    /** Adds a toast at the front, gathering out of scattered characters. Returns its id. */
+    push(toast: Toast): number;
+    /** Takes a toast out: it breaks into characters that drift up and away while the stack closes up. */
+    dismiss(id: number): void;
+    /** Dismisses every toast. */
+    clear(): void;
+    /** Ids of the toasts shown, oldest first. */
+    readonly toasts: number[];
+}
+/**
+ * A stack of toasts: each one gathers out of scattered characters, the newest in front and the rest tucked behind,
+ * fanning out while pointed at or focused. Dismissed toasts break into characters that drift up and away.
+ */
+declare function toastStack(container: HTMLElement, options?: ToastStackOptions): ToastStackHandle;
+
+type ThinkingState = 'thinking' | 'streaming' | 'done';
+interface ThinkingOptions extends KitOptions {
+    /** Line-shaped bands of drifting dots shown while thinking. Default 3. */
+    lines?: number;
+    /** An element to write the status into: `Thinking…`, then `Thought for 2s`. */
+    label?: HTMLElement | null;
+    /** The status texts. */
+    labels?: {
+        thinking?: string;
+        done?: (seconds: number) => string;
+    };
+    /** Start thinking at once. Default true; false waits for `think()`. */
+    start?: boolean;
+    /** Ms between one word and the next fading in. Default 38. */
+    stagger?: number;
+    /** A dotted rule under the finished answer. Default true. */
+    rule?: boolean;
+}
+interface ThinkingHandle extends KitHandle<ThinkingOptions> {
+    /** Clears the answer and thinks again, as for Regenerate. */
+    think(): void;
+    /** Writes the answer, word by word, as the dots give way. Pass a string or an async iterable of chunks. Resolves when it has settled. */
+    stream(text: string | AsyncIterable<string>): Promise<void>;
+    readonly state: ThinkingState;
+}
+/**
+ * The thinking state of an assistant reply: line-shaped bands of drifting dots while the model thinks, then the answer
+ * fades in word by word as the dots give way, leaving a quiet dotted rule under it.
+ */
+declare function thinking(element: HTMLElement, options?: ThinkingOptions): ThinkingHandle;
+
+type StreamState = 'idle' | 'streaming' | 'done' | 'stopped';
+interface StreamTextOptions extends KitOptions {
+    /** A block caret after the last character: bright while writing, dim at rest. Default true. */
+    caret?: boolean;
+    /** Ms a token's first character flickers before it resolves; each following character takes `stagger` ms more. Defaults 60 and 18. */
+    settle?: number;
+    stagger?: number;
+    /** Called on every state change. */
+    onState?: (state: StreamState) => void;
+    /** Reasoning lines `reasoning()` keeps in view above the reply; older ones scroll up and fade. Default 2. */
+    reasoningLines?: number;
+}
+interface StreamTextHandle extends KitHandle<StreamTextOptions> {
+    /** Appends a token: its characters land as flickering glyph cells that resolve into letters, left to right. */
+    write(token: string): void;
+    /** No more tokens: resolves once the last characters have landed. */
+    done(): Promise<void>;
+    /** Lands what has been written at once and stops. */
+    stop(): void;
+    /** Adds a line to the reasoning tail above the reply. The tail collapses once the reply is done or stopped. */
+    reasoning(line: string): void;
+    /** Clears the text and the reasoning for a new reply. */
+    reset(): void;
+    readonly state: StreamState;
+    readonly text: string;
+}
+/**
+ * Streamed text with a glyph write head: each token lands as flickering character cells that resolve into letters left
+ * to right, with a block caret after the last one. The real text is in the DOM all along, for selection and screen readers.
+ */
+declare function streamText(element: HTMLElement, options?: StreamTextOptions): StreamTextHandle;
+
+interface CompareOptions extends KitOptions {
+    /** The photo: a URL, or an `<img>` (one inside the element is used in place). */
+    image: string | HTMLImageElement;
+    /** Share of the frame showing the photo, from the left, 0–100. Default 50. */
+    position?: number;
+    /** The handle's accessible name. Default `Photo and ASCII split`. */
+    label?: string;
+    /** Called as the split moves. */
+    onChange?: (position: number) => void;
+}
+interface CompareHandle extends KitHandle<CompareOptions> {
+    /** Moves the split; `glide` eases it there. */
+    set(position: number, glide?: boolean): void;
+    readonly position: number;
+}
+/**
+ * A before and after slider: the photo on the left of the split and the same photo in characters, in its own colours,
+ * on the right. Drag anywhere, or use the arrow keys, Page Up and Down, Home and End on the handle.
+ */
+declare function compare(element: HTMLElement, options: CompareOptions): CompareHandle;
+
+interface AccordionImage {
+    src: string;
+    /** Read with the title as the panel's accessible name. */
+    alt?: string;
+    title?: string;
+    meta?: string;
+    /** Crop focus, 0–1 on each axis. Default the centre. */
+    focus?: {
+        x: number;
+        y: number;
+    };
+}
+interface AccordionOptions extends KitOptions {
+    images: (string | AccordionImage)[];
+    /** The panel open at first. Default 0. */
+    open?: number;
+    /** Ms a panel takes to open. Default 280. */
+    duration?: number;
+    /** Accessible name of the group. Default `Images`. */
+    label?: string;
+    onChange?: (index: number) => void;
+}
+interface AccordionHandle extends KitHandle<AccordionOptions> {
+    /** Opens a panel; `focus` moves focus to it too. */
+    select(index: number, focus?: boolean): void;
+    readonly open: number;
+}
+/**
+ * A strip of image panels: the open one shows its photo, the closed ones the same photos in characters. Pointing at,
+ * pressing or focusing a panel opens it, and as it opens its characters flare denser for a beat, then give way to the photo.
+ */
+declare function accordion(element: HTMLElement, options: AccordionOptions): AccordionHandle;
+
+type DropState = 'empty' | 'developing' | 'done';
+interface DroppedImage {
+    file: File | null;
+    src: string;
+    width: number;
+    height: number;
+}
+interface DropzoneOptions extends KitOptions {
+    /** Called once an image has been accepted and drawn. */
+    onImage?: (image: DroppedImage) => void;
+    /** Called when a file is refused: not an image, or over `maxBytes`. */
+    onError?: (message: string, file: File) => void;
+    /** Largest file accepted, in bytes. Default 10 MB. */
+    maxBytes?: number;
+    /** Ms the image takes to develop in characters. Default 720. */
+    develop?: number;
+    /** File name for `download()`. Default `<name>-ascii.png`. */
+    filename?: string;
+}
+interface DropzoneHandle extends KitHandle<DropzoneOptions> {
+    /** Shows an image (a URL, Blob or File), developing it in characters. */
+    setImage(src: string | Blob): Promise<void>;
+    /** Back to the empty zone. */
+    clear(): void;
+    /** Opens the file picker. */
+    pick(): void;
+    /** Saves the image as drawn in characters, as a PNG. Resolves with the Blob, or null without the field or an image. */
+    download(filename?: string): Promise<Blob | null>;
+    readonly state: DropState;
+}
+/**
+ * An image dropzone whose border is a quiet ring of characters that thickens and breathes while a file is dragged over.
+ * A dropped image develops in characters, in its own colours. Any element inside with `data-dropzone="pick"`, `"clear"`
+ * or `"download"` is wired to that action. Without content of your own it adds a title, hint and Choose file button.
+ */
+declare function dropzone(element: HTMLElement, options?: DropzoneOptions): DropzoneHandle;
+
+interface DisintegrateOptions extends KitOptions {
+    /** Ms the characters take to drift away. Default 620. */
+    duration?: number;
+    /** Close the row's height once the characters are on their way. Default true. */
+    collapse?: boolean;
+    /** Remove the row from the DOM at the end. Default false: it is left hidden and collapsed, for your framework to remove. */
+    remove?: boolean;
+    /** The element the field is drawn over. Default the row's parent, so the characters can drift past the row's own box. */
+    host?: HTMLElement;
+}
+/**
+ * Deletes a row into characters: its text and icons become glyphs that thin out from the right and drift up and away,
+ * while the row closes up. Resolves when it is done. Without WebGL2, or under reduced motion, the row closes at once.
+ */
+declare function disintegrate(row: HTMLElement, options?: DisintegrateOptions): Promise<void>;
+
+type PullState = 'idle' | 'pulling' | 'refreshing' | 'done';
+interface PullRefreshOptions extends KitOptions {
+    /** Runs the refresh. The spinner turns until its promise settles. */
+    onRefresh: () => unknown;
+    /** The element that moves down with the pull. Default the first child. */
+    content?: HTMLElement | null;
+    /** Pull distance in px that triggers a refresh on release. Default 88. */
+    threshold?: number;
+    /** What a screen reader hears. */
+    messages?: {
+        refreshing?: string;
+        done?: string;
+        failed?: string;
+    };
+    /** A selector for the rows `onRefresh` added, such as `'[data-new]'`: they resolve in from characters as the content springs back. Each row is revealed once. */
+    reveal?: string;
+}
+interface PullRefreshHandle extends KitHandle<PullRefreshOptions> {
+    /** Refreshes as if pulled, for a Refresh button or a keyboard shortcut. */
+    refresh(): Promise<void>;
+    /** Resolves these rows in from characters: they appear as glyphs of their own text and media, then hand over to the HTML. */
+    revealRows(rows: Iterable<Element>): void;
+    readonly state: PullState;
+}
+/**
+ * Pull to refresh: dragging the content down at the top gathers an orb of characters in the gap, which tightens into a
+ * ring at the threshold. Let go past it and the ring spins while `onRefresh` runs, then draws a check and springs back.
+ */
+declare function pullRefresh(element: HTMLElement, options: PullRefreshOptions): PullRefreshHandle;
+
+export { type AccordionHandle, type AccordionImage, type AccordionOptions, type ArtPanelHandle, type ArtPanelOptions, type AsciiVideoHandle, type AsciiVideoOptions, BEAM_PALETTES, type BeamHandle, type BeamMode, type BeamOptions, type BeamPalette, type BlockChartHandle, type BlockChartOptions, type Box, type ButtonLoadingHandle, type ButtonLoadingOptions, type ButtonState, type CodeInputHandle, type CodeInputOptions, type CodeState, type CommandPaletteHandle, type CommandPaletteOptions, type CompareHandle, type CompareOptions, type DecodeHandle, type DecodeOptions, type DisintegrateOptions, type DropState, type DroppedImage, type DropzoneHandle, type DropzoneOptions, type FieldBackgroundHandle, type FieldBackgroundOptions, type FieldPreset, type GenerateState, type ImageGenerateHandle, type ImageGenerateOptions, type ImageStream, type ImageUpdate, type KitHandle, type KitOptions, type LikeBurstHandle, type LikeBurstOptions, type LikeMark, type OdometerHandle, type OdometerOptions, type OrbState, PILL_TONES, type PageDissolveHandle, type PageDissolveOptions, type PaintFrame, type PillHandle, type PillOptions, type PillTone, type PricingGlowHandle, type PricingGlowOptions, type PullRefreshHandle, type PullRefreshOptions, type PullState, type SkeletonBlock, type SkeletonHandle, type SkeletonOptions, type SlideToConfirmHandle, type SlideToConfirmOptions, type StatusOrbHandle, type StatusOrbOptions, type StreamState, type StreamTextHandle, type StreamTextOptions, type Surface, type SurfaceConfig, type SwipeDeckHandle, type SwipeDeckOptions, type TabsHandle, type TabsOptions, type ThinkingHandle, type ThinkingOptions, type ThinkingState, type Toast, type ToastStackHandle, type ToastStackOptions, VOICE_PALETTES, type VoiceOrbHandle, type VoiceOrbOptions, type VoicePalette, type VoiceState, type WordmarkHandle, type WordmarkOptions, accordion, artPanel, asciiVideo, beam, beamPalette, blockChart, buttonLoading, codeInput, commandPalette, compare, decode, disintegrate, dropzone, fieldBackground, imageGenerate, likeBurst, mountSurface, odometer, pageDissolve, pill, pricingGlow, pullRefresh, resolveColor, skeleton, slideToConfirm, statusOrb, streamText, swipeDeck, tabs, thinking, toastStack, voiceOrb, wordmark };