@threenative/core 0.3.0 → 0.3.2

package/dist/{canvas-layer-CtrZHgIh.d.ts → renderer-C6hqZpoG.d.ts}

@@ -1,5 +1,4 @@
-import * as three from 'three';
-import { Object3D, Matrix4, Camera, Vector2, Vector3, Scene, OrthographicCamera } from 'three';
+import { Object3D, Matrix4, Camera } from 'three';
 import { MRTNode, Node } from 'three/webgpu';
 
 /**
@@ -72,6 +71,8 @@ interface IFrameSurfaceState {
      * 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;
@@ -112,6 +113,8 @@ interface IFrameBudgetWindow {
      * 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. */
@@ -137,6 +140,8 @@ interface IFrameBudgetOptions {
     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.
@@ -176,6 +181,170 @@ declare class FrameBudget {
     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";
 /**
@@ -258,6 +427,8 @@ 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";
@@ -324,8 +495,8 @@ interface IRenderChainVelocityRequest {
     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[];
+    /** 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;
@@ -338,7 +509,11 @@ interface IRenderChainStageContext {
     readonly quality: (typeof RENDER_CHAIN_TIERS)[RenderChainTier];
 }
 interface IRenderChainStage {
-    readonly name: RenderChainStageName;
+    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;
@@ -348,9 +523,11 @@ interface IRenderChainStage {
     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: RenderChainStageName;
+    readonly name: RenderChainStageId;
     readonly reason: string;
 }
 interface IRenderChainVelocityReport {
@@ -361,10 +538,14 @@ interface IRenderChainVelocityReport {
     readonly measurementFrame?: number;
 }
 interface IRenderChainApplied {
+    readonly contributions: readonly {
+        readonly graphOutputChanged: boolean;
+        readonly name: RenderChainStageId;
+    }[];
     readonly dropped: readonly IRenderChainDroppedStage[];
-    readonly requested: readonly RenderChainStageName[];
+    readonly requested: readonly RenderChainStageId[];
     readonly source: RenderChainSource;
-    readonly stages: readonly RenderChainStageName[];
+    readonly stages: readonly RenderChainStageId[];
     readonly tier: RenderChainTier;
     readonly velocity: IRenderChainVelocityReport;
 }
@@ -373,6 +554,8 @@ interface IRenderChainMarker {
     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">;
     };
@@ -380,6 +563,8 @@ interface IRenderChainBudgetWindow {
 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[];
@@ -459,7 +644,25 @@ interface IRendererLike {
      * 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>;
+    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.
@@ -499,10 +702,12 @@ interface IRendererLike {
      * 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, re-applying it immediately. The adaptive scaler is the only
+     * 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;
@@ -521,6 +726,13 @@ interface IRendererPlatformSource {
     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;
@@ -530,15 +742,22 @@ interface IRendererOptions {
     /** 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.
+     * 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;
@@ -548,61 +767,4 @@ interface IRendererOptions {
     }>) => 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 };
+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 };