@forgeax/engine-render 0.1.6 → 0.1.7

package/README.md

@@ -90,6 +90,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,
@@ -131,6 +140,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.