@forgeax/engine-render 0.1.6 → 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
@@ -90,6 +188,15 @@ 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,
@@ -99,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.
 
@@ -131,6 +255,136 @@ 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.
 
+## Points and Lines authoring (M1)
+
+Points and Lines are first-class render components. Their geometry remains a
+normal `MeshAsset`, and their material remains the engine-owned
+`Materials.unlit` asset. The M1 path validates the complete candidate before
+any render publication; it does not add a second mesh, material, CLI, RPC, or
+manifest authority.
+
+```ts
+import { Lines, Materials, PointShapeValue, Points, admitPointsLines } from '@forgeax/engine-render';
+import { World } from '@forgeax/engine-ecs';
+import type { MeshAsset } from '@forgeax/engine-types';
+
+const positions = new Float32Array([0, 0, 0, 1, 0, 0, 2, 0, 0]);
+const pointMesh = {
+  kind: 'mesh',
+  vertices: positions,
+  attributes: { position: positions },
+  submeshes: [{
+    indexOffset: 0,
+    indexCount: 0,
+    vertexCount: 3,
+    topology: 'point-list',
+    materialSlot: 0,
+  }],
+  materialSlots: [{ slotName: 'default' }],
+} satisfies MeshAsset;
+const material = Materials.unlit([1, 0.5, 0.25, 1], { castShadow: false });
+const world = new World();
+const entity = world.spawn({
+  component: Points,
+  data: { sizePx: 4, shape: PointShapeValue.circle },
+}).unwrap();
+const admitted = admitPointsLines({
+  entity,
+  points: { sizePx: 4, shape: PointShapeValue.circle },
+  mesh: pointMesh,
+  material,
+});
+if (!admitted.ok) throw new Error(admitted.error.hint);
+
+world.spawn({ component: Lines, data: { widthPx: 2 } }).unwrap();
+```
+
+The style vocabulary is deliberately small in M1:
+
+| Component | Field | Default | Accepted values |
+|:--|:--|--:|:--|
+| `Points` | `sizePx` | `4` | finite number greater than `0` |
+| `Points` | `shape` | `square` | `square` or `circle` |
+| `Lines` | `widthPx` | `1` | finite number greater than `0` |
+
+Admission consumes one style component, one ordinary mesh topology, and one
+unlit forward material. Indexed and non-indexed `point-list` meshes are valid
+for `Points`; indexed and non-indexed paired `line-list` meshes are valid for
+`Lines`.
+
+| Candidate | M1 result | Reason |
+|:--|:--:|:--|
+| `Points` + `point-list` + finite positive `sizePx` + unlit forward material | supported | `square` and `circle` are the only point shapes |
+| `Lines` + paired `line-list` + finite positive `widthPx` + unlit forward material | supported | each pair is one line segment |
+| `line-strip`, triangle topology, mixed submeshes, or an odd line-list tail | refused | topology cannot be inferred or admitted atomically |
+| both `Points` and `Lines` on one candidate | refused | one entity has one style lane |
+| `Materials.standard`, shadow-caster, deferred, or another shader module | refused | M1 accepts one engine-owned unlit forward pass |
+| candidate count over `maxPoints` or `maxSegments` | refused | bounded admission prevents partial publication |
+
+When admission refuses a candidate, consume the structured result rather than
+parsing its message. The result exposes `.code`, `.expected`, `.hint`, and a
+code-specific `.detail` containing the relevant entity, component, mesh,
+material, submesh, lane, generation, or stage facts:
+
+```ts
+const result = admitPointsLines({ entity, points: {}, mesh: pointMesh, material });
+if (!result.ok) {
+  console.error(result.error.code);
+  console.error(result.error.expected);
+  console.error(result.error.hint);
+  console.error(result.error.detail);
+}
+```
+
+M1 intentionally refuses strip expansion, joins, caps, dashes, picking, and
+visible point/line draw preparation. Those are later implementation lanes, not
+implicit fallbacks in authoring code.
+
+## Points and Lines runtime contract
+
+The complete public closure is `MeshAsset` topology, one `Points` or `Lines`
+component, `Materials.unlit`, and the Standard renderer. The owner retains the
+source view, derives expanded geometry during prepare, and records the dedicated
+points-lines pipeline in the active main geometry pass. Applications do not
+create a second mesh, GPU buffer, shader module, cache, recovery ledger, or
+backend branch.
+
+| Surface | Supported contract | Refused or not claimed |
+|:--|:--|:--|
+| topology | indexed or non-indexed `point-list` and paired `line-list` | strips, triangles, mixed topology, and odd line tails |
+| style | finite positive `Points.sizePx` and `Lines.widthPx`; circle or square points | negative, non-finite, or lane-conflicting values |
+| material | engine-owned `Materials.unlit` forward material | standard/PBR, deferred, shadow-only, or custom runtime shader |
+| capability lane | direct WebGPU runtime; clustered unlit preserves the same authoring contract | CPU and WebGL2 require their declared capability route; no pixel result is inferred from RhiNull |
+| structural lane | RhiNull records retained projection, preparation, bindings, and draw shape | RhiNull is never hardware or pixel evidence |
+
+Prepare and record remain one lifecycle. A failed result is an owner fact, not a
+request to fall back to a generic mesh draw. Inspect the structured error and
+repair the source or producer, then retry the same renderer:
+
+```ts
+const inspection = renderer.inspect();
+const pointsLines = inspection.renderScene.pointsLines;
+// Repair the named source or producer, then retry inspection and draw.
+report(pointsLines);
+```
+
+Inspection reports source bytes, derived bytes, vertex/index counts, cache
+state, upload state, draw count, lane, and the retained `lastKnownGood` state.
+Recovery is `inspect -> producer rebuild or cold-cook -> prepare -> record`.
+It never publishes a partial expansion and never hides a stale-generation or
+missing-resource error.
+
+For visual evidence, use the topology probe and retain its raw screenshot,
+readback, source/derived byte counts, draw count, and validation errors. A
+focused direct-WebGPU probe is evidence for that lane only. The repository-wide
+`pnpm test:browser` gate was explicitly skipped by human override in this
+milestone and must not be reported as passed; the controlled Dawn attempt
+timed out during environment build before Dawn Vitest ran.
+
+The M5 boundary does not include strip joins, caps, dashes, picking, a new CLI
+or RPC operation, application-local WGSL, a second Geometry factory, or a
+separate cache/recovery authority.
+
 > [!IMPORTANT]
 > Owner: render vocabulary and the extract → prepare → record frame boundary. Runtime selects concrete services and calls this package; it does not re-own these tokens.
 
@@ -308,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.
 
@@ -506,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.