@cueframe/kernel 0.2.2 → 0.2.3

package/dist/_members/animate/scene/finishing.d.ts

@@ -0,0 +1,69 @@
+import React from 'react';
+import type { SceneFrameSize } from './scaling.js';
+export interface ScenePostTreatment {
+    grain: number;
+    vignette: number;
+}
+/** FNV-1a over UTF-16 code units: a small, dependency-free, deterministic 32-bit hash. */
+export declare function hashSeed(seed: string): number;
+/** The `feTurbulence` seed for one frame of one shot: a function of the render seed and the local frame only. */
+export declare function grainSeed(seed: string, frame: number): number;
+/** A document-unique filter id derived from the render seed, so two shots on screen at once cannot share one. */
+export declare function postFilterId(seed: string): string;
+export type PostStage = 'grain' | 'vignette';
+/** Which treatments are on; zero explicitly disables one. Grain is applied first, vignette darkens it. */
+export declare function postFilterStages(post: ScenePostTreatment): PostStage[];
+/** The CSS that routes the composed shot through the filter, or nothing when finishing is off. */
+export declare function postFilterStyle(id: string, post: ScenePostTreatment): React.CSSProperties;
+export interface PostFilterProps {
+    id: string;
+    post: ScenePostTreatment;
+    seed: string;
+    frame: number;
+    /** Output size in px; the vignette is laid out in the element's own pixel space. */
+    size: SceneFrameSize;
+    /** Reference scale (output width / reference width); the grain frequency divides by it. */
+    scale: number;
+}
+/** Grain frequency in cycles per reference pixel; divided by the reference scale at render. */
+export declare const GRAIN_BASE_FREQUENCY = 0.85;
+/** `feTurbulence` base frequency for a shot rendered at `scale`: the grain keeps its reference-pixel size. */
+export declare function grainFrequency(scale: number): number;
+/**
+ * The shot-level finishing filter, applied to the shot's DOM layers — the CSS backdrop and the
+ * screen text — with `filter: url(#id)`. Every stage is an opaque treatment blended over the layer,
+ * and the last primitive cuts the result back to the layer's own alpha with `feComposite in`, so a
+ * transparent backdrop stays transparent and antialiased glyph edges keep their coverage. Only
+ * synchronous primitives are used: nothing here fetches an image, so readiness cannot race the
+ * filter.
+ *
+ * It is NOT applied to the world. The world is a WebGL canvas, and a `filter` over a layer holding
+ * one is what let Chromium rasterize a whole shot once at 756x413 and tile that raster across six
+ * frames of a 390-frame render (defect D4). The world's grain and vignette are the same arithmetic,
+ * run in the focus pass's output stage instead (`focusShaders.ts`), against the same
+ * `grainSeed(seed, frame)` and the same `sceneVignetteFactor`. Both layers here and the world are
+ * finished independently and composited by the browser afterwards, which is exact for the vignette
+ * (a per-pixel scalar multiply distributes over `over`) and exact for the grain wherever the two
+ * colours sit on the same side of the overlay's half.
+ *
+ * The first primitive puts the layer's colour on an opaque carrier. `feBlend` works on
+ * premultiplied colour, so blending an opaque treatment over a partly covered pixel and then
+ * cutting back to that coverage leaves the treatment weighted by the coverage twice over — a dark
+ * fringe on every antialiased glyph edge, and a bright one under a multiply. `feColorMatrix` works
+ * unpremultiplied, so lifting the alpha to one first makes the blends operate on the colour alone
+ * and the closing `feComposite in` restore the coverage exactly once. On an opaque layer it is the
+ * identity, so it changes no pixel of an opaque backdrop.
+ *
+ * Grain: fractal noise seeded from `grainSeed`, greyed, pulled toward mid-grey by `1 - grain`
+ * (overlay with 0.5 is the identity), overlay-blended. Vignette: a white core flooded over the
+ * middle of the frame and blurred outward; its coverage becomes a brightness factor
+ * `1 - vignette × (1 - coverage)`, multiply-blended. The blur and the colour matrix carry the
+ * full frame as an explicit subregion: a primitive with none inherits the union of its inputs'
+ * regions, which for these two is the flood's core rectangle — outside it the factor would be
+ * transparent, the multiply a no-op, and the darkening confined to the middle of the frame (the
+ * defect Stage 0c measured). Both run in sRGB so they read like the CSS
+ * overlays they replace. `feTurbulence` works in output pixels, so its base frequency is divided
+ * by the reference scale to keep the grain the size the author saw; the vignette's core and blur
+ * are proportional to the frame and need no scale. Both are therefore resolution-independent.
+ */
+export declare function PostFilter({ id, post, seed, frame, size, scale }: PostFilterProps): React.JSX.Element | null;

package/dist/_members/animate/scene/finishingMath.d.ts

@@ -0,0 +1,60 @@
+import type { SceneFrameSize } from './scaling.js';
+/**
+ * The arithmetic of the shot's finishing, in one place, because it is now applied twice.
+ *
+ * The backdrop and the screen text are DOM and are finished by the SVG filter in `finishing.tsx`;
+ * the world is WebGL and is finished inside the focus pass's output stage, where no filter can
+ * reach it. Both halves must therefore agree at every pixel, so the geometry that builds the
+ * filter's primitives and the geometry the shader evaluates are the same functions, stated here
+ * once. `finishing.tsx` builds `feFlood`/`feGaussianBlur`/`feColorMatrix` out of these; the
+ * composite shader mirrors `sceneVignetteFactor` and `sceneGrainLevel` line for line.
+ */
+/** The vignette's white core, as a fraction of the frame: the middle 70 %. */
+export declare const VIGNETTE_CORE_INSET = 0.15;
+/** The core's blur, as a fraction of each axis. Proportional, so the vignette is resolution-free. */
+export declare const VIGNETTE_SIGMA = 0.16;
+export interface VignetteGeometry {
+    /** The core rectangle in frame pixels: left, top, right, bottom. */
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+    readonly sigmaX: number;
+    readonly sigmaY: number;
+}
+/** The core rectangle and the blur radii for one frame size, in that frame's own pixels. */
+export declare function vignetteGeometry(size: SceneFrameSize): VignetteGeometry;
+/**
+ * Abramowitz–Stegun 7.1.26; |error| < 1.5e-7, and the same series the shader evaluates.
+ *
+ * `Math.sign`, matching GLSL's `sign`, so that both halves return exactly zero at zero — the series
+ * itself leaves 1.46e-9 there, and zero is where the vignette core's own edge lands.
+ */
+export declare function erf(x: number): number;
+/** A Gaussian-blurred half-plane pair: the blurred coverage of `[a, b]` at `p` with deviation `s`. */
+export declare function blurredCoverage(a: number, b: number, sigma: number, p: number): number;
+/**
+ * The brightness the vignette multiplies a pixel by, at a point in frame pixels (y down).
+ *
+ * The filter floods the core white, blurs it over the whole frame and turns the coverage into
+ * `1 - vignette x (1 - coverage)`; a Gaussian blur of an axis-aligned rectangle is separable and
+ * its coverage is the product of two error-function differences, which is what this evaluates. The
+ * blur is the *ideal* Gaussian: Skia approximates it with box passes, and the two differ by a
+ * measured mean of 0.649 and a worst 2.89 parts in 255 of the factor (worst at the frame centre,
+ * where the factor is near one), so the world's vignette and the backdrop's differ by that
+ * fraction of each pixel's own value — 0.03 of a code on this suite's backdrop.
+ */
+export declare function sceneVignetteFactor(vignette: number, size: SceneFrameSize, x: number, y: number): number;
+/**
+ * The filter's `feComponentTransfer` on the greyed noise: `slope x noise + (1 - slope) / 2`, which
+ * pulls the field toward the mid-grey that makes an overlay blend the identity, so `grain` is the
+ * fraction of the full-strength field that survives.
+ */
+export declare function sceneGrainLevel(grain: number, noise: number): number;
+/**
+ * `feBlend mode="overlay"` for one channel: the CSS compositing definition, `HardLight` with its
+ * arguments swapped. Both branches are affine in the backdrop, which is why applying it to the
+ * world and to the backdrop separately and compositing the two is the same picture as applying it
+ * once to the composed pair — for as long as both are on the same side of the half.
+ */
+export declare function sceneOverlay(backdrop: number, source: number): number;

package/dist/_members/animate/scene/finishingPass.d.ts

@@ -0,0 +1,35 @@
+import { type ScenePostTreatment } from './finishing.js';
+import type { SceneFrameSize } from './scaling.js';
+/**
+ * What the composite shader needs to put one frame's finishing on the world.
+ *
+ * Every field is the filter's own number: the frequency `finishing.tsx` writes into
+ * `feTurbulence`'s `baseFrequency`, the stitch that attribute's `stitchTiles="stitch"` implies for
+ * a tile the size of the frame, the seed `grainSeed` hands the filter, and the core and deviations
+ * `vignetteGeometry` gives `feFlood` and `feGaussianBlur`. Nothing is a shader-side approximation
+ * of an authored value; the two halves are given the same numbers.
+ */
+export interface SceneFinishingUniforms {
+    readonly grain: number;
+    readonly vignette: number;
+    readonly frame: readonly [number, number];
+    /** The `feTurbulence` seed for this frame; the lattice is a function of it alone. */
+    readonly seed: number;
+    readonly grainBase: readonly [number, number];
+    /** Lattice period in x and y, then the wrap point in x and y. */
+    readonly grainStitch: readonly [number, number, number, number];
+    /** The core rectangle: left, top, right, bottom, in frame pixels. */
+    readonly vignetteCore: readonly [number, number, number, number];
+    readonly vignetteSigma: readonly [number, number];
+    /** This seed's lattice packed for the shader, or `null` when grain is off and none is sampled. */
+    readonly lattice: Float32Array | null;
+}
+/**
+ * The finishing of one frame of one shot, in the units the pass works in.
+ *
+ * Grain off and vignette off are spelled as zeros, which is what the shader branches on, so a shot
+ * with no finishing runs the composite it ran before this stage existed. The lattice is rebuilt
+ * per frame because the seed is: `grainSeed(seed, frame)` re-seeds every frame, which is what makes
+ * the grain move, and rebuilding it is two thousand steps of a Lehmer stream.
+ */
+export declare function sceneFinishingUniforms(post: ScenePostTreatment, seed: string, frame: number, size: SceneFrameSize, scale: number): SceneFinishingUniforms;

package/dist/_members/animate/scene/focusBlur.d.ts

@@ -0,0 +1,56 @@
+import type { SceneFocusV2 } from '../../composition/scene/index.js';
+import type { SceneFrameSize } from './scaling.js';
+/**
+ * Taps per side of each separable pass. Seventeen samples across a diameter is enough that the
+ * widest circle of confusion this renderer allows does not band, and it is a compile-time constant
+ * so the loop bound is legal in GLSL ES 1.00 and the cost is the same on every frame.
+ */
+export declare const FOCUS_TAPS = 8;
+/**
+ * The circle of confusion at a camera-space distance, in output pixels.
+ *
+ * The contract's own definition: how far the point is from the focus distance, as a fraction of
+ * the focus range, clamped at one, times the maximum blur. Everything is in world units, which are
+ * output pixels — the same space the blur's radius is measured in, so the scaling that takes a
+ * shot from 1080p to 4K carries the focus with it and needs no second rule.
+ */
+export declare function focusBlurRadius(distance: number, focus: SceneFocusV2): number;
+/** Everything the focus shader needs for one frame, in output pixels and camera-space units. */
+export interface FocusPassUniforms {
+    distance: number;
+    range: number;
+    maxBlur: number;
+    near: number;
+    far: number;
+    texel: [number, number];
+}
+/**
+ * The focus a shot that declares none renders through: a maximum blur of zero.
+ *
+ * `absent focus disables focus` is the contract, and this is that sentence in the units the pass
+ * works in. Zero maximum blur makes every circle of confusion exactly zero (`focusBlurRadius`
+ * multiplies by it), which makes the gather the identity — every tap lands on the centre texel.
+ * The plane and the range are then multiplied by zero and cannot reach the picture; they are one
+ * only because they must be finite and the range must not be zero, and `focusUniforms` scales
+ * them like any other. Nothing here is a stand-in for an authored value: a shot with no
+ * `post.focus` renders through the same pass, with the same resources, differing from a shot that
+ * authors `maxBlur: 0` in nothing at all.
+ */
+export declare const FOCUS_OFF: SceneFocusV2;
+/**
+ * The evaluated focus of one frame in the units the pass works in: reference pixels times the
+ * reference scale for the three focus numbers, the camera's own near/far for reconstructing
+ * camera-space distance from the depth buffer, and the texel size of the frame.
+ *
+ * `null` is a shot with no authored focus, which is `FOCUS_OFF` — the pass runs either way.
+ */
+export declare function focusUniforms(focus: SceneFocusV2 | null, scale: number, camera: {
+    near: number;
+    far: number;
+}, frame: SceneFrameSize): FocusPassUniforms;
+/**
+ * Camera-space distance from a depth-buffer value, the way Three's own
+ * `perspectiveDepthToViewZ` does it, mirrored here so the shader's arithmetic can be checked
+ * without a GPU. Positive in front of the camera.
+ */
+export declare function viewDistanceFromDepth(depth: number, near: number, far: number): number;

package/dist/_members/animate/scene/focusResources.d.ts

@@ -0,0 +1,190 @@
+import { DataTexture, OrthographicCamera, Scene, ShaderMaterial, WebGLRenderTarget } from 'three';
+import type { SceneFinishingUniforms } from './finishingPass.js';
+import { type FocusPassUniforms } from './focusBlur.js';
+import { type SceneActualResourceRegistrarV1 } from './v2/runtimeAllocations.js';
+/** The WebGL extension registry three exposes as `renderer.extensions`; a test supplies a double. */
+export interface FocusRendererExtensions {
+    has(name: string): boolean;
+}
+/** The slice of the WebGL context the pass reads: the sample count of the bound framebuffer. */
+export interface FocusRendererContext {
+    readonly SAMPLES: number;
+    getParameter(name: number): unknown;
+}
+/** The renderer surface the pass drives; a node test supplies a recording double. */
+export interface FocusRenderer {
+    extensions: FocusRendererExtensions;
+    /**
+     * The renderer's tone-mapping constant. Read only to be asserted constant: every lit material in
+     * a scene shot applies this curve ITSELF (`three/toneMapping.ts`), and three bakes the chosen
+     * function into the compiled program on first compile, so a renderer whose curve changed
+     * mid-scene would keep drawing the old one out of the program cache with nothing to say so.
+     */
+    toneMapping: number;
+    getContext(): FocusRendererContext;
+    getRenderTarget(): unknown;
+    setRenderTarget(target: unknown): void;
+    render(scene: unknown, camera: unknown): void;
+}
+/**
+ * The two extensions that make a half-float colour attachment renderable. Either is enough, and
+ * this is the same pair three itself tests before choosing `HalfFloatType` for its own
+ * intermediates (`WebGLRenderer`, three 0.183.2) — asking the question the way the renderer asks it
+ * is what keeps the answer true of the target it will actually allocate.
+ *
+ * The same pair is asked for before capture, on the page-level WebGL2 context, by
+ * `@cueframe/component-runtime`'s `webglProbe.ts` (`HALF_FLOAT_COLOR_TARGET_EXTENSIONS`), which
+ * refuses the browser typed `component_graphics_unavailable` and names the extensions. That is
+ * where a host without them is turned away; this stays as the second gate, for a host whose
+ * page-level answer and whose render-time answer disagree. The list is stated in both places
+ * because neither package can import the other — that one is bundled for the plain-Node script
+ * lane and must stay cheap to bundle, and this one is not among its dependencies — so neither copy
+ * may change alone.
+ */
+export declare const HALF_FLOAT_TARGET_EXTENSIONS: readonly ["EXT_color_buffer_half_float", "EXT_color_buffer_float"];
+/**
+ * What a refusal from this pass is about.
+ *
+ * `post`, not `post.focus`: every scene shot's world is composed through this pass, whether or not
+ * the shot authors focus, so a host that cannot allocate its targets refuses the shot's whole
+ * finishing section rather than an optional key the author may never have written.
+ */
+export declare const FOCUS_SPEC_PATH = "post";
+/**
+ * Refuse a host that cannot render into half-float colour.
+ *
+ * The pass round-trips the whole frame through its intermediates, so their precision is the
+ * precision of every scene shot, in focus or not. Eight-bit linear is not a near-enough substitute:
+ * stored as `round(L * 255)` it collapses sRGB codes 16-24 onto one or two levels, which is exactly
+ * where a dark product-UI gradient lives. Dropping to it silently would put a quietly posterized
+ * frame in front of an author who never learned the host could not give it — the substitution the
+ * spec's admission rules forbid. So this is a refusal, not a fallback.
+ */
+export declare function assertHalfFloatColorTargets(gl: FocusRenderer, path: string): void;
+/**
+ * The multisample count of the surface this pass replaces.
+ *
+ * The world used to be drawn straight onto the canvas, whose framebuffer fiber creates with
+ * `antialias: true`; now it is drawn into this pass's target, and a target allocated at one sample
+ * would hand every scene shot a hard-edged silhouette where it had a resolved one. So the target
+ * is allocated at the canvas's own count, read from the canvas's own framebuffer.
+ *
+ * `SAMPLES` is a property of whatever framebuffer is bound, so this is only the canvas's count
+ * while the canvas is bound. It is read once, during the pass's construction, which happens while
+ * the component renders and before any frame callback has bound anything — and the binding is
+ * checked rather than assumed, because a wrong answer here is not an error anywhere, only a frame
+ * that is quietly rougher or costlier than the one before it.
+ */
+export declare function canvasSampleCount(gl: FocusRenderer, path: string): number;
+/**
+ * One shot instance's world resources: two colour targets, the depth the world was drawn with, the
+ * two full-screen materials and the private quad they are drawn on.
+ *
+ * Owned per instance, never shared: two shots on screen at once each render their own world into
+ * their own targets, so neither can read the other's depth or half-blurred colour. Only the
+ * immutable shader source is common to them.
+ *
+ * The colour targets are half-float in the working (linear) colour space, which is what Three
+ * writes when a render target is bound; the composite pass is the one place the frame is encoded
+ * for output. Linear is the reason the precision matters: an 8-bit linear intermediate spends most
+ * of its codes above mid-grey and leaves the dark end of a colour-managed screenshot with almost
+ * none, so the round trip alone would band the gradients the shot exists to show. The host is
+ * asked for the capability once, here, and refused if it has not got it.
+ *
+ * The world target carries the canvas's own multisample count (`canvasSampleCount`), because it
+ * stands in for the canvas: every scene shot's geometry is rasterized here, and three resolves the
+ * colour and the depth into the attached textures when the target is unbound. `gathered` is
+ * written by a full-screen quad with no edges in it, so it is allocated single-sampled.
+ */
+export declare class FocusResources {
+    private readonly registerActual;
+    /**
+     * The renderer these resources were built for and measured against.
+     *
+     * Kept so the pass can check it is still being driven by that renderer. The targets, their
+     * textures and their framebuffers belong to one GL context, and `samples` was read from that
+     * context's canvas; handing them to a different renderer would draw through objects it has never
+     * uploaded. Fiber builds one renderer per canvas and never swaps it, so this is a guard against a
+     * future change rather than a case anyone can reach today — but the symptom would be a blank or
+     * wrong frame with no error, which is exactly the kind of thing that has to be asserted.
+     */
+    readonly renderer: FocusRenderer;
+    readonly world: WebGLRenderTarget;
+    readonly gathered: WebGLRenderTarget;
+    readonly blur: ShaderMaterial;
+    readonly composite: ShaderMaterial;
+    readonly quadScene: Scene;
+    readonly quadCamera: OrthographicCamera;
+    /** The canvas's multisample count, read once at construction and kept across resizes. */
+    readonly samples: number;
+    /**
+     * The renderer's tone-mapping curve when these resources were built.
+     *
+     * Kept for the same reason `renderer` is, and checked the same way. Every lit material this
+     * package draws carries its own copy of the curve, injected by `onBeforeCompile` from
+     * `renderer.toneMapping` — and three calls that ONCE PER PROGRAM, then serves the compiled
+     * program out of its cache. `customProgramCacheKey` cannot repair that: three computes the cache
+     * key before the material has ever seen a renderer, so the key could only ever carry the curve
+     * of a PREVIOUS compile, and a genuine change would still hit the stale program. So the curve is
+     * asserted constant instead of keyed — which is the truth of this renderer anyway, since fiber
+     * sets it from `flat` at canvas construction and nothing in this package writes it afterwards.
+     */
+    readonly toneMapping: number;
+    /**
+     * One frame's grain lattice, as a float texture the composite samples.
+     *
+     * Owned per instance like everything else here, and refreshed only when the frame's seed changes
+     * — which is every frame a shot with grain renders, since `grainSeed` re-seeds per frame, and
+     * never for a shot without it.
+     */
+    readonly grainLattice: DataTexture;
+    private grainLatticeSeed;
+    private readonly geometry;
+    private readonly mesh;
+    private releaseMeasurement;
+    constructor(gl: FocusRenderer, width: number, height: number, registerActual?: SceneActualResourceRegistrarV1);
+    get size(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Follow the frame. `WebGLRenderTarget.setSize` resizes its colour textures but not the depth
+     * texture attached to it, which would leave the depth attachment at the old size and the
+     * framebuffer incomplete — so the depth texture is resized here and dropped, and Three rebuilds
+     * both from the new sizes on the next draw.
+     */
+    resize(width: number, height: number): void;
+    /** Point the quad at one of the two materials; the pass draws the same geometry twice. */
+    use(material: ShaderMaterial): void;
+    /** Write one frame's focus into both materials. Uniform writes only: no program is rebuilt. */
+    apply(uniforms: FocusPassUniforms): void;
+    /**
+     * Write one frame's finishing into the composite material.
+     *
+     * Uniform writes and, when the seed moved, one 25 KB texture upload; no program is rebuilt. The
+     * lattice is skipped when grain is off, because nothing samples it then.
+     */
+    applyFinishing(finishing: SceneFinishingUniforms): void;
+    dispose(): void;
+}
+/**
+ * Draw one frame of the world, in place of the renderer's ordinary draw.
+ *
+ * The world is drawn once, into a colour target with the depth it was drawn with; the gather runs
+ * horizontally into the second target and then vertically into whatever target was bound when the
+ * pass began — the frame, ordinarily. Screen text never enters this: it is DOM above the canvas,
+ * so it cannot be softened by the pass, which is what the contract requires of it.
+ *
+ * This is the only way a scene shot's world reaches the frame. A shot with focus and a shot
+ * without run exactly these three draws with exactly these targets; the authored focus reaches the
+ * picture through `uniforms` alone, and a maximum blur of zero makes the two gathers the identity.
+ * That is what makes `post.focus` a blur and only a blur: the alternative — the world straight onto
+ * the canvas when no focus is authored — composites in a different space (clamped 8-bit sRGB with
+ * the renderer's tone curve, resolved by the canvas's own multisample) and so changed the colour
+ * of in-focus pixels the moment focus was turned on.
+ *
+ * The third draw also finishes the world: the shot's grain and vignette are the composite's last
+ * stage, because the world cannot be routed through the SVG filter that finishes the shot's DOM
+ * layers without putting the WebGL canvas inside a filtered layer — which is what defect D4 was.
+ */
+export declare function renderFocusPass(gl: FocusRenderer, scene: unknown, camera: unknown, resources: FocusResources, uniforms: FocusPassUniforms, finishing: SceneFinishingUniforms): void;

package/dist/_members/animate/scene/focusShaders.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The GLSL for the depth-aware focus pass, kept in one small module so the two materials share one
+ * gather and the node tests can assert what the pass declares without a GPU.
+ *
+ * There is no shader package here and none is needed: two `ShaderMaterial` full-screen quads.
+ */
+/** A full-screen quad in clip space; the geometry is already `[-1,1]`, so no matrices are needed. */
+export declare const FOCUS_VERTEX_SHADER = "\nvarying vec2 vUv;\nvoid main() {\n  vUv = uv;\n  gl_Position = vec4(position.xy, 0.0, 1.0);\n}\n";
+/**
+ * The shared half of both fragment shaders: reconstruct camera-space distance from the depth
+ * buffer, turn it into a circle of confusion, and gather along one axis.
+ *
+ * Depth-aware in both directions. The gather reaches out to the centre pixel's own circle of
+ * confusion, so an out-of-focus surface is softened by exactly its own radius and an in-focus one
+ * is left alone — at radius zero every tap lands on the centre pixel and the result is the centre
+ * pixel. A tap NEARER than the centre contributes only if its own circle of confusion reaches the
+ * centre, which is what keeps a sharp foreground from smearing across a blurred background; a tap
+ * at or beyond the centre's depth is inside the centre's own circle by construction and always
+ * contributes.
+ *
+ * The known limit of a two-pass gather: a blurred foreground softens inside its silhouette but
+ * does not spill past it onto an in-focus background, because nothing outside the centre's own
+ * radius is ever sampled. A scattering pass is the fix if a fixture ever needs that spill.
+ *
+ * Alpha: the colour target holds premultiplied RGBA — Three's normal blending accumulates
+ * `src.rgb * src.a` and `src.a` into a target cleared to zero — and a weighted average of
+ * premultiplied samples is itself premultiplied. Blurring here therefore cannot pull colour out of
+ * a transparent texel, which is exactly the dark fringe a straight-alpha blur would produce around
+ * a shot with a transparent backdrop.
+ */
+export declare const FOCUS_GATHER_CHUNK = "\nuniform sampler2D tColor;\nuniform sampler2D tDepth;\nuniform vec2 uTexel;\nuniform vec2 uDirection;\nuniform float uNear;\nuniform float uFar;\nuniform float uFocusDistance;\nuniform float uFocusRange;\nuniform float uMaxBlur;\nvarying vec2 vUv;\n\nfloat focusViewDistance(vec2 uv) {\n  float depth = texture2D(tDepth, uv).x;\n  return -((uNear * uFar) / ((uFar - uNear) * depth - uFar));\n}\n\nfloat focusCircleOfConfusion(float distance) {\n  return min(1.0, abs(distance - uFocusDistance) / uFocusRange) * uMaxBlur;\n}\n\nvoid focusTap(vec2 offset, float radius, float weight, float centreDistance, inout vec4 sum, inout float total) {\n  vec2 uv = vUv + offset;\n  float tapDistance = focusViewDistance(uv);\n  float allow = tapDistance < centreDistance ? step(radius, focusCircleOfConfusion(tapDistance)) : 1.0;\n  float w = weight * allow;\n  sum += texture2D(tColor, uv) * w;\n  total += w;\n}\n\nvec4 focusGather() {\n  float centreDistance = focusViewDistance(vUv);\n  float centreRadius = focusCircleOfConfusion(centreDistance);\n  vec4 sum = texture2D(tColor, vUv);\n  float total = 1.0;\n  for (int i = 1; i <= FOCUS_TAPS; i++) {\n    float t = float(i) / float(FOCUS_TAPS);\n    float weight = exp(-2.0 * t * t);\n    float radius = t * centreRadius;\n    vec2 offset = uDirection * uTexel * radius;\n    focusTap(offset, radius, weight, centreDistance, sum, total);\n    focusTap(-offset, radius, weight, centreDistance, sum, total);\n  }\n  return sum / total;\n}\n";
+/** The first pass: gather along one axis, target to target, both in the working colour space. */
+export declare const FOCUS_BLUR_FRAGMENT_SHADER = "\nuniform sampler2D tColor;\nuniform sampler2D tDepth;\nuniform vec2 uTexel;\nuniform vec2 uDirection;\nuniform float uNear;\nuniform float uFar;\nuniform float uFocusDistance;\nuniform float uFocusRange;\nuniform float uMaxBlur;\nvarying vec2 vUv;\n\nfloat focusViewDistance(vec2 uv) {\n  float depth = texture2D(tDepth, uv).x;\n  return -((uNear * uFar) / ((uFar - uNear) * depth - uFar));\n}\n\nfloat focusCircleOfConfusion(float distance) {\n  return min(1.0, abs(distance - uFocusDistance) / uFocusRange) * uMaxBlur;\n}\n\nvoid focusTap(vec2 offset, float radius, float weight, float centreDistance, inout vec4 sum, inout float total) {\n  vec2 uv = vUv + offset;\n  float tapDistance = focusViewDistance(uv);\n  float allow = tapDistance < centreDistance ? step(radius, focusCircleOfConfusion(tapDistance)) : 1.0;\n  float w = weight * allow;\n  sum += texture2D(tColor, uv) * w;\n  total += w;\n}\n\nvec4 focusGather() {\n  float centreDistance = focusViewDistance(vUv);\n  float centreRadius = focusCircleOfConfusion(centreDistance);\n  vec4 sum = texture2D(tColor, vUv);\n  float total = 1.0;\n  for (int i = 1; i <= FOCUS_TAPS; i++) {\n    float t = float(i) / float(FOCUS_TAPS);\n    float weight = exp(-2.0 * t * t);\n    float radius = t * centreRadius;\n    vec2 offset = uDirection * uTexel * radius;\n    focusTap(offset, radius, weight, centreDistance, sum, total);\n    focusTap(-offset, radius, weight, centreDistance, sum, total);\n  }\n  return sum / total;\n}\n\nvoid main() {\n  gl_FragColor = focusGather();\n}\n";
+/**
+ * The shot's finishing, for the world only: the same grain and the same vignette the SVG filter
+ * puts on the DOM layers (`finishing.tsx`), evaluated per pixel here because a `filter` over a
+ * layer holding a WebGL canvas is what let Chromium tile one raster of a shot across six frames
+ * (defect D4). Nothing about the treatment changes; only who applies it to the world.
+ *
+ * Everything is in the frame's own pixels with y down, so the two halves are laid out in one
+ * coordinate system. The grain is `grainNoise.ts`'s port of the `feTurbulence` generator, seeded by
+ * the same `grainSeed(seed, frame)` integer, greyed and levelled exactly as the filter's
+ * `feColorMatrix`/`feComponentTransfer` pair does, then overlay-blended; the vignette is
+ * `finishingMath.ts`'s Gaussian coverage of the same flooded core, multiplied in. The lattice for
+ * one frame's seed arrives as a float texture rather than a uniform array: 514 selectors and three
+ * channels of gradients do not fit in a fragment shader's uniform budget on every host.
+ *
+ * The stage runs on the ENCODED colour, after `colorspace_fragment`, because that is the space the
+ * filter runs in (`color-interpolation-filters="sRGB"`), and on the colour alone rather than the
+ * colour times its coverage, because the filter's closing `feComposite in` restores coverage after
+ * the treatment. It clamps first for the same reason: the filter's source is an 8-bit layer.
+ */
+export declare const FOCUS_FINISHING_CHUNK = "\nuniform float uGrain;\nuniform float uVignette;\nuniform vec2 uFrameSize;\n/** The stitched base frequency, per axis: cycles per output pixel. */\nuniform vec2 uGrainBase;\n/** The stitch: lattice period in x and y, then the wrap point in x and y. */\nuniform vec4 uGrainStitch;\n/** The vignette core rectangle: left, top, right, bottom, in frame pixels. */\nuniform vec4 uVignetteCore;\nuniform vec2 uVignetteSigma;\nuniform sampler2D tGrainLattice;\n\nconst float SCENE_SQRT2 = 1.4142135623730951;\n\n/** Abramowitz\u2013Stegun 7.1.26, the series finishingMath.ts evaluates, sign and all. */\nfloat sceneErf(float x) {\n  float s = sign(x);\n  float a = abs(x);\n  float t = 1.0 / (1.0 + 0.3275911 * a);\n  float y = 1.0 - (((((1.061405429 * t - 1.453152027) * t) + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * exp(-a * a);\n  return s * y;\n}\n\nfloat sceneBlurredCoverage(float a, float b, float sigma, float p) {\n  return 0.5 * (sceneErf((b - p) / (sigma * SCENE_SQRT2)) - sceneErf((a - p) / (sigma * SCENE_SQRT2)));\n}\n\nfloat sceneVignetteFactor(vec2 point) {\n  float coverage = sceneBlurredCoverage(uVignetteCore.x, uVignetteCore.z, uVignetteSigma.x, point.x)\n                 * sceneBlurredCoverage(uVignetteCore.y, uVignetteCore.w, uVignetteSigma.y, point.y);\n  return uVignette * coverage + (1.0 - uVignette);\n}\n\nfloat sceneGrainSelector(float index) {\n  return texture2D(tGrainLattice, vec2((index + 0.5) / float(GRAIN_TABLE_WIDTH), 0.5 / float(GRAIN_TABLE_HEIGHT))).r;\n}\n\n/** One lattice corner's gradient dotted with (rx, ry), for the three channels the grey averages. */\nvec3 sceneGrainCorner(float index, float rx, float ry) {\n  vec4 ab = texture2D(tGrainLattice, vec2((index + 0.5) / float(GRAIN_TABLE_WIDTH), 1.5 / float(GRAIN_TABLE_HEIGHT)));\n  vec2 c = texture2D(tGrainLattice, vec2((index + 0.5) / float(GRAIN_TABLE_WIDTH), 2.5 / float(GRAIN_TABLE_HEIGHT))).rg;\n  return vec3(rx * ab.x + ry * ab.y, rx * ab.z + ry * ab.w, rx * c.x + ry * c.y);\n}\n\n/** The spec's noise2 for three channels at once, with the stitch wrap already folded. */\nvec3 sceneGrainNoise(vec2 v, vec4 stitch) {\n  float bx0 = floor(v.x), bx1 = bx0 + 1.0;\n  float rx0 = v.x - bx0, rx1 = rx0 - 1.0;\n  float by0 = floor(v.y), by1 = by0 + 1.0;\n  float ry0 = v.y - by0, ry1 = ry0 - 1.0;\n  if (bx0 >= stitch.z) bx0 -= stitch.x;\n  if (bx1 >= stitch.z) bx1 -= stitch.x;\n  if (by0 >= stitch.w) by0 -= stitch.y;\n  if (by1 >= stitch.w) by1 -= stitch.y;\n  bx0 = mod(bx0, float(GRAIN_LATTICE));\n  bx1 = mod(bx1, float(GRAIN_LATTICE));\n  by0 = mod(by0, float(GRAIN_LATTICE));\n  by1 = mod(by1, float(GRAIN_LATTICE));\n  float i = sceneGrainSelector(bx0);\n  float j = sceneGrainSelector(bx1);\n  float sx = rx0 * rx0 * (3.0 - 2.0 * rx0);\n  float sy = ry0 * ry0 * (3.0 - 2.0 * ry0);\n  vec3 a = mix(sceneGrainCorner(sceneGrainSelector(i + by0), rx0, ry0), sceneGrainCorner(sceneGrainSelector(j + by0), rx1, ry0), sx);\n  vec3 b = mix(sceneGrainCorner(sceneGrainSelector(i + by1), rx0, ry1), sceneGrainCorner(sceneGrainSelector(j + by1), rx1, ry1), sx);\n  return mix(a, b, sy);\n}\n\n/** type=\"fractalNoise\" over two octaves, greyed by the filter's own 0.3333 coefficient. */\nfloat sceneGrainField(vec2 point) {\n  vec2 v = point * uGrainBase;\n  vec4 stitch = uGrainStitch;\n  vec3 sum = vec3(0.0);\n  float ratio = 1.0;\n  for (int octave = 0; octave < GRAIN_OCTAVES; octave++) {\n    sum += sceneGrainNoise(v, stitch) / ratio;\n    v *= 2.0;\n    ratio *= 2.0;\n    stitch *= 2.0;\n  }\n  vec3 fractal = (sum + 1.0) * 0.5;\n  return clamp((fractal.x + fractal.y + fractal.z) * GRAIN_GREY_COEFFICIENT, 0.0, 1.0);\n}\n\n/** feBlend mode=\"overlay\": the CSS blend formula, switching on the backdrop. */\nvec3 sceneOverlay(vec3 backdrop, float source) {\n  vec3 lo = 2.0 * backdrop * source;\n  vec3 hi = 1.0 - 2.0 * (1.0 - backdrop) * (1.0 - source);\n  return mix(hi, lo, step(backdrop, vec3(0.5)));\n}\n\nvec3 sceneFinishing(vec3 color) {\n  if (uGrain <= 0.0 && uVignette <= 0.0) return color;\n  // The pixel's top-left corner in the frame's own pixels, y down: the space both halves share.\n  vec2 pixel = vec2(gl_FragCoord.x - 0.5, uFrameSize.y - gl_FragCoord.y - 0.5);\n  vec3 finished = clamp(color, 0.0, 1.0);\n  if (uGrain > 0.0) {\n    float level = uGrain * sceneGrainField(pixel + float(GRAIN_SAMPLE_OFFSET)) + (1.0 - uGrain) * 0.5;\n    finished = sceneOverlay(finished, level);\n  }\n  if (uVignette > 0.0) {\n    finished *= sceneVignetteFactor(pixel + 0.5);\n  }\n  return finished;\n}\n";
+/**
+ * The second pass: gather along the other axis, finish the world, and write the frame.
+ *
+ * The colour arrives premultiplied and linear and has to leave premultiplied and encoded, and the
+ * transfer function belongs on the colour, not on the colour times its coverage — so the alpha is
+ * divided out, `colorspace_fragment` encodes into the renderer's output colour space, the shot's
+ * grain and vignette are applied to that encoded colour, and the coverage is put back. The canvas
+ * is a premultiplied surface, so that is what it wants; a transparent shot keeps the coverage it
+ * had, with no colour pulled toward black at its edges and none acquired from the finishing.
+ *
+ * Finishing last and coverage after it is the same order the filter states: treat, then
+ * `feComposite in` back to the source's own alpha. With both treatments off, `sceneFinishing`
+ * returns before it touches the colour and this is the pass it was before.
+ */
+export declare const FOCUS_COMPOSITE_FRAGMENT_SHADER = "\nuniform sampler2D tColor;\nuniform sampler2D tDepth;\nuniform vec2 uTexel;\nuniform vec2 uDirection;\nuniform float uNear;\nuniform float uFar;\nuniform float uFocusDistance;\nuniform float uFocusRange;\nuniform float uMaxBlur;\nvarying vec2 vUv;\n\nfloat focusViewDistance(vec2 uv) {\n  float depth = texture2D(tDepth, uv).x;\n  return -((uNear * uFar) / ((uFar - uNear) * depth - uFar));\n}\n\nfloat focusCircleOfConfusion(float distance) {\n  return min(1.0, abs(distance - uFocusDistance) / uFocusRange) * uMaxBlur;\n}\n\nvoid focusTap(vec2 offset, float radius, float weight, float centreDistance, inout vec4 sum, inout float total) {\n  vec2 uv = vUv + offset;\n  float tapDistance = focusViewDistance(uv);\n  float allow = tapDistance < centreDistance ? step(radius, focusCircleOfConfusion(tapDistance)) : 1.0;\n  float w = weight * allow;\n  sum += texture2D(tColor, uv) * w;\n  total += w;\n}\n\nvec4 focusGather() {\n  float centreDistance = focusViewDistance(vUv);\n  float centreRadius = focusCircleOfConfusion(centreDistance);\n  vec4 sum = texture2D(tColor, vUv);\n  float total = 1.0;\n  for (int i = 1; i <= FOCUS_TAPS; i++) {\n    float t = float(i) / float(FOCUS_TAPS);\n    float weight = exp(-2.0 * t * t);\n    float radius = t * centreRadius;\n    vec2 offset = uDirection * uTexel * radius;\n    focusTap(offset, radius, weight, centreDistance, sum, total);\n    focusTap(-offset, radius, weight, centreDistance, sum, total);\n  }\n  return sum / total;\n}\n\n\nuniform float uGrain;\nuniform float uVignette;\nuniform vec2 uFrameSize;\n/** The stitched base frequency, per axis: cycles per output pixel. */\nuniform vec2 uGrainBase;\n/** The stitch: lattice period in x and y, then the wrap point in x and y. */\nuniform vec4 uGrainStitch;\n/** The vignette core rectangle: left, top, right, bottom, in frame pixels. */\nuniform vec4 uVignetteCore;\nuniform vec2 uVignetteSigma;\nuniform sampler2D tGrainLattice;\n\nconst float SCENE_SQRT2 = 1.4142135623730951;\n\n/** Abramowitz\u2013Stegun 7.1.26, the series finishingMath.ts evaluates, sign and all. */\nfloat sceneErf(float x) {\n  float s = sign(x);\n  float a = abs(x);\n  float t = 1.0 / (1.0 + 0.3275911 * a);\n  float y = 1.0 - (((((1.061405429 * t - 1.453152027) * t) + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * exp(-a * a);\n  return s * y;\n}\n\nfloat sceneBlurredCoverage(float a, float b, float sigma, float p) {\n  return 0.5 * (sceneErf((b - p) / (sigma * SCENE_SQRT2)) - sceneErf((a - p) / (sigma * SCENE_SQRT2)));\n}\n\nfloat sceneVignetteFactor(vec2 point) {\n  float coverage = sceneBlurredCoverage(uVignetteCore.x, uVignetteCore.z, uVignetteSigma.x, point.x)\n                 * sceneBlurredCoverage(uVignetteCore.y, uVignetteCore.w, uVignetteSigma.y, point.y);\n  return uVignette * coverage + (1.0 - uVignette);\n}\n\nfloat sceneGrainSelector(float index) {\n  return texture2D(tGrainLattice, vec2((index + 0.5) / float(GRAIN_TABLE_WIDTH), 0.5 / float(GRAIN_TABLE_HEIGHT))).r;\n}\n\n/** One lattice corner's gradient dotted with (rx, ry), for the three channels the grey averages. */\nvec3 sceneGrainCorner(float index, float rx, float ry) {\n  vec4 ab = texture2D(tGrainLattice, vec2((index + 0.5) / float(GRAIN_TABLE_WIDTH), 1.5 / float(GRAIN_TABLE_HEIGHT)));\n  vec2 c = texture2D(tGrainLattice, vec2((index + 0.5) / float(GRAIN_TABLE_WIDTH), 2.5 / float(GRAIN_TABLE_HEIGHT))).rg;\n  return vec3(rx * ab.x + ry * ab.y, rx * ab.z + ry * ab.w, rx * c.x + ry * c.y);\n}\n\n/** The spec's noise2 for three channels at once, with the stitch wrap already folded. */\nvec3 sceneGrainNoise(vec2 v, vec4 stitch) {\n  float bx0 = floor(v.x), bx1 = bx0 + 1.0;\n  float rx0 = v.x - bx0, rx1 = rx0 - 1.0;\n  float by0 = floor(v.y), by1 = by0 + 1.0;\n  float ry0 = v.y - by0, ry1 = ry0 - 1.0;\n  if (bx0 >= stitch.z) bx0 -= stitch.x;\n  if (bx1 >= stitch.z) bx1 -= stitch.x;\n  if (by0 >= stitch.w) by0 -= stitch.y;\n  if (by1 >= stitch.w) by1 -= stitch.y;\n  bx0 = mod(bx0, float(GRAIN_LATTICE));\n  bx1 = mod(bx1, float(GRAIN_LATTICE));\n  by0 = mod(by0, float(GRAIN_LATTICE));\n  by1 = mod(by1, float(GRAIN_LATTICE));\n  float i = sceneGrainSelector(bx0);\n  float j = sceneGrainSelector(bx1);\n  float sx = rx0 * rx0 * (3.0 - 2.0 * rx0);\n  float sy = ry0 * ry0 * (3.0 - 2.0 * ry0);\n  vec3 a = mix(sceneGrainCorner(sceneGrainSelector(i + by0), rx0, ry0), sceneGrainCorner(sceneGrainSelector(j + by0), rx1, ry0), sx);\n  vec3 b = mix(sceneGrainCorner(sceneGrainSelector(i + by1), rx0, ry1), sceneGrainCorner(sceneGrainSelector(j + by1), rx1, ry1), sx);\n  return mix(a, b, sy);\n}\n\n/** type=\"fractalNoise\" over two octaves, greyed by the filter's own 0.3333 coefficient. */\nfloat sceneGrainField(vec2 point) {\n  vec2 v = point * uGrainBase;\n  vec4 stitch = uGrainStitch;\n  vec3 sum = vec3(0.0);\n  float ratio = 1.0;\n  for (int octave = 0; octave < GRAIN_OCTAVES; octave++) {\n    sum += sceneGrainNoise(v, stitch) / ratio;\n    v *= 2.0;\n    ratio *= 2.0;\n    stitch *= 2.0;\n  }\n  vec3 fractal = (sum + 1.0) * 0.5;\n  return clamp((fractal.x + fractal.y + fractal.z) * GRAIN_GREY_COEFFICIENT, 0.0, 1.0);\n}\n\n/** feBlend mode=\"overlay\": the CSS blend formula, switching on the backdrop. */\nvec3 sceneOverlay(vec3 backdrop, float source) {\n  vec3 lo = 2.0 * backdrop * source;\n  vec3 hi = 1.0 - 2.0 * (1.0 - backdrop) * (1.0 - source);\n  return mix(hi, lo, step(backdrop, vec3(0.5)));\n}\n\nvec3 sceneFinishing(vec3 color) {\n  if (uGrain <= 0.0 && uVignette <= 0.0) return color;\n  // The pixel's top-left corner in the frame's own pixels, y down: the space both halves share.\n  vec2 pixel = vec2(gl_FragCoord.x - 0.5, uFrameSize.y - gl_FragCoord.y - 0.5);\n  vec3 finished = clamp(color, 0.0, 1.0);\n  if (uGrain > 0.0) {\n    float level = uGrain * sceneGrainField(pixel + float(GRAIN_SAMPLE_OFFSET)) + (1.0 - uGrain) * 0.5;\n    finished = sceneOverlay(finished, level);\n  }\n  if (uVignette > 0.0) {\n    finished *= sceneVignetteFactor(pixel + 0.5);\n  }\n  return finished;\n}\n\nvoid main() {\n  vec4 gathered = focusGather();\n  float coverage = gathered.a;\n  gl_FragColor = vec4(coverage > 0.0 ? gathered.rgb / coverage : gathered.rgb, coverage);\n  #include <colorspace_fragment>\n  gl_FragColor.rgb = sceneFinishing(gl_FragColor.rgb);\n  gl_FragColor.rgb *= coverage;\n}\n";

package/dist/_members/animate/scene/fontReadiness.d.ts

@@ -0,0 +1,27 @@
+/** The subset of `document.fonts` this renderer uses; a test supplies a double. */
+export interface FontSource {
+    load(font: string, text?: string): Promise<unknown>;
+    check(font: string, text?: string): boolean;
+    ready: Promise<unknown>;
+}
+/** `document.fonts`, or null where there is no document (server rendering, node tests). */
+export declare function documentFonts(): FontSource | null;
+/**
+ * Resolve once the face named by a CSS `font` shorthand can be drawn with.
+ *
+ * Deterministic and event-driven: `load` for the exact face and sample text, then the source's own
+ * `ready`, which settles when nothing is still loading. No timer and no polling — a timeout would
+ * make the frame's content depend on how fast the machine was.
+ *
+ * A rejected load is the author's problem and is reported as one: a face the shot names but the
+ * runtime cannot produce would otherwise be silently replaced by a fallback and captured. So is a
+ * host with no font source at all: the raster would then be drawn with whatever face the canvas
+ * happened to fall back to, which is the same silent substitution arriving by a different route.
+ * The world-text path only runs where a canvas is mounted, so a null source means the host is not
+ * one this renderer can draw text on, not that the check may be skipped.
+ *
+ * Note the limit: `check` returns true for a family with no registered face (the browser treats it
+ * as a system font), so this cannot by itself prove the authored face is the one that drew. Sealing
+ * the font set is the preparation stage's job; this is the render-time gate.
+ */
+export declare function whenFontReady(fonts: FontSource | null, shorthand: string, sample: string, path: string): Promise<void>;