@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/dist/debug-draw-glue.d.ts

@@ -0,0 +1,5 @@
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import type { Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame, RenderPipelineTarget } from './render-pipeline';
+export declare function addTypedDebugOverlayPass(graph: RenderGraphBuilder<RenderPipelineFrame>, output: RenderPipelineTarget): Result<void, RenderGraphError>;
+//# sourceMappingURL=debug-draw-glue.d.ts.map

package/dist/debug-draw-glue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-draw-glue.d.ts","sourceRoot":"","sources":["../src/debug-draw-glue.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACzF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEnF,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAiChC"}

package/dist/device/device-scope.d.ts

@@ -0,0 +1,83 @@
+import { type Result } from '@forgeax/engine-types';
+import { LifecycleConstructionError } from '../errors/render';
+import type { DeviceResourceKind, DeviceScopeReceipt } from './resource-types';
+export { DEVICE_RESOURCE_KINDS, type DeviceResourceKind, type DeviceScopeReceipt, } from './resource-types';
+export type DeviceScopeState = 'active' | 'retiring' | 'retired' | 'abandoned' | 'disposed';
+export interface ResourceRef<T> {
+    readonly kind: DeviceResourceKind;
+    readonly owner: string;
+    readonly generation: number;
+    readonly value: T;
+    isCurrent(scope: DeviceScope): boolean;
+    isStale(scope: DeviceScope): boolean;
+}
+export declare class DeviceResourceRef<T> implements ResourceRef<T> {
+    readonly kind: DeviceResourceKind;
+    readonly owner: string;
+    readonly generation: number;
+    readonly value: T;
+    constructor(kind: DeviceResourceKind, owner: string, generation: number, value: T);
+    isCurrent(scope: DeviceScope): boolean;
+    isStale(scope: DeviceScope): boolean;
+}
+interface OwnedResource {
+    readonly ref: DeviceResourceRef<unknown>;
+    readonly cleanup: (value: unknown) => void | Promise<void>;
+}
+export declare class DeviceScope {
+    readonly generation: number;
+    readonly owner: string;
+    readonly parent: DeviceScope | undefined;
+    private lifecycleState;
+    private readonly resources;
+    private readonly children;
+    private constructor();
+    static create(generation: number, owner: string): DeviceScope;
+    get state(): DeviceScopeState;
+    get childrenSnapshot(): readonly DeviceScope[];
+    ref<T>(kind: DeviceResourceKind, value: T): ResourceRef<T>;
+    accepts(ref: ResourceRef<unknown>): boolean;
+    isAlive(): boolean;
+    resourceDelta(): number;
+    /** @internal */
+    _adopt<T>(kind: DeviceResourceKind, value: T, cleanup: (value: T) => void | Promise<void>): ResourceRef<T>;
+    /** @internal */
+    _clearResources(): OwnedResource[];
+    retire(): void;
+    abandon(): void;
+    dispose(): void;
+    replace(generation: number, resources: readonly LifecycleResourceSpec<unknown>[]): Promise<LifecycleResult>;
+    /** @internal */
+    _receipt(): DeviceScopeReceipt;
+}
+export interface LifecycleResourceSpec<T> {
+    readonly kind: DeviceResourceKind;
+    readonly create: () => T | Promise<T>;
+    readonly cleanup: (value: T) => void | Promise<void>;
+}
+export interface LifecycleCleanupFailure {
+    readonly resourceKind: DeviceResourceKind;
+    readonly cause: unknown;
+}
+export interface LifecycleFailure {
+    readonly primary: LifecycleConstructionError;
+    readonly cleanupFailures: readonly LifecycleCleanupFailure[];
+    readonly receipt: DeviceScopeReceipt;
+}
+export type LifecycleResult = Result<DeviceScope, LifecycleFailure>;
+export interface LifecycleTransactionOptions {
+    readonly failureAt?: number;
+}
+export declare class LifecycleTransaction {
+    private readonly scope;
+    private readonly resources;
+    private readonly options;
+    private committed;
+    constructor(scope: DeviceScope, options?: LifecycleTransactionOptions);
+    add<T>(spec: LifecycleResourceSpec<T>): this;
+    commit(): Promise<LifecycleResult>;
+    failure(operation: 'create' | 'dispose', resourceKind?: DeviceResourceKind, cleanupFailures?: readonly LifecycleCleanupFailure[], cause?: unknown): LifecycleResult;
+    private cleanupCreated;
+    private cleanupOne;
+}
+//# sourceMappingURL=device-scope.d.ts.map

package/dist/device/device-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-scope.d.ts","sourceRoot":"","sources":["../../src/device/device-scope.ts"],"names":[],"mappings":"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"}

package/dist/device/gpu-residency.d.ts

@@ -0,0 +1,337 @@
+import { type MipmapShaderModuleFactory } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import { type VertexLayoutProjection } from '@forgeax/engine-geometry';
+import { type Buffer, type Result, type RhiCaps, type RhiDevice, RhiError, type RhiQueue, type Sampler, type TextureFormat, type TextureView } from '@forgeax/engine-rhi';
+import { type AssetError, type DecodedImage, type EquirectAsset, type Handle, type ImageError, type PrimitiveTopology, type SamplerAsset, type Submesh, type TextureAsset, type MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
+import { GpuBuffer, GpuTexture } from '../gpu-resource';
+import { type IblShaderModuleFactory } from '../ibl/IblPipelineCache';
+import type { RhiErrorListenerRegistry } from '../lifecycle';
+import type { DeviceScope } from './device-scope';
+export type FaceUniformsDevice = Pick<RhiDevice, 'createBuffer'> & {
+    readonly queue: Pick<RhiQueue, 'writeBuffer'>;
+};
+export declare function createFaceUniformsBuffer(device: FaceUniformsDevice): Result<Buffer, RhiError>;
+export declare function createPrefilterUniformsBuffer(device: FaceUniformsDevice): Result<Buffer, RhiError>;
+export declare function writeFaceUniforms(device: FaceUniformsDevice, buffer: Buffer, faceIdx: number, viewProj: Float32Array): Result<void, RhiError>;
+export declare function writeAllFaceUniforms(device: FaceUniformsDevice, buffer: Buffer): Result<void, RhiError>;
+export declare function writePrefilterUniforms(device: FaceUniformsDevice, buffer: Buffer, subPassIdx: number, roughness: number, mipFaceSize: number): Result<void, RhiError>;
+export declare function writeAllPrefilterUniforms(device: FaceUniformsDevice, buffer: Buffer): Result<void, RhiError>;
+/** Cube-POD register-relay injected by the wire layer (D-3). */
+type RegisterCube = (world: World, pod: EquirectAsset) => Result<Handle<'EquirectAsset', 'shared'>, AssetError>;
+interface TextureGpuEntry {
+    readonly texture: GpuTexture;
+    /** Opaque RHI view handle; lifetime is bound to the parent texture. */
+    readonly view: TextureView;
+}
+export interface MeshGpuHandles {
+    readonly vertexBuffer: GpuBuffer;
+    /**
+     * Index buffer wrapper, or `null` for a vertex-only mesh
+     * (no `MeshAsset.indices`). When `null` the record stage takes the
+     * non-indexed `pass.draw(vertexCount)` path and never calls
+     * `setIndexBuffer`. Gated on `indexed` below.
+     */
+    readonly indexBuffer: GpuBuffer | null;
+    /**
+     * Allocation byte sizes for the vbo / ibo (mirrors GPUBuffer.size). Used
+     * by `updateMeshById` to decide reuse vs reallocation; tracked here so
+     * the runtime never reads `.size` off the opaque RHI handle (which is
+     * not on the spec-aligned RHI Buffer interface; charter §RHI form rules).
+     */
+    readonly vboBytes: number;
+    /** Allocation byte size for the ibo, or 0 when indexBuffer is null. */
+    readonly iboBytes: number;
+    readonly indexCount: number;
+    readonly indexFormat: 'uint16' | 'uint32';
+    /**
+     * Vertex stride discriminator (feat-20260611). `'12F'` = 48 B
+     * (position+normal+uv+tangent); `'18F'` = 72 B (12F + skinIndex(uint16x4) +
+     * skinWeight(float32x4)). Mirrors `MeshRenderData.layout` in render-data.ts
+     * and `MeshRenderData.layout` -- the residency and render-data layout
+     * fields are the same union and move together.
+     */
+    readonly layout: '12F' | '18F';
+    /** Geometry-owned vertex layout projection used by every GPU consumer. */
+    readonly layoutProjection: VertexLayoutProjection;
+    /**
+     * Number of UV sets the interleaved buffer carries (1 = single `uv`, +1 per
+     * `uv1..uv7`). feat-20260629-multi-uv-set-support: threaded to the record
+     * stage so the forward PSO's vertex layout stride matches the buffer for
+     * meshes with a real extra UV set. Mirrors MeshRenderData.uvSetCount /
+     * MeshRenderData.uvSetCount.
+     */
+    readonly uvSetCount: number;
+    /** Vertex count uses 18F for skin or the geometry-owned canonical base stride. */
+    readonly vertexCount: number;
+    /** True when `MeshAsset.indices` is present (indexed draw path). */
+    readonly indexed: boolean;
+    /** Primitive topology (default 'triangle-list'). */
+    readonly topology: PrimitiveTopology;
+    /**
+     * Submeshes from MeshAsset.submeshes, carried through to the record stage
+     * so per-submesh drawIndexed can iterate independently (feat-20260608 M4 / w16).
+     * For single-submesh meshes this is a 1-element array (byte-identical to pre-M4).
+     */
+    readonly submeshes: readonly import('@forgeax/engine-types').Submesh[];
+}
+/**
+ * GPU residency store. Owns the per-handle GPU caches and the upload
+ * primitives that build them. Constructed once per renderer; wired with the
+ * GPU device via `configureGpuDevice` after `Renderer.initialization` resolves.
+ */
+export declare class GpuResidencyCache {
+    /** Monotonic token for mesh GPU residency or contents changes. */
+    meshResidencyEpoch: number;
+    /** Monotonic token for texture/sampler identities used by material bind groups. */
+    materialResourceEpoch: number;
+    private gpuDevice;
+    /** RHI-only owner for IBL projection; never populated with a raw GPUDevice. */
+    private iblDevice;
+    /** RHI Result-returning shader factory paired with `iblDevice`. */
+    private iblShaderModuleFactory;
+    private deviceScope;
+    private asyncCreateShaderModule;
+    private registerCube;
+    private errorRegistry;
+    private caps;
+    private readonly textureGpuHandles;
+    private readonly samplerGpuHandles;
+    private readonly cubemapGpuHandles;
+    private readonly cubemapIdempotentMap;
+    private readonly meshGpuHandles;
+    /**
+     * Compose a cache key from the raw handle slot and its owning World. The
+     * draw-time world index is only a position in one frame's `worlds[]`; it is
+     * not an asset identity and can be reused by a later World. World objects
+     * therefore receive a renderer-local namespace, while numeric callers keep
+     * the legacy namespace for low-level tests and built-in upload paths.
+     */
+    private readonly worldNamespaces;
+    private nextWorldNamespace;
+    private worldKey;
+    /**
+     * Wire the GPU device, shader-module factory, and cube-POD register relay.
+     * Called once by createRenderer after `Renderer.initialization` resolves. Unlike the
+     * pre-extraction AssetRegistry.configureGpuDevice, this performs NO replay:
+     * the pull model builds resources lazily at first `ensureResident` access.
+     */
+    configureGpuDevice(device: RhiDevice, asyncCreateShaderModule: MipmapShaderModuleFactory | undefined, registerCube: RegisterCube, caps: RhiCaps): void;
+    /**
+     * Bind the IBL projection to the same opaque RhiDevice used by assembly.
+     * This is deliberately separate from the legacy-compatible mipmap fixture
+     * seam: unit fixtures that only exercise ordinary residency do not need an
+     * IBL device, while a real IBL projection never accepts a raw GPUDevice.
+     */
+    configureIblDevice(device: RhiDevice, shaderModuleFactory: IblShaderModuleFactory | undefined): void;
+    /** Bind residency ownership to the renderer's single DeviceScope tree. */
+    bindDeviceScope(scope: DeviceScope): void;
+    /**
+     * Wrap a raw RHI Buffer handle into a GpuBuffer. The wrapper holds a
+     * reference to the device so `.destroy()` forwards to
+     * `device.destroyBuffer(handle)` (M-3 / w11; plan-strategy D-2).
+     *
+     * Pre: `configureGpuDevice` has been called. Callers that build a buffer
+     * via `device.createBuffer` already gate on a wired device, so this private
+     * helper trusts the caller; an unwired call is a programmer error and
+     * surfaces as a non-null assertion rather than a structured error.
+     */
+    private wrapBuf;
+    /** Wrap a raw RHI Texture handle into a GpuTexture (mirror of wrapBuf). */
+    private wrapTex;
+    /**
+     * Walk the three handle maps and destroy every GpuResource, then clear
+     * the maps. Called from `Renderer.dispose()` (M-5) as the first step of
+     * the dispose chain (plan-strategy D-2: dispose chain walks
+     * `gpuStore.destroyAll()` → `graph.drain()` → `instanceBuffers.clear()`
+     * → ...).
+     *
+     * Idempotent: a second call after the maps were cleared is a no-op
+     * (architecture-principles §6 idempotency). Each `.destroy()` call
+     * routes through the RHI shim's per-handle bookkeeping, so a stray
+     * second-destroy on a handle the runtime did not flip to destroyed
+     * surfaces as the structured `'destroy-after-destroy'` error from the
+     * RHI shim; that error is *not* re-thrown here -- destroyAll is a
+     * sweep that tolerates per-handle failures so the dispose chain can
+     * make progress (plan-strategy D-3 / D-8).
+     */
+    destroyAll(): void;
+    /**
+     * Set the error registry channel (wired by createRenderer). evict /
+     * releaseUnreferenced fire structured errors here instead of throwing -
+     * sweeps continue past individual failures (feat-20260619 D-1/D-6).
+     */
+    setErrorRegistry(registry: RhiErrorListenerRegistry): void;
+    /**
+     * evictTexture / evictMesh / evictCubemap — per-handle evict primitives.
+     *
+     * Reuses destroyAll's isDestroyed dedup logic + cubemap wrapper
+     * shared-dedup (feat-20260619 D-1). Returns {freed, errors} so callers
+     * can consume the aggregate result (D-3). Key not present -> no-op
+     * returning {freed:0, errors:[]}.
+     */
+    evictTexture(handle: Handle<'TextureAsset', 'shared'>, worldId?: World | number): {
+        freed: number;
+        errors: RhiError[];
+    };
+    evictMesh(handle: Handle<'MeshAsset', 'shared'>, worldId?: World | number): {
+        freed: number;
+        errors: RhiError[];
+    };
+    evictCubemap(id: number): {
+        freed: number;
+        errors: RhiError[];
+    };
+    /**
+     * releaseUnreferenced — iterate the three handle maps and evict entries
+     * whose key is NOT in `liveSet`.
+     *
+     * Iterates Map keys (not liveSet — store has no reverse index, D-8).
+     * IDs in liveSet that don't exist in the store are naturally ignored.
+     * Empty liveSet -> full release; second call -> no-op (maps empty,
+     * evict primitives are key-not-present no-op).
+     */
+    releaseUnreferenced(liveSet: Set<number>): {
+        freed: number;
+        errors: RhiError[];
+    };
+    /**
+     * Prewarm the mipmap pipeline cache for the given texture formats (D-9).
+     * Called from `createRenderer.initialization` (already async): builds the one-time
+     * mipmap shader module + per-format render pipeline into the mipmap-generator
+     * deviceCache so the per-texture mipmap blit at record-stage `ensureResident`
+     * is pure synchronous encoder work. A format absent from this list will make
+     * the sync `ensureResident` texture arm return a structured RhiError rather
+     * than lazily await a build (which would break the sync draw contract).
+     */
+    prewarmMipmapPipeline(device: RhiDevice, formats: readonly TextureFormat[]): Promise<Result<void, RhiError>>;
+    /**
+     * Return the GpuTexture wrapper for a `Handle<TextureAsset>` if it has been
+     * made resident, else `undefined`.
+     *
+     * @internal — test-only seam for cow-survivor / AC-02 integration tests; not
+     * part of the engine's public API surface.
+     */
+    _getTextureGpuTexture(handle: Handle<'TextureAsset', 'shared'>, worldId?: World | number): GpuTexture | undefined;
+    /**
+     * Return the GPU texture-view for a `Handle<TextureAsset>` if it has been
+     * made resident, else `undefined`.
+     */
+    getTextureGpuView(handle: Handle<'TextureAsset', 'shared'>, worldId?: World | number): TextureView | undefined;
+    /**
+     * Lazily materialise and cache a sampler descriptor for a material texture.
+     * Samplers are opaque, non-destroyable RHI handles, so disposal only drops
+     * this store's cache and lets the device own their lifetime.
+     */
+    ensureSamplerResident(handle: Handle<'SamplerAsset', 'shared'>, pod: SamplerAsset, worldId?: World | number): Result<Sampler, RhiError>;
+    /**
+     * Return the GpuTexture wrapper for the cubemap, or `undefined` if not
+     * uploaded yet. Consumers that need the raw RHI Texture handle (e.g.
+     * `device.createTextureView` arguments) read `.handle` on the wrapper;
+     * `.destroy()` routes through the destroy chain (M-3 / w11).
+     */
+    getCubemapGpuTexture(handle: Handle<'EquirectAsset', 'shared'>): GpuTexture | undefined;
+    /** Return the full-cube texture view, or `undefined` if not uploaded yet. */
+    getCubemapGpuView(handle: Handle<'EquirectAsset', 'shared'>): TextureView | undefined;
+    /** Return per-face 2D views (6 faces), or `undefined` if not uploaded yet. */
+    getCubemapFaceViews(handle: Handle<'EquirectAsset', 'shared'>): readonly TextureView[] | undefined;
+    /**
+     * Query the projection status for an equirect source handle (D-3 SSOT: the
+     * store's CubemapGpuEntry is the single authority). Returns `undefined` when
+     * no projection has been launched for this source yet (the record arm reads
+     * this to decide whether to fire the lazy projection; feat-20260630 M3 / w18):
+     *   - undefined -> no entry: caller may launch projection (fire-and-forget)
+     *   - 'pending' -> projection launched, not complete: bind white-cube fallback
+     *   - 'ready'   -> projected cube + IBL views live: bind real IBL
+     *   - 'failed'  -> projection errored: bind white fallback, do NOT retry (R-2)
+     */
+    getCubemapStatus(handle: Handle<'EquirectAsset', 'shared'>): 'pending' | 'ready' | 'failed' | undefined;
+    /**
+     * Return the GPU vertex / index buffer handles + index count for a
+     * `Handle<MeshAsset>` if resident, else `undefined`. Consumers treat this
+     * as the canonical "mesh asset has GPU residency" probe.
+     */
+    getMeshGpuHandles(handle: Handle<'MeshAsset', 'shared'>, worldId?: World | number): MeshGpuHandles | undefined;
+    /**
+     * Drop one mutable shared mesh's GPU copy after ECS publishes `markChanged`.
+     * The next record pass resolves the same POD and rebuilds residency through
+     * the normal pull path, so ECS remains the payload authority.
+     */
+    invalidateMesh(handle: number, worldId?: World | number): void;
+    /**
+     * Pull-model residency: build the GPU resource for `handle` from the
+     * caller-provided POD on a miss, return the cached handles on a hit (D-2).
+     *
+     * - mesh POD -> synchronous vertex / index buffer upload (mirrors the
+     *   pre-extraction `uploadMeshById`).
+     * - texture POD -> synchronous texture upload + mipmap blit (D-9). The
+     *   mipmap pipeline MUST have been prewarmed via `prewarmMipmapPipeline`;
+     *   an un-prewarmed format returns a structured RhiError (never awaits).
+     *
+     * Cubemap is NOT routed here -- it is an eager user call
+     * (`_uploadCubemapFromEquirect`). Builtin meshes are NOT routed here either
+     * (createRenderer step-3 owns them; D-1).
+     */
+    ensureResident(handle: Handle<'MeshAsset', 'shared'>, pod: TypesMeshAsset, worldId?: World | number): Result<MeshGpuHandles, RhiError | AssetError | ImageError>;
+    ensureResident(handle: Handle<'TextureAsset', 'shared'>, pod: TextureAsset, worldId?: World | number): Result<TextureGpuEntry, RhiError | AssetError | ImageError>;
+    /**
+     * Eager public surface: upload decoded image bytes into a GPU texture and
+     * cache (texture + view) under the handle. The TextureAsset POD supplies the
+     * GPU format (D-2: caller provides POD, store never reaches a registry); the
+     * DecodedImage supplies the pixel bytes + colorSpace. Retains the async
+     * signature so callers that have not prewarmed can drive a mipmap build here
+     * (the one async source).
+     */
+    uploadTexture(handle: Handle<'TextureAsset', 'shared'>, pod: TextureAsset, decoded: DecodedImage, worldId?: World | number): Promise<Result<void, AssetError | ImageError | RhiError>>;
+    /**
+     * Synchronous texture upload used by `ensureResident` (D-9). Identical to
+     * `uploadTexture` except the mipmap pipeline is read from the prewarmed
+     * cache via the synchronous `blitMipmapsSync` -- an un-prewarmed format
+     * returns a structured RhiError instead of awaiting a build.
+     */
+    private uploadTextureSync;
+    /**
+     * Shared texture-upload prelude: format / colorSpace consistency assertion,
+     * GPU texture allocation + writeTexture. Returns `gpuTexture: undefined`
+     * (with ok) when no device is wired (deferred path).
+     */
+    private prepareTextureUpload;
+    /**
+     * Project an equirectangular HDR `EquirectAsset` into a GPU cubemap + IBL
+     * precompute. NOT part of the `ensureResident` pull path.
+     *
+     * @internal — feat-20260630 D-3 / F-9: the cubemap projection is engine
+     * internals, not a user surface. AI users declare `Skylight{equirect}` and
+     * the render-system record arm (same package) drives this method per-frame;
+     * the `_` prefix + `@internal` mark it package-internal (lint:internal gate)
+     * so it never appears as a user-facing call. (A cross-file `private` is not
+     * reachable by the record arm; package-internal is the correct visibility.)
+     *
+     * Idempotent: a second call with the same source handle returns the cached
+     * cubemap handle (no second GPU texture). The minted cubemap handle is an
+     * `EquirectAsset` shared ref catalogued via the injected `registerCube` relay
+     * (D-3); the store never imports AssetRegistry.
+     *
+     * Status (D-3): every entry written carries `status`. A failed projection
+     * records `status:'failed'` EXPLICITLY (R-2 / AC-09) so the caller never
+     * retries by inferring "no entry => try again".
+     */
+    _uploadCubemapFromEquirect(world: World, sourceHandle: Handle<'EquirectAsset', 'shared'>, sourcePod: EquirectAsset): Promise<Result<Handle<'EquirectAsset', 'shared'>, AssetError | RhiError>>;
+    /**
+     * Upload `MeshAsset.vertices` + `MeshAsset.indices` to GPU buffers and cache
+     * the handles under the asset id. Synchronous; mirrors the pre-extraction
+     * `uploadMeshById` byte-for-byte. Returns the cached entry on success.
+     */
+    private uploadMeshById;
+    /**
+     * Update an existing mesh's GPU buffer data in-place (or expand). The handle
+     * must already be resident. Mirrors the pre-extraction `updateMeshById`.
+     */
+    private updateMeshById;
+    /**
+     * Public surface for updating an existing unmanaged mesh handle's GPU buffer
+     * data in-place. The handle must have been made resident.
+     */
+    updateMesh(handle: Handle<'MeshAsset', 'shared'>, newVertices: Float32Array, newIndices: Uint16Array, worldId?: World | number, submeshes?: readonly Submesh[]): void;
+}
+export {};
+//# sourceMappingURL=gpu-residency.d.ts.map

package/dist/device/gpu-residency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-residency.d.ts","sourceRoot":"","sources":["../../src/device/gpu-residency.ts"],"names":[],"mappings":"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"}

package/dist/device/resource-types.d.ts

@@ -0,0 +1,8 @@
+export declare const DEVICE_RESOURCE_KINDS: readonly ["listener", "surface", "shader", "pipeline", "buffer", "texture", "binding", "scene-table", "feature", "post-effect"];
+export type DeviceResourceKind = (typeof DEVICE_RESOURCE_KINDS)[number];
+export interface DeviceScopeReceipt {
+    readonly owner: string;
+    readonly generation: number;
+    readonly resourceCount: number;
+}
+//# sourceMappingURL=resource-types.d.ts.map

package/dist/device/resource-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-types.d.ts","sourceRoot":"","sources":["../../src/device/resource-types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,iIAWxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}

package/dist/engine-metrics.d.ts

@@ -0,0 +1,23 @@
+import type { EngineMetrics } from '@forgeax/engine-types';
+export type { EngineMetrics };
+/**
+ * Default `EngineMetrics` implementation — a thin `Map<string, number>` with
+ * the three-method surface bolted on. The map is private; readers consume
+ * the snapshot accessor.
+ *
+ * @internal — instances are constructed by `createRenderer` and retained by
+ * owner services; AI users do not import this class directly.
+ */
+export declare class EngineMetricsImpl implements EngineMetrics {
+    private readonly counters;
+    increment(name: string): void;
+    snapshot(): Readonly<Record<string, number>>;
+    reset(): void;
+}
+/**
+ * Fresh `EngineMetrics` factory; the only construction path used by
+ * `createRenderer`. Keeping the constructor private (via the factory) leaves
+ * room to swap the backing store without touching call sites.
+ */
+export declare function createEngineMetrics(): EngineMetrics;
+//# sourceMappingURL=engine-metrics.d.ts.map

package/dist/engine-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-metrics.d.ts","sourceRoot":"","sources":["../src/engine-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA4C3D,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI7B,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAQ5C,KAAK,IAAI,IAAI;CAGd;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD"}

package/dist/errors/ecs-validation.d.ts

@@ -0,0 +1,3 @@
+export type RenderValidationErrorCode = 'resource-invalid-value' | 'spawn-light-invalid-bounds' | 'sprite-instances-count-mismatch' | 'sprite-instances-requires-sprite-shader' | 'sprite-instances-mutually-exclusive-with-instances';
+export { ResourceInvalidValueError, SpawnLightInvalidBoundsError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, } from '@forgeax/engine-ecs/projection';
+//# sourceMappingURL=ecs-validation.d.ts.map

package/dist/errors/ecs-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecs-validation.d.ts","sourceRoot":"","sources":["../../src/errors/ecs-validation.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,yBAAyB,GACjC,wBAAwB,GACxB,4BAA4B,GAC5B,iCAAiC,GACjC,yCAAyC,GACzC,oDAAoD,CAAC;AAEzD,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,iCAAiC,EACjC,kDAAkD,EAClD,wCAAwC,GACzC,MAAM,gCAAgC,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ecs-validation';
+export * from './recover';
+export * from './render';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}

package/dist/errors/recover.d.ts

@@ -0,0 +1,105 @@
+import type { DeviceScopeReceipt } from '../device/resource-types';
+/**
+ * Closed union of recover() error codes.
+ *
+ * Exactly 4 members (feat-20260622-s5 M3 / D-2 add-only minor; the S3
+ * skeleton shipped the first two):
+ *   - `'recover-not-needed'` — health state is `'alive'`, no recovery required
+ *     (also returned after a successful recover: the renderer is alive again,
+ *     so a second recover() is a no-op signal — A-AC-08 idempotency)
+ *   - `'recover-not-implemented'` — **reserved**. The S3 skeleton returned this
+ *     for each degraded state; M3 implements recover() so this code is no longer
+ *     produced. Kept in the union (not deleted) so consumers' exhaustive
+ *     switches stay valid — AGENTS.md Change stance: `*ErrorCode` unions evolve
+ *     add-only minor, never remove a member
+ *   - `'recover-adapter-unavailable'` — rebuild requested a new adapter but
+ *     `requestAdapter` returned no adapter (driver / GPU may have been reset)
+ *   - `'recover-device-unavailable'` — an adapter was obtained but
+ *     `requestDevice` failed or threw (device creation is driver-dependent)
+ *
+ * On both failure codes the health state stays `'device-lost'` (recover() never
+ * fakes the renderer back to `'alive'` on failure — A-AC-07). recover() is a
+ * single idempotent attempt: no retry loop, no backoff, no timer (A-OOS-1).
+ *
+ * AI users exhaustively switch without default; TS guards completeness.
+ */
+export type RecoverErrorCode = keyof typeof RECOVER_ERROR_POLICY;
+declare const RECOVER_ERROR_POLICY: {
+    'recover-not-needed': {
+        message: string;
+        expected: string;
+        hint: string;
+    };
+    'recover-not-implemented': {
+        message: string;
+        expected: string;
+        hint: string;
+    };
+    'recover-adapter-unavailable': {
+        message: string;
+        expected: string;
+        hint: string;
+    };
+    'recover-device-unavailable': {
+        message: string;
+        expected: string;
+        hint: string;
+    };
+};
+/**
+ * Structured error for `Renderer.recover()` failures.
+ *
+ * Carries the standard 3-field surface per AGENTS.md error model:
+ *   - `.code: RecoverErrorCode` — closed union discriminant
+ *   - `.expected: string` — expected-state description
+ *   - `.hint: string` — actionable recovery guidance
+ *
+ * No `.detail` field: each code has fixed semantics with no variable data.
+ */
+export declare class RecoverError extends Error {
+    readonly code: RecoverErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    constructor(code: RecoverErrorCode);
+}
+declare const RENDER_RECOVERY_ERROR_POLICY: {
+    readonly 'recover-lifecycle-failed': {
+        readonly expected: "the replacement DeviceScope must publish only after lifecycle cleanup succeeds";
+        readonly hint: "inspect detail and cleanupFailures, then recover or rebuild the DeviceScope";
+    };
+    readonly 'recover-disposed-during-rebuild': {
+        readonly expected: "dispose wins over an in-flight recovery rebuild";
+        readonly hint: "stop using the disposed renderer and create a new Renderer";
+    };
+};
+export type RenderRecoveryErrorCode = keyof typeof RENDER_RECOVERY_ERROR_POLICY;
+export interface RenderRecoveryFailureDetail {
+    readonly owner: string;
+    readonly generation: number;
+    readonly recovery: 'recover' | 'rebuild' | 'stop';
+    readonly receipt: DeviceScopeReceipt;
+    readonly cause: unknown;
+}
+export declare class RenderRecoveryError extends Error {
+    readonly code: RenderRecoveryErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderRecoveryFailureDetail;
+    constructor(code: RenderRecoveryErrorCode, detail: RenderRecoveryFailureDetail);
+}
+export type RecoverFailure = RecoverError | RenderRecoveryError;
+export type IblCapabilityLossCode = 'ibl-hdr-capability-loss';
+export interface IblCapabilityLossDetail {
+    readonly fallbackArtifact: 'white-cube';
+    readonly rgba16floatRenderable: false;
+    readonly lastKnownGood: string;
+}
+export declare class IblCapabilityLossError extends Error {
+    readonly code: IblCapabilityLossCode;
+    readonly expected = "rgba16float renderability is required for the IBL HDR producer";
+    readonly hint = "enable rgba16floatRenderable or inspect the last-known-good IBL capture";
+    readonly detail: IblCapabilityLossDetail;
+    constructor(lastKnownGood: string);
+}
+export {};
+//# sourceMappingURL=recover.d.ts.map

package/dist/errors/recover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../src/errors/recover.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAEjE,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;CA+BzB,CAAC;AAEF;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,gBAAgB;CAQnC;AAED,QAAA,MAAM,4BAA4B;;;;;;;;;CASxB,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,MAAM,OAAO,4BAA4B,CAAC;AAEhF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;gBAEjC,IAAI,EAAE,uBAAuB,EAAE,MAAM,EAAE,2BAA2B;CAS/E;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAEhE,MAAM,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,gBAAgB,EAAE,YAAY,CAAC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,KAAK,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAA6B;IACjE,QAAQ,CAAC,QAAQ,oEAAoE;IACrF,QAAQ,CAAC,IAAI,6EAA6E;IAC1F,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;gBAE7B,aAAa,EAAE,MAAM;CASlC"}