@cueframe/kernel 0.2.2 → 0.2.4

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

@@ -0,0 +1,118 @@
+/**
+ * The grain field: the SVG `feTurbulence` generator, in TypeScript.
+ *
+ * The shot's finishing puts grain on three layers that must agree — the CSS backdrop and the DOM
+ * screen text, which go through the real `feTurbulence` in `finishing.tsx`, and the world, which is
+ * WebGL and cannot reach an SVG filter. So the world runs the same generator: this module is the
+ * SVG 1.1 reference implementation of `feTurbulence` (the Park–Miller stream, the 256-entry
+ * gradient lattice, the shuffle, the fractal sum), seeded by the same `grainSeed(seed, frame)`
+ * integer the filter is given. `grainLatticeTable` packs one seed's lattice for the shader, which
+ * evaluates `grainTurbulence`'s arithmetic per pixel; `grainTurbulence` itself is the reference the
+ * shader mirrors and the thing the tests pin.
+ *
+ * Measured against Chromium's own `feTurbulence` (a 240x160 element, `baseFrequency` 0.85, two
+ * octaves, `stitchTiles="stitch"`, greyed by the same `feColorMatrix`, screenshotted and compared
+ * code for code): mean absolute difference **0.38 of 255**, worst 3, 63 % of pixels exact,
+ * correlation **0.99929**. The residue is Skia's 8-bit rounding of an intermediate, not a different
+ * field.
+ */
+/** Lattice size; the spec's `BSize`. Indices wrap at 256, which is why `BM` is a mask of 255. */
+export declare const GRAIN_LATTICE = 256;
+/** The spec's `PerlinN`: a large multiple of `BSize` added so negative coordinates still mask. */
+export declare const GRAIN_PERLIN_N = 4096;
+/** The four noise channels the generator produces; the filter greys the first three. */
+export declare const GRAIN_CHANNELS = 4;
+/** Octaves in the fractal sum; the filter's `numOctaves`. */
+export declare const GRAIN_OCTAVES = 2;
+/** The channels the grey matrix averages: R, G and B. */
+export declare const GRAIN_GREY_CHANNELS = 3;
+/** The grey matrix's own coefficient, spelled as the filter spells it, not as a third. */
+export declare const GRAIN_GREY_COEFFICIENT = 0.3333;
+/**
+ * Where in a pixel the browser samples the field.
+ *
+ * Measured, not assumed: correlating this implementation against Chromium's rendered
+ * `feTurbulence` over a 240x160 element at `baseFrequency` 0.85 puts the maximum at exactly
+ * `(x + 1, y + 1)` for the pixel whose top-left corner is `(x, y)` — 0.99913 there against 0.1772
+ * at the pixel centre and -0.1294 at the corner, and the same answer with the element moved to
+ * (37, 23), so it is a property of the generator and not of where the layer sits. One pixel of
+ * base-frequency-0.85 noise is more than a whole lattice cell, so a sample point taken on faith
+ * would have decorrelated the world's grain from the backdrop's completely.
+ */
+export declare const GRAIN_SAMPLE_OFFSET = 1;
+/**
+ * The spec's `setup_seed`: fold the seed into `[1, 2^31 - 2]` without ever returning zero.
+ *
+ * Through a 32-bit float first, because that is where the browser's copy of the seed has been.
+ * `feTurbulence`'s `seed` is an SVG `<number>`, which Blink parses into a float and Skia rounds
+ * back to an int, so a seed above 2^24 is not the seed the filter actually runs with:
+ * `grainSeed('scene-shot:shot-a', 7)` is 831 820 165 and the filter's is 831 820 160. Measured, the
+ * difference is the whole field — correlation **-0.007** against Chromium's rendered noise without
+ * this line and **0.99929** with it. `grainSeed` returns values across the whole Lehmer range, so
+ * most frames of most shots land above 2^24 and would otherwise have grained the world from a
+ * lattice no other layer of the shot was using.
+ */
+export declare function grainSetupSeed(seed: number): number;
+/** One step of the Park–Miller stream the lattice is built from: `r = 16807 r mod (2^31 - 1)`. */
+export declare function grainNextRandom(seed: number): number;
+export interface GrainLattice {
+    /** `BSize + BSize + 2` selectors; the tail duplicates the head so `i + by` never runs off. */
+    readonly selector: Int32Array;
+    /** Per channel, `(BSize + BSize + 2) * 2` unit gradient components. */
+    readonly gradient: readonly Float64Array[];
+}
+/**
+ * The spec's `init`: four channels of unit gradients drawn from the stream in channel-major order,
+ * then a 255-swap shuffle of the selector, then the two-entry-plus-block duplication that lets
+ * `noise2` index `selector[i] + by` without a second mask.
+ */
+export declare function grainLattice(seed: number): GrainLattice;
+/**
+ * The stitch state for one tile, in the form the shader uses.
+ *
+ * `stitchTiles="stitch"` moves the base frequency to the nearer frequency that fits a whole number
+ * of periods across the tile, and then wraps the lattice at that period, so the field is continuous
+ * across the tile's edges. The spec keeps the wrap points offset by `PerlinN`, because its `noise2`
+ * adds `PerlinN` to the coordinate before flooring; the shader does not add it (the coordinates
+ * here are never negative, and `PerlinN` is a multiple of the lattice, so it cannot change a masked
+ * index), so the offset is taken off the wrap points once, here.
+ */
+export interface GrainStitch {
+    readonly baseX: number;
+    readonly baseY: number;
+    readonly width: number;
+    readonly height: number;
+    readonly wrapX: number;
+    readonly wrapY: number;
+}
+/** The stitched frequencies and wrap points for a tile at the origin of the given size. */
+export declare function grainStitch(frequency: number, tileWidth: number, tileHeight: number): GrainStitch;
+/**
+ * The spec's `noise2` for one channel, with the `PerlinN` offset folded out (see `GrainStitch`).
+ * The lattice cell is picked by the floor of the coordinate, wrapped by the stitch and masked to
+ * the lattice; the value is the s-curve blend of the four corners' gradient dot products.
+ */
+export declare function grainNoise2(lattice: GrainLattice, channel: number, x: number, y: number, stitch: GrainStitch): number;
+/**
+ * `type="fractalNoise"` at a point: the signed octave sum, each octave at twice the frequency and
+ * half the amplitude, mapped from `[-1, 1]` into `[0, 1]`. The stitch doubles with the octave.
+ */
+export declare function grainTurbulence(lattice: GrainLattice, channel: number, x: number, y: number, stitch: GrainStitch, octaves: number): number;
+/**
+ * What the filter's grey matrix produces from the field: the mean of the first three channels, with
+ * the filter's own 0.3333 coefficient rather than a third, clamped like an 8-bit channel.
+ */
+export declare function grainGrey(lattice: GrainLattice, x: number, y: number, stitch: GrainStitch, octaves: number): number;
+/** Texels across the shader's lattice table: the whole selector, head and duplicated tail. */
+export declare const GRAIN_TABLE_WIDTH: number;
+/** Rows: the selector, then the first two channels' gradients, then the third's. */
+export declare const GRAIN_TABLE_HEIGHT = 3;
+/**
+ * One seed's lattice as RGBA float texels for the shader.
+ *
+ * Row 0 holds the selector in red. Row 1 holds channels 0 and 1's gradients as `(x, y, x, y)` and
+ * row 2 channel 2's as `(x, y, 0, 0)`, so a corner costs two fetches for all three greyed channels
+ * instead of three. The fourth channel is not packed: the filter's grey matrix drops it, and the
+ * alpha it would have produced is replaced by the source's own coverage.
+ */
+export declare function grainLatticeTable(seed: number): Float32Array;

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

@@ -0,0 +1,19 @@
+export type { SceneShotRender } from './render.js';
+export { SceneShotError, type SceneShotErrorCode } from './errors.js';
+export { referenceScale, type SceneFrameSize } from './scaling.js';
+export { conjugateF, sceneWorldMatrix, sceneCssMatrix, sceneLayerPose, scaleSceneTransform, SCENE_EULER_ORDER, F, type SceneVec3, type SceneWorldTransform, type ThreeLayerPose, } from './coordinates.js';
+export { SceneShotV2, backdropStyleV2, resolveSceneAssetsV2, type SceneShotV2Props, } from './v2/SceneShotV2.js';
+export { PreparedSceneShotV1, PreparedSceneShotError, type PreparedSceneShotV1Props } from './v2/PreparedSceneShotV1.js';
+export { SceneVideoBindingV1, SceneVideoTextureCommitV1, type SceneVideoBindingPropsV1, type SceneVideoTextureBindingV1 } from './v2/videoBinding.js';
+export { acquireSceneRuntimeAllocationV1, registerActualSceneResourcesV1, resetSceneRuntimeAllocationCountersV1, sceneRuntimeAllocationSnapshotV1, type SceneActualResourceRowV1, type SceneActualResourceReceiptV1, type SceneRuntimeAllocationSnapshotV1 } from './v2/runtimeAllocations.js';
+export { sceneShadowBoundsV2 } from './v2/shadow.js';
+export { LaptopObject, PageObject, SlabObject, WorldTextObject, PosedObject, SLAB_CONTENT_OFFSET } from './v2/builders.js';
+export type { SceneShotSpecV2, SceneObjectV2, SceneGroupV2, SceneLaptopV2, ScenePhoneV2, SceneSlabV2, ScenePageV2, SceneWorldTextV2, SceneScreenTextV2, SceneBackdropV2, ScenePostV2, SceneRigV2, SceneGeneratedStudioRigV2, ScenePhotographicStudioRigV1, SceneSurfaceBindingV2 } from '../../composition/scene/index.js';
+export { PhotographicStudioRig, PhotographicStudioEnvironmentError, verifyPhotographicStudioHdr, PHOTOGRAPHIC_STUDIO_RIG_ID, PHOTOGRAPHIC_STUDIO_HDRI_PATH, PHOTOGRAPHIC_STUDIO_HDRI_SHA256, PHOTOGRAPHIC_STUDIO_HDRI_BYTES, PHOTOGRAPHIC_STUDIO_PMREM_VERSION, PHOTOGRAPHIC_STUDIO_LIGHTING_VERSION, PHOTOGRAPHIC_STUDIO_EDGE_LIGHTS, PHOTOGRAPHIC_STUDIO_EDGE_INTENSITY, PHOTOGRAPHIC_STUDIO_GPU_BYTES, PHOTOGRAPHIC_STUDIO_RIG_FACTS, } from './v2/PhotographicStudioRig.js';
+export { SLAB_TESSELLATION, SLAB_TESSELLATION_VERSION, SLAB_TRIANGLES, SLAB_DEFAULTS, SCENE_MAX_TRIANGLES, SCENE_MAX_LAYERS, slabBodyGeometry, slabTriangleCount, slabTrianglesFor, withNormalisedFaceUv, } from './v2/slabGeometry.js';
+export { SLAB_FINISHES, SLAB_FINISH_SPEC, slabFinishMaterial, slabFinishDeclaredBytes, satinRoughnessMap, satinRoughnessScalar, brushedNormal, anodisedGrainNormal, type SceneSlabFinish, } from './v2/finishes.js';
+export { admitLightingProfile, admitSceneRigKind, admitSceneRigV2, assertNoObjectLightField, sceneRigIdentityV2, sceneLightCount, lightingProfileDeclaredBytes, SceneLightingRefusal, SCENE_OBJECT_LIGHT_FIELDS, SCENE_ENVIRONMENT_VERSION, type SceneLightingRefusalCode, type SceneRigIdentityV2, type SceneRigKindV2, type SceneGeneratedStudioRigIdentityV2, type ScenePhotographicStudioRigIdentityV1, } from './v2/lighting.js';
+export { sceneSlotsFor, sceneBoundSurfaces, assertSceneSurfaceResolution, type SceneSlotDescriptor, } from './v2/slots.js';
+export { RESOLUTION_BOUND, ALLOWED_BAKE_SCALES, DEFAULT_BAKE_SCALE, SceneResolutionRefusal, checkSurfaceResolution, selectSceneBakeScale, projectedSlotEdges, projectToOutputPixels, type SceneBakeScale, type SceneResolutionResult, type SceneBakeScaleSelection, type SceneEvaluatedPose, type SceneSlotRect, type SceneResolutionRefusalCode, } from './v2/projectedResolution.js';
+export { sceneSlabPreparationFactsV1, scenePresetBuilderDescriptorV1, generatedStudioPreparationFactsV1, photographicStudioPreparationFactsV1, sceneGrainPreparationAllocationV1, sceneGrainPreparationCpuAllocationV1, sceneFocusPreparationAllocationsV1, } from './v2/preparationFacts.js';
+export { preparedSurfaceDeviceProps, type PreparedSceneSurfaceVisualV1 } from './v2/preparedSurface.js';

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

@@ -0,0 +1,29 @@
+/**
+ * Internal surface of the scene-shot renderer: the pieces later stages and tests reach for, kept
+ * off the package barrel so authored components see only `SceneShot` and the geometry helpers.
+ */
+export { screenTextStyle, ScreenText, type ScreenTextProps, type EvaluatedScreenText } from './text.js';
+export { PostFilter, postFilterId, postFilterStages, postFilterStyle, grainSeed, grainFrequency, hashSeed, GRAIN_BASE_FREQUENCY, type PostFilterProps, type ScenePostTreatment, type PostStage, } from './finishing.js';
+export { vignetteGeometry, sceneVignetteFactor, sceneGrainLevel, sceneOverlay, blurredCoverage, erf, VIGNETTE_CORE_INSET, VIGNETTE_SIGMA, type VignetteGeometry, } from './finishingMath.js';
+export { grainLattice, grainLatticeTable, grainStitch, grainNoise2, grainTurbulence, grainGrey, grainSetupSeed, grainNextRandom, GRAIN_LATTICE, GRAIN_OCTAVES, GRAIN_PERLIN_N, GRAIN_CHANNELS, GRAIN_GREY_CHANNELS, GRAIN_GREY_COEFFICIENT, GRAIN_SAMPLE_OFFSET, GRAIN_TABLE_WIDTH, GRAIN_TABLE_HEIGHT, type GrainLattice, type GrainStitch, } from './grainNoise.js';
+export { sceneFinishingUniforms, type SceneFinishingUniforms } from './finishingPass.js';
+export { sceneImageHandle, type SceneImageSlotRef } from './assets.js';
+export { planeFit, planeImageRect, type PlaneFitResult, type PlaneSize, type SceneImageFit } from './planeFit.js';
+export { LoadGenerations, EMPTY_TEXTURE_STATE, onTextureLoaded, onTextureError, onTextureCommitted, onTextureOwnerUnmounted, type Disposable, type CommittedTexture, type ScreenTextureState, type ReadinessEffects, type TextureSlotRef, } from './readiness.js';
+export { useSceneImageTexture, type SceneImageSlotKind } from './useSceneImageTexture.js';
+export { useWorldTextTexture } from './useWorldTextTexture.js';
+export { textBlockLayout, lineBaselineY, lineOriginX, textFontShorthand, resolveSceneFontFamily, type TextBlockLayout, type TextLineBox, type TextLayoutInput, type TextFontMetrics, } from './textLayout.js';
+export { drawWorldText, worldTextCacheKey, worldTextLayout, worldTextRasterSize, WORLD_TEXT_MAX_TEXTURE, type TextRasterContext, } from './worldTextRaster.js';
+export { createWorldTextTexture, type WorldTextRasterRequest } from './worldTextTexture.js';
+export { RasterCache, worldTextRasterCache } from './rasterCache.js';
+export { onRasterReady, onRasterCommitted, onRasterOwnerUnmounted, type HeldRaster } from './rasterReadiness.js';
+export { whenFontReady, documentFonts, type FontSource } from './fontReadiness.js';
+export { focusBlurRadius, focusUniforms, viewDistanceFromDepth, FOCUS_OFF, FOCUS_TAPS, type FocusPassUniforms } from './focusBlur.js';
+export { FOCUS_VERTEX_SHADER, FOCUS_GATHER_CHUNK, FOCUS_BLUR_FRAGMENT_SHADER, FOCUS_COMPOSITE_FRAGMENT_SHADER, FOCUS_FINISHING_CHUNK, } from './focusShaders.js';
+export { FocusResources, renderFocusPass, assertHalfFloatColorTargets, canvasSampleCount, HALF_FLOAT_TARGET_EXTENSIONS, FOCUS_SPEC_PATH, type FocusRenderer, type FocusRendererExtensions, } from './focusResources.js';
+export { FocusPass, FOCUS_PASS_PRIORITY, focusCameraPlanes, type FocusPassProps } from './FocusPass.js';
+export { advanceRendererOnce } from './redraw.js';
+export { applyLayerOpacity } from './deviceOpacity.js';
+export { textureImageSize } from './textureImageSize.js';
+export { deviceShellCorners, pointsBounds, unionBounds, type WorldPoint } from './worldBounds.js';
+export { UnlitPlane, UNLIT_PLANE_ALPHA_TEST, type UnlitPlaneProps } from './UnlitPlane.js';

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

@@ -0,0 +1,46 @@
+export type SceneImageFit = 'contain' | 'cover';
+export interface PlaneSize {
+    width: number;
+    height: number;
+}
+/**
+ * How a decoded image lands on an authored world plane.
+ *
+ * `size` is the quad actually drawn, `repeat`/`offset` are the texture's UV window. The two carry
+ * the two halves of the fit between them: `cover` keeps the authored plane and crops the image
+ * through the UV window; `contain` keeps the whole image and shrinks the quad to the image's
+ * aspect inside the authored box. Shrinking the quad — rather than padding the UVs — means the
+ * plane never samples outside [0,1], so no edge texel is smeared into a letterbox bar and the
+ * plane's transparent margin stays genuinely absent rather than a black rectangle.
+ */
+export interface PlaneFitResult {
+    size: PlaneSize;
+    /** Three `Texture.repeat`, the fraction of the image the quad shows. */
+    repeat: [number, number];
+    /** Three `Texture.offset`, the UV-space corner of that fraction. */
+    offset: [number, number];
+}
+/**
+ * The region of the source image a fitted plane shows, in fractions of the image with the origin
+ * at the image's TOP-left and y running down — the orientation an author reasons about, and the
+ * one a quadrant fixture is checked against.
+ *
+ * The conversion from `offset` is an identity because both crops are centred: a `cover` crop
+ * removes the same fraction from the top and the bottom, so the distance from the image's top
+ * equals the UV-space distance from its bottom. Orientation itself comes from two facts that hold
+ * for every page plane this renderer builds: `PlaneGeometry` puts v = 1 at local +y, and a
+ * `TextureLoader` image has `flipY` true, which puts the image's first row at v = 1. The plane's
+ * top therefore shows the image's top, with no flip anywhere in the transform chain — the layer
+ * conversion `F·M·F` conjugates the pose, it does not mirror the geometry's own frame.
+ */
+export declare function planeImageRect(fit: PlaneFitResult): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Fit a decoded image of `image` pixels onto an authored `plane` (both in the same units; the
+ * caller has already applied the reference scale to the plane). Pure: no texture, no renderer.
+ */
+export declare function planeFit(fit: SceneImageFit, plane: PlaneSize, image: PlaneSize): PlaneFitResult;

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

@@ -0,0 +1,25 @@
+import type { SceneWorldTextV2 } from '../../composition/scene/index.js';
+import type { TextBlockLayout } from './textLayout.js';
+/** Raster inputs already resolved before the Three consumer mounts. */
+export interface PreparedWorldTextLayer {
+    kind: 'worldText';
+    layer: SceneWorldTextV2 & {
+        width: number;
+    };
+    index: number;
+    layout: TextBlockLayout;
+    size: {
+        width: number;
+        height: number;
+    };
+    key: string;
+}
+/** A world text raster maps one-to-one onto its world plane. */
+export declare function worldTextPlaneFit(layout: TextBlockLayout): {
+    size: {
+        width: number;
+        height: number;
+    };
+    repeat: [number, number];
+    offset: [number, number];
+};

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

@@ -0,0 +1,30 @@
+import type { Texture } from 'three';
+import type { Disposable } from '../three/textureLifecycle.js';
+/**
+ * A cache of immutable rasters shared by content identity, with one reference count per holder.
+ *
+ * The contract lets instances share immutable decoded inputs while keeping mutable meshes,
+ * materials, cameras and render targets per instance. A world-text raster is exactly that kind of
+ * input: static within a shot, identical whenever the resolved text, typography and scale are
+ * identical, and never written to after it is drawn. Each holder acquires and releases, and the
+ * value is disposed on the release that takes the count to zero — so one shot unmounting can
+ * never dispose the texture another shot is still drawing with, and a shot that reacquires the
+ * same identity does not redraw it.
+ *
+ * A release for a value that is no longer the cached one disposes that value alone: it belonged
+ * to a superseded entry and only its holder can free it.
+ */
+export declare class RasterCache<T extends Disposable> {
+    private readonly entries;
+    acquire(key: string, create: () => T): T;
+    release(key: string, value: T): void;
+    /** How many holders a key has right now; 0 when it is not cached. Tests and diagnostics only. */
+    refs(key: string): number;
+    get size(): number;
+}
+/**
+ * The renderer's world-text rasters. One process-wide table keyed by content and scale: two shots
+ * saying the same thing at the same size decode it once. Nothing mutable lives here — see the
+ * class doc for why that is the line.
+ */
+export declare const worldTextRasterCache: RasterCache<Texture<unknown>>;

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

@@ -0,0 +1,33 @@
+import type { Disposable } from '../three/textureLifecycle.js';
+import type { RasterCache } from './rasterCache.js';
+import type { LoadGenerations, ReadinessEffects } from './readiness.js';
+/** A shared raster this layer holds a reference to, with the readiness handle its build took. */
+export interface HeldRaster<T extends Disposable = Disposable> {
+    key: string;
+    raster: T;
+    handle: number;
+}
+/**
+ * A raster's prerequisites (its font) are ready.
+ *
+ * Live: the shared raster is acquired — built only if no other holder has it — and returned for
+ * React to commit; its handle stays open until the commit step has drawn it. Obsolete (a newer
+ * identity began, or the owner unmounted): nothing is acquired, so nothing has to be given back,
+ * and only this load's own handle is released.
+ */
+export declare function onRasterReady<T extends Disposable>(generations: LoadGenerations, cache: RasterCache<T>, token: number, key: string, handle: number, create: () => T, effects: Pick<ReadinessEffects, 'continueRender'>): HeldRaster<T> | null;
+/**
+ * React committed a raster. Draw once (the frame loop is `never` while rendering), then release
+ * the handle, then — and only then — give back the reference this commit replaced. Releasing the
+ * previous reference last is what keeps a shared raster alive across an identity change that
+ * resolves to the same content: the new acquisition is already counted before the old one goes.
+ */
+export declare function onRasterCommitted<T extends Disposable>(cache: RasterCache<T>, held: HeldRaster<T> | null, committed: HeldRaster<T>, effects: Pick<ReadinessEffects, 'continueRender'> & {
+    redraw(): void;
+}): HeldRaster<T>;
+/**
+ * The owner unmounted, possibly mid-build: no later completion may acquire anything, and the
+ * reference it holds goes back to the cache — which disposes the raster only if this was the last
+ * holder, so another shot drawing the same words is untouched.
+ */
+export declare function onRasterOwnerUnmounted<T extends Disposable>(generations: LoadGenerations, cache: RasterCache<T>, held: HeldRaster<T> | null): null;

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

@@ -0,0 +1,69 @@
+import { type Disposable } from '../three/textureLifecycle.js';
+/**
+ * Generation tokens for one asynchronous resource. Each load takes a token; only the newest is
+ * live, and none is once the owner closes. A completion checks its token before touching anything.
+ */
+export declare class LoadGenerations {
+    private current;
+    private closed;
+    begin(): number;
+    isLive(token: number): boolean;
+    close(): void;
+}
+export type { Disposable };
+/** A loaded texture handed to React with the readiness handle its load took. */
+export interface CommittedTexture<T extends Disposable = Disposable> {
+    texture: T;
+    handle: number;
+}
+/** What one layer's texture loads have produced so far. */
+export interface ScreenTextureState<T extends Disposable = Disposable> {
+    /** The texture the scene was last drawn with. */
+    drawn: T | null;
+    /** Loaded and handed to React, but not yet through the commit step. */
+    pending: T | null;
+}
+export declare const EMPTY_TEXTURE_STATE: ScreenTextureState<never>;
+export interface ReadinessEffects {
+    continueRender(handle: number): void;
+    cancelRender(error: Error): void;
+}
+/**
+ * A texture finished loading. Live: it becomes pending and is returned for React to commit; its
+ * handle stays open until the commit step has drawn it. Obsolete (a newer load began, or the
+ * owner unmounted): the texture is disposed and only its own handle is released — the drawn
+ * scene and any other handle are untouched.
+ */
+export declare function onTextureLoaded<T extends Disposable>(generations: LoadGenerations, state: ScreenTextureState<T>, token: number, texture: T, handle: number, effects: Pick<ReadinessEffects, 'continueRender'>): {
+    state: ScreenTextureState<T>;
+    commit: CommittedTexture<T> | null;
+};
+/** Which binding a failed load belongs to: the slot name, and what the shot wanted it for. */
+export interface TextureSlotRef {
+    slot: string;
+    what: string;
+}
+/**
+ * A load failed. Live: the render is cancelled with a typed error naming the slot. Obsolete: the
+ * layer that owned this load is gone or has moved on, so only its own handle is released.
+ */
+export declare function onTextureError(generations: LoadGenerations, token: number, error: unknown, handle: number, target: TextureSlotRef, effects: ReadinessEffects): 'cancelled' | 'released';
+/**
+ * React committed a loaded texture. Draw once (the frame loop is `never` while rendering), then
+ * release the handle, then — and only then — dispose the texture this one replaced. The
+ * replacement rule itself is `commitImageTexture`, the one dispose-on-commit policy this package
+ * has; this function adds only the readiness handle and the draw that must precede it.
+ */
+export declare function onTextureCommitted<T extends Disposable>(state: ScreenTextureState<T>, committed: CommittedTexture<T>, effects: Pick<ReadinessEffects, 'continueRender'> & {
+    redraw(): void;
+}): ScreenTextureState<T>;
+/**
+ * The owner unmounted, possibly mid-load: no later completion may touch anything, the drawn
+ * texture goes, and so does one that loaded but never reached the commit step.
+ *
+ * Both disposals are `textureLifecycle`'s, not restatements of it: what an unmounted owner does
+ * with what it last drew is `releaseImageTexture`, and a texture that arrived for an owner that is
+ * gone is `discardStaleTexture` — the same rule `onTextureLoaded` applies to a superseded load.
+ * This function adds only the generation close and the pending case.
+ */
+export declare function onTextureOwnerUnmounted<T extends Disposable>(generations: LoadGenerations, state: ScreenTextureState<T>): ScreenTextureState<never>;

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

@@ -0,0 +1,10 @@
+/**
+ * Draw the fiber scene once, now. During rendering the frame loop is `never` and `invalidate()`
+ * is a no-op, so a change committed outside Remotion's own per-frame advance (a texture that
+ * arrived) is invisible until something calls `advance`. This is the one place the scene renderer
+ * reads a clock: fiber's `advance` wants a timestamp to hand its frame callbacks. This renderer
+ * registers exactly one — `FocusPass`, which claims the render priority — and that callback takes
+ * neither the timestamp nor the delta, so the wall clock cannot reach a drawn frame through it
+ * (asserted in `FocusPass.test.tsx`). Authored components never call this; the readiness hook does.
+ */
+export declare function advanceRendererOnce(advance: (timestamp: number) => void): void;

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

@@ -0,0 +1,9 @@
+/** Output facts supplied by the admitted render host for one scene frame. */
+export interface SceneShotRender {
+    frame: number;
+    fps: number;
+    width: number;
+    height: number;
+    seed: string;
+    colorSpace: 'srgb';
+}

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

@@ -0,0 +1,13 @@
+export interface SceneFrameSize {
+    width: number;
+    height: number;
+}
+/**
+ * The uniform reference-pixel scale for an output frame: output width over reference width.
+ * Only defined at an equal aspect; anything else is a re-layout the author must do, not a crop
+ * this renderer may invent. Checked by cross-multiplication so integer sizes compare exactly.
+ */
+export declare function referenceScale(render: SceneFrameSize, reference: {
+    width: number;
+    height: number;
+}): number;

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

@@ -0,0 +1,40 @@
+import React from 'react';
+import type { SceneScreenTextV2 } from '../../composition/scene/index.js';
+import type { SceneFrameSize } from './scaling.js';
+export interface EvaluatedScreenText {
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+    opacity: number;
+}
+/**
+ * Inline style for a screen-space text block. The box comes from `textBlockLayout`, the same
+ * module the world-text rasterizer draws from, so the two paths cannot drift *in their boxes* —
+ * run-boundary shaping is the one place they still can, and `drawWorldText` documents it: the block is
+ * `width` wide and exactly `lines × fontSize × lineHeight` tall (lines are explicit, so its
+ * height is known without measuring), centred on the frame centre plus (x, y), all in reference
+ * pixels times `scale`. Rotation and the uniform scale act about the block centre. `lineHeight`
+ * is a unitless multiplier and is not scaled; `whiteSpace: pre` keeps authored spacing and
+ * forbids reflow. `index` is the layer's array index, used for validator-style error paths
+ * (`layers.N.color`).
+ */
+export declare function screenTextStyle(layer: SceneScreenTextV2 & {
+    width: number;
+}, index: number, evaluated: EvaluatedScreenText, scale: number, frame: SceneFrameSize): React.CSSProperties;
+export interface ScreenTextProps {
+    layer: SceneScreenTextV2 & {
+        width: number;
+    };
+    /** The layer's index in `spec.layers`, for error paths. */
+    index: number;
+    evaluated: EvaluatedScreenText;
+    scale: number;
+    frame: SceneFrameSize;
+}
+/**
+ * Screen text as DOM from typed runs: one block per line, one span per run, text as text nodes.
+ * A run colour overrides the layer colour for that run only; there is no substring matching and
+ * no markup path, so a run reading `<b>` renders those three characters.
+ */
+export declare function ScreenText({ layer, index, evaluated, scale, frame }: ScreenTextProps): React.JSX.Element;

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

@@ -0,0 +1,78 @@
+import type { SceneFontFamily, SceneTextLineV2 } from '../../composition/scene/index.js';
+/** The typography and content both text paths read; screen and world text differ only in placement. */
+export interface TextLayoutInput {
+    fontFamily: SceneFontFamily;
+    fontWeight: number;
+    fontStyle: 'normal' | 'italic';
+    /** Reference pixels. */
+    fontSize: number;
+    /** Unitless multiplier, never scaled. */
+    lineHeight: number;
+    letterSpacing: number;
+    align: 'left' | 'center' | 'right';
+    /** Reference pixels. */
+    width: number;
+    lines: readonly SceneTextLineV2[];
+}
+/** One line's box in the block, in output pixels from the block's top-left. */
+export interface TextLineBox {
+    index: number;
+    top: number;
+    height: number;
+}
+/** The block's boxes in output pixels: what the DOM lays out and what the rasterizer draws into. */
+export interface TextBlockLayout {
+    width: number;
+    height: number;
+    /** The reference scale this block was laid out at; both paths name the same face with it. */
+    scale: number;
+    fontSize: number;
+    /** The unitless multiplier, carried through unscaled for the DOM's `line-height`. */
+    lineHeight: number;
+    /** `fontSize * lineHeight`, the height of every line box. */
+    lineBox: number;
+    align: 'left' | 'center' | 'right';
+    lines: TextLineBox[];
+}
+/**
+ * The one line/run layout both text paths consume: the DOM screen-text block and the world-text
+ * rasterizer.
+ *
+ * Lines are authored explicitly, so a block's height is known without measuring anything: `lines ×
+ * fontSize × lineHeight`, the CSS line-box model with a unitless `line-height`. Reference pixels
+ * scale by the output scale; the multiplier does not. Nothing here needs a font to be loaded,
+ * which is what lets the DOM path lay out before the raster path has measured a glyph.
+ */
+export declare function textBlockLayout(layer: TextLayoutInput, scale: number): TextBlockLayout;
+/** A font's vertical extent at the laid-out size, as `measureText` reports it. */
+export interface TextFontMetrics {
+    ascent: number;
+    descent: number;
+}
+/**
+ * The alphabetic baseline of a line box, in output pixels from the block's top.
+ *
+ * CSS centres the font's content box inside the line box and splits the remainder evenly above and
+ * below it (half-leading); the baseline is then the ascent below the content box's top. A
+ * rasterizer that put the baseline anywhere else would drift from the DOM path as `lineHeight`
+ * moved away from 1.
+ */
+export declare function lineBaselineY(box: TextLineBox, metrics: TextFontMetrics): number;
+/**
+ * Where a line of measured width `lineWidth` starts, in output pixels from the block's left edge.
+ * The same rule CSS `text-align` applies; a line wider than the block overflows both ways rather
+ * than being truncated, because the contract forbids reflow and truncation alike.
+ */
+export declare function lineOriginX(layout: TextBlockLayout, lineWidth: number): number;
+/**
+ * The family a text layer actually draws with. A brand font token is resolved during preparation,
+ * like a brand colour; one that reaches the renderer would otherwise be handed to the font loader
+ * as a family name and quietly replaced by a fallback face, so it is refused with its path.
+ */
+export declare function resolveSceneFontFamily(family: SceneFontFamily, path: string): string;
+/**
+ * The CSS `font` shorthand for a layer at an output scale, in the order the shorthand requires
+ * (style, weight, size, family). Both paths use it: the DOM through its own properties, the
+ * rasterizer through `ctx.font` and `document.fonts`, so neither can drift onto another face.
+ */
+export declare function textFontShorthand(layer: TextLayoutInput, scale: number, path?: string): string;

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

@@ -0,0 +1,4 @@
+import type { Texture } from 'three';
+import type { PlaneSize } from './planeFit.js';
+/** The decoded pixel size of a loaded texture's image, refused rather than guessed if absent. */
+export declare function textureImageSize(texture: Texture, slot: string, layerIndex: number): PlaneSize;

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

@@ -0,0 +1,21 @@
+import { Texture } from 'three';
+/** What an image slot is for; only the wording of a handle and of a load failure differs. */
+export type SceneImageSlotKind = 'screenshot' | 'page image';
+/**
+ * One image slot's bytes as an sRGB Three texture, under Remotion readiness: a device layer's
+ * screenshot or a page layer's image. A thin wrapper — every decision about what a completion may
+ * touch lives in the pure policy functions in `readiness.ts`, which the node tests drive directly.
+ *
+ * Every `src` takes a fresh `delayRender` handle and a generation token. The first handle is
+ * taken during render, not in an effect: the cold frame is the one whose readiness poll could
+ * otherwise land between the commit and the effect. A live completion is committed through
+ * state; the layout effect after that commit draws the scene once, releases the handle, and only
+ * then disposes the texture it replaced. Must run inside the fiber canvas (it uses `useThree`).
+ *
+ * The texture is owned by this hook's instance: two layers binding the same slot decode their
+ * own, so one layer's crop or disposal can never reach the other's material.
+ *
+ * `what` names the slot in the readiness handle and in a load failure ("screenshot", "page
+ * image"); the failure path stays `assets.<slot>`, the binding map the author must correct.
+ */
+export declare function useSceneImageTexture(src: string, slot: string, what: SceneImageSlotKind, resourceOwner?: string): Texture | null;

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

@@ -0,0 +1,21 @@
+import type { Texture } from 'three';
+import type { PreparedWorldTextLayer } from './preparedWorldText.js';
+/**
+ * One world-text layer's rasterized texture, under Remotion readiness. A thin wrapper: every
+ * decision about what a completion may touch lives in the pure policy in `rasterReadiness.ts`,
+ * which the node tests drive directly.
+ *
+ * The shape is the image path's, with two differences the raster forces:
+ *
+ * 1. The wait is for a font, not for bytes. Nothing is drawn until `document.fonts` reports the
+ *    exact face ready under this render's `delayRender` handle, so a frame can never be captured
+ *    with a fallback face that a later frame would draw differently. No timer is involved.
+ * 2. The texture is immutable and shared by content identity, so it is acquired from and released
+ *    to `worldTextRasterCache` rather than disposed directly. Two shots saying the same thing at
+ *    the same scale rasterize once, and either unmounting cannot dispose what the other draws.
+ *
+ * Every identity takes a fresh handle and a generation token; a completion that is no longer live
+ * releases its own handle and acquires nothing. The reference the layer replaces is given back
+ * only in the commit effect, after the redraw that drew its replacement.
+ */
+export declare function useWorldTextTexture(prepared: PreparedWorldTextLayer): Texture | null;

package/dist/_members/animate/scene/v2/MeasuredPlaneGeometry.d.ts

@@ -0,0 +1,7 @@
+/** A Fiber-owned plane whose actual Three disposal closes its measured allocation receipt. */
+export declare function MeasuredPlaneGeometry({ width, height, owner, name }: {
+    width: number;
+    height: number;
+    owner: string;
+    name: string;
+}): import("react").JSX.Element;

package/dist/_members/animate/scene/v2/PhotographicStudioRig.d.ts

@@ -0,0 +1,11 @@
+export { PHOTOGRAPHIC_STUDIO_EDGE_INTENSITY, PHOTOGRAPHIC_STUDIO_EDGE_LIGHTS, PHOTOGRAPHIC_STUDIO_GPU_BYTES, PHOTOGRAPHIC_STUDIO_HDRI_BYTES, PHOTOGRAPHIC_STUDIO_HDRI_PATH, PHOTOGRAPHIC_STUDIO_HDRI_SHA256, PHOTOGRAPHIC_STUDIO_LIGHTING_VERSION, PHOTOGRAPHIC_STUDIO_PMREM_VERSION, PHOTOGRAPHIC_STUDIO_RIG_FACTS, PHOTOGRAPHIC_STUDIO_RIG_ID, } from '../../../composition/scene/index.js';
+export declare class PhotographicStudioEnvironmentError extends Error {
+    readonly code: 'scene_photographic_environment_fetch_failed' | 'scene_photographic_environment_digest_mismatch' | 'scene_photographic_environment_decode_failed';
+    constructor(code: PhotographicStudioEnvironmentError['code'], message: string);
+}
+/** Refuse any bytes other than the redistributed, pinned CC0 environment before decoding them. */
+export declare function verifyPhotographicStudioHdr(bytes: Uint8Array): Promise<void>;
+/** The original three-card reflection rig: fixed environment, five fixed lights, no floor/shadows. */
+export declare function PhotographicStudioRig({ worldScale }: {
+    worldScale?: number;
+}): import("react").JSX.Element;

package/dist/_members/animate/scene/v2/PreparedSceneShotV1.d.ts

@@ -0,0 +1,12 @@
+import { type SealedSceneShotPlanV1 } from '../../../composition/scene/index.js';
+import type { SceneShotRender } from '../render.js';
+export declare class PreparedSceneShotError extends Error {
+    readonly code: 'scene_plan_output_mismatch' | 'scene_builder_descriptor_unavailable' | 'scene_builder_descriptor_mismatch';
+    constructor(code: 'scene_plan_output_mismatch' | 'scene_builder_descriptor_unavailable' | 'scene_builder_descriptor_mismatch', message: string);
+}
+export interface PreparedSceneShotV1Props {
+    plan: SealedSceneShotPlanV1;
+    render: SceneShotRender;
+}
+/** Renders only decisions already sealed by preparation; unsupported builders refuse by authored kind. */
+export declare function PreparedSceneShotV1({ plan, render }: PreparedSceneShotV1Props): import("react").JSX.Element;