asciify-engine 4.25.0 → 4.26.0

package/dist/field.d.ts

@@ -1,286 +1,143 @@
-import { H as HoverScope } from './hover-guide-DdFnAnfU.js';
+export { D as DEFAULT_FIELD_FLUID, a as DEFAULT_FIELD_LANTERN, b as DEFAULT_FIELD_SETTINGS, c as DEFAULT_FIELD_TRAIL, F as FIELD_HOVERS, d as FIELD_MARKS, e as FIELD_SCENES, f as FieldClearElement, g as FieldClearZone, h as FieldColor, i as FieldFit, j as FieldFluidOptions, k as FieldHover, l as FieldLanternOptions, m as FieldMark, n as FieldScene, o as FieldSource, p as FieldTrailOptions, G as GlyphField, q as GlyphFieldInput, r as GlyphFieldOptions, s as GlyphFieldSettings, t as activeFieldHover, u as fieldCellLayout, v as fieldClearFromRects, w as fieldGlyphs, x as fieldLevels, y as fieldSourceRect, z as glyphFieldTier, A as isGlyphFieldSupported, B as mountGlyphField, C as normalizeFieldSettings, E as prewarmGlyphAtlas } from './glyph-field-DRC-7uVf.js';
+export { H as FieldHoverScope } from './hover-guide-DdFnAnfU.js';
 
-/** Pure option handling for the GPU glyph field, kept free of DOM and WebGL so it can be tested in Node. */
-
-type FieldColor = 'ink' | 'source';
-type FieldFit = 'cover' | 'contain';
-/**
- * Generated motion used when there is no media source. The later ones are the kit's background scenes: caustic light, drifting contour lines, aurora ribbons, water rings, a halo,
- * two interfering ring grids, a gradient mesh, falling streaks in three depths, and linked points.
- */
-declare const FIELD_SCENES: readonly ["none", "flow", "orb", "drift", "swell", "caustics", "contour", "aurora", "ripple", "halo", "interference", "mesh", "cascade", "constellation"];
-type FieldScene = typeof FIELD_SCENES[number];
-/**
- * What each cell draws. `glyph` draws characters from the atlas; `dot` draws a halftone: one circle per cell, its area
- * following the tone. The rest are the Studio's tile and print styles, drawn per cell from the cell's tone and colour:
- * tiles (`pixel`, `mosaic`, `lego`, `voxel`, `disco`, `hex`, `led`) fade with the tone in ink colour and stay solid in source
- * colour; `dither` lights whole cells through a 4x4 Bayer screen; `cmyk` separates the cell's colour into offset ink dots;
- * the print marks (`stipple`, `engraving`, `crosshatch`, `woodblock`, `risograph`, `pointillism`) carry the tone in their size.
- * Every mark but `dot` leaves empty the cells the charset would leave blank.
- */
-declare const FIELD_MARKS: readonly ["glyph", "dot", "pixel", "mosaic", "lego", "voxel", "disco", "dither", "hex", "led", "cmyk", "stipple", "engraving", "crosshatch", "woodblock", "risograph", "pointillism"];
-type FieldMark = typeof FIELD_MARKS[number];
-/**
- * An area the field keeps quiet, so content above it stays readable. Coordinates are fractions of the field,
- * from the top left; `feather` is the soft edge, as a fraction of the field's shorter side.
- */
-interface FieldClearZone {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    feather: number;
-    shape: 'ellipse' | 'rect';
-}
 /**
- * How the field answers the pointer.
- * - `fluid`: an incompressible fluid that bends the image and swirls the characters. Bold, liquid.
- * - `lantern`: a soft light that glides after the pointer and lifts the characters it passes. Subtle, no distortion.
- * - `trail`: the Asciify Trail. The same ink field as the studio's Trail; the wake folds each character's tone, then settles.
- * - `loupe`: a glass loupe glides after the pointer and magnifies what it covers, easing through a soft rim. Uses `lantern` for radius, gain and follow.
- * - `reveal`: under a soft spotlight the characters take the source's own colours. Uses `lantern` settings.
- * - `none`: still under the pointer.
+ * What every glyph field on a page shares: one WebGL2 context drawing off screen, one frame loop, one set of page listeners
+ * and observers, and the programs and glyph atlases built in that context. Each field draws its frame into the shared
+ * context and copies it to its own canvas with a 2D blit, so a page with many fields holds one context: no per-field context
+ * creation or teardown, no browser context limit, and fields stay ordinary canvases in the page's own stacking and clipping.
  */
-type FieldHover = 'fluid' | 'lantern' | 'trail' | 'loupe' | 'reveal' | 'none';
-declare const FIELD_HOVERS: readonly {
-    value: FieldHover;
-    label: string;
-    description: string;
-}[];
-interface FieldLanternOptions {
-    /** Light radius as a fraction of the field height. */
-    radius: number;
-    /** How far the light lifts characters toward denser glyphs. */
-    strength: number;
-    /** Seconds the light's tail takes to fade. 0 is no tail. */
-    trail: number;
-    /** How quickly the light catches the pointer; higher follows more tightly. */
-    follow: number;
+type Locations = Record<string, WebGLUniformLocation | null>;
+interface SharedProgram {
+    program: WebGLProgram;
+    locations: Locations | null;
+    fragment: WebGLShader;
 }
-declare const DEFAULT_FIELD_LANTERN: FieldLanternOptions;
-/** Matches the studio's Trail hover settings, so a look moves between renderers unchanged. */
-interface FieldTrailOptions {
-    /** 0–1. How far the wake folds tone. */
-    strength: number;
-    /** 0.1–1. Wake width. */
-    radius: number;
+interface SharedAtlas {
+    key: string;
+    texture: WebGLTexture;
+    refs: number;
+    final: boolean;
+    users: Set<() => void>;
+    bytes: number;
 }
-declare const DEFAULT_FIELD_TRAIL: FieldTrailOptions;
-interface FieldFluidOptions {
-    /** Brush radius as a fraction of the field height. */
-    radius: number;
-    /** How strongly pointer speed pushes the fluid. */
-    force: number;
-    /** Velocity decay per second; higher settles faster. */
-    dissipation: number;
-    /** How far the fluid bends the sampled image, in field heights per unit of velocity. */
-    refraction: number;
-    /** How much a wake lifts characters toward denser glyphs and the highlight color. */
-    glow: number;
-    /** Longest side of the simulation grid in cells. */
-    resolution: number;
-    /** Vorticity: how strongly the wake curls into eddies. 0 is a straight smear. */
-    curl: number;
-}
-interface GlyphFieldSettings {
-    /** Ordered from empty to dense. Any graphemes, including words such as " .:-+ASCIIFY". */
-    charset: string;
-    /** Cell height in CSS pixels. */
-    cellSize: number;
-    /** Cell width divided by height. 1 is a square grid. */
-    cellAspect: number;
-    /**
-     * `pixel` (default) snaps each cell to whole device pixels. `fill` fits a whole number of cells of at least `cellSize` to the
-     * canvas and stretches them to fill it exactly, as asciify-engine's core renderer lays out a frame, so rows and columns keep their
-     * place however fractional the cell; each glyph sits centred in its cell, texel for texel.
-     */
-    cellFit: 'pixel' | 'fill';
-    font: string;
-    fontWeight: number;
-    /** Glyph height relative to the cell. */
-    glyphScale: number;
-    /** See `FIELD_MARKS`. Only `glyph` reads the atlas; the others keep the charset for which cells stay empty. */
-    mark: FieldMark;
-    /** Largest dot as a fraction of the cell, for `mark: 'dot'`. */
-    dotScale: number;
-    color: FieldColor;
-    ink: string;
-    /** Color the wake lifts characters toward. 'auto' brightens each character's own color, so the wake never turns white. */
-    highlight: string;
-    /** Any CSS hex color, or "transparent". */
-    background: string;
-    brightness: number;
-    contrast: number;
-    gamma: number;
-    invert: boolean;
-    /** Stretch the source's tonal range so the whole charset is used. */
-    levels: 'auto' | 'none';
-    /**
-     * Shades between two characters, drawn by mixing them across neighbouring cells in a fixed 4x4 pattern, as print
-     * halftones do. 'auto' turns it on for photo and video sources drawn in nine or fewer characters, whose steps are coarse;
-     * drawn interface shapes stay crisp, and ramps of ten and more are left as they are. 'coarse' does the same for any
-     * source, for a canvas that paints photos. The pattern is locked to the grid, so it never shimmers.
-     */
-    blend: 'auto' | 'coarse' | 'on' | 'off';
-    /** Glyph color saturation in source color mode. */
-    saturation: number;
-    /** How far darker tones dim the ink, so same-density glyphs such as words still carry the image. 0 is one flat ink. */
-    shade: number;
-    /** Opacity of a soft, blurred copy of the source behind the characters. 0 draws characters only. */
-    backdrop: number;
-    fit: FieldFit;
-    /** Crop focus for cover, 0–1 on each axis. */
-    focus: {
-        x: number;
-        y: number;
-    };
-    vignette: number;
-    /** Slow ambient sampling drift that keeps a still image alive. 0 is still. */
-    drift: number;
-    scene: FieldScene;
-    /** Size of generated scenes' features; higher is finer. */
-    scale: number;
-    clear: FieldClearZone | false;
-    /** Speed of generated scenes and drift. */
-    speed: number;
-    /** Which pointer response runs. */
-    hover: FieldHover;
-    /** Settings for the fluid hover. `false` turns it off. */
-    fluid: FieldFluidOptions | false;
-    /** Settings for the lantern hover. */
-    lantern: FieldLanternOptions;
-    /** Settings for the trail hover. */
-    trail: FieldTrailOptions;
-    /**
-     * Where the pointer response acts: `all` (default) everywhere, `subject` only on the source's subject, `outside` only on
-     * the ground around it. The subject is the source's alpha, or for an opaque source on a plain, even ground, its distance
-     * from that ground; feathered at the edge. A busy photo and generated scenes have no subject, so every scope acts as `all`.
-     */
-    scope: HoverScope;
-    maxPixelRatio: number;
-    /** Stop ambient motion and soften the wake when the visitor prefers reduced motion. */
-    respectReducedMotion: boolean;
+type Task = (now: number) => void;
+/** How many times longer ambient motion waits between frames right now: 1, or 2 to 3 while frames are expensive. */
+declare const ambientFactor: () => number;
+/** Runs `task` in the next shared frame. A task asked for twice in one frame runs once. */
+declare function requestFieldFrame(task: Task): void;
+declare function cancelFieldFrame(task: Task): void;
+interface PointerClient {
+    /** Where to read the pointer: the window, or an element whose events (bubbling from its content) count. */
+    target: HTMLElement | Window;
+    move(event: PointerEvent): void;
+    /** The pointer left the target, or the page. */
+    leave(): void;
+    /** False while the field cannot be under the pointer (scrolled away), so moves elsewhere skip it. */
+    near?(): boolean;
+    inside?: boolean;
 }
-declare const DEFAULT_FIELD_FLUID: FieldFluidOptions;
-declare const DEFAULT_FIELD_SETTINGS: GlyphFieldSettings;
-type GlyphFieldInput = Partial<Omit<GlyphFieldSettings, 'fluid' | 'focus' | 'lantern' | 'trail' | 'clear'>> & {
-    clear?: Partial<FieldClearZone> | false;
-    trail?: Partial<FieldTrailOptions>;
-    fluid?: Partial<FieldFluidOptions> | boolean;
-    lantern?: Partial<FieldLanternOptions>;
-    focus?: Partial<GlyphFieldSettings['focus']>;
-};
-/** Splits a charset into graphemes so emoji, block elements and accented letters each take one cell. */
-declare function fieldGlyphs(charset: string): string[];
-/** Mount options may carry an element-based clear zone; normalizing ignores it, since only a mounted field can measure it. */
-type ClearElementLike = {
-    element: unknown;
-} | {
-    nodeType: number;
-};
-declare function normalizeFieldSettings(input?: Omit<GlyphFieldInput, 'clear'> & {
-    clear?: GlyphFieldInput['clear'] | ClearElementLike;
-}, base?: GlyphFieldSettings): GlyphFieldSettings;
-/** Maps field UV (0–1, top left) to source UV as `source = uv * scale + offset`. */
-declare function fieldSourceRect(fieldWidth: number, fieldHeight: number, sourceWidth: number, sourceHeight: number, fit: FieldFit, focus?: {
-    x: number;
-    y: number;
-}): {
-    scale: [number, number];
-    offset: [number, number];
-};
-/** Device-pixel cell and atlas layout. Cells are whole pixels so glyphs are sampled texel for texel. */
-declare function fieldCellLayout(cellSize: number, cellAspect: number, pixelRatio: number, glyphCount: number): {
-    width: number;
-    height: number;
-    columns: number;
-    rows: number;
-    atlasWidth: number;
-    atlasHeight: number;
-};
-/** 2nd and 98th luminance percentiles of RGBA pixels, used to stretch a source across the charset. */
-declare function fieldLevels(pixels: Uint8ClampedArray | Uint8Array): [number, number];
-/** The hover that actually runs: fluid needs its settings, and anything is off without a pointer response. */
-declare const activeFieldHover: (settings: GlyphFieldSettings) => FieldHover;
-/** The clear zone around an element, in field fractions; `padding` is CSS pixels added on every side. */
-declare function fieldClearFromRects(field: {
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-}, element: {
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-}, padding?: number, feather?: number, shape?: FieldClearZone['shape']): FieldClearZone | false;
-
-type FieldSource = string | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | ImageBitmap;
-interface GlyphFieldOptions extends Omit<GlyphFieldInput, 'clear'> {
-    /**
-     * Keep the field quiet around content: an element (followed through layout changes), an element with
-     * `padding` (CSS px), `feather` (fraction of the shorter side) and `shape`, a zone in field fractions, or `false`.
-     */
-    clear?: GlyphFieldInput['clear'] | HTMLElement | FieldClearElement;
-    /** Image or video URL, or a decoded element. Without one, `scene` draws generated motion. */
-    source?: FieldSource | null;
-    /** Where pointer movement is read. Defaults to the window, so overlaid text never blocks the wake. */
-    interactionTarget?: HTMLElement | Window | null;
-    /** Accessible name for the canvas. */
-    label?: string;
-    onError?: (error: Error) => void;
-}
-interface FieldClearElement {
-    element: HTMLElement;
-    padding?: number;
-    feather?: number;
-    shape?: 'ellipse' | 'rect';
-}
-interface GlyphField {
-    readonly canvas: HTMLCanvasElement;
-    /** Resolves once the first frame with the current source has been drawn. */
-    readonly ready: Promise<void>;
-    /** Merges settings; only the parts that changed are rebuilt. */
-    update(options: GlyphFieldOptions): void;
-    setSource(source: FieldSource | null): Promise<void>;
-    /** Moves the wake programmatically, in CSS pixels relative to the canvas. `null` lifts the pointer. */
-    pointer(x: number | null, y?: number): void;
-    /**
-     * Draws the current frame now, so the canvas can be read with drawImage in the same task. Before `ready`, while the shaders
-     * are still compiling in parallel, it leaves the first frame to the field's own loop rather than block on the compiler.
-     */
-    redraw(): void;
+/**
+ * Pointer moves over the target, through the page's one listener. A target in a shadow root, or in another document, is
+ * listened to directly: the page's listener can't see into either. Returns the unsubscribe.
+ */
+declare function watchPointer(client: PointerClient): () => void;
+/** The tab shown or hidden. */
+declare const watchVisibility: (fn: () => void) => () => void;
+/** `prefers-reduced-motion` changed. */
+declare const watchMotionPreference: (fn: () => void) => () => void;
+/** The colour scheme, or a class or attribute theme on the root, changed. */
+declare const watchTheme: (fn: () => void) => () => void;
+type GlCanvas = OffscreenCanvas | HTMLCanvasElement;
+declare class FieldContext {
+    gl: WebGL2RenderingContext;
+    canvas: GlCanvas;
+    lost: boolean;
+    /** Index into SCALES; 0 is full resolution. */
+    level: number;
+    private programs;
+    private atlases;
+    private vertex;
+    private vao;
+    private clients;
+    private parallel;
+    private timer;
+    private queries;
+    private open;
+    private drew;
+    private gpuMs;
+    private cpuMs;
+    private changedAt;
+    private lostTimer;
+    renderer: string;
+    /** At the lowest render scale and still over budget: ambient motion slows down too. */
+    overloaded: boolean;
+    constructor();
+    private create;
+    private onLost;
+    private onRestored;
+    private restored;
+    private reset;
+    private idleTimer;
+    join(client: FieldClient): void;
+    leave(client: FieldClient): void;
+    private dispose;
+    /** The program for a fragment shader, linked once per context. Linking finishes in the browser's compiler. */
+    program(fragment: string): SharedProgram;
+    /** True once linked; collects uniform locations then. Throws if linking failed. */
+    linked(entry: {
+        program: WebGLProgram;
+        locations: Locations | null;
+        fragment?: WebGLShader;
+    }, wait?: boolean): boolean;
+    get canCompileInParallel(): boolean;
+    vertexArray(): WebGLVertexArrayObject;
     /**
-     * Sends a ring through the field, for interface events such as a save or a message.
-     * `x` and `y` are CSS pixels relative to the canvas, or pass an element to start from its centre. Ignored under reduced motion.
+     * The glyph atlas for `key`, painted once and shared by every field drawing the same glyphs at the same size. `final` is
+     * false when the font was still loading; the first field that sees it arrive repaints it for all.
      */
-    pulse(options?: {
-        x?: number;
-        y?: number;
-        element?: Element;
-        strength?: number;
+    atlas(key: string, paint: () => {
+        image: TexImageSource;
+        final: boolean;
+    }, user: () => void): SharedAtlas;
+    /** True when the atlas for `key` exists, in use or spare. */
+    hasAtlas(key: string): boolean;
+    paintAtlas(entry: SharedAtlas, paint: () => {
+        image: TexImageSource;
+        final: boolean;
     }): void;
-    play(): void;
-    pause(): void;
-    resize(): void;
-    destroy(): void;
-    readonly settings: GlyphFieldSettings;
+    releaseAtlas(entry: SharedAtlas | null, user: () => void): void;
+    /** Deletes unused atlases past the spare count, oldest first, and all of them while over the memory budget. */
+    private evictAtlases;
+    /** Shrinks the shared drawing buffer once the largest field it was grown for has gone. */
+    private fit;
+    /** GPU memory the page's fields hold now, in bytes (see FIELD_MEMORY_BUDGET). */
+    get bytes(): number;
+    get overBudget(): boolean;
+    /** Room for another field: a margin under the budget, so fields at its edge don't mount and release in turn. */
+    get roomy(): boolean;
+    /** Readies the shared drawing buffer for a frame of this size; it only grows, in steps, so fields rarely resize it. */
+    begin(width: number, height: number): void;
+    /** Copies the frame just drawn (the bottom-left `width` x `height` of the shared buffer) to a field's canvas. */
+    present(target: CanvasRenderingContext2D, width: number, height: number): void;
+    /** After each shared frame: collects GPU time where the browser reports it, else main-thread draw time, and sets the scale. */
+    endFrame(now: number): void;
+    private adapt;
+    get scale(): number;
+    get atMinimum(): boolean;
 }
-/** 'gpu', 'software' (WebGL2 emulated on the CPU, such as SwiftShader or llvmpipe) or 'none'. Probed once per page. */
-declare function glyphFieldTier(): 'gpu' | 'software' | 'none';
-/**
- * True when WebGL2 runs on a GPU. Software WebGL draws every pixel on the CPU and would starve the rest of the page,
- * so it reports false unless `allowSoftware` is set. Mounting can still fail on a blocked GPU, so handle errors.
- */
-declare function isGlyphFieldSupported(options?: {
-    allowSoftware?: boolean;
-}): boolean;
-/**
- * A GPU character field: every cell samples the source once and draws its glyph texel for texel,
- * while a small advected fluid bends the sampling and lifts characters under the cursor.
- * Idle fields stop drawing until the pointer, a video frame or generated motion needs a new frame.
- * Each frame shades one fragment per cell, then draws the glyphs per pixel, so the cost of the scene does not grow with pixel density.
- */
-declare function mountGlyphField(canvas: HTMLCanvasElement, options?: GlyphFieldOptions): GlyphField;
+interface FieldClient {
+    lost(): void;
+    restored(): void;
+    rescale(): void;
+    /** The field's frame in device pixels. */
+    size(): [number, number];
+    /** GPU memory the field holds of its own, in bytes. */
+    bytes(): number;
+}
+/** The page's shared context if one exists, without making one. */
+declare const currentFieldContext: () => FieldContext | null;
+/** True for a field canvas drawn through the shared context: it holds no WebGL context of its own. */
+declare const isSharedFieldCanvas: (canvas: object) => boolean;
 
-export { DEFAULT_FIELD_FLUID, DEFAULT_FIELD_LANTERN, DEFAULT_FIELD_SETTINGS, DEFAULT_FIELD_TRAIL, FIELD_HOVERS, FIELD_MARKS, FIELD_SCENES, type FieldClearElement, type FieldClearZone, type FieldColor, type FieldFit, type FieldFluidOptions, type FieldHover, HoverScope as FieldHoverScope, type FieldLanternOptions, type FieldMark, type FieldScene, type FieldSource, type FieldTrailOptions, type GlyphField, type GlyphFieldInput, type GlyphFieldOptions, type GlyphFieldSettings, activeFieldHover, fieldCellLayout, fieldClearFromRects, fieldGlyphs, fieldLevels, fieldSourceRect, glyphFieldTier, isGlyphFieldSupported, mountGlyphField, normalizeFieldSettings };
+export { ambientFactor, cancelFieldFrame, currentFieldContext, isSharedFieldCanvas, requestFieldFrame, watchMotionPreference, watchPointer, watchTheme, watchVisibility };