@haiyue/extensions 0.1.0 → 0.2.0

package/dist/ray-tracing/hybrid/types.d.ts

@@ -0,0 +1,144 @@
+import type { RayPackedAcceleration } from '../acceleration/index.js';
+export type RayHybridEffect = 'shadow' | 'reflection' | 'ao';
+export type RayHybridResolution = 'full' | 'half';
+export type RayHybridDebugView = 'composite' | RayHybridEffect;
+export type RayHybridPhase = 'admission' | 'plan' | 'upload' | 'shadow' | 'reflection' | 'ao' | 'composite' | 'lifecycle';
+export interface RayHybridDiagnostic {
+    readonly phase: RayHybridPhase;
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly context: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface RayHybridTemporalOptions {
+    readonly enabled?: boolean;
+    readonly feedback?: number;
+}
+interface BaseEffectOptions {
+    readonly enabled?: boolean;
+    readonly resolution?: RayHybridResolution;
+    readonly raysPerPixel?: 1 | 2 | 4;
+    readonly maxRaysPerFrame?: number;
+    readonly bias?: number;
+    readonly strength?: number;
+    readonly temporal?: RayHybridTemporalOptions;
+}
+export interface RayHybridShadowOptions extends BaseEffectOptions {
+    readonly maxDistance?: number;
+    readonly angularRadius?: number;
+}
+export interface RayHybridReflectionOptions extends BaseEffectOptions {
+    readonly maxDistance?: number;
+    readonly maxRoughness?: number;
+}
+export interface RayHybridAoOptions extends BaseEffectOptions {
+    readonly radius?: number;
+}
+export interface RayHybridOptions {
+    readonly shadow?: RayHybridShadowOptions;
+    readonly reflection?: RayHybridReflectionOptions;
+    readonly ao?: RayHybridAoOptions;
+    readonly debugView?: RayHybridDebugView;
+    readonly transparentPolicy?: 'skip';
+    readonly sceneColorSpace?: 'linear' | 'srgb';
+    readonly coexistence?: {
+        readonly shadowMap?: 'multiply';
+        readonly ssao?: 'multiply';
+        readonly reflection?: 'additive-clamped' | 'prefer-existing';
+    };
+}
+export interface RayHybridExistingEffects {
+    readonly shadowMap?: boolean;
+    readonly ssao?: boolean;
+    readonly planarReflection?: boolean;
+    readonly ssr?: boolean;
+}
+export interface RayHybridFrameRevision {
+    readonly scene: string;
+    readonly camera: string;
+    readonly depth: string;
+    readonly normal: string;
+    readonly material: string;
+    readonly sceneColor: string;
+}
+export interface RayHybridFrameInputs {
+    readonly viewId: string;
+    readonly width: number;
+    readonly height: number;
+    readonly acceleration: RayPackedAcceleration;
+    /** Borrowed raster resources. This runtime never destroys them. */
+    readonly depth: GPUTexture;
+    readonly normal: GPUTexture;
+    readonly material: GPUTexture;
+    readonly sceneColor: GPUTexture;
+    readonly inverseViewProjection: readonly number[];
+    readonly viewProjection: readonly number[];
+    readonly cameraOrigin: readonly [number, number, number];
+    readonly directionalLight: readonly [number, number, number];
+    readonly environmentColor?: readonly [number, number, number];
+    readonly revision: RayHybridFrameRevision;
+    readonly existingEffects?: RayHybridExistingEffects;
+}
+export interface RayHybridResolvedEffect {
+    readonly effect: RayHybridEffect;
+    readonly enabled: boolean;
+    readonly resolution: RayHybridResolution;
+    readonly width: number;
+    readonly height: number;
+    readonly raysPerPixel: 1 | 2 | 4;
+    readonly rayCount: number;
+    readonly maxRaysPerFrame: number;
+    readonly temporalEnabled: boolean;
+    readonly temporalFeedback: number;
+    readonly historyKey: string;
+    readonly parameters: Readonly<Record<string, number>>;
+}
+export interface RayHybridFrameContract {
+    readonly status: 'ready' | 'bypassed' | 'failed';
+    readonly width: number;
+    readonly height: number;
+    readonly effects: Readonly<Record<RayHybridEffect, RayHybridResolvedEffect>>;
+    readonly debugView: RayHybridDebugView;
+    readonly sceneColorSpace: 'linear' | 'srgb';
+    readonly diagnostics: readonly RayHybridDiagnostic[];
+}
+export interface RayHybridPass {
+    readonly kind: 'upload' | RayHybridEffect | 'composite' | 'consumer';
+    readonly label: string;
+    readonly enabled: boolean;
+}
+export interface RayHybridCounters {
+    readonly rays: number;
+    readonly tlasNodes: number;
+    readonly blasNodes: number;
+    readonly primitiveTests: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly transparentSkips: number;
+    readonly stackOverflows: number;
+    readonly invalidAccesses: number;
+}
+export interface RayHybridEffectStatistics {
+    readonly enabled: boolean;
+    readonly width: number;
+    readonly height: number;
+    readonly rayCount: number;
+    readonly historySamples: number;
+    readonly historyReset: boolean;
+    readonly gpuTimeNs: number | null;
+    readonly gpuTimeKind: 'timestamp-query' | 'unavailable';
+    readonly ownedBytes: number;
+    readonly counters: RayHybridCounters;
+}
+export interface RayHybridRenderResult {
+    readonly status: 'ok' | 'bypassed' | 'failed';
+    readonly outputTexture: GPUTexture | null;
+    readonly outputOwnership: 'borrowed-raster' | 'hybrid-runtime' | 'none';
+    readonly effects: Readonly<Record<RayHybridEffect, RayHybridEffectStatistics>>;
+    readonly diagnostics: readonly RayHybridDiagnostic[];
+}
+export interface RayHybridCreateResult {
+    readonly renderer: import('./runtime.js').RayHybridRenderer | null;
+    readonly diagnostics: readonly RayHybridDiagnostic[];
+}
+export {};

package/dist/ray-tracing/lifecycle/device-recovery.d.ts

@@ -0,0 +1,31 @@
+import type { RayDeviceRecoveryOwnerOptions, RayDeviceRecoveryResult, RayRecoveryDiagnostic } from './types.js';
+export declare class RayDeviceRecoveryOwner<TSource> {
+    private readonly options;
+    private device;
+    private source;
+    private bundle;
+    private controller;
+    private generationValue;
+    private destroyedValue;
+    private recoveryTask;
+    private lastRecoveryResult;
+    private readonly diagnosticValues;
+    private readonly maxRecoveryAttempts;
+    constructor(options: RayDeviceRecoveryOwnerOptions<TSource>);
+    get destroyed(): boolean;
+    get generation(): number;
+    get liveResourceCount(): number;
+    get ownedBytes(): number;
+    get diagnostics(): readonly RayRecoveryDiagnostic[];
+    initialize(device: GPUDevice, source: TSource): Promise<RayDeviceRecoveryResult>;
+    replaceSource(source: TSource): Promise<RayDeviceRecoveryResult>;
+    recoverWith(device: GPUDevice): Promise<RayDeviceRecoveryResult>;
+    awaitIdle(): Promise<RayDeviceRecoveryResult | null>;
+    destroy(): void;
+    private install;
+    private observeLoss;
+    private recoverAutomatically;
+    private releaseBundle;
+    private emit;
+    private result;
+}

package/dist/ray-tracing/lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './device-recovery.js';

package/dist/ray-tracing/lifecycle/types.d.ts

@@ -0,0 +1,37 @@
+export type RayRecoveryDiagnosticCode = 'RAY_DEVICE_LOST' | 'RAY_DEVICE_RECOVERY_REQUIRED' | 'RAY_DEVICE_RECOVERY_STARTED' | 'RAY_DEVICE_RECOVERY_COMPLETED' | 'RAY_DEVICE_RECOVERY_FAILED' | 'RAY_DEVICE_RECOVERY_EXHAUSTED' | 'RAY_DEVICE_STALE_RESOURCE_DISPOSED' | 'RAY_DEVICE_OWNER_DISPOSED';
+export interface RayRecoveryDiagnostic {
+    readonly phase: 'device-loss' | 'device-recovery' | 'lifecycle';
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly code: RayRecoveryDiagnosticCode;
+    readonly message: string;
+    readonly context: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface RayOwnedRecoverableResource {
+    readonly label: string;
+    readonly liveResourceCount: number;
+    readonly ownedBytes?: number;
+    destroy(): void;
+}
+export interface RayRecoveryResourceBundle {
+    readonly resources: readonly RayOwnedRecoverableResource[];
+    /** History generation is diagnostic evidence and must equal the active device generation. */
+    readonly historyGeneration: number;
+}
+export interface RayDeviceRecoveryOwnerOptions<TSource> {
+    readonly label: string;
+    readonly create: (device: GPUDevice, source: TSource, context: {
+        readonly generation: number;
+        readonly signal: AbortSignal;
+    }) => Promise<RayRecoveryResourceBundle>;
+    readonly acquireDevice?: (context: {
+        readonly attempt: number;
+        readonly lost: GPUDeviceLostInfo;
+    }) => Promise<GPUDevice>;
+    readonly maxRecoveryAttempts?: number;
+    readonly onDiagnostic?: (diagnostic: RayRecoveryDiagnostic) => void;
+}
+export interface RayDeviceRecoveryResult {
+    readonly status: 'ready' | 'failed' | 'stale' | 'destroyed';
+    readonly generation: number;
+    readonly diagnostics: readonly RayRecoveryDiagnostic[];
+}

package/dist/ray-tracing/material/index.d.ts

@@ -0,0 +1,2 @@
+export { packRayPbrMaterialScene } from './pack.js';
+export type { RayMaterialDiagnostic, RayMaterialPackOptions, RayMaterialPackResult, RayMaterialPhase, RayMaterialSeverity, RayPackedMaterialBuffer, RayPackedMaterialScene, RayPackedSurfaceBuffer, RayPackedTextureAtlas, RayTexturePixels, RayTextureResolver, } from './types.js';

package/dist/ray-tracing/material/pack.d.ts

@@ -0,0 +1,5 @@
+import type { World } from '@haiyue/engine/ecs';
+import type { Scene } from '@haiyue/engine/scene';
+import type { RayPackedAcceleration } from '../acceleration/index.js';
+import type { RayMaterialPackOptions, RayMaterialPackResult } from './types.js';
+export declare function packRayPbrMaterialScene(source: Scene | World, acceleration: RayPackedAcceleration, options?: RayMaterialPackOptions): RayMaterialPackResult;

package/dist/ray-tracing/material/types.d.ts

@@ -0,0 +1,63 @@
+import type { MaterialTextureSource, PbrTextureSlot } from '@haiyue/engine/material';
+import type { RayPackedAcceleration } from '../acceleration/index.js';
+export type RayMaterialSeverity = 'info' | 'warning' | 'error';
+export type RayMaterialPhase = 'extract' | 'material-pack' | 'texture-pack' | 'surface-pack';
+export interface RayMaterialDiagnostic {
+    readonly phase: RayMaterialPhase;
+    readonly severity: RayMaterialSeverity;
+    readonly code: string;
+    readonly message: string;
+    readonly context: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface RayTexturePixels {
+    readonly identity: string;
+    readonly revision: number;
+    readonly width: number;
+    readonly height: number;
+    /** Tightly packed RGBA8 texels in the source slot's declared color space. */
+    readonly data: Uint8Array | Uint8ClampedArray;
+}
+export type RayTextureResolver = (source: MaterialTextureSource, slot: PbrTextureSlot, materialIdentity: string) => RayTexturePixels | null;
+export interface RayPackedTextureAtlas {
+    readonly width: number;
+    readonly height: number;
+    readonly layerCount: number;
+    readonly bytesPerRow: number;
+    readonly data: Uint8Array;
+    readonly identities: readonly string[];
+    readonly fingerprint: string;
+}
+export interface RayPackedMaterialBuffer {
+    readonly stride: 128;
+    readonly count: number;
+    readonly data: ArrayBuffer;
+}
+export interface RayPackedSurfaceBuffer {
+    readonly stride: 128;
+    readonly count: number;
+    readonly data: ArrayBuffer;
+}
+export interface RayPackedMaterialScene {
+    readonly schemaVersion: 1;
+    readonly accelerationFingerprint: string;
+    readonly revision: string;
+    readonly fingerprint: string;
+    readonly materials: RayPackedMaterialBuffer;
+    readonly surfaces: RayPackedSurfaceBuffer;
+    readonly textures: RayPackedTextureAtlas;
+    readonly materialIdentities: readonly string[];
+    readonly diagnostics: readonly RayMaterialDiagnostic[];
+    readonly unsupportedFeatures: readonly string[];
+}
+export interface RayMaterialPackOptions {
+    readonly textureResolver?: RayTextureResolver;
+    readonly maxTextureDimension?: number;
+    readonly maxTextureLayers?: number;
+}
+export interface RayMaterialPackResult {
+    readonly packed: RayPackedMaterialScene | null;
+    readonly diagnostics: readonly RayMaterialDiagnostic[];
+}
+export interface RayMaterialSourceContext {
+    readonly acceleration: RayPackedAcceleration;
+}

package/dist/ray-tracing/reference/index.d.ts

@@ -0,0 +1,122 @@
+/** GPU-independent ray/hit semantics used as the M04 correctness oracle. */
+export type RayVec3 = readonly [number, number, number];
+export type RayBarycentric = readonly [number, number, number];
+export type RayMatrix4 = readonly number[];
+export declare const RAY_REFERENCE_SEMANTICS: Readonly<{
+    readonly schemaVersion: 1;
+    readonly directionLengthEpsilon: 1e-12;
+    readonly parallelRelativeEpsilon: 1e-12;
+    readonly degenerateRelativeEpsilon: 1e-24;
+    readonly rangeEpsilon: 1e-12;
+    readonly tieRelativeEpsilon: 1e-9;
+    readonly faceRule: "front when dot(ray.direction, windingNormal) < 0";
+    readonly barycentricOrder: "[vertex0, vertex1, vertex2]";
+    readonly normalRule: "inverse-transpose, aligned to the world-space winding normal";
+    readonly tieBreak: "instanceId, geometryId, geometryRevision, primitiveIndex, entityId";
+}>;
+export type RayDiagnosticSeverity = 'info' | 'warning' | 'error';
+export interface RayDiagnostic {
+    readonly phase: 'reference' | 'scene-extraction';
+    readonly severity: RayDiagnosticSeverity;
+    readonly code: string;
+    readonly message: string;
+    readonly context: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface RayInput {
+    readonly origin: RayVec3;
+    readonly direction: RayVec3;
+    readonly tMin?: number;
+    readonly tMax?: number;
+}
+export interface CanonicalRay {
+    readonly origin: RayVec3;
+    readonly direction: RayVec3;
+    readonly tMin: number;
+    readonly tMax: number;
+}
+export interface RayPrimitiveIdentity {
+    readonly instanceId: string;
+    readonly entityId: string;
+    readonly geometryId: string;
+    readonly geometryRevision: number;
+    readonly primitiveIndex: number;
+}
+export interface RaySceneTriangleGeometry {
+    readonly kind: 'triangle-mesh';
+    readonly geometryId: string;
+    readonly revision: number;
+    readonly positions: readonly number[];
+    readonly normals: readonly number[] | null;
+    readonly indices: readonly number[] | null;
+    readonly primitiveCount: number;
+}
+export interface RaySceneInstance {
+    readonly instanceId: string;
+    readonly entityId: string;
+    readonly geometryId: string;
+    readonly geometryRevision: number;
+    readonly transform: RayMatrix4;
+}
+export interface RaySceneAnalyticSphere {
+    readonly kind: 'sphere';
+    readonly identity: RayPrimitiveIdentity;
+    readonly center: RayVec3;
+    readonly radius: number;
+    readonly transform: RayMatrix4;
+}
+export interface RayReferenceScene {
+    readonly geometries: readonly RaySceneTriangleGeometry[];
+    readonly instances: readonly RaySceneInstance[];
+    readonly analyticPrimitives: readonly RaySceneAnalyticSphere[];
+}
+export interface RayHit {
+    readonly primitiveKind: 'triangle' | 'sphere';
+    readonly identity: RayPrimitiveIdentity;
+    readonly t: number;
+    readonly position: RayVec3;
+    readonly barycentric: RayBarycentric | null;
+    readonly frontFace: boolean;
+    /** World-space normal from primitive winding/implicit surface, never face-flipped. */
+    readonly geometricNormal: RayVec3;
+    /** Inverse-transpose normal aligned to geometricNormal, never face-flipped. */
+    readonly shadingNormal: RayVec3;
+    /** shadingNormal oriented against the incoming ray. */
+    readonly facingNormal: RayVec3;
+}
+export interface RayTraceResult {
+    readonly ray: CanonicalRay | null;
+    readonly hit: RayHit | null;
+    readonly diagnostics: readonly RayDiagnostic[];
+    readonly testedPrimitiveCount: number;
+}
+export interface RayHitExpectation {
+    readonly primitiveKind?: RayHit['primitiveKind'];
+    readonly identity?: Partial<RayPrimitiveIdentity>;
+    readonly t?: number;
+    readonly position?: RayVec3;
+    readonly barycentric?: RayBarycentric | null;
+    readonly frontFace?: boolean;
+    readonly geometricNormal?: RayVec3;
+    readonly shadingNormal?: RayVec3;
+    readonly facingNormal?: RayVec3;
+}
+export interface RayReferenceCorpusCase {
+    readonly id: string;
+    readonly scene: RayReferenceScene;
+    readonly ray: RayInput;
+    readonly expected: RayHitExpectation | null;
+    readonly tolerance: number;
+}
+export declare function traceRayBruteForce(scene: RayReferenceScene, input: RayInput): RayTraceResult;
+export declare function compareRayHit(expected: RayHitExpectation | null, actual: RayHit | null, tolerance?: number): readonly string[];
+export declare function formatRayHitMismatch(caseId: string, mismatches: readonly string[]): string;
+export declare function replayRayReferenceCorpus(): Readonly<{
+    passed: boolean;
+    cases: readonly Readonly<{
+        id: string;
+        passed: boolean;
+        message: string;
+        result: RayTraceResult;
+    }>[];
+}>;
+export declare const RAY_REFERENCE_CORPUS: readonly RayReferenceCorpusCase[];

package/dist/ray-tracing/renderer/index.d.ts

@@ -0,0 +1,7 @@
+export { createRayPathBindGroupLayouts, RAY_PATH_LAYOUT } from './layout.js';
+export { createRayPathRenderPlan } from './plan.js';
+export { createRayPathPrimaryRay, evaluateRayPbrDirectReference, toneMapRayColor } from './reference.js';
+export type { RayPbrSurfaceReference } from './reference.js';
+export { RayPathTracingRenderer } from './runtime.js';
+export { extractRayPathSceneFacts } from './scene.js';
+export type { RayPathCamera, RayPathCounters, RayPathDiagnostic, RayPathDiagnosticPhase, RayPathDiagnosticSeverity, RayPathEnvironment, RayPathLight, RayPathMemory, RayPathRendererCreateResult, RayPathRenderOptions, RayPathRenderPlan, RayPathRenderPlanPass, RayPathRenderResult, RayPathSceneExtractionOptions, RayPathSceneExtractionResult, RayPathSceneFacts, RayToneMapping, } from './types.js';

package/dist/ray-tracing/renderer/layout.d.ts

@@ -0,0 +1,20 @@
+export declare const RAY_PATH_LAYOUT: Readonly<{
+    artifactFormat: "haiyue-precompiled-shader-artifact";
+    artifactVersion: 2;
+    artifactHash: "6154b14932ab083ad96da72fcf762c6da5d4a5f368717bb15e1a5671bdf5d8b2";
+    compilerVersion: "shader-language-ray-path-tracing-v1";
+    tracePassId: "ray-path-tracing";
+    tonePassId: "ray-tone-mapping";
+    workgroupSizeX: 8;
+    workgroupSizeY: 8;
+    materialStride: 128;
+    surfaceStride: 128;
+    parameterBytes: 128;
+    lightBytes: 512;
+    diagnosticBytes: 48;
+    maxLights: 8;
+    maxBounces: 8;
+    requiredStorageBuffersPerShaderStage: 8;
+    requiredBindingsPerBindGroup: 15;
+}>;
+export declare function createRayPathBindGroupLayouts(device: GPUDevice): readonly [GPUBindGroupLayout, GPUBindGroupLayout];

package/dist/ray-tracing/renderer/plan.d.ts

@@ -0,0 +1,2 @@
+import type { RayPathRenderPlan } from './types.js';
+export declare function createRayPathRenderPlan(width: number, height: number): RayPathRenderPlan;

package/dist/ray-tracing/renderer/reference.d.ts

@@ -0,0 +1,17 @@
+import type { RayVec3 } from '../reference/index.js';
+import type { RayPathCamera, RayToneMapping } from './types.js';
+export interface RayPbrSurfaceReference {
+    readonly baseColor: RayVec3;
+    readonly metallic: number;
+    readonly roughness: number;
+    readonly ior: number;
+    readonly specularFactor: number;
+    readonly specularColor: RayVec3;
+    readonly normal: RayVec3;
+}
+export declare function createRayPathPrimaryRay(camera: RayPathCamera, width: number, height: number, x: number, y: number): Readonly<{
+    origin: RayVec3;
+    direction: RayVec3;
+}>;
+export declare function evaluateRayPbrDirectReference(surface: RayPbrSurfaceReference, viewDirection: RayVec3, lightDirection: RayVec3, radiance: RayVec3): RayVec3;
+export declare function toneMapRayColor(linear: RayVec3, exposure?: number, operator?: RayToneMapping): RayVec3;

package/dist/ray-tracing/renderer/runtime.d.ts

@@ -0,0 +1,39 @@
+import type { RayPackedAcceleration } from '../acceleration/index.js';
+import type { RayPackedMaterialScene } from '../material/index.js';
+import type { RayPathRendererCreateResult, RayPathRenderOptions, RayPathRenderResult, RayPathSceneFacts } from './types.js';
+export declare class RayPathTracingRenderer {
+    readonly artifactHash: "6154b14932ab083ad96da72fcf762c6da5d4a5f368717bb15e1a5671bdf5d8b2";
+    readonly accelerationFingerprint: string;
+    readonly materialFingerprint: string;
+    private readonly _device;
+    private readonly _acceleration;
+    private readonly _materials;
+    private readonly _buffers;
+    private _layouts;
+    private _tracePipeline;
+    private _tonePipeline;
+    private _materialTexture;
+    private _defaultEnvironment;
+    private _materialSampler;
+    private _environmentSampler;
+    private _hdrTexture;
+    private _outputTexture;
+    private _width;
+    private _height;
+    private _destroyed;
+    private _rendering;
+    private _generation;
+    private _lostMessage;
+    private readonly _uncapturedErrors;
+    private readonly _uncapturedHandler;
+    private constructor();
+    static create(device: GPUDevice, acceleration: RayPackedAcceleration, materials: RayPackedMaterialScene): Promise<RayPathRendererCreateResult>;
+    get destroyed(): boolean;
+    get outputTexture(): GPUTexture | null;
+    get liveResourceCount(): number;
+    render(facts: RayPathSceneFacts, options: RayPathRenderOptions): Promise<RayPathRenderResult>;
+    destroy(): void;
+    private resize;
+    private staticBytes;
+    private memory;
+}

package/dist/ray-tracing/renderer/scene.d.ts

@@ -0,0 +1,4 @@
+import type { World } from '@haiyue/engine/ecs';
+import type { Scene } from '@haiyue/engine/scene';
+import type { RayPathSceneExtractionOptions, RayPathSceneExtractionResult } from './types.js';
+export declare function extractRayPathSceneFacts(source: Scene | World, options?: RayPathSceneExtractionOptions): RayPathSceneExtractionResult;

package/dist/ray-tracing/renderer/types.d.ts

@@ -0,0 +1,115 @@
+import type { RayVec3 } from '../reference/index.js';
+export type RayPathDiagnosticPhase = 'extract' | 'upload' | 'path-tracing' | 'tone-mapping' | 'readback' | 'lifecycle';
+export type RayPathDiagnosticSeverity = 'info' | 'warning' | 'error';
+export type RayToneMapping = 'linear' | 'reinhard' | 'aces';
+export interface RayPathDiagnostic {
+    readonly phase: RayPathDiagnosticPhase;
+    readonly severity: RayPathDiagnosticSeverity;
+    readonly code: string;
+    readonly message: string;
+    readonly context: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface RayPathCamera {
+    readonly projection: 'perspective' | 'orthographic';
+    readonly origin: RayVec3;
+    readonly right: RayVec3;
+    readonly up: RayVec3;
+    /** Normalized world-space viewing direction. */
+    readonly forward: RayVec3;
+    readonly verticalFov: number;
+    readonly orthographicHeight: number;
+    readonly near: number;
+    readonly far: number;
+    readonly revision: string;
+}
+export interface RayPathLight {
+    readonly identity: string;
+    readonly type: 'ambient' | 'directional' | 'point';
+    readonly color: RayVec3;
+    readonly intensity: number;
+    /** Direction the directional light travels. */
+    readonly direction: RayVec3;
+    readonly position: RayVec3;
+    readonly range: number;
+    readonly revision: string;
+}
+export interface RayPathEnvironment {
+    readonly color: RayVec3;
+    readonly intensity: number;
+    readonly rotation: number;
+    /** Borrowed Engine texture. The renderer never destroys it. */
+    readonly texture: GPUTexture | null;
+    readonly textureVersion: number;
+    readonly revision: string;
+}
+export interface RayPathSceneFacts {
+    readonly camera: RayPathCamera;
+    readonly lights: readonly RayPathLight[];
+    readonly environment: RayPathEnvironment;
+    readonly revision: string;
+    readonly diagnostics: readonly RayPathDiagnostic[];
+}
+export interface RayPathSceneExtractionOptions {
+    readonly cameraEntityId?: number;
+    readonly maxLights?: number;
+}
+export interface RayPathSceneExtractionResult {
+    readonly facts: RayPathSceneFacts | null;
+    readonly diagnostics: readonly RayPathDiagnostic[];
+}
+export interface RayPathRenderOptions {
+    readonly width: number;
+    readonly height: number;
+    readonly maxBounces?: number;
+    readonly seed?: number;
+    readonly exposure?: number;
+    readonly toneMapping?: RayToneMapping;
+    readonly readback?: boolean;
+}
+export interface RayPathCounters {
+    readonly pixels: number;
+    readonly rays: number;
+    readonly bounces: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly shadowRays: number;
+    readonly emissiveHits: number;
+    readonly stackOverflows: number;
+    readonly invalidAccesses: number;
+}
+export interface RayPathMemory {
+    readonly accelerationBytes: number;
+    readonly materialBytes: number;
+    readonly textureBytes: number;
+    readonly outputBytes: number;
+    readonly diagnosticBytes: number;
+    readonly readbackBytes: number;
+    readonly peakBytes: number;
+    readonly liveResourceCount: number;
+}
+export interface RayPathRenderResult {
+    readonly status: 'ok' | 'failed';
+    readonly width: number;
+    readonly height: number;
+    readonly revision: string;
+    readonly outputTexture: GPUTexture | null;
+    readonly pixels: Uint8Array | null;
+    readonly counters: RayPathCounters;
+    readonly gpuTimeNs: number | null;
+    readonly gpuTimeKind: 'timestamp-query' | 'unavailable';
+    readonly memory: RayPathMemory;
+    readonly diagnostics: readonly RayPathDiagnostic[];
+}
+export interface RayPathRendererCreateResult {
+    readonly renderer: import('./runtime.js').RayPathTracingRenderer | null;
+    readonly diagnostics: readonly RayPathDiagnostic[];
+}
+export interface RayPathRenderPlanPass {
+    readonly kind: 'upload' | 'path-tracing' | 'tone-mapping' | 'consumer';
+    readonly label: string;
+}
+export interface RayPathRenderPlan {
+    readonly width: number;
+    readonly height: number;
+    readonly passes: readonly RayPathRenderPlanPass[];
+}

package/dist/ray-tracing/sampling/index.d.ts

@@ -0,0 +1,8 @@
+export { RAY_PROGRESSIVE_LAYOUT } from './layout.js';
+export { createRayProgressiveRenderPlan } from './plan.js';
+export type { RayProgressivePlanPass } from './plan.js';
+export { classifyRayProgressiveReset, createRayProgressiveAccumulationKey, createRayProgressiveFrameRevision } from './revision.js';
+export { RayProgressiveRenderer } from './runtime.js';
+export { createRayProgressiveSequenceSample } from './sequence.js';
+export { RAY_ACCUMULATION_FORMAT, RAY_PROGRESSIVE_SEQUENCE_ID, } from './types.js';
+export type { RayProgressiveAccumulationKey, RayProgressiveCreateResult, RayProgressiveDiagnostic, RayProgressiveFrame, RayProgressiveFrameRevision, RayProgressiveMemory, RayProgressiveOptions, RayProgressiveRenderResult, RayProgressiveResetEvent, RayProgressiveResetReason, RayProgressiveSequenceSample, RayProgressiveStageTiming, RayProgressiveStatistics, RayProgressiveView, } from './types.js';

package/dist/ray-tracing/sampling/layout.d.ts

@@ -0,0 +1,12 @@
+export declare const RAY_PROGRESSIVE_LAYOUT: Readonly<{
+    artifactHash: "68dbd34a27343815b6b1af275d7909c28b21bd0558b9a0aea6bc8cd54c5bc060";
+    accumulatePassId: "ray-progressive-accumulate";
+    presentPassId: "ray-progressive-present";
+    parameterBytes: 64;
+    diagnosticBytes: 16;
+    workgroupSizeX: 8;
+    workgroupSizeY: 8;
+    requiredStorageTextures: 4;
+    requiredBindings: 9;
+}>;
+export declare function createRayProgressiveLayouts(device: GPUDevice): readonly [GPUBindGroupLayout, GPUBindGroupLayout];

package/dist/ray-tracing/sampling/plan.d.ts

@@ -0,0 +1,5 @@
+export interface RayProgressivePlanPass {
+    readonly kind: 'sample' | 'accumulate' | 'denoise-temporal' | 'denoise-spatial' | 'present';
+    readonly label: string;
+}
+export declare function createRayProgressiveRenderPlan(denoise: boolean): readonly RayProgressivePlanPass[];