@forgeax/engine-render 0.1.21 → 0.1.24

package/README.md

@@ -8,6 +8,30 @@
 
 ## Public frame contract
 
+## 灯光最短入口
+
+三条最短入口：
+
+1. `RectAreaLight`：在现有 `Transform` 上声明单面矩形发光体，尺寸由 `width` 与 `height` 持有。
+2. `SpotLight`：用 `iesProfile` 和 `cookie` 绑定现有资产，用 `rollDeg` 共享方位角；缺席 handle 是乘法单位元。
+3. `LightProbe`：声明 27 个 `irradiance` 值和唯一的 `radius`，位置与朝向仍来自 `Transform`。
+
+这些是 authored/render 输入，不是 GPU slot、LTC、probe asset 或第二个 Renderer API。尺寸、半径和 `rollDeg` 在场景序列化中保留；资产 GUID 通过 Pack/Catalog 的 `refs` 往返，不能从 URL 或数组位置推断身份。
+
+### Extended-lighting consumer route
+
+The three smallest public examples are `RectAreaLight(width, height)`,
+`SpotLight(iesProfile, cookie, rollDeg)`, and `LightProbe(irradiance, radius)`.
+Probe diffuse uses `A={admitted && d<r}`, `c=1-(d/r)^2`, scaled finite `qhat`,
+`alpha=q/Q`, `C=1-prod(1-c)`, and `S=1-C`; Sky is only
+`S*E_sky(N)`. It never enters probe admission, `Q`, `alpha`, specular, or
+`DirectLightSlot`. `recordByteLength=160` is the per-object ABI receipt.
+
+Recovery is inspected as data: read `code`, `expected`, `hint`, and typed
+`detail`; keep the current LKG until the replacement generation is accepted.
+GPU, Browser, and Dawn evidence that cannot execute is `not-run` or
+`unavailable`, never a verified structural substitute.
+
 The public frame vocabulary is intentionally small. `Camera` is the authoring
 owner for tone, antialiasing, bloom, and `historyVersion`; `Atmosphere` and
 `Fog` are independent ECS components. The renderer extracts these facts into
@@ -18,17 +42,76 @@ capability facts, then `observe(receipt, request)` for receipt-bound evidence.
 
 ### AI cold-start route
 
-An AI consumer can start with the public sequence `createRenderer -> attach ->
-draw -> inspect -> observe`. Keep the draw input unchanged when retrying. On a
-failure, branch on `error.code`; read the correlated `expected`, `hint`, and
-typed `detail`, repair that owner, and submit the same request again. Public
-consumers do not parse `message` and never receive graph nodes, devices,
-history textures, or prepared handles.
+An AI consumer can start with the public sequence `state -> inspect -> recover
+-> FrameReceipt`. `Renderer.state()` is the closed lifecycle union: only
+`alive` admits a frame; `device-lost` permits one explicit recovery flight;
+`recovering` shares that flight; `faulted` requires a new Renderer; and
+`disposed` is terminal. `inspect()` is detached POD evidence for the current
+state and recovery attempt. After `recover()` succeeds, submit the unchanged
+draw input and use the new `FrameReceipt` as the proof for that generation.
+
+`inspect().recovery` is always present. Its `phase` is `null` outside an active
+attempt and otherwise follows `quiesce`, `acquire-adapter`, `acquire-device`,
+`rehydrate`, `compile-graph`, `publish`, and `cleanup`. The projection also
+reports the `fromGeneration`/`candidateGeneration` fence, monotonic `attempt`,
+`lastOutcome`, committed `rehydratedRoots`, and bounded `staleLossEvents`.
+These are detached facts; they never expose devices, graphs, textures, or
+mutable resource collections.
+
+During `device-lost` or `recovering`, the App keeps its host heartbeat but does
+not advance the World or submit a frame. A failed `Result` is repaired from
+`error.code`, `expected`, `hint`, and typed `detail`: wait for the shared
+recovery flight, explicitly retry, repair the named owner, or create a new
+Renderer according to the closed error. Do not parse `message`. Target and
+history tokens retain logical identity, but their new-generation contents are
+uninitialized until a successful receipt; a neutral target or last-known-good
+fallback is not proof of real recovery. Public consumers never receive graph
+nodes, devices, history textures, or prepared handles.
+
+ The current-source manifest and schema identify `source`, `build`, `backend`,
+ `runner`, and `frameIdentity`. Structural graph receipts, Browser/Dawn
+ readback or PNG evidence, and historical oracle data are separate evidence
+ classes. An unavailable backend is reported as unavailable.
+
+## RenderFeature: the producer seam (first-read index)
+
+### Material contract projection
+
+Render consumes only the Pack-owned material publication projection. Its
+inputs are runtime bool/value data, composed module slots, and the closed
+compiler context; render never authors, cooks, writes DDC, or selects a
+fallback material. The projection preserves `layoutIdentity`,
+`programIdentity`, `cookIdentity`, and `materialPublicationIdentity` so a
+stale draw can be traced to the first producer divergence.
+
+The public route is one `RenderFeature<FrameData>` through the Standard
+Pipeline and the active RenderGraph pass. In the examples below, `type FrameData`
+is the producer-owned extracted value. A feature extracts one frame value,
+then its mandatory `plan(data, context)` declares named resources and passes;
+the host derives graph access, preparation, recording, and recovery from that
+plan. Register it at construction with
+`createRenderer(canvas, { features: [feature] })`. A feature never receives a
+device, queue, encoder, staging builder, or submit callback.
+
+## RenderFeature: the producer seam (first-read index)
+
+The public route is one `RenderFeature<FrameData>` through the active RenderGraph
+and `Standard Pipeline`. Here `type FrameData` is the
+producer-owned extracted value; `plan(data, context)` declares named resources and passes.
+Register it with
+`createRenderer(canvas, { features: [feature] })`. The renderer derives graph
+access, preparation, recording, and recovery; the feature never receives a
+device, queue, encoder, or submit callback. Each declaration becomes a
+`RenderGraph pass` inside the active frame submit boundary.
+
+### Material contract projection
 
-The current-source manifest and schema identify `source`, `build`, `backend`,
-`runner`, and `frameIdentity`. Structural graph receipts, Browser/Dawn
-readback or PNG evidence, and historical oracle data are separate evidence
-classes. An unavailable backend is reported as unavailable.
+Render consumes only the Pack-owned material publication projection. Its
+inputs are runtime bool/value data, composed module slots, and the closed
+compiler context; render never authors, cooks, writes DDC, or selects a
+fallback material. The projection preserves `layoutIdentity`,
+`programIdentity`, `cookIdentity`, and `materialPublicationIdentity` so a
+stale draw can be traced to the first producer divergence.
 
 ### Directional shadow quality: author → inspect → recover
 
@@ -231,10 +314,74 @@ if (!frame.ok) throw frame.error;
 const observation = await renderer.observe(frame.value, { include: ['timings'] });
 ```
 
-The Standard pipeline selects direct or clustered lighting from capabilities and keeps shadow,
-PBR, IBL, SSAO, bloom, tone, antialiasing, sky, material, VFX, and debug feature ownership inside
-the same graph and submit boundary. CPU and WebGL2 fallback are capability lanes of that pipeline,
-not second renderer identities.
+The Standard pipeline uses one Cluster transport for every local light on storage-capable devices
+and keeps shadow, PBR, IBL, SSAO, bloom, tone, antialiasing, sky, material, VFX, and debug feature
+ownership inside the same graph and submit boundary. CPU and WebGL2 remain capability lanes for the
+Cluster membership producer or for mesh/instance storage fallback; they do not reintroduce a
+PointLight/SpotLight buffer or a fixed four-light ABI.
+## SSR M0 admission: inspect owners, then decide
+
+> [!IMPORTANT]
+> SSR M0 is a consumer-only admission boundary. It reads detached producer,
+> r32float format, and temporal receipts with one four-field integration
+> identity. Any missing, stale, structural-only, or mismatched receipt stays
+> `fallback-only` and emits zero SSR work; this section does not describe SSR
+> capture, ray tracing, Hi-Z, temporal resolve, composition, or history.
+
+```mermaid
+flowchart LR
+  P["producer detached receipt"] --> A["admitSsrM0"]
+  F["format stage receipt"] --> A
+  T["temporal submit receipt"] --> A
+  A -->|"all identity and verdict checks pass"| E["admitted: parent M1 may unlock"]
+  A -->|"missing, stale, unavailable, or mismatched"| B["fallback-only: zero work"]
+```
+
+The inspection route is deliberately progressive:
+
+| Layer | Read first | Owner action on failure |
+|:--|:--|:--|
+| Status | `status`, `failure.code`, `failure.expected` | branch on the closed failure code |
+| Identity | `sourceHead`, `sourceTree`, `lockSha256`, `buildSha256` | rebuild the owner receipt for the current identity |
+| Generation | producer `generation`, format `deviceGeneration`, temporal `generation` | discard stale completion and reinspect |
+| Recovery | `failure.hint`, typed `detail.owner`, `detail.action` | use LKG/Skylight/neutral, recapture, rebuild, or retry through that owner |
+| Work | attachment/pass/binding/resource/history/temporal counters | require exact zero on every blocked path |
+
+```ts
+const admission = admitSsrM0({ requested, identity, reflectionFallback, format, temporal });
+if (admission.status === 'fallback-only') {
+  // Read admission.failure.code and route recovery to its owner.
+  console.log(admission.work); // every SSR counter is zero
+}
+```
+
+Use `inspect -> owner recovery -> matching submit -> reinspect` as the complete
+AI route. No returned field is a device, graph node, texture, buffer, encoder,
+or other live handle. A stable generation keeps `resetCount`, `rebuildCount`,
+and additional format probe work at zero; a changed generation must be
+reinspected before admission can be considered again.
+
+`inspect()` is a synchronous snapshot. The first snapshot after binding may show
+an absent format or temporal receipt while the owner probe and first submit are
+still in flight; it is not a `pending` verdict. Run the ordinary owner frame,
+await `FrameReceipt.completed`, then inspect again before routing recovery.
+
+There are two action projections. `admission.failure.detail.action` is the coarse
+M0 gate instruction (`retry` for demand/readiness and `rebuild` for a missing or
+mismatched receipt). `reflectionFallbackInspection.recoveryAction` is the
+producer's more specific source/recapture instruction. Neither is a second SSR
+API; use the existing owner operation shown here, then submit and inspect again:
+
+| Action field | Owner operation | Next observation |
+|:--|:--|:--|
+| `reflectionFallbackInspection.recoveryAction = use-LKG` | Keep the compatible probe row and draw the next frame | Read the committed row and matching temporal receipt |
+| `reflectionFallbackInspection.recoveryAction = use-Skylight` / `use-neutral` | Change the World-owned probe/`Skylight` source, then draw | Confirm selected source and committed generation |
+| `reflectionFallbackInspection.recoveryAction = recapture` / `rebuild` / `retry` | Draw again so the producer/RHI owner retries pending work | Await completion and inspect the owner receipt/failure |
+| `admission.failure.detail.action = retry` / `rebuild` | Retry the consumer frame, or rebuild the named owner receipt | Reinspect admission and all three receipt generations |
+| device-loss recovery | `await renderer.recover()` before the next draw | Confirm the replacement `deviceGeneration`, then re-probe |
+
+SSR never invokes these operations or mutates producer/device state; this table
+maps the typed action to the existing public World and Renderer seams.
 
 ## Target and probe lifecycle index
 
@@ -250,6 +397,12 @@ Use `inspect()` for bounded target/probe counts, pending work, and the last stru
 or reports `{ kind: 'skylight' }` for the explicit fallback. `recover()` is meaningful only from `device-lost`; on a healthy renderer its structured
 `renderer-state-invalid` result is a guard. Device recovery invalidates old generations and
 rebuilds producer-owned physical resources, so old tickets and sources must not be reused.
+For the SSR dependency producer, `inspection.reflectionProbes.reflectionFallbackInspection`
+is the bounded recovery projection: its `receipt` is the committed source row selected for
+the current lighting selection, while `failureStage`, `failureCode`, `expected`, and
+`recoveryAction` describe the latest closed failure without exposing a texture, graph, or
+device handle. `reflectionFallbackReadback` is the separate completed attachment fact; it
+must match the committed row's frame and device generation before it is used as evidence.
 The exact public names and stable consumer IDs are machine-readable in
 `src/__tests__/render-target-public-schema.json`.
 
@@ -355,26 +508,6 @@ gate exercises the browser delivery path. Runtime inspection uses the public
 belongs in `packages/render/bench` and its dev-verify producer. Render does
 not expose a timing controller or a second membership-specific API.
 
-## RenderFeature: the producer seam (first-read index)
-
-### Material contract projection
-
-Render consumes only the Pack-owned material publication projection. Its
-inputs are runtime bool/value data, composed module slots, and the closed
-compiler context; render never authors, cooks, writes DDC, or selects a
-fallback material. The projection preserves `layoutIdentity`,
-`programIdentity`, `cookIdentity`, and `materialPublicationIdentity` so a
-stale draw can be traced to the first producer divergence.
-
-The public route is one `RenderFeature<FrameData>` through the Standard
-Pipeline and the active RenderGraph pass. In the examples below, `type FrameData`
-is the producer-owned extracted value. A feature extracts one frame value,
-then its mandatory `plan(data, context)` declares named resources and passes;
-the host derives graph access, preparation, recording, and recovery from that
-plan. Register it at construction with
-`createRenderer(canvas, { features: [feature] })`. A feature never receives a
-device, queue, encoder, staging builder, or submit callback.
-
 ## Motion Blur temporal consumer
 
 The Standard camera may carry the presence-enabled `MotionBlur` component. Its
@@ -407,6 +540,70 @@ Render owns this consumption route:
 | `cook` output | Record only validated shader artifacts. |
 | `recovery` | Preserve the structured failure so the source contract or cooked module can be repaired. |
 
+## Standard physical material authoring
+
+`Materials.standard` is the public authoring entry point for the Standard
+root. It emits one `MaterialAsset.parameters` contract; values and texture
+coordinates are projections of that contract, not a second feature mask. A
+base-only root keeps `forward + deferred + shadow`, while declaring any
+second-stage layer or physical texture selects `forward + shadow`.
+
+```ts
+import { Materials } from '@forgeax/engine-render';
+
+const material = Materials.standard({
+  baseColor: [0.72, 0.48, 0.22, 1],
+  metallic: 0,
+  roughness: 0.34,
+  clearcoat: 0.7,
+  clearcoatRoughness: 0.18,
+  anisotropyStrength: 0.35,
+  anisotropyRotation: Math.PI / 2,
+  sheenColor: [0.08, 0.03, 0.02],
+  sheenRoughness: 0.25,
+  iridescence: 0.5,
+  iridescenceIor: 1.4,
+  iridescenceThicknessMinimum: 120,
+  iridescenceThicknessMaximum: 380,
+  specular: 0.9,
+  specularColor: [1, 0.92, 0.8],
+  ior: 1.5,
+});
+```
+
+The layer contract and texture semantics are fixed at the root:
+
+| Layer / slot | Defaults | Texture facts | Pass / frame rule |
+|:--|:--|:--|:--|
+| `clearcoat`, `clearcoatRoughness` | `0`, `0` | `clearcoatTexture.R`, `clearcoatRoughnessTexture.G`, `clearcoatNormalTexture.RG` | coat normal needs `NORMAL + UV + tangent`; coat energy attenuates the base |
+| `anisotropyStrength`, `anisotropyRotation` | `0`, `0` radians | `anisotropyTexture.RG` direction, `.B` strength | always needs a tangent frame; rotation changes the GGX highlight axis |
+| `sheenColor`, `sheenRoughness` | `[0,0,0]`, `0` | color RGB is sRGB; roughness A is linear | Charlie lobe stays below clearcoat and uses existing IBL resources |
+| `iridescence`, `iridescenceIor`, `iridescenceThickness*` | `0`, `1.3`, `100..400 nm` | strength R, thickness G; min may exceed max | bounded thin-film Fresnel modifies base reflection |
+| `specular`, `specularColor`, `ior` | `1`, `[1,1,1]`, `1.5` | `specularTexture.A` and `specularColorTexture.RGB` (sRGB for color) | dielectric F0 uses valid IOR; metallic uses the base metal response |
+
+> [!CAUTION]
+> A missing or conflicting anisotropy tangent input returns the structured
+> `material-tangent-required` error. Repair the mesh producer by supplying a
+> finite `TANGENT : vec4` (including `.w` handedness), or by supplying
+> `NORMAL`, the selected UV set, and triangle topology so the importer can
+> generate and persist the frame. Do not substitute an identity or derivative
+> fallback.
+
+For a texture, pass a `MaterialTextureValue` when the slot needs a sampler or
+non-default coordinates; `coordinates.set` and `coordinates.transform` stay
+with that slot. glTF authors use the same fields through the importer, which
+preserves the chain `parse → MaterialAsset → cook → Pack refs → load`.
+
+The public recovery path is:
+
+```mermaid
+flowchart LR
+  A["inspect root and receipt"] --> B["branch on error.code"]
+  B --> C["repair source, mesh, or root"]
+  C --> D["re-import / re-cook"]
+  D --> E["load the new generation and draw"]
+```
+
 ### Mesh material binding resolution
 
 Render resolves one effective material table per logical mesh slot before
@@ -424,6 +621,25 @@ uses the neutral engine material.
 
 The render path is `MaterialAsset` -> extract snapshot -> prepare resources -> record the per-slot `coordinates` and values. The effective `parent` is already resolved before extract. If a material contract or reflection binding fails, preserve the structured error and repair the source contract or cooked module before drawing again; that is the recovery route. The render package owns consumption, not material import or cook policy.
 
+### Materials factory color inputs
+
+The high-level `Materials.standard` and `Materials.unlit` factories normalize
+authored colors at their boundary. Numeric RGB/RGBA tuples are linear-sRGB and
+are copied unchanged; CSS/Hex strings and `0xRRGGBB` integers are sRGB inputs
+and are decoded once. Use `Materials.srgb(tuple)` when a numeric tuple is known
+to be sRGB. Generated assets carry `colorSpace: 'linear'`, so extraction does
+not decode them a second time. The low-level `MaterialAsset` contract remains
+authored-sRGB by default for serialized `type: 'color'` values; mark those
+values `colorSpace: 'linear'` when they are already linear. Texture color space
+continues to come from each texture asset and is not overridden by material
+array metadata.
+
+```ts
+const linear = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+const css = Materials.standard({ baseColor: '#808080' });
+const explicitSrgb = Materials.unlit(Materials.srgb([0.5, 0.5, 0.5, 1]));
+```
+
 ### Resident material observation
 
 `renderer.inspect().meshMaterialBindings[]` is the detached observation of the
@@ -660,7 +876,7 @@ authority.
 
 Inspect the current path through `renderer.inspect()`. Its detached CPU snapshot exposes
 full rebuilds, no-change and delta frames, transform/material/instance updates,
-removals, the journal cursor, projection cardinality, and the last resync
+removals, the consumer-owned read version, projection cardinality, and the last resync
 reason. The nested `gpu` status is one of `inactive`, `unsupported`, `resident`,
 `rebuild-pending`, or `error`; resident state additionally reports capacity,
 upload ranges and bytes, grows, clears, rebuilds, and no-change frames. The
@@ -684,9 +900,9 @@ and emits indirect arguments with `firstInstance = 0`.
 
 The Standard frame activates the production raster lane when compute, storage
 buffers, and indirect drawing are available. The current lane accepts opaque,
-rigid default-unlit passes with batch-stable render state, ordinary instances,
-indexed or non-indexed geometry, multiple submeshes and material slots, and the
-canonical `12F` vertex layout. It also accepts persistent rigid multi-World
+rigid default-unlit triangle-list passes with batch-stable render state,
+ordinary instances, indexed or non-indexed geometry, multiple submeshes and
+material slots, and the canonical `12F` vertex layout. It also accepts persistent rigid multi-World
 composition. Candidates come from the complete persistent projection rather
 than the CPU-visible snapshot. The same typed graph imports the scene and mesh
 buffers, runs the three compute passes, and consumes generated arguments with
@@ -998,3 +1214,30 @@ const temporal = catalog.require('forgeax::scene-data::temporal-v1');
 available, `SceneDataUnavailableError` exposes the closed `reason`, missing
 producer IDs (at most 32 plus an omission count), and explicit `recovery`.
 Repair capability or producer coverage at its owner, then retry the next frame.
+
+## AI-readable SSR fallback route
+
+For the reflection fallback dependency evidence, call `renderer.inspect()` first
+and run the paired fixture. The fixture writes the current Browser/Dawn manifests;
+the collector then seals a fresh joint M0 guard for the current checkout:
+
+```bash
+pnpm --filter @forgeax/app-learn-render-6-pbr-4-render-target-reflection smoke:ssr-fallback
+pnpm --filter @forgeax/app-learn-render-6-pbr-4-render-target-reflection smoke:browser
+node scripts/forgeax/collect-ssr-dependency-report.mjs \
+  --input artifacts/ssr-fallback/dawn/ssr-dependencies-input.json \
+  --build-summary packages/render/dist/index.mjs \
+  --output artifacts/ssr-fallback/ssr-dependency-report.json
+```
+
+Each smoke writes its own detached `ssr-dependencies-input.json` beside the lane
+manifest; the command above uses the just-completed Dawn input (use the Browser
+path when inspecting that lane separately). The collector signs the output with
+the current source/tree/lock/build identity; it never promotes a stale
+sibling-loop report or an authored manifest. Read identity, generation, evidence
+level, and closed failure fields before following the named owner recovery action.
+Submit the same consumer request and reinspect after recovery. The route returns
+detached facts only: no live GPU handle, second owner, or second ledger is exposed.
+Missing or mismatched receipts remain
+`fallback-only` with zero SSR work; SSR v1, Hi-Z, ray marching, temporal resolve,
+compose, and history are out of scope.

package/dist/assembly/backend-contract.d.ts

@@ -2,6 +2,19 @@ import type { Result, RhiCanvasContext, RhiDevice, RhiError, RhiInstance, Shader
 /** Optional host hooks for recorder and device-lifecycle capabilities. */
 export interface RhiBackendInstrumentation {
     readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+    /**
+     * Optional deterministic submit fault seam for backend-owned integration
+     * fixtures. The callback runs after `finish()` and before the queue submit;
+     * returning an error aborts the frame transaction without changing the
+     * production queue contract.
+     */
+    readonly beforeSubmit?: (device: RhiDevice) => RhiError | undefined;
+    /**
+     * Optional device-loss projection for deterministic recovery fixtures. A
+     * backend may compose this promise with its native `device.lost` promise;
+     * normal production packs leave it undefined and use the native signal.
+     */
+    readonly deviceLost?: (device: RhiDevice) => RhiDevice['lost'];
     readonly onFrameBoundary?: () => void;
     readonly onDeviceLost?: () => void;
 }

package/dist/assembly/backend-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend-contract.d.ts","sourceRoot":"","sources":["../../src/assembly/backend-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACnF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG;QAC1B,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,MAAM,EAAE,iBAAiB,GAAG,eAAe,KACxC,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CACrC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAC3D,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;KAC1B,CAAC;IACF,gBAAgB;IAChB,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,SAAS,CAAC;IAC7E,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,CAAC,EAAE,yBAAyB,CAAC;CACtD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;CACnD;AAiCD,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;gBAElC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,4BAAiC;CAWtE"}
+{"version":3,"file":"backend-contract.d.ts","sourceRoot":"","sources":["../../src/assembly/backend-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACnF;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,QAAQ,GAAG,SAAS,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG;QAC1B,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,MAAM,EAAE,iBAAiB,GAAG,eAAe,KACxC,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CACrC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAC3D,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;KAC1B,CAAC;IACF,gBAAgB;IAChB,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,SAAS,CAAC;IAC7E,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,CAAC,EAAE,yBAAyB,CAAC;CACtD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;CACnD;AAiCD,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;gBAElC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,4BAAiC;CAWtE"}

package/dist/assembly/bundler-contract.d.ts

@@ -0,0 +1,9 @@
+import type { ImportTransport } from '@forgeax/engine-types';
+/** Build-tool inputs forwarded from the host into renderer assembly. */
+export interface BundlerOptions {
+    readonly importTransport?: ImportTransport | undefined;
+    readonly shaderManifestUrl?: string | undefined;
+    /** Exact checkout revision emitted by the build-tool adapter. */
+    readonly build?: string | undefined;
+}
+//# sourceMappingURL=bundler-contract.d.ts.map

package/dist/assembly/bundler-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundler-contract.d.ts","sourceRoot":"","sources":["../../src/assembly/bundler-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC"}

package/dist/assembly/device-feature-admission.d.ts

@@ -1,5 +1,13 @@
 import type { RhiAdapter, RhiDevice } from '@forgeax/engine-rhi';
 export declare const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+/**
+ * The complete Standard physical root can declare all optional texture slots.
+ * Its material group therefore needs one more sampled-texture entry than the
+ * extended-lighting topology alone. Request this ceiling when the adapter can
+ * provide it; lower-capability devices remain fail-closed at material
+ * pipeline admission instead of receiving an invalid WebGPU layout.
+ */
+export declare const STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES = 21;
 export interface DeviceFeatureAdmissionOptions {
     readonly gpuPassTiming?: object | undefined;
     readonly captureGpuTimings?: boolean | undefined;

package/dist/assembly/device-feature-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device-feature-admission.d.ts","sourceRoot":"","sources":["../../src/assembly/device-feature-admission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAYjE,eAAO,MAAM,sCAAsC,KAAK,CAAC;AAEzD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,gBAAgB,EAAE,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,gCAAgC,EAAE,MAAM,CAAC;KACnD,CAAC;CACH;AAED,KAAK,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE9F,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,6BAA6B,GACtC,sBAAsB,CAoBxB;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,6BAA6B,GACtC,sBAAsB,GAAG,SAAS,CAKpC;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,4BAA4B,CAAC,GAC7E,OAAO,CAOT"}
+{"version":3,"file":"device-feature-admission.d.ts","sourceRoot":"","sources":["../../src/assembly/device-feature-admission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAejE,eAAO,MAAM,sCAAsC,KAAK,CAAC;AACzD;;;;;;GAMG;AACH,eAAO,MAAM,2CAA2C,KAAK,CAAC;AAE9D,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,gBAAgB,EAAE,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,gCAAgC,EAAE,MAAM,CAAC;KACnD,CAAC;CACH;AAED,KAAK,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE9F,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,6BAA6B,GACtC,sBAAsB,CA0BxB;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,6BAA6B,GACtC,sBAAsB,GAAG,SAAS,CAKpC;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,4BAA4B,CAAC,GAC7E,OAAO,CAOT"}

package/dist/assembly/extended-lighting-fallback.d.ts

@@ -0,0 +1,13 @@
+import type { Buffer, RhiDevice, Texture, TextureView } from '@forgeax/engine-rhi';
+export interface ExtendedLightingFallbackResources {
+    readonly iesProfileTexture: Texture;
+    readonly cookieTexture: Texture;
+    readonly cookieMatrixBuffer: Buffer;
+    readonly iesProfileTextureView: TextureView;
+    readonly cookieTextureView: TextureView;
+    readonly ltcLambertTextureView: TextureView;
+    readonly ltcGgxTextureView: TextureView;
+}
+/** Allocate the always-valid fallback resources for the extended-lighting BGL. */
+export declare function createExtendedLightingFallbackResources(device: RhiDevice, enabled: boolean): ExtendedLightingFallbackResources | undefined;
+//# sourceMappingURL=extended-lighting-fallback.d.ts.map

package/dist/assembly/extended-lighting-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extended-lighting-fallback.d.ts","sourceRoot":"","sources":["../../src/assembly/extended-lighting-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EAEN,SAAS,EAET,OAAO,EACP,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAgB7B,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC;CACzC;AA0FD,kFAAkF;AAClF,wBAAgB,uCAAuC,CACrD,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,OAAO,GACf,iCAAiC,GAAG,SAAS,CA0F/C"}