@forgeax/engine-render 0.1.7 → 0.1.19

package/README.md

@@ -1,5 +1,61 @@
 # `@forgeax/engine-render`
 
+> [!IMPORTANT]
+> The Standard pipeline keeps dark-gradient color in `rgba16float` until one
+> `outputTransform` reaches the `surface.storage.raw` endpoint; `inspect()` and
+> `observe()` expose stable graph/backend identity facts, while pixel metrics
+> belong exclusively to the Engine-owned hello-fxaa fixture report.
+
+## Public frame contract
+
+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
+an immutable `FramePlan`, records one frame, and returns a `FrameReceipt`.
+`FrameReceipt` is the only successful synchronous proof that the host submit
+reached the queue. Use `Renderer.inspect()` for detached lifecycle and
+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.
+
+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.
+
+```ts
+import {
+  ANTIALIAS_TAA,
+  Atmosphere,
+  Camera,
+  Fog,
+  type FramePlan,
+  type Renderer,
+} from '@forgeax/engine-render';
+
+void ANTIALIAS_TAA;
+void Atmosphere;
+void Camera;
+void Fog;
+declare const renderer: Renderer;
+declare const plan: FramePlan;
+void renderer.inspect();
+void plan;
+```
+
+Environment selection is a closed `none | image | atmosphere` fact. Multiple
+environment owners or multiple fog owners return structured errors with a
+code-specific `detail`; they do not create a second registry or silently pick
+the first entity. Frame facts contain IDs, revisions, and POD values only, not
+textures, buffers, devices, or other live GPU objects.
+
 ## Render happy path
 
 `RenderScene -> Standard Pipeline -> DeviceScope -> FrameReceipt` is the only frame
@@ -28,6 +84,36 @@ PBR, IBL, SSAO, bloom, tone, antialiasing, sky, material, VFX, and debug feature
 the same graph and submit boundary. CPU and WebGL2 fallback are capability lanes of that pipeline,
 not second renderer identities.
 
+## Stable inspection and dark-gradient evidence
+
+Progressive disclosure is intentional: read Camera configuration first, then
+the graph facts, backend facts, and finally the stable observation identity.
+The JSON-safe `RenderInspection` projection names the output contract directly:
+
+| Field | Meaning | Owner |
+|:--|:--|:--|
+| `outputTransform` | `forgeax::standard::output-transform` | Standard post chain |
+| `displayEncoded` | final output is display encoded | Output Transform |
+| `intermediateFormat` | linear intermediate format (`rgba16float`) | Standard target owner |
+| `surfaceStorage` / `surfaceDisplay` | raw storage and display surface formats | surface adapter |
+| `endpoint` | `surface.storage.raw` | backend adapter |
+| `capability` / `error` | structured availability and recovery facts | RHI/render surface |
+| `observation.observationId` / `frameId` | stable correlation refs | renderer observation owner |
+
+`renderer.inspect()` and `renderer.observe()` never carry ROI pixels, scanlines,
+brightness or level metrics. The hello-fxaa `hello-fxaa/dark-gradient/v1`
+fixture report owns those fields and records the fixed camera, low-light scene,
+800x600 resolution, 300-frame schedule, ROI, scanline, backend/lane, surface
+formats, pixel hash, validation errors and mutation falsifiers.
+
+The report gates are explicit: unique-color ratio $r_U \ge 0.75$, level ratio
+$\ge 0.70$, mean absolute channel delta $\le 2/255$, parity $\ge 0.95$, and
+non-black pixels with zero validation errors. The three local-only falsifiers
+(`eight-bit-intermediate`, `missing-oetf`, `duplicate-oetf`) must each fail their
+expected gate. Missing Browser, Dawn or WebGL2 evidence remains
+`insufficient-evidence`; a screenshot, RhiNull topology result or M3 surface
+contract is not a pixel proof.
+
 ## Direct-light parity contract
 
 The direct-light proposition is: one public `DirectionalLight`/`PointLight`/
@@ -70,6 +156,18 @@ must retain `provenance`, `captures`, `raw hash`, `analyticMax`, `roiMax`, and
 `verdict` for each backend x pipeline x case. A same-canvas self-comparison or
 analytic-only green result is not direct-light parity evidence.
 
+## Transmission and refraction route
+
+Standard material transmission is consumed through the existing renderer path. The renderer owns one
+`TransmissionBackdrop` copy and optional rough-mip chain per active view, then records transmission
+before ordinary transparent work and publishes detached facts through `renderer.inspect().transmission`.
+Use the returned `extent`, `format`, `mipCount`, `bytes`, capability, lifecycle, and recovery fields as
+the evidence source; do not create an app-local backdrop or parse diagnostic messages.
+
+Smooth and rough refraction share the same Standard material contract. Roughness selects the renderer
+owned mip path, while edge/TIR fallback resolves to environment and then unrefracted color. The direct
+and clustered lanes consume the same topology and one submit.
+
 ## Particle feature boundary
 
 Particle rendering is provided by
@@ -108,6 +206,23 @@ 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
+validated parameters are `shutterAngle` in `[0, 360]`, `maxRadiusPixels` in
+`[0, 64]`, and integer `sampleCount` in `[4, 16]`. Zero shutter is an explicit
+zero-work case. The feature reads the shared `scene-data-temporal` sampled token
+and contributes one raster pass after optional TAA and before Bloom. It does
+not own a previous frame, write TAA history, allocate storage/compute state, or
+cache an RHI handle.
+
+`renderer.inspect()` exposes only detached Motion Blur POD facts when the
+component is active: status, bounded parameters, demand, pass identity, and
+the invariant `historyWrites: 0`. Invalid parameters and unavailable temporal
+data are structured failures with owner-specific recovery; callers should fix
+the component or capability and retry the same frame. The hello-taa carrier
+contains the four-lane smoke and falsifier evidence.
+
 > [!IMPORTANT]
 > Render consumes the effective MaterialAsset snapshot produced by extract. Each texture slot carries its own coordinate set and transform into the built-in PBR binding layout; render records do not reinterpret authoring fields or manufacture shader artifacts. The effective `passes` are already validated.
 
@@ -447,8 +562,8 @@ world.spawn({
 }).unwrap();
 ```
 
-The built-in pass samples the HDR target and writes the LDR result through the
-registered `forgeax::tonemap` fullscreen shader. Shader source authority is
+The built-in Output Transform samples the linear scene target and writes the
+display-encoded result before FXAA, post effects, and present. Shader source authority is
 [`packages/shader/src/tonemap.wgsl`](../shader/src/tonemap.wgsl); the render
 package does not duplicate those formulas.
 
@@ -645,3 +760,26 @@ hide the issue with a custom mesh, camera workaround, or material substitute.
 Out of scope: camera frustum policy, picking, app lifecycle, asset import, and
 VFX shadow behavior. `@forgeax/engine-vfx-render` remains the producer-owned
 particle bridge and consumes the same effective visibility boundary.
+
+## Semantic scene data
+
+Temporal consumers request the producer-owned `forgeax::scene-data::temporal-v1`
+schema through `createSceneDataCatalog`. The catalog returns an opaque,
+sampled-read-only `SceneDataTarget`; consumers place that token in
+`RenderFeaturePlan` `sampledTargets` and never author an attachment, raw GPU
+handle, private velocity buffer, or parallel graph ledger.
+
+```ts
+const catalog = createSceneDataCatalog({
+  featureIdentity: 'taa',
+  generation: 1,
+  planIdentity: 'taa:1',
+  rgba16floatRenderable: true,
+});
+const temporal = catalog.require('forgeax::scene-data::temporal-v1');
+```
+
+`catalog.inspect()` is the bounded inspection surface. If the schema is not
+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.