@frapx/core 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.5.0 - 2026-10-15
+
+### Added
+
+- `ShaderCompileError` carries `stage` (`"vertex"`, `"fragment"`, `"link"` or `null`) and `lines`: each error the driver's info log locates, with its line number, message, that source line and two lines of context either side (`ShaderErrorLine`). The message is still the raw log.
+- `parseShaderLog(log, source)` for runtimes that compile their own shaders.
+- `keyframes(tracks, { ease })`: a dependency-free `UniformSource` that interpolates float and vec2–vec4 keyframes per component, with `"linear"`, `"smooth"`, `"step"` or custom eases.
+- `createUniformBindings()`: ordered `UniformSource`s merged into normalized uniforms for a time, for runtimes that implement `bindUniforms()`.
+
+### Fixed
+
+- `createProgram()` no longer leaks the compiled vertex shader when the fragment shader fails to compile.
+- After a WebGL context is restored, an instance that was not running (stopped, or on a manual clock) returns to its previous status instead of staying `"context-lost"`, and a stopped realtime instance redraws.
+
+## 0.4.0 - 2026-10-13
+
+### Added
+
+- Shared program state for runtimes built on the host, moved here from `@frapx/fx-canvas` so `@frapx/fx-passes` can reuse it:
+  - Uniform helpers `normalizeUniform`, `applyUniform`, `applyProgramUniform`, `applyUniforms`, `collectUniformLocations` and `createUniformCache`, with the `NormalizedUniform` type and the uniform input types (`UniformInput`, `UniformInputMap`, `UniformRuntimeValue`, `ExplicitUniformInput`, `UniformType`, `UniformScalar`, `UniformVec2`–`UniformVec4`).
+  - `createTextureSet(inputs)`: named image textures with texture-unit allocation (`reserveUnit` also covers runtime-owned samplers), superseded-load handling, binding and disposal.
+  - `createFullscreenProgram(gl, fragment, vertex?)`: compiles a fragment shader with the matching fullscreen-quad vertex shader and exposes its uniform locations, `use()`, `draw()` and `dispose()`.
+- `rgba32f` render targets (`createRenderTarget` / `createPingPong`), with the same WebGL2 + `EXT_color_buffer_float` requirement as `rgba16f`. They sample with nearest filtering unless `OES_texture_float_linear` is available. `captureFrame({ format: "rgba16f" })` also reads an `rgba32f` capture source.
+- `onCaptureDraw(state, signal)` host option: draws the frame `captureFrame()` reads over several tasks (for example sample accumulation that waits for the GPU between draws). The host holds its render lock until it settles, so other frames do not interleave, and reads the result in the settling task. Resizes requested meanwhile apply after the frame is read, and a context lost (even if restored) meanwhile rejects the capture.
+- `signal` capture option: an aborted signal rejects `captureFrame()` before drawing and is passed to `onCaptureDraw`.
+- `waitForGpu(gl)`: resolves once the GPU has finished the submitted work by polling a fence between tasks, so long renders can yield and avoid the GPU watchdog. Resolves immediately on WebGL1.
+
 ## 0.3.0 - 2026-10-10
 
 ### Added

package/dist/index.d.ts

@@ -23,11 +23,24 @@ type TextureOptions = {
 };
 type TextureInput = TextureSource | TextureOptions;
 type TextureMap = Record<string, TextureInput>;
+type UniformScalar = number;
+type UniformVec2 = [number, number] | readonly [number, number];
+type UniformVec3 = [number, number, number] | readonly [number, number, number];
+type UniformVec4 = [number, number, number, number] | readonly [number, number, number, number];
+type UniformType = "float" | "vec2" | "vec3" | "vec4" | "mat3" | "mat4";
+type ExplicitUniformInput = {
+    type: UniformType;
+    value: number[] | Float32Array;
+};
+type UniformInput = UniformScalar | UniformVec2 | UniformVec3 | UniformVec4 | Float32Array | ExplicitUniformInput;
+type UniformInputMap = Record<string, UniformInput>;
+type UniformRuntimeValue<T> = T extends ExplicitUniformInput ? ExplicitUniformInput : T extends Float32Array ? Float32Array : T extends readonly [number, number] ? UniformVec2 : T extends readonly [number, number, number] ? UniformVec3 : T extends readonly [number, number, number, number] ? UniformVec4 : T extends number ? number : UniformInput;
 /**
- * Storage format of a render target. `rgba16f` (half float) needs WebGL2 with
- * `EXT_color_buffer_float`.
+ * Storage format of a render target. `rgba16f` (half float) and `rgba32f`
+ * (float) need WebGL2 with `EXT_color_buffer_float`. `rgba32f` is sampled with
+ * nearest filtering unless `OES_texture_float_linear` is available.
  */
-type RenderTargetFormat = "rgba8" | "rgba16f";
+type RenderTargetFormat = "rgba8" | "rgba16f" | "rgba32f";
 type RenderTargetOptions = {
     /** Defaults to `"rgba8"`. */
     format?: RenderTargetFormat;
@@ -75,6 +88,11 @@ type CaptureFormat = "png" | "rgba8" | "rgba16f";
 type CaptureOptions<F extends CaptureFormat = CaptureFormat> = {
     /** Defaults to `"png"`. */
     format?: F;
+    /**
+     * Rejects the capture with the signal's reason when aborted before drawing,
+     * or between the steps of a capture that draws over several tasks.
+     */
+    signal?: AbortSignal;
 };
 type CaptureResult<F extends CaptureFormat> = F extends "rgba16f" ? Float32Array : F extends "rgba8" ? Uint8Array : Blob;
 type HostPointer = {
@@ -142,6 +160,14 @@ type RuntimeHostOptions = {
      * precision, if any. `captureFrame({ format: "rgba16f" })` reads from it.
      */
     captureSource?: () => RenderTarget | null;
+    /**
+     * Draws the frame `captureFrame()` reads, in place of `onDraw`, when drawing
+     * it takes more than one task (such as accumulating samples while waiting
+     * for the GPU). The host holds its render lock until the promise settles and
+     * reads the result in the task that settled it, so the final draw into the
+     * canvas must happen in that task. Receives the capture's abort signal.
+     */
+    onCaptureDraw?: (state: HostFrameState, signal: AbortSignal | undefined) => Promise<void>;
     onContextLost?: () => void;
     onContextRestored?: (gl: GLContext, width: number, height: number) => Promise<void> | void;
     onReady?: () => void;
@@ -182,20 +208,122 @@ type RuntimeHostInstance = {
 
 declare const createRuntimeHost: (options: RuntimeHostOptions) => RuntimeHostInstance;
 
+/**
+ * Resolves once the GPU has finished every command submitted so far, polling
+ * a fence between tasks. Waiting between heavy draws keeps each submission
+ * short, so a long render never trips the browser's GPU watchdog and loses
+ * the context. Resolves immediately on WebGL1.
+ */
+declare const waitForGpu: (gl: GLContext) => Promise<void>;
+
 declare class ShaderError extends Error {
     constructor(message: string);
 }
+/** One line of a shader compile error, located in the source that was compiled. */
+type ShaderErrorLine = {
+    /** 1-based line in the compiled source (after `glsl` template interpolation). */
+    line: number;
+    message: string;
+    /** That line of the source, or "" when the log points past the end. */
+    source: string;
+    /** Up to two lines either side, with their numbers, the error line included. */
+    context: ReadonlyArray<{
+        line: number;
+        source: string;
+    }>;
+};
+/** `"link"` for program link errors, which carry no line numbers. */
+type ShaderStage = "vertex" | "fragment" | "link";
 declare class UnsupportedError extends ShaderError {
 }
 declare class TargetNotFoundError extends ShaderError {
 }
 declare class ShaderCompileError extends ShaderError {
+    /** The stage that failed, or `null` for errors not tied to compiling a shader. */
+    readonly stage: ShaderStage | null;
+    /** Errors located in the source, parsed from the driver's info log. Empty when it had none. */
+    readonly lines: readonly ShaderErrorLine[];
+    constructor(message: string, details?: {
+        stage?: ShaderStage;
+        lines?: readonly ShaderErrorLine[];
+    });
 }
 declare class TextureLoadError extends ShaderError {
 }
 declare class DestroyedError extends ShaderError {
 }
 
+/**
+ * Finds the errors in a shader info log and attaches the source lines they
+ * point at. Lines the log does not locate are left out; the log itself stays
+ * the error message.
+ */
+declare const parseShaderLog: (log: string, source: string) => ShaderErrorLine[];
+
+type NormalizedUniform = {
+    type: UniformType;
+    value: number[] | Float32Array;
+};
+declare const normalizeUniform: (input: UniformInput) => NormalizedUniform;
+declare const applyUniform: (gl: GLContext, location: WebGLUniformLocation, uniform: NormalizedUniform) => void;
+declare const applyProgramUniform: (gl: GLContext, program: WebGLProgram, location: WebGLUniformLocation, uniform: NormalizedUniform) => void;
+/**
+ * Uploads every cached uniform to the bound program. Calls `onMissing` with
+ * the name of each uniform the program lacks or optimized out.
+ */
+declare const applyUniforms: (gl: GLContext, locations: ReadonlyMap<string, WebGLUniformLocation>, cache: ReadonlyMap<string, NormalizedUniform>, onMissing?: (name: string) => void) => void;
+declare const collectUniformLocations: (gl: GLContext, program: WebGLProgram) => Map<string, WebGLUniformLocation>;
+declare const createUniformCache: (uniforms: Record<string, UniformInput> | undefined) => Map<string, NormalizedUniform>;
+
+/**
+ * Supplies uniform values for a time, such as a keyframe timeline. Runtimes
+ * call `get()` with the same time as `u_time` before drawing.
+ */
+type UniformSource = {
+    get(time: number): Readonly<Record<string, UniformInput>>;
+};
+/** Ordered sources whose values override the runtime's own uniforms. */
+type UniformBindings = {
+    /** Adds `source`; a later source wins for the same name. Returns its removal. */
+    add(source: UniformSource): () => void;
+    readonly size: number;
+    /** Merged, normalized values at `time`, keyed by uniform name (`u_` prefixed). */
+    evaluate(time: number): Map<string, NormalizedUniform>;
+    /** A stable string of the values at `time`, to notice when they change. */
+    signature(time: number): string;
+};
+declare const createUniformBindings: () => UniformBindings;
+type KeyframeValue = number | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number];
+/** `[time in seconds, value]`. */
+type Keyframe = readonly [number, KeyframeValue];
+/**
+ * How a segment eases from one key to the next: `"linear"`, `"smooth"`
+ * (smoothstep), `"step"` (hold the earlier key), or a function of the
+ * segment's 0–1 progress.
+ */
+type Ease = "linear" | "smooth" | "step" | ((t: number) => number);
+type KeyframeTrack = readonly Keyframe[] | {
+    keys: readonly Keyframe[];
+    ease?: Ease;
+};
+type KeyframeOptions = {
+    /** Default ease for tracks that do not set their own. Defaults to `"linear"`. */
+    ease?: Ease;
+};
+/**
+ * A `UniformSource` that interpolates keyframes per component: floats and
+ * vec2–vec4 as tuples. Keys may come in any order; times before the first key
+ * or after the last hold that key's value.
+ *
+ * ```ts
+ * fx.bindUniforms(keyframes({
+ *   camPos: [[0, [0, 1, 6]], [4, [3, 1.5, 2]]],
+ *   glow: { keys: [[0, 0], [2, 1]], ease: "smooth" }
+ * }));
+ * ```
+ */
+declare const keyframes: (tracks: Readonly<Record<string, KeyframeTrack>>, options?: KeyframeOptions) => UniformSource;
+
 declare const toUniformName: (name: string) => string;
 declare const fromUniformName: (name: string) => string;
 
@@ -228,6 +356,63 @@ type LoadedTexture = {
 };
 declare const loadTexture: (gl: GLContext, name: string, input: TextureInput, unit: number) => Promise<LoadedTexture>;
 
+type TextureSet = {
+    /** The textures loaded so far, by name. */
+    readonly textures: ReadonlyMap<string, LoadedTexture>;
+    /** Whether `name` was given as an input, loaded or not. */
+    hasInput(name: string): boolean;
+    /**
+     * Returns the texture unit for `name`, taking the lowest free unit on first
+     * use. Runtimes reserve units for their own samplers (feedback, pass inputs)
+     * here too, so they never collide with image textures.
+     */
+    reserveUnit(gl: GLContext, name: string): number;
+    /**
+     * Loads every input, then replaces the previously loaded textures. Used for
+     * the initial load and after a context restore.
+     */
+    loadAll(gl: GLContext, isCancelled: () => boolean): Promise<void>;
+    /**
+     * Loads `input` as `name`. Resolves to the loaded texture, or `null` when a
+     * later `set()` for the same name or `isCancelled()` superseded it (its
+     * texture is deleted). On failure the unit is released if `name` is unused,
+     * and the error is rethrown.
+     */
+    set(gl: GLContext, name: string, input: TextureInput, isCancelled: () => boolean): Promise<LoadedTexture | null>;
+    /**
+     * Binds every loaded texture to its unit and points its sampler uniform at
+     * it. Calls `onMissing` with the uniform name when the program lacks it.
+     */
+    bind(gl: GLContext, locations: ReadonlyMap<string, WebGLUniformLocation>, onMissing?: (uniformName: string) => void): void;
+    /** Deletes every loaded texture. */
+    dispose(gl: GLContext): void;
+};
+/**
+ * Tracks named image textures and the texture units they occupy, for a
+ * runtime that binds them to one or more programs.
+ */
+declare const createTextureSet: (inputs?: TextureMap) => TextureSet;
+
+type FullscreenProgram = {
+    readonly program: WebGLProgram;
+    /** Active uniform locations by name, array uniforms without `[0]`. */
+    readonly locations: ReadonlyMap<string, WebGLUniformLocation>;
+    /**
+     * Binds the program, its quad buffer and `a_position`, so a draw is correct
+     * whatever GL state user hooks left behind.
+     */
+    use(): void;
+    /** Draws the fullscreen quad with the current GL state. */
+    draw(): void;
+    dispose(): void;
+};
+/**
+ * Compiles `fragment` with a fullscreen-quad vertex shader (the GLSL ES 3.00
+ * one when `fragment` starts with `#version 300 es`, unless `vertex` is
+ * given) and leaves it bound.
+ */
+declare const createFullscreenProgram: (gl: GLContext, fragment: string, vertex?: string) => FullscreenProgram;
+
 declare const defaultVertexShader = "\nattribute vec2 a_position;\nvarying vec2 v_uv;\n\nvoid main() {\n  v_uv = a_position * 0.5 + 0.5;\n  gl_Position = vec4(a_position, 0.0, 1.0);\n}\n";
 declare const defaultVertexShader300 = "#version 300 es\nin vec2 a_position;\nout vec2 v_uv;\n\nvoid main() {\n  v_uv = a_position * 0.5 + 0.5;\n  gl_Position = vec4(a_position, 0.0, 1.0);\n}\n";
 declare const isGLSL300: (src: string) => boolean;
@@ -255,7 +440,8 @@ declare const createBlitter: (gl: GLContext) => Blitter;
 
 /**
  * Whether `format` can be allocated as a color attachment on `gl`. `rgba8` is
- * always available; `rgba16f` needs WebGL2 and `EXT_color_buffer_float`.
+ * always available; `rgba16f` and `rgba32f` need WebGL2 and
+ * `EXT_color_buffer_float`.
  * Enables the extension as a side effect when present.
  */
 declare const supportsRenderTargetFormat: (gl: GLContext, format: RenderTargetFormat) => boolean;
@@ -276,4 +462,4 @@ declare const createRenderTarget: (gl: GLContext, width: number, height: number,
  */
 declare const createPingPong: (gl: GLContext, width: number, height: number, options?: RenderTargetOptions) => PingPong;
 
-export { type Blitter, type CaptureFormat, type CaptureOptions, type CaptureResult, type ClockMode, DestroyedError, type DomSetup, type DprOption, type GLContext, type HostFrameState, type HostPointer, type LoadedTexture, type PingPong, type RenderMode, type RenderTarget, type RenderTargetFormat, type RenderTargetOptions, type Resolution, type RuntimeHostInstance, type RuntimeHostOptions, type SetupCanvasOptions, ShaderCompileError, ShaderError, type ShaderLayer, type ShaderStatus, TargetNotFoundError, type TextureInput, TextureLoadError, type TextureMap, type TextureOptions, type TextureSource, UnsupportedError, createBlitter, createFullscreenBuffer, createPingPong, createProgram, createRenderTarget, createRuntimeHost, defaultVertexShader, defaultVertexShader300, fromUniformName, isGLSL300, isWebGL2Context, loadTexture, resizeCanvasToTarget, resolveDpr, resolveElement, resolveRenderTargetFormat, setupCanvas, supportsRenderTargetFormat, toUniformName };
+export { type Blitter, type CaptureFormat, type CaptureOptions, type CaptureResult, type ClockMode, DestroyedError, type DomSetup, type DprOption, type Ease, type ExplicitUniformInput, type FullscreenProgram, type GLContext, type HostFrameState, type HostPointer, type Keyframe, type KeyframeOptions, type KeyframeTrack, type KeyframeValue, type LoadedTexture, type NormalizedUniform, type PingPong, type RenderMode, type RenderTarget, type RenderTargetFormat, type RenderTargetOptions, type Resolution, type RuntimeHostInstance, type RuntimeHostOptions, type SetupCanvasOptions, ShaderCompileError, ShaderError, type ShaderErrorLine, type ShaderLayer, type ShaderStage, type ShaderStatus, TargetNotFoundError, type TextureInput, TextureLoadError, type TextureMap, type TextureOptions, type TextureSet, type TextureSource, type UniformBindings, type UniformInput, type UniformInputMap, type UniformRuntimeValue, type UniformScalar, type UniformSource, type UniformType, type UniformVec2, type UniformVec3, type UniformVec4, UnsupportedError, applyProgramUniform, applyUniform, applyUniforms, collectUniformLocations, createBlitter, createFullscreenBuffer, createFullscreenProgram, createPingPong, createProgram, createRenderTarget, createRuntimeHost, createTextureSet, createUniformBindings, createUniformCache, defaultVertexShader, defaultVertexShader300, fromUniformName, isGLSL300, isWebGL2Context, keyframes, loadTexture, normalizeUniform, parseShaderLog, resizeCanvasToTarget, resolveDpr, resolveElement, resolveRenderTargetFormat, setupCanvas, supportsRenderTargetFormat, toUniformName, waitForGpu };