@forgeax/engine-render 0.1.2

package/dist/environment/signature.d.ts

@@ -0,0 +1,70 @@
+import type { Vec3 } from '@forgeax/engine-math';
+export interface EnvironmentSignatureInput {
+    readonly atmosphere: {
+        readonly turbidity: number;
+        readonly rayleigh: number;
+        readonly mieCoefficient: number;
+        readonly mieDirectionalG: number;
+        readonly sunAngularRadius: number;
+    };
+    readonly sun: {
+        readonly direction: Vec3 | readonly [number, number, number];
+        readonly color: Vec3 | readonly [number, number, number];
+        readonly illuminance: number;
+    };
+    readonly quality: EnvironmentQuality;
+    readonly algorithmRevision: string;
+    readonly worldId: number;
+    readonly entity: number;
+    readonly deviceGeneration: number;
+    readonly outputFormat: EnvironmentOutputFormat;
+}
+export interface EnvironmentQuality {
+    readonly skySize: number;
+    readonly irradianceSize: number;
+    readonly prefilterMips: number;
+}
+/** Analytic sky is an HDR producer. LDR fallback would silently change the
+ * radiometry contract and is intentionally not part of this union. */
+export type EnvironmentOutputFormat = 'rgba16float';
+export type EnvironmentSignature = string & {
+    readonly __environmentSignature: unique symbol;
+};
+declare function floatBits(value: number): string;
+/**
+ * Canonical output identity. Float32 bit patterns are used deliberately: a
+ * rounded JSON representation cannot distinguish the values that reach a GPU
+ * uniform, while this identity must invalidate the candidate on those changes.
+ */
+export declare function environmentSignature(input: EnvironmentSignatureInput): EnvironmentSignature;
+export { floatBits as canonicalEnvironmentFloatBits };
+export interface EnvironmentCubeDescriptor {
+    readonly kind: 'sky' | 'irradiance' | 'prefilter';
+    readonly width: number;
+    readonly height: number;
+    readonly mipLevel: number;
+    readonly arrayLayers: 6;
+    readonly format: EnvironmentOutputFormat;
+    readonly usage: readonly ['render-attachment', 'texture-binding'];
+}
+export interface EnvironmentCubeFace {
+    readonly kind: EnvironmentCubeDescriptor['kind'];
+    readonly mipLevel: number;
+    readonly face: 0 | 1 | 2 | 3 | 4 | 5;
+    readonly width: number;
+    readonly height: number;
+    readonly bytes: number;
+}
+export interface EnvironmentBundleDescriptors {
+    readonly sky: EnvironmentCubeDescriptor;
+    readonly irradiance: EnvironmentCubeDescriptor;
+    readonly prefilter: EnvironmentCubeDescriptor;
+    readonly mips: readonly EnvironmentCubeDescriptor[];
+    readonly faces: readonly EnvironmentCubeFace[];
+    readonly bytesPerTexel: 8 | 4;
+    readonly logicalBytes: number;
+}
+export declare function deriveEnvironmentBundleDescriptors(quality: EnvironmentQuality, format: EnvironmentOutputFormat): EnvironmentBundleDescriptors;
+/** Recompute logical inspection bytes from raw descriptor roster, independently. */
+export declare function environmentBundleBytes(descriptors: EnvironmentBundleDescriptors): number;
+//# sourceMappingURL=signature.d.ts.map

package/dist/environment/signature.d.ts.map

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

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,78 @@
+/**
+ * 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 any 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);
+}
+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":"AAUA;;;;;;;;;;;;;;;;;;;;;;;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,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"}