@threenative/core 0.2.0 → 0.3.1

package/dist/renderer-C6hqZpoG.d.ts

@@ -0,0 +1,770 @@
+import { Object3D, Matrix4, Camera } from 'three';
+import { MRTNode, Node } from 'three/webgpu';
+
+/**
+ * Per-presented-frame cost attribution, on by default, for every platform.
+ *
+ * A device once read 18.3 fps with nothing in the repository able to say where the frame went;
+ * the answer took a hand-written 468-line probe that monkey-patched `requestAnimationFrame` and
+ * `renderer.render` from inside the game. That probe had to guess the phase boundaries because it
+ * lived outside the loop. This lives inside the loop, so it knows them: the framework owns the
+ * simulation/render split, the render call and the frame's start and end, and no game should ever
+ * write this again.
+ *
+ * Two consumers, one measurement:
+ *
+ *  - a windowed `TN_FRAME_BUDGET` marker line, printed periodically on stdout (and therefore in
+ *    logcat on Android), so a cold agent reading standard device-lane output sees the attribution
+ *    without instrumenting anything;
+ *  - a per-frame sample carried into the playtest render series, so `assert.performance` can bound
+ *    an fps floor and a per-phase ceiling and a mobile regression is a red gate rather than a vibe.
+ *
+ * Fail closed: malformed options throw at construction rather than silently disabling the budget,
+ * and a phase that was never measured reports zero samples so a consumer asserting on it fails
+ * instead of skipping.
+ */
+/** Marker printed once per report window. */
+declare const FRAME_BUDGET_MARKER = "TN_FRAME_BUDGET";
+/** Marker printed the moment a gap between presented frames exceeds `hitchMs`. */
+declare const FRAME_HITCH_MARKER = "TN_FRAME_HITCH";
+/**
+ * The named parts of one presented frame. They partition the frame: `hostGap` is the time before
+ * the callback (present wait plus whatever the host did between callbacks), and `update`,
+ * `render`, `overlay` and `residual` sum to the callback's own duration.
+ */
+declare const FRAME_BUDGET_PHASES: readonly ["hostGap", "update", "render", "overlay", "residual"];
+type FrameBudgetPhase = (typeof FRAME_BUDGET_PHASES)[number];
+/** One frame's cost, split by phase. Every field is milliseconds. */
+interface IFramePhaseSample {
+    readonly hostGap: number;
+    readonly update: number;
+    readonly render: number;
+    readonly overlay: number;
+    readonly residual: number;
+}
+/**
+ * What the frame the window measured was actually drawn at.
+ *
+ * A resolution number without its sample count does not describe an image, and neither of them
+ * describes anything at all unless the window that carries the fps also carries them. This is
+ * reported whether the scale was pinned by the game or chosen by the engine: turning the
+ * convention off does not turn its measurement off.
+ */
+interface IFrameSurfaceState {
+    /** The applied drawing-buffer scale, in `(0, 1]`. */
+    readonly resolutionScale: number;
+    /**
+     * `"pinned"` when the game fixed the number, `"auto"` when the engine chose it, and
+     * `"auto-pinned"` when the engine chose it and then stopped moving it — the oscillation guard
+     * holding a rung is a different state from a game that pinned one, and reads as one.
+     */
+    readonly scaleSource: "pinned" | "auto" | "auto-pinned";
+    /** Multisample count of the 3D drawing buffer; 1 when sampling is off. */
+    readonly sampleCount: number;
+    readonly drawingBufferWidth: number;
+    readonly drawingBufferHeight: number;
+    /**
+     * True when the scaler is at its lowest rung and the tail is still over budget.
+     *
+     * A window that reports 0.23 and nothing else reads as a met budget at a low resolution. It is
+     * the opposite: the engine ran out of room and the game is still missing its target. Always
+     * false under a pinned scale, which has no floor to reach.
+     */
+    readonly atFloor: boolean;
+    /** Compilation overlapped the measured window; automatic scaling waits for a clean window. */
+    readonly compiling?: boolean;
+}
+interface IFrameBudgetSummary {
+    readonly samples: number;
+    readonly mean: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly p99: number;
+    readonly max: number;
+}
+interface IFrameBudgetWindow {
+    /** 1 for the first reported window, incrementing thereafter. */
+    readonly window: number;
+    /** Presented frames counted in this window, hitches excluded. */
+    readonly frames: number;
+    /** Frames excluded from the window because their present gap exceeded `hitchMs`. */
+    readonly hitches: number;
+    /** Derived from the mean presented interval: the number a player would read off a counter. */
+    readonly fps: number;
+    /** Interval between presented frames — the honest frame period. */
+    readonly presented: IFrameBudgetSummary;
+    /** Duration of the frame callback itself, entry to exit. */
+    readonly frame: IFrameBudgetSummary;
+    /** Fixed simulation steps executed in the callback. */
+    readonly substeps: IFrameBudgetSummary;
+    readonly phases: Readonly<Record<FrameBudgetPhase, IFrameBudgetSummary>>;
+    /** Each phase's mean as a fraction of the mean presented interval. */
+    readonly shares: Readonly<Record<FrameBudgetPhase, number>>;
+    /**
+     * The resolution and sampling this window's frames were drawn at, when the loop reported one.
+     * Absent rather than defaulted: a consumer asserting on it must fail loudly instead of reading
+     * a fabricated `1.0` that no frame was ever drawn at.
+     */
+    readonly surface?: IFrameSurfaceState;
+    /**
+     * GPU milliseconds for a frame in this window, from `timestamp-query`, when the adapter has it.
+     *
+     * Absent rather than zero when there is nothing to report: an adapter without timestamps and a
+     * frame that genuinely cost no GPU time are different facts, and a zero would merge them.
+     */
+    readonly gpuMs?: number;
+    /** Age of the resolved GPU timestamp in Three.js frame IDs; absent means unobservable. */
+    readonly gpuAgeFrames?: number;
+}
+interface IFrameBudgetOptions {
+    /** Presented frames per report window. Default 300. */
+    readonly reportEvery?: number;
+    /** A present gap at or above this is a hitch, not a frame. Default 2000 ms. */
+    readonly hitchMs?: number;
+    /** Ring capacity per series. Default 1024. */
+    readonly capacity?: number;
+    /** Where marker lines go. Default `console.log`. */
+    readonly report?: (line: string) => void;
+    /** Wall clock for hitch markers. Default `Date.now`. */
+    readonly wallClock?: () => number;
+    /**
+     * Called with each completed window, after its marker line. A HUD reads it to show the split
+     * on screen; a measurement run reads it to advance in lockstep with the instrument instead of
+     * guessing when a window closed.
+     */
+    readonly onWindow?: (window: IFrameBudgetWindow) => void;
+    /**
+     * Reads what the frames were drawn at, called once per reported window. Wired by the frame
+     * loop, which is the only place that knows both the renderer and the window boundary.
+     */
+    readonly readSurface?: () => IFrameSurfaceState;
+    /** Reads the last resolved GPU frame time, called once per reported window. */
+    readonly readGpuMs?: () => number | undefined;
+    /** Reads the successful GPU query frame age, not the age of the last resolve attempt. */
+    readonly readGpuAgeFrames?: () => number | undefined;
+}
+/**
+ * Accumulates one frame at a time and reports windowed attribution.
+ *
+ * The caller is the frame loop; the sequence per frame is
+ * `beginFrame` → `markSimulationEnd` → (`addRender` / `addOverlay`) → `endFrame`.
+ * Calling them out of order throws rather than producing a plausible-looking split.
+ */
+declare class FrameBudget {
+    #private;
+    readonly reportEvery: number;
+    readonly hitchMs: number;
+    constructor(options?: IFrameBudgetOptions);
+    /**
+     * @param timestampMs the frame timestamp the host handed the callback — the presented-frame
+     *   clock, which is not the same as `nowMs` and is what the interval between frames comes from.
+     * @param nowMs the monotonic clock at callback entry.
+     */
+    beginFrame(timestampMs: number, nowMs: number): void;
+    /** The boundary between the fixed-step simulation and everything the render phase does. */
+    markSimulationEnd(nowMs: number, substeps: number): void;
+    addRender(ms: number): void;
+    addOverlay(ms: number): void;
+    /**
+     * Closes the frame and returns its phase split, or `undefined` when the frame was a hitch and
+     * therefore excluded — a 27-second startup stall is not a frame time and must not enter a
+     * percentile anybody is asked to act on.
+     *
+     * `wantSample` is false when the caller is going to discard the split, which is the default
+     * shipping configuration. The object is small but it escapes this method, so V8 cannot scalar-
+     * replace it, and building one per frame is one dead allocation per frame in every game. The
+     * window meters below are pushed either way: turning the sample off must not turn measurement
+     * off, and `window()` reads the same numbers whichever way this is called.
+     */
+    endFrame(nowMs: number, wantSample?: boolean): IFramePhaseSample | undefined;
+    /** Reads the window in progress without disturbing it. */
+    window(): IFrameBudgetWindow;
+}
+
+/**
+ * A bounded observation of the pipelines a Three.js renderer actually asked the GPU device to make.
+ *
+ * This module deliberately knows the shape of Three's private render object, but not its cache-key
+ * algorithm. Three owns the identity; the collector only reads the object at the backend boundary
+ * where a cache miss becomes a real device creation. That keeps a material label from becoming a
+ * pipeline key and makes the same observation useful on browser WebGPU and the native binding.
+ *
+ * The backend boundary alone is not the whole device, and a census that claims otherwise is
+ * wrong by exactly the pipelines it cannot see: Three's texture pass utils build mipmap transfer
+ * pipelines straight on the device, which is why a Bayview native capture logged 94 device
+ * creations against 92 renderer events. So the device's own creation methods are observed too,
+ * with creations reached through the wrapped backend attributed to their backend event rather
+ * than counted twice, and a direct creation reported with the label the device was given, an
+ * explicitly unknown pass and unknown provenance rather than the render object that happened to
+ * be drawing when a texture uploaded.
+ */
+declare const PIPELINE_CENSUS_VERSION: 1;
+declare const PIPELINE_CENSUS_CAPABILITY: "runtime.pipelineCensus";
+declare const DEFAULT_PIPELINE_CENSUS_LIMIT = 512;
+type PipelineCensusStatus = "created" | "failed" | "pending";
+type PipelineCensusMode = "sync" | "async";
+interface IPipelineShaderObservation {
+    readonly bytes: number;
+    readonly hash: string;
+}
+interface IPipelineProvenance {
+    readonly material?: {
+        readonly id?: number;
+        readonly name?: string;
+        readonly type?: string;
+    };
+    readonly object?: {
+        readonly id?: number;
+        readonly name?: string;
+        readonly uuid?: string;
+    };
+    /** True when no stable material/object label was available at the creation boundary. */
+    readonly unknown: boolean;
+}
+interface IPipelineCensusEvent {
+    /** Monotonic sequence, useful for detecting a dropped event in a merged native log. */
+    readonly sequence: number;
+    /** Three's program identity: the generated vertex/fragment source pair. */
+    readonly programIdentity: string;
+    /** Backend identity, separate from the program identity and from the material label. */
+    readonly pipelineIdentity: string;
+    readonly kind: "compute" | "render";
+    readonly pass: string;
+    readonly mode: PipelineCensusMode;
+    readonly status: PipelineCensusStatus;
+    readonly vertex?: IPipelineShaderObservation;
+    readonly fragment?: IPipelineShaderObservation;
+    readonly compute?: IPipelineShaderObservation;
+    readonly provenance: IPipelineProvenance;
+    /** The label the device was handed, when one was observed. A label is never read as a pass. */
+    readonly label?: string;
+    /** Structural inputs observed beside the generated shader, not a guessed reason. */
+    readonly reasons: readonly string[];
+    /** Host monotonic milliseconds relative to the capture origin. */
+    readonly startedMs: number;
+    readonly settledMs?: number;
+    /** Synchronous device-call wall time; absent for an async promise. */
+    readonly serviceMs?: number;
+    /** Promise latency is retained as latency, never labelled native compiler time. */
+    readonly promiseMs?: number;
+    readonly error?: string;
+    /** Whether this event settled before the first present boundary. */
+    readonly beforeFirstPresent?: boolean;
+}
+interface IPipelineCensusCounts {
+    readonly lookups: number;
+    readonly creations: number;
+    readonly failures: number;
+    readonly pending: number;
+    readonly uniquePrograms: number;
+    readonly uniquePipelines: number;
+    readonly recordedEvents: number;
+    readonly droppedEvents: number;
+    /**
+     * Every creation seen at the device, including those attributed to a backend event. Absent
+     * when the device could not be observed at all, so no reader mistakes silence for zero.
+     */
+    readonly deviceCreations?: number;
+    /** Creations seen only at the device, never reached through the wrapped backend methods. */
+    readonly directCreations?: number;
+}
+interface IPipelineCensus {
+    readonly version: typeof PIPELINE_CENSUS_VERSION;
+    readonly complete: boolean;
+    readonly overflowed: boolean;
+    readonly unsupported: boolean;
+    readonly limit: number;
+    readonly clock: {
+        readonly originMs: number;
+        readonly source: "performance" | "date";
+    };
+    readonly build: {
+        readonly identity: string;
+    };
+    readonly adapter: {
+        readonly identity: string;
+        readonly thermal: string;
+    };
+    readonly backend: {
+        readonly kind: "webgpu" | "webgl2";
+        readonly identity: string;
+    };
+    readonly firstPresent?: {
+        readonly boundaryMs: number;
+        readonly eventsSettled: number;
+    };
+    readonly counts: IPipelineCensusCounts;
+    readonly events: readonly IPipelineCensusEvent[];
+    readonly incompleteReasons: readonly string[];
+}
+interface IPipelineCensusOptions {
+    readonly adapterIdentity?: string;
+    readonly buildIdentity?: string;
+    readonly kind: "webgpu" | "webgl2";
+    readonly limit?: number;
+    readonly now?: () => number;
+    readonly backendIdentity?: string;
+    readonly thermalIdentity?: string;
+}
+interface IRendererHookTarget {
+    backend?: unknown;
+    renderObject?: (...args: unknown[]) => unknown;
+}
+/**
+ * Create and install a bounded census. The returned object is intentionally small: renderers own
+ * lifecycle and callers only need `snapshot()`, `withRenderObject()`, and `firstPresent()`.
+ */
+declare function createPipelineCensus(options: IPipelineCensusOptions): PipelineCensus;
+declare class PipelineCensus {
+    #private;
+    constructor(options: IPipelineCensusOptions);
+    /** Install the backend creation hooks and the render-object context wrapper once. */
+    install(backendValue: unknown): () => void;
+    /** Install every renderer-side hook owned by this capture. */
+    installRenderer(renderer: IRendererHookTarget): void;
+    /** Restore private hooks while retaining the immutable capture already recorded. */
+    dispose(): void;
+    /** Wrap Three's public render-object method so compileAsync retains the authored pass id. */
+    withRenderObject<T>(args: readonly unknown[], callback: () => T): T;
+    /** Mark the first renderer render call as the first-present boundary. */
+    firstPresent(): void;
+    snapshot(): IPipelineCensus;
+}
+
+/** The marker shared by alpha-antialiasing logs, playtests, and native diagnostics. */
+declare const ALPHA_ANTIALIASING_MARKER = "TN_ALPHA_ANTIALIASING";
+interface IAlphaAntialiasingReport {
+    /** True once at least one cutout material has been put on the coverage mask. */
+    readonly applied: boolean;
+    readonly marker: typeof ALPHA_ANTIALIASING_MARKER;
+    /** Empty when applied; otherwise why the convention did nothing, and what to change. */
+    readonly reason: string;
+    /** The sample count the decision was made against. One means there is no coverage mask. */
+    readonly sampleCount: number;
+    /** How many distinct cutout materials this renderer has converted. */
+    readonly materials: number;
+}
+
+/** The output name shared by the scene pass and temporal consumers. */
+declare const VELOCITY_OUTPUT_NAME = "velocity";
+/**
+ * The pass surface needed to add and read the shared screen-space output.
+ *
+ * Keeping this structural lets the same seam work with Three's `PassNode` and a native adapter
+ * without making the game depend on either implementation.
+ */
+interface IVelocityRenderPass {
+    getMRT(): MRTNode | null;
+    getTextureNode(name?: string): Node;
+    setMRT(value: MRTNode | null): unknown;
+}
+/** The symbol read by the patched Three.js instance accessor. */
+declare const VELOCITY_PREVIOUS_INSTANCE_MATRICES: unique symbol;
+/** The symbol read by the patched Three.js velocity accessor for rigid history. */
+declare const VELOCITY_PREVIOUS_WORLD_MATRIX: unique symbol;
+/** The symbol read by the patched Three.js skinning accessor for bone history. */
+declare const VELOCITY_PREVIOUS_BONE_MATRICES: unique symbol;
+/**
+ * Adds the velocity output to a scene pass without creating its texture until it is read.
+ *
+ * The existing outputs remain intact. A pass with no prior MRT receives the normal colour output
+ * as well, so adding history does not remove the frame's visible colour.
+ * @situation add a velocity target before a temporal stage consumes a scene pass
+ * @constraint call only when a temporal stage is active
+ */
+declare function ensureVelocityOutput(pass: IVelocityRenderPass): MRTNode;
+/**
+ * Returns the velocity texture node after ensuring the pass writes it.
+ * @situation read screen-space motion for a temporal stage
+ */
+declare function velocityTexture(pass: IVelocityRenderPass): Node;
+/**
+ * Gives a composed TSL graph the velocity source used by temporal nodes.
+ * Plain game values are returned unchanged, which keeps the chain's diagnostic seam lightweight.
+ * @situation hand the provisioned velocity source through a composed temporal graph
+ */
+declare function withVelocityContext<T>(node: T, source: Node): T;
+/**
+ * Captures instance matrices at the framework's pre-render boundary and enables previous data on
+ * every renderable in the graph. The previous snapshot is never the array the game writes next.
+ * @situation retain previous transforms for animated and instanced renderables
+ * @constraint call `update()` after gameplay writes and `commit()` after the render
+ */
+declare class VelocityTracker {
+    #private;
+    /** Schedule the committed snapshot that the current colour and velocity frame must read. */
+    update(root: Object3D): void;
+    /** Commit transforms after the renderer has consumed the scheduled velocity frame. */
+    commit(root: Object3D): void;
+    /** Restore caller-owned flags and release all retained frame snapshots. */
+    clear(): void;
+    private enable;
+    private captureWorld;
+    private captureBones;
+    private captureInstance;
+    private captureBatch;
+    private commitInstance;
+    private restore;
+}
+/**
+ * Reads the scheduled previous instance/sub-draw array for conformance tests and renderer adapters.
+ * @situation inspect the previous instance frame at a renderer adapter boundary
+ */
+declare function readVelocityPreviousMatrices(object: Object3D): Float32Array | undefined;
+/**
+ * Reads the scheduled previous world matrix for conformance tests and renderer adapters.
+ * @situation inspect the previous rigid transform at a renderer adapter boundary
+ */
+declare function readVelocityPreviousWorldMatrix(object: Object3D): Matrix4 | undefined;
+/**
+ * Reads the scheduled previous bone array for conformance tests and renderer adapters.
+ * @situation inspect the previous skinned pose at a renderer adapter boundary
+ */
+declare function readVelocityPreviousBoneMatrices(object: Object3D): Float32Array | undefined;
+
+/** The marker shared by render-chain logs, playtests, and native diagnostics. */
+declare const RENDER_CHAIN_MARKER = "TN_RENDER_CHAIN";
+/** Canonical order for the stages a game may request. */
+declare const RENDER_CHAIN_STAGE_ORDER: readonly ["probeVolume", "ambientOcclusion", "ssgi", "godRays", "ssr", "denoise", "temporalReproject", "taa", "traa", "motionBlur", "sharpen", "bloom", "vignette", "lensDistortion", "sparkle", "gradualBackground"];
+type RenderChainStageName = (typeof RENDER_CHAIN_STAGE_ORDER)[number];
+/** Built-in stage names plus an opaque id owned by the game that supplied the stage. */
+type RenderChainStageId = RenderChainStageName | (string & {});
+type RenderChainTier = "high" | "medium" | "low" | "off";
+type RenderChainTierRequest = RenderChainTier | "auto";
+type RenderChainSource = "pinned" | "auto";
+type RenderChainVelocitySource = "mrt" | "per-object" | null;
+interface IRenderChainVelocityMeasurement {
+    /** Monotonic frame number derived from the stage's completed velocity result. */
+    readonly frame: number;
+    /** Share of result pixels whose temporal history was rejected in that frame. */
+    readonly rejectionFraction: number;
+}
+interface IRenderChainVelocityResult {
+    /** Monotonic frame number from the active temporal stage's completed result. */
+    readonly frame: number;
+    /** One binary value per result pixel: one means the temporal history was rejected. */
+    readonly rejectionMask: ArrayLike<number>;
+}
+interface IRenderChainRenderer {
+    readonly kind: RendererKind;
+    readonly raw: unknown;
+    clearOutputNode?(): void;
+    /** Internal renderer seam used to turn on core-owned previous-frame bookkeeping for active temporal stages. */
+    setRenderChainVelocityEnabled?(enabled: boolean): void;
+    /** Install a graph and identify the authored world pass that follows the rendered scene root. */
+    setOutputNode(node: unknown, worldPass?: unknown): void;
+}
+/** Quality values are algorithm parameters, not appearance values. Templates own the latter. */
+declare const RENDER_CHAIN_TIERS: {
+    readonly high: {
+        readonly denoiseIterations: 3;
+        readonly sliceCount: 3;
+        readonly stepCount: 16;
+    };
+    readonly low: {
+        readonly denoiseIterations: 1;
+        readonly sliceCount: 1;
+        readonly stepCount: 12;
+    };
+    readonly medium: {
+        readonly denoiseIterations: 2;
+        readonly sliceCount: 2;
+        readonly stepCount: 8;
+    };
+    readonly off: {
+        readonly denoiseIterations: 0;
+        readonly sliceCount: 0;
+        readonly stepCount: 0;
+    };
+};
+interface IRenderChainVelocityRequest {
+    /** The scene pass that owns the shared velocity output. */
+    pass?: IVelocityRenderPass;
+    /** Treat the renderer's MRT velocity output as provisioned. */
+    mrt?: boolean;
+    /** Treat objects carrying `userData.useVelocity === true` as provisioned. */
+    objectFlags?: boolean;
+    /** Alias accepted by integrations that call this route per-object velocity. */
+    perObject?: boolean;
+    /**
+     * Compatibility source for completed temporal measurements. The stage reader wins when it
+     * returns a result; this callback is consulted when an integration cannot expose that reader.
+     */
+    rejectionMeasurement?: () => IRenderChainVelocityMeasurement | undefined;
+    /** Explicit route, useful for a native host whose MRT is not introspectable from JavaScript. */
+    source?: Exclude<RenderChainVelocitySource, null>;
+}
+interface IRenderChainRequest {
+    /** Built-ins use canonical order; authored stages use their supplied anchor order. */
+    stages?: readonly RenderChainStageId[];
+    /** A fixed tier pins quality; `auto` enables the measured frame-budget ladder. */
+    tier?: RenderChainTierRequest;
+    velocity?: IRenderChainVelocityRequest;
+}
+interface IRenderChainStageContext {
+    readonly tier: RenderChainTier;
+    readonly velocity: IRenderChainVelocityReport;
+    /** TSL source handed to temporal stages when the request owns a scene pass. */
+    readonly velocityNode?: Node;
+    readonly quality: (typeof RENDER_CHAIN_TIERS)[RenderChainTier];
+}
+interface IRenderChainStage {
+    readonly name: RenderChainStageId;
+    /** Place an authored stage immediately before this built-in or supplied stage. */
+    readonly before?: RenderChainStageId;
+    /** Place an authored stage immediately after this built-in or supplied stage. */
+    readonly after?: RenderChainStageId;
+    readonly build: (input: unknown, context: IRenderChainStageContext) => unknown;
+    /** Stages below this tier are named as dropped instead of silently changing the graph. */
+    readonly minimumTier?: RenderChainTier;
+    /** Return a reason to drop the stage on this target, or true when it is available. */
+    readonly available?: (context: IRenderChainStageContext) => boolean | string;
+    /** Read the completed velocity result after rendering; the chain derives its rejection fraction. */
+    readonly readVelocityResult?: (node: unknown) => IRenderChainVelocityResult | undefined;
+    /** Defaults from the canonical stage name for the temporal stages. */
+    readonly requiresVelocity?: boolean;
+    /** Release resources allocated while building this stage's graph. */
+    readonly dispose?: () => void;
+}
+interface IRenderChainDroppedStage {
+    readonly name: RenderChainStageId;
+    readonly reason: string;
+}
+interface IRenderChainVelocityReport {
+    readonly provisioned: boolean;
+    readonly required: boolean;
+    readonly source: RenderChainVelocitySource;
+    readonly rejectionFraction?: number;
+    readonly measurementFrame?: number;
+}
+interface IRenderChainApplied {
+    readonly contributions: readonly {
+        readonly graphOutputChanged: boolean;
+        readonly name: RenderChainStageId;
+    }[];
+    readonly dropped: readonly IRenderChainDroppedStage[];
+    readonly requested: readonly RenderChainStageId[];
+    readonly source: RenderChainSource;
+    readonly stages: readonly RenderChainStageId[];
+    readonly tier: RenderChainTier;
+    readonly velocity: IRenderChainVelocityReport;
+}
+interface IRenderChainMarker {
+    readonly applied: IRenderChainApplied;
+    readonly marker: typeof RENDER_CHAIN_MARKER;
+}
+interface IRenderChainBudgetWindow {
+    /** Compilation-contaminated windows remain observable but cannot drive quality changes. */
+    readonly surface?: Pick<NonNullable<IFrameBudgetWindow["surface"]>, "compiling">;
+    readonly phases: {
+        readonly render: Pick<IFrameBudgetWindow["phases"]["render"], "p95">;
+    };
+}
+interface IRenderChainOptions {
+    readonly renderer: IRenderChainRenderer;
+    readonly input?: unknown;
+    /** Explicit scene pass for output retargeting; avoids traversing a composed graph to find it. */
+    readonly worldPass?: unknown;
+    readonly report?: (line: string) => void;
+    readonly request?: IRenderChainRequest;
+    readonly stages?: readonly IRenderChainStage[];
+    readonly targetFps?: number;
+    /** Number of consecutive over-budget windows before the automatic ladder steps down. */
+    readonly dwellWindows?: number;
+    /** Optional scene-like traversal for detecting `userData.useVelocity` flags. */
+    readonly scene?: {
+        traverse(callback: (object: {
+            userData?: Record<string, unknown>;
+        }) => void): void;
+    };
+}
+/**
+ * Read the last chain marker associated with a renderer or its raw renderer.
+ * @situation expose the render tier and dropped-stage reasons to a playtest
+ * @situation inspect whether a temporal pass received velocity
+ * @constraint an absent value means no chain was installed and must fail a chain assertion
+ * @example const chain = readRenderChainReport(ctx.renderer);
+ */
+declare function readRenderChainReport(renderer: unknown): IRenderChainMarker | undefined;
+/** JSON-safe observation used by the browser and native playtest bridges. */
+declare function readRenderChainObservation(renderer: unknown): IRenderChainMarker["applied"] | undefined;
+/**
+ * Compose game-provided nodes through one ordered, measured, honest render seam.
+ *
+ * The chain owns only stage ordering, availability, velocity provisioning and quality selection.
+ * Every stage factory is supplied by the game/template, so this module never chooses a material,
+ * colour, light, shader or post-processing look.
+ */
+declare class RenderChain {
+    #private;
+    constructor(renderer: IRenderChainRenderer, options?: Omit<IRenderChainOptions, "renderer">);
+    constructor(options: IRenderChainOptions);
+    get applied(): IRenderChainApplied;
+    get disposed(): boolean;
+    /** Rebuild and install the current tier. */
+    apply(): IRenderChainApplied;
+    /** Samples the active temporal stage's completed velocity result after rendering. */
+    observeFrame(): IRenderChainApplied;
+    /** Feed the chain the same render-window evidence used by the frame budget. */
+    observeFrameBudget(window: IRenderChainBudgetWindow): RenderChainTier;
+    dispose(): void;
+}
+
+type RendererKind = "webgpu" | "webgl2";
+/**
+ * Put transient meshes through the renderer's first-use shader path during loading.
+ *
+ * A prewarmed mesh stays in the requested subtree with zero opacity. Do not hide transient effects
+ * with `.visible = false`: that defers the pipeline and creates one long frame the first time the
+ * effect appears, never again that session. Ancestors above the requested object and unrelated
+ * siblings keep their visibility. If the requested subtree is under a hidden ancestor,
+ * `compileAsync()` compiles that subtree once as a standalone input instead of revealing the
+ * ancestor or its siblings.
+ */
+declare function prewarm(object: Object3D | readonly Object3D[]): void;
+interface IRendererLike {
+    readonly domElement: HTMLCanvasElement;
+    readonly kind: RendererKind;
+    readonly raw: unknown;
+    /**
+     * The underlying renderer's statistics (`render.drawCalls`, `render.triangles`, …).
+     *
+     * Throws when the running renderer has none — the same fail-closed shape as `setOutputNode` —
+     * because a game that cannot count its own draws cannot apply a draw-count lever on evidence.
+     */
+    get info(): unknown;
+    /**
+     * Builds and compiles a scene's pipelines before anything draws it.
+     *
+     * On a phone each distinct shader is compiled the first time something using it is drawn, which
+     * happens inside a frame the player is watching: 2,500 ms of a 2,882 ms Pixel 8 cold start sits
+     * between the bundle finishing and the first frame reaching the display. Calling this during
+     * load moves that cost somewhere the player is already waiting.
+     *
+     * It is on the wrapper for one reason: without it a game must cast through `.raw` to warm up,
+     * and a game that cannot warm up without a cast will not warm up.
+     */
+    compileAsync(scene: Object3D, camera: Camera, targetScene?: Object3D): Promise<void>;
+    /** A warm-up may outlive its caller's timeout; its render targets must remain alive. */
+    readonly compiling?: boolean;
+    /** Compilation starts, including work that settles entirely between rendered frames. */
+    readonly compileCount?: number;
+    /** The bounded, fail-closed pipeline observation for this renderer, when enabled. */
+    readonly pipelineCensus?: () => IPipelineCensus;
+    /**
+     * What alpha antialiasing did with the multisampled surface, and why, when it did nothing.
+     *
+     * MSAA resolves triangle edges; a cutout silhouette is carved inside the triangle by an alpha
+     * test and resolves through the coverage mask or not at all. This is where to read whether the
+     * samples this surface pays for reach the game's foliage, fences and hair.
+     *
+     * Optional on the interface for the same reason the render-chain seams are: a stub renderer
+     * implements the drawing contract, not every report. `createRenderer` always provides it, and
+     * the `TN_ALPHA_ANTIALIASING` marker is printed either way, so nothing is only readable here.
+     */
+    alphaAntialiasing?: () => IAlphaAntialiasingReport;
+    compute(node: unknown): void;
+    /**
+     * Copies one GPU storage attribute back to the CPU, asynchronously.
+     *
+     * It is on the wrapper for the same reason `compute` is: the call is WebGPU-only and a game that
+     * must cast through `.raw` to read its own simulation will either not read it or read it wrong.
+     * The copy is asynchronous by nature — the caller gets the bytes some frames after the frame
+     * that produced them, and `GPUReadback` is what turns that latency into a reported number
+     * instead of a silent one.
+     */
+    readback(attribute: unknown): Promise<ArrayBuffer>;
+    render(scene: Object3D, camera: Camera): void;
+    /** Draws after the world without clearing or passing through the world's output pipeline. */
+    renderOverlay(scene: Object3D, camera: Camera): void;
+    /** Removes the output pipeline installed by a render-chain. */
+    clearOutputNode?(): void;
+    /** Creates the core-owned chain seam without making generated render source import the package. */
+    createRenderChain?: (options: Omit<IRenderChainOptions, "renderer">) => RenderChain;
+    /** Feeds automatic render-chain tiers the completed frame-budget window. */
+    observeRenderChainBudget?: (window: IRenderChainBudgetWindow) => void;
+    /** Samples render-chain telemetry after the renderer completes a frame. */
+    observeRenderChainFrame?: () => void;
+    /** Whether the active chain requested core-owned per-object velocity history. */
+    renderChainUsesPerObjectVelocity?: () => boolean;
+    /** Internal callback used by RenderChain; games should request velocity through the chain. */
+    setRenderChainVelocityEnabled?: (enabled: boolean) => void;
+    /** Installs a graph; pass the authored world pass when the graph contains auxiliary passes. */
+    setOutputNode(node: unknown, worldPass?: unknown): void;
+    setSize(width: number, height: number, updateStyle?: boolean): void;
+    /**
+     * The GPU time the last resolved frame actually cost, in milliseconds, or `undefined` when the
+     * adapter has no `timestamp-query` and there is nothing to report.
+     *
+     * Every GPU number in this repository's performance record before this was wall-clock algebra:
+     * ablate scene content, difference a blocking device poll in a diagnostic build that never
+     * ships. This is the measurement itself. Resolving is asynchronous and off the frame path — the
+     * caller reads whatever the last resolve produced.
+     */
+    gpuFrameMs(): number | undefined;
+    /** Age in Three.js frame IDs of the resolved render timestamp; absent when unobservable. */
+    gpuFrameAge?(): number | undefined;
+    /** Starts a resolve of the GPU timestamps for the frames drawn since the last call. */
+    resolveGpuFrame(): void;
+    /**
+     * Moves the drawing-buffer scale, deferring while a compile retains its targets. The adaptive scaler is the only
+     * caller; a pinned game never reaches this, which is what makes "pinned" mean pinned.
+     */
+    setResolutionScale(scale: number, scaleSource: "auto" | "auto-pinned"): void;
+    /**
+     * What this renderer is actually drawing at. Read once per frame-budget window so every fps
+     * number is self-describing; a record and a tree once disagreed about the scale for a whole
+     * session because nothing in the measurement could say which one produced it.
+     */
+    surface(): IFrameSurfaceState;
+    dispose(): void;
+}
+interface IRendererPlatformSource {
+    createCanvas(): HTMLCanvasElement;
+    hasWebGPU(): boolean;
+    observeResize(canvas: HTMLCanvasElement, resize: () => void): () => void;
+    readSize(canvas: HTMLCanvasElement): readonly [width: number, height: number];
+}
+interface IRendererOptions {
+    /**
+     * Resolves alpha-tested cutout silhouettes — foliage, fences, hair — through the multisample
+     * coverage mask instead of a binary `discard`. Defaults to true, and does nothing at all on a
+     * single-sampled surface, which it reports rather than pretends. Godot's
+     * `alpha_antialiasing_mode`, in Three.js's `alphaToCoverage`.
+     */
+    alphaAntialiasing?: boolean;
+    /** Requests multisample antialiasing from the renderer. Defaults to true. */
+    antialias?: boolean;
+    canvas?: HTMLCanvasElement;
+    preferWebGPU?: boolean;
+    /** CSS-pixel multiplier for the drawing buffer. The default is intentional DPR 1. */
+    resolutionScale?: number;
+    /** Whether the game pinned that scale or the engine chose it. Reported, never inferred. */
+    scaleSource?: "pinned" | "auto" | "auto-pinned";
+    /**
+     * Physical pixels per logical (CSS) pixel of the canvas this draws into. Default: the device's
+     * own `devicePixelRatio` on both runtimes (unified 2026-09-01; web's old DPR-1 buffer read as
+     * pixelation on any HiDPI display). The resolution scaler composes on top, so an unaffordable
+     * density is trimmed by scaler rungs rather than by the developer. An explicit value wins on
+     * both runtimes.
+     */
+    pixelRatio?: number;
+    /** Where convention markers go. Defaults to the console, exactly as the render chain reports. */
+    report?: (line: string) => void;
+    /**
+     * Bounded pipeline detail for a real launch capture. It is on by default so a town does not
+     * need an instrumented build; pass `false` for an identical-build overhead control.
+     */
+    pipelineCensus?: false | {
+        readonly limit?: number;
+    };
+    source?: IRendererPlatformSource;
+    webgpuFactory?: (canvas: HTMLCanvasElement, options: Readonly<{
+        antialias: boolean;
+    }>) => Promise<unknown> | unknown;
+    webgl2Factory?: (canvas: HTMLCanvasElement, options: Readonly<{
+        antialias: boolean;
+    }>) => unknown;
+}
+
+export { readRenderChainObservation as $, type IVelocityRenderPass as A, PIPELINE_CENSUS_VERSION as B, PipelineCensus as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type PipelineCensusMode as E, FRAME_BUDGET_MARKER as F, type PipelineCensusStatus as G, RENDER_CHAIN_STAGE_ORDER as H, type IRendererLike as I, RENDER_CHAIN_TIERS as J, RenderChain as K, type RenderChainSource as L, type RenderChainStageId as M, type RenderChainStageName as N, type RenderChainTier as O, PIPELINE_CENSUS_CAPABILITY as P, type RenderChainTierRequest as Q, RENDER_CHAIN_MARKER as R, type RenderChainVelocitySource as S, VELOCITY_PREVIOUS_BONE_MATRICES as T, VELOCITY_PREVIOUS_INSTANCE_MATRICES as U, VELOCITY_OUTPUT_NAME as V, VELOCITY_PREVIOUS_WORLD_MATRIX as W, VelocityTracker as X, createPipelineCensus as Y, ensureVelocityOutput as Z, prewarm as _, FRAME_BUDGET_PHASES as a, readRenderChainReport as a0, readVelocityPreviousBoneMatrices as a1, readVelocityPreviousMatrices as a2, readVelocityPreviousWorldMatrix as a3, velocityTexture as a4, withVelocityContext as a5, type IRendererOptions as a6, FRAME_HITCH_MARKER as b, FrameBudget as c, type FrameBudgetPhase as d, type IFrameBudgetOptions as e, type IFrameBudgetSummary as f, type IFrameBudgetWindow as g, type IFramePhaseSample as h, type IPipelineCensus as i, type IPipelineCensusCounts as j, type IPipelineCensusEvent as k, type IPipelineCensusOptions as l, type IPipelineProvenance as m, type IPipelineShaderObservation as n, type IRenderChainApplied as o, type IRenderChainBudgetWindow as p, type IRenderChainDroppedStage as q, type IRenderChainOptions as r, type IRenderChainRenderer as s, type IRenderChainRequest as t, type IRenderChainStage as u, type IRenderChainStageContext as v, type IRenderChainVelocityMeasurement as w, type IRenderChainVelocityReport as x, type IRenderChainVelocityRequest as y, type IRenderChainVelocityResult as z };