@threenative/core 0.1.0 → 0.3.0

package/dist/canvas-layer-CtrZHgIh.d.ts

@@ -0,0 +1,608 @@
+import * as three from 'three';
+import { Object3D, Matrix4, Camera, Vector2, Vector3, Scene, OrthographicCamera } 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;
+}
+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;
+}
+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;
+}
+/**
+ * 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;
+}
+
+/** 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];
+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 {
+    /** Stages are sorted into {@link RENDER_CHAIN_STAGE_ORDER}; an empty list is a no-op. */
+    stages?: readonly string[];
+    /** 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: RenderChainStageName;
+    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;
+}
+interface IRenderChainDroppedStage {
+    readonly name: RenderChainStageName;
+    readonly reason: string;
+}
+interface IRenderChainVelocityReport {
+    readonly provisioned: boolean;
+    readonly required: boolean;
+    readonly source: RenderChainVelocitySource;
+    readonly rejectionFraction?: number;
+    readonly measurementFrame?: number;
+}
+interface IRenderChainApplied {
+    readonly dropped: readonly IRenderChainDroppedStage[];
+    readonly requested: readonly RenderChainStageName[];
+    readonly source: RenderChainSource;
+    readonly stages: readonly RenderChainStageName[];
+    readonly tier: RenderChainTier;
+    readonly velocity: IRenderChainVelocityReport;
+}
+interface IRenderChainMarker {
+    readonly applied: IRenderChainApplied;
+    readonly marker: typeof RENDER_CHAIN_MARKER;
+}
+interface IRenderChainBudgetWindow {
+    readonly phases: {
+        readonly render: Pick<IFrameBudgetWindow["phases"]["render"], "p95">;
+    };
+}
+interface IRenderChainOptions {
+    readonly renderer: IRenderChainRenderer;
+    readonly input?: 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): Promise<void>;
+    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;
+    /** Starts a resolve of the GPU timestamps for the frames drawn since the last call. */
+    resolveGpuFrame(): void;
+    /**
+     * Moves the drawing-buffer scale, re-applying it immediately. 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 {
+    /** 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 1.
+     *
+     * Native reports a real `devicePixelRatio` and a canvas measured in logical pixels, so the
+     * buffer is `logical × pixelRatio × resolutionScale` — arithmetic that reproduces the physical
+     * surface exactly and moves no tuned game's frame. Web keeps the default of 1 and its
+     * intentional DPR-1 buffer; unifying web onto real device density is a separate decision with
+     * its own visuals gate, and this option is where it would be made.
+     */
+    pixelRatio?: number;
+    source?: IRendererPlatformSource;
+    webgpuFactory?: (canvas: HTMLCanvasElement, options: Readonly<{
+        antialias: boolean;
+    }>) => Promise<unknown> | unknown;
+    webgl2Factory?: (canvas: HTMLCanvasElement, options: Readonly<{
+        antialias: boolean;
+    }>) => unknown;
+}
+
+interface IViewportSize {
+    readonly aspect: number;
+    readonly height: number;
+    readonly width: number;
+}
+interface IViewportInsets {
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+}
+interface IViewportSafeArea extends IViewportInsets {
+    /** The safe rectangle in drawable pixel coordinates, with y measured from the top edge. */
+    readonly height: number;
+    readonly source: "full-drawable-fallback" | "measured";
+    readonly width: number;
+    readonly x: number;
+    readonly y: number;
+}
+interface IViewportOptions {
+    readonly camera: Camera;
+    readonly renderer: IRendererLike;
+    readonly source?: IViewportPlatformSource;
+}
+type ViewportResizeHandler = (size: IViewportSize) => void;
+interface IViewportPlatformSource {
+    observeResize(canvas: HTMLCanvasElement, resize: () => void): () => void;
+    readSize(canvas: HTMLCanvasElement): IViewportSize;
+    readSafeArea?(canvas: HTMLCanvasElement, size: IViewportSize): IViewportInsets | undefined;
+}
+declare class Viewport {
+    #private;
+    readonly camera: Camera;
+    readonly renderer: IRendererLike;
+    constructor(options: IViewportOptions);
+    get size(): IViewportSize;
+    get safeArea(): IViewportSafeArea;
+    projectPosition(screen: Vector2, z?: number, target?: Vector3): Vector3;
+    unprojectPosition(world: Vector3, target?: Vector2): Vector2;
+    onResize(handler: ViewportResizeHandler): () => void;
+    resize(): void;
+    dispose(): void;
+}
+
+/** A Godot-shaped render surface that is independent of the world camera and post pipeline. */
+declare class CanvasLayer {
+    #private;
+    readonly scene: Scene<three.Object3DEventMap>;
+    readonly camera: OrthographicCamera;
+    /** Declares that this layer covers the framebuffer, allowing the world pass to be skipped. */
+    opaque: boolean;
+    constructor(viewport: Pick<Viewport, "onResize" | "size">);
+    dispose(): void;
+    /** Subscribe to drawable-size changes after this layer has updated its camera. */
+    onResize(handler: (size: IViewportSize) => void): () => void;
+}
+
+export { type RenderChainTier as A, type RenderChainTierRequest as B, CanvasLayer as C, type RenderChainVelocitySource as D, VELOCITY_PREVIOUS_BONE_MATRICES as E, FRAME_BUDGET_MARKER as F, VELOCITY_PREVIOUS_INSTANCE_MATRICES as G, VELOCITY_PREVIOUS_WORLD_MATRIX as H, type IRendererLike as I, VelocityTracker as J, ensureVelocityOutput as K, prewarm as L, readRenderChainObservation as M, readRenderChainReport as N, readVelocityPreviousBoneMatrices as O, readVelocityPreviousMatrices as P, readVelocityPreviousWorldMatrix as Q, RENDER_CHAIN_MARKER as R, velocityTexture as S, withVelocityContext as T, Viewport as U, VELOCITY_OUTPUT_NAME as V, type IRendererOptions as W, type IViewportOptions as X, FRAME_BUDGET_PHASES as a, 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 IRenderChainApplied as i, type IRenderChainBudgetWindow as j, type IRenderChainDroppedStage as k, type IRenderChainOptions as l, type IRenderChainRenderer as m, type IRenderChainRequest as n, type IRenderChainStage as o, type IRenderChainStageContext as p, type IRenderChainVelocityMeasurement as q, type IRenderChainVelocityReport as r, type IRenderChainVelocityRequest as s, type IRenderChainVelocityResult as t, type IVelocityRenderPass as u, RENDER_CHAIN_STAGE_ORDER as v, RENDER_CHAIN_TIERS as w, RenderChain as x, type RenderChainSource as y, type RenderChainStageName as z };