@forgeax/engine-render 0.1.2

package/src/components/environment.ts

@@ -0,0 +1,206 @@
+// @forgeax/engine-runtime - Skylight (ambient environment light).
+//
+// Schema: 4 fields -- equirect (Handle<EquirectAsset>, u32-stored handle,
+// OPTIONAL) + color (array<f32,3>, default [1,1,1] = white) + intensity (f32,
+// default 1.0) + rotation (quaternion xyzw, default identity). feat-20260709 M2 collapsed colorR/G/B into one inline
+// array<f32,3> column. Naming convention follows the DirectionalLight / PointLight /
+// SpotLight family: no Component suffix (AGENTS.md rule #1).
+//
+// Plan-strategy D-6: Skylight component schema is registered but no
+// independent ECS system is created. All Skylight processing happens inside
+// RenderSystem's extract/record phases.
+//
+// AI user minimum spawn (AC-13, charter P4):
+//   world.spawn({ component: Skylight, data: {} });  // instant white ambient
+//
+// A single Skylight activates ambient lighting transparently. The `equirect`
+// field is OPTIONAL: omit it for a constant solid-color ambient that needs NO
+// async GPU precompute -- the engine binds a 1x1 white irradiance cube, so
+// ambient = color * intensity * albedo is live on the very first frame (this
+// is the fix for the downstream "scene is black until the async IBL cubemap
+// finishes uploading" gap). Supply an equirect to upgrade to full image-based
+// lighting (diffuse irradiance + specular prefilter); `color` * `intensity`
+// still scales the IBL result, so both are live dynamic dials either way.
+//
+// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w16:
+// the field is `equirect: shared<EquirectAsset>` (the retired
+// `cubemap: shared<CubeTextureAsset>` is gone). AI users declare the equirect
+// source directly; the render-system record arm projects the cubemap + IBL
+// chain internally and lazily (no user upload call) -- there is no
+// uploadCubemapFromEquirect on the public surface.
+//
+// Edge cases handled by w18 / w19:
+//   - Multi-Skylight: first archetype hit wins, console.warn in dev+prod
+//   - intensity=0: ambient term = 0, mathematically valid, no warn
+//   - No equirect: solid-color ambient via the white fallback cube (no async)
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Skylight ambient environment light.
+ *
+ * A single Skylight entity provides ambient lighting for all StandardMaterial
+ * surfaces. Two modes share one component:
+ *
+ * - **Solid-color ambient (no equirect).** Omit `equirect` for a constant
+ *   ambient = `color` * `intensity` applied immediately, with no async GPU
+ *   precompute. The engine samples a built-in 1x1 white irradiance cube, so a
+ *   freshly-loaded scene is lit on its first frame instead of being black
+ *   until an IBL upload finishes.
+ * - **Image-based lighting (with equirect).** Supply `equirect` to upgrade to
+ *   diffuse irradiance + specular prefilter IBL. The engine runs the full
+ *   precompute (equirect->cubemap, irradiance convolution, prefilter mip
+ *   chain, BRDF LUT) transparently inside the render-system record arm;
+ *   `color` * `intensity` then scale the IBL ambient.
+ *
+ * `equirect` is an OPTIONAL `Handle<EquirectAsset>` resolved from a vite
+ * pack-index GUID via `assets.load(guid, equirectAssetKind)`. The
+ * cubemap projection is internal and idempotent: the same equirect source
+ * always resolves to the same GPU cubemap (no user upload call).
+ *
+ * `color` is the linear-space ambient tint (default white [1, 1, 1]).
+ * `intensity` is a linear multiplier (default 1.0; 0 disables ambient). Both
+ * are read every frame, so they are live dynamic dials.
+ *
+ * `rotation` is an environment-space quaternion in `[x, y, z, w]` order.
+ * The default identity quaternion leaves the source orientation unchanged;
+ * changing it rotates the IBL at sample time without rebaking the source.
+ *
+ * @example Instant white ambient (no asset, no async):
+ *   world.spawn({ component: Skylight, data: {} });
+ *
+ * @example Dim warm ambient:
+ *   world.spawn({ component: Skylight, data: { color: [1, 0.9, 0.8], intensity: 0.3 } }); // color is [r, g, b]
+ *
+ * @example Full IBL from an HDR equirect (declarative -- no upload call):
+ *   // 1. resolve GUID from vite pack-index (see forgeax-engine-vite-plugin-pack)
+ *   import { AssetGuid } from '@forgeax/engine-pack/guid';
+ *   const guidRes = AssetGuid.parse('019e4a26-3c29-7420-af5d-20f2724a16b0');
+ *   if (!guidRes.ok) throw guidRes.error;
+ *   // 2. load the HDR equirect via the GUID-addressed pack route
+ *   const hdrRes = await assets.load(guidRes.value, equirectAssetKind);
+ *   if (!hdrRes.ok) throw hdrRes.error;
+ *   // 3. spawn the Skylight — the equirect handle activates the full IBL path;
+ *   //    the cubemap + IBL precompute happen lazily inside the record arm.
+ *   world.spawn({ component: Skylight, data: { equirect: hdrRes.value } });
+ */
+export const Skylight = defineComponent('Skylight', {
+  // The GPU equirect-to-cubemap projection is render-owned presentation
+  // state. Record/restore preserves the portable lighting controls while the
+  // render owner resolves this asset again on the target world.
+  equirect: { type: 'shared<EquirectAsset>', simulationTransient: true },
+  // color carries an explicit layer-2 default [1,1,1] (white); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1.0 },
+  rotation: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
+});
+
+export const Fog = defineComponent('Fog', {
+  color: { type: 'array<f32, 3>', default: new Float32Array([0.5, 0.5, 0.5]) },
+  density: { type: 'f32', default: 0.01 },
+  heightFalloff: { type: 'f32', default: 0 },
+  maxOpacity: { type: 'f32', default: 1 },
+});
+
+// @forgeax/engine-runtime - SkyboxBackground (environment cubemap render background).
+//
+// Schema: 3 fields -- equirect (Handle<EquirectAsset>, u32-stored handle)
+// + mode (f32 enum column, discriminator) + rotation (quaternion xyzw,
+// default identity). Naming convention follows the
+// single-semantic component rule: no Component suffix (AGENTS.md rule #1).
+//
+// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w16:
+// the field is `equirect: shared<EquirectAsset>` (the retired
+// `cubemap: shared<CubeTextureAsset>` is gone). The skybox reuses the same
+// equirect handle as the Skylight; the cubemap projection is internal and
+// driven by the render-system record arm (no user upload call).
+//
+// Plan-strategy D-5: mode is a f32 enum column (ECS columns are POD, no
+// string unions in archetype storage). Consumer-facing type safety is
+// provided by the `SkyboxMode` literal union + `skyboxModeFromF32` mapper
+// (same pattern as cameraProjectionFromF32 in camera.ts:51,105,145,221-237).
+//
+// OOS-1: `mode: 'atmosphere'` implementation is deferred -- the union
+// shape leaves room for additive growth without breaking the f32 enum
+// encoding.
+//
+// AI user minimum spawn (charter P4):
+//   world.spawn({ component: SkyboxBackground, data: { equirect, mode: 0 } });
+//
+// Single component activates the skybox render pass transparently when a
+// Skylight + tonemap active camera is present (skybox reuses the same
+// equirect handle as Skylight).
+
+/**
+ * Skybox mode literal union (AC-02 narrowing surface).
+ * Currently only 'cubemap' -- future 'atmosphere' deferred per OOS-1.
+ */
+export type SkyboxMode = 'cubemap';
+
+/** Numeric encoding of cubemap skybox mode (schema value for `mode`). */
+export const SKYBOX_MODE_CUBEMAP = 0;
+
+/**
+ * Map a `SkyboxBackground.mode` numeric value to the closed `SkyboxMode`
+ * string-literal union. Only member currently is 'cubemap'; the exhaustive
+ * switch is ready for future mode additions (e.g. 'atmosphere', OOS-1).
+ */
+export function skyboxModeFromF32(value: number): SkyboxMode {
+  switch (value) {
+    case SKYBOX_MODE_CUBEMAP:
+      return 'cubemap';
+    // Future: case SKYBOX_MODE_ATMOSPHERE: return 'atmosphere';
+  }
+  // Unrecognised value: fall back to 'cubemap' (charter P3 -- no silent
+  // exception; the fallback preserves rendering on stale numerics while the
+  // exhaustive switch shape ensures AI users catch new members at compile
+  // time when a mode is added).
+  return 'cubemap';
+}
+
+/**
+ * SkyboxBackground: full-screen environment cubemap background.
+ *
+ * Renders a fullscreen triangle that reconstructs world-space view
+ * direction from the camera's inverseViewProj matrix (View UBO),
+ * samples a cubemap with the view direction, and writes an HDR color
+ * to the hdrColor render target (before the main geometry pass).
+ *
+ * The skybox pass is automatically activated when a SkyboxBackground
+ * entity exists, a Skylight entity provides the equirect source, and the
+ * active Camera has tonemap active. The skybox reuses the same equirect
+ * handle as the Skylight entity -- two independent components sharing the
+ * same GPU resource (the internally-projected cubemap).
+ *
+ * `equirect` is a `Handle<EquirectAsset>` resolved from a vite pack-index
+ * GUID via `engine.assets.loadByGuid<EquirectAsset>(guid)`. The cubemap
+ * projection is internal and driven by the render-system record arm; there
+ * is no user upload call.
+ *
+ * `mode` is a numeric discriminator column (`f32`). Use
+ * `SKYBOX_MODE_CUBEMAP` for the cubemap render path.
+ *
+ * `rotation` is an environment-space quaternion in `[x, y, z, w]` order.
+ * It rotates the sampled cubemap without changing the camera or rebaking the
+ * source equirectangular asset.
+ *
+ * @example Minimum spawn (defaults mode=0):
+ *   // equirectHandle resolved from loadByGuid<EquirectAsset> (same handle as
+ *   // the Skylight).
+ *   world.spawn({ component: SkyboxBackground, data: { equirect: equirectHandle } });
+ *
+ * @example Single handle shared between Skylight (IBL) and SkyboxBackground:
+ *   const hdrRes = await engine.assets.loadByGuid<EquirectAsset>(guid);
+ *   if (!hdrRes.ok) throw hdrRes.error;
+ *   world.spawn({ component: Skylight, data: { equirect: hdrRes.value } });
+ *   world.spawn({ component: SkyboxBackground, data: { equirect: hdrRes.value } });
+ */
+export const SkyboxBackground = defineComponent('SkyboxBackground', {
+  // The GPU skybox projection is render-owned presentation state; restore
+  // keeps the portable mode/rotation controls and lets the owner re-resolve
+  // the environment asset on the target world.
+  equirect: { type: 'shared<EquirectAsset>', simulationTransient: true },
+  mode: { type: 'f32', default: SKYBOX_MODE_CUBEMAP },
+  rotation: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
+});

package/src/components/glyph-text.ts

@@ -0,0 +1,63 @@
+// @forgeax/engine-runtime - GlyphText component (feat-20260531-world-space-msdf-text-rendering M4 / w14).
+//
+// `GlyphText` is the authoring source component for world-space MSDF text
+// (requirements AC-06 / §domain model). It carries ONLY authoring data; the
+// glyph quad baking + MeshFilter / MeshRenderer attachment is the job of the
+// `glyphTextLayoutSystem` (plan-strategy D-2: GlyphText is pure authoring
+// data, baking is a system responsibility). There is NO `TextLayoutAsset`
+// intermediate (OOS-5) -- layout output lives directly in a baked MeshAsset.
+//
+// Naming: single-semantic component drops the `Component` suffix
+// (AGENTS.md §Component naming rule #1 -- Transform / Camera / GlyphText).
+//
+// Schema vocab:
+//   - `fontHandle: 'shared<FontAsset>'` -> `Handle<'FontAsset', 'shared'>`
+//     (u32-stored; AssetRegistry owns the FontAsset lifecycle). AI users
+//     obtain the handle via `assets.load(guid, fontAssetKind)`.
+//   - `text: 'string'` -> native JS string (UniqueRefStore-backed, same
+//     dispatch as `Name.value`).
+//   - `fontSize: 'f32'` -> layout scale applied to the FontAsset metrics.
+//   - `color: 'array<f32, 4>'` -> linear-space rgba tint (feat-20260709 M3:
+//     collapsed from four `colorR/G/B/A` scalar columns into one inline
+//     stride-4 SoA column, mirroring the DirectionalLight direction/color
+//     idiom). Explicit layer-2 default [1,1,1,1] (opaque white).
+//
+// charter mapping: P1 (single import surface from `@forgeax/engine-render`,
+// co-located with `glyphTextLayoutSystem` that consumes it) + P3
+// (machine-readable schema literal) + P5 (consistent abstraction: same
+// `'shared<T>'` idiom as MeshFilter.assetHandle / MeshRenderer.materials).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Glyph text authoring component (world-space MSDF text).
+ *
+ * Spawn an entity with a `GlyphText` and the `glyphTextLayoutSystem`
+ * (auto-wired by `createRenderer` / `createApp`) lays out the glyph quads,
+ * bakes a `MeshAsset`, and attaches `MeshFilter` + `MeshRenderer` on the
+ * next frame (Commands-deferred). Mutating `text` / `fontSize` / `color`
+ * re-bakes the mesh in place (plan-strategy D-1 updateMesh; registry size
+ * unchanged, AC-08).
+ *
+ * @example Spawn a world-space label:
+ *   import { GlyphText } from '@forgeax/engine-render/authoring';
+ *   const font = (await assets.load(fontGuid, fontAssetKind)).unwrap();
+ *   world.spawn({
+ *     component: GlyphText,
+ *     data: { fontHandle: font, text: 'Hello', fontSize: 32,
+ *             color: [1, 1, 1, 1] },
+ *   });
+ */
+export const GlyphText = defineComponent('GlyphText', {
+  // The layout/render owner re-resolves the font asset on the target world;
+  // authoring text and style remain portable simulation state.
+  fontHandle: {
+    type: 'shared<FontAsset>',
+    default: 0 as never,
+  },
+  text: { type: 'string', default: '' },
+  fontSize: { type: 'f32', default: 16 },
+  // color carries an explicit layer-2 default [1,1,1,1] (opaque white); the
+  // array layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: 'array<f32, 4>', default: new Float32Array([1, 1, 1, 1]) },
+});

package/src/components/index.ts

@@ -0,0 +1,49 @@
+export { Atmosphere } from './atmosphere';
+export * from './camera';
+export * from './directional-light';
+export {
+  Fog,
+  SKYBOX_MODE_CUBEMAP,
+  SkyboxBackground,
+  type SkyboxMode,
+  Skylight,
+  skyboxModeFromF32,
+} from './environment';
+export { Instances, type InstancesData } from './instances';
+export { Layer } from './layer';
+export * from './mesh-filter';
+export * from './mesh-renderer';
+export { PointLight } from './point-light';
+export { PointLightShadow } from './point-light-shadow';
+export { PostProcessParams } from './post-process-params';
+export {
+  SceneInstance,
+  type SceneInstanceOverrideRecord,
+  type SceneInstanceState,
+} from './scene-instance';
+export { SortKey } from './sort-key';
+export { SpotLight } from './spot-light';
+export { SpriteAnimation } from './sprite-animation';
+export { SpriteInstances, type SpriteInstancesData } from './sprite-instances';
+export {
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  type SpritePlaybackMode,
+  spritePlaybackModeFromU32,
+} from './sprite-playback-mode';
+export { SpriteRegionOverride } from './sprite-region-override';
+export {
+  decodeSortScope,
+  encodeSortScope,
+  markTileLayerDirty,
+  type SortScope,
+  TileLayer,
+  type TileLayerData,
+} from './tile-layer';
+export { Tilemap } from './tilemap';
+export {
+  Visibility,
+  type VisibilityState,
+  VisibilityStateValue,
+  visibilityStateFromU32,
+} from './visibility';

package/src/components/instances.ts

@@ -0,0 +1,207 @@
+// @forgeax/engine-render - Instances component (per-entity instanced-draw transforms).
+//
+// Two sources, one component (feat-20260622-chunk-gpu-instancing-sprite-tilemap
+// / AC-09; charter P4 consistent abstraction + charter P1 progressive disclosure).
+// The `Instances` ECS component has exactly TWO sources of `transforms` data, and
+// AI users should hold the boundary explicitly to avoid misreading the ECS view:
+//
+//   Source 1 (EXPLICIT, the only source that lands in ECS) — AI user opt-in.
+//     The AI user hand-attaches `Instances { transforms }` onto an entity at
+//     spawn / set time for high-performance instanced draw. `world.get(e,
+//     Instances)` returns the AI user's payload verbatim (a `Float32Array`
+//     snapshot of column-major mat4 instances; stride = 16). This is the sole
+//     code path through which `Instances` ever appears on an entity.
+//
+//   Source 2 (TRANSPARENT, never written back into ECS) — engine record-stage
+//     fold. When the AI user spawns N independent sprite / tilemap-cell
+//     entities sharing the same (Layer.value, posZ, materialHandle) sort
+//     equivalence class, the engine record stage transparently folds the
+//     equivalent run into ONE `drawIndexed(indexCount, count)` using an
+//     INTERNAL transient buffer (see `render-system-record.ts` fold operator
+//     + `render.instancing.foldedDraws` metric, and the `RhiError
+//     'instancing-exceeds-uniform-cap'` fallback). The fold operator does
+//     NOT auto-inject `Instances` onto those entities — `world.get(e,
+//     Instances)` on a folded entity returns `Result.err` exactly as before.
+//     The ECS view is preserved bit-for-bit (per-cell / per-sprite entity
+//     retained, query / despawn / picking unchanged); the optimisation is
+//     invisible at the component layer (charter P4: consistent abstraction —
+//     the high-performance path is opt-in via Source 1, the default spawn
+//     shape stays untouched).
+//
+// AI user reading this header: do NOT expect engine-side fold to materialise
+// as an `Instances` row on your entity. Read the metric (foldedDraws) or the
+// RhiError code to observe fold behaviour; never gate logic on a runtime
+// `world.get(e, Instances)` lookup after spawn.
+//
+// Schema: 1 array<f32> field `transforms` carrying packed column-major mat4
+// instance transforms (16 f32 per instance, stride = 16). Stride is enforced
+// through a TWO-LAYER contract:
+//
+//   1. AI user set-site: spawn / `world.set` / `world.push` callers pass a
+//      `Float32Array` (or numeric array) whose `length` is a non-zero
+//      multiple of 16. The set site is the AI user's responsibility -- the
+//      engine cannot prove the column-major mat4 packing without the
+//      caller's intent.
+//   2. RenderSystem extract entry: `render-system-extract.ts` performs a
+//      defensive `transforms.length % 16 === 0` check on every
+//      `world.get(e, Instances).transforms` snapshot at frame extract time;
+//      violations route a structured `InstanceTransformsStrideMismatchError`
+//      (`code: 'instance-transforms-stride-mismatch'`,
+//      `detail: { actualLength, expectedStride: 16 }`) through the World
+//      Layer-3 ErrorHandler and the renderable is skipped (fail-fast: the
+//      malformed length never reaches the GPU upload path).
+//
+// feat-20260515-buffer-array-vocab-collapse M3 / w16 (decision §2.3 stride
+// responsibility migration): the legacy component-level
+// stride-declaration option (`{ transforms: 16 }` keyed on the retired
+// per-component stride defineComponent option key) was retired because:
+//   - The ECS layer no longer carries any per-component stride schema (M2 /
+//     w9 dropped the option from `DefineComponentOptions` -- the SSOT
+//     moved to the RenderSystem entry + AI user set site).
+//   - Centralising the check at the consumer (RenderSystem extract) rather
+//     than the producer (ECS write paths) lets the GPU upload path stay
+//     trust-the-snapshot; AI users get one structured error per offending
+//     frame rather than one per write.
+//
+// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w14:
+// migrated from the legacy `{ buffer: 'ref', count: 'u32' }` pair (which
+// cross-coupled with the now-deleted `AssetRegistry.createInstancedBuffer`
+// pipeline + the `InstancedBufferAsset` POD) to the ECS-managed array path.
+// Resize is a `world.push(e, Instances, 'transforms', value)` away (one f32
+// at a time) plus a future `world.grow` if a bulk-resize affordance is
+// added.
+//
+// Storage buffer cap-gate (D-5 OOS-08 follow-up):
+//   - The runtime RenderSystem consumer (`render-system-record.ts`) checks
+//     `device.caps.storageBuffer` before binding the per-entity transforms;
+//     `caps.storageBuffer === false` (backend lacking storage buffer support,
+//     e.g. rhi-wgpu webgl backend) routes a `RhiError` ('feature-not-enabled').
+//     A future loop owns the per-draw fallback path.
+//
+// Group transform chained semantics (charter proposition 5 mental migration):
+//   - When the same entity carries both `Transform` (entity_world) and
+//     `Instances` (per-instance local transforms), the vertex shader
+//     composes per instance:
+//
+//       world_position[i] = entity_world * instances_local[i] * vertex_position
+//
+//   - `Instances.transforms[i*16..i*16+15]` is interpreted as a local-space
+//     transform under the entity, exactly like a child entity's `Transform`
+//     under `ChildOf { parent }` in the hierarchy system. AI users reuse
+//     the `parent x local` intuition without a new concept. Set the
+//     entity's `Transform` to identity to make `instances_local[i]`
+//     directly world-space.
+//
+// 4-segment minimum contract (read this header before reaching for
+// the source body):
+//
+// ===== (a) single-component import + spawn example =====
+//
+//   import {
+//     createRenderer,
+//     createPrimitiveMesh,
+//     MeshFilter, MeshRenderer, Transform,
+//     Instances, type InstancesData,
+//   } from '@forgeax/engine-render';
+//
+//   // 1 entity rendering N instanced cubes (16N packed f32, column-major mat4):
+//   const transforms = new Float32Array(N * 16);
+//   // ... fill column-major mat4 columns per instance ...
+//   world.spawn(
+//     { component: MeshFilter,    data: { assetHandle: cubeMesh } },
+//     { component: MeshRenderer,  data: {} },
+//     { component: Instances,     data: { transforms } },
+//   );
+//
+// ===== (b) packed mat4 layout =====
+//
+//   const transforms = new Float32Array(N * 16); // column-major mat4 per instance
+//   // instance i occupies floats [i*16 .. i*16+15]:
+//   //   [m00 m10 m20 m30   <- column 0
+//   //    m01 m11 m21 m31   <- column 1
+//   //    m02 m12 m22 m32   <- column 2
+//   //    m03 m13 m23 m33]  <- column 3 (translation in m03/m13/m23)
+//
+// `transforms.length` MUST be a non-zero multiple of 16. AI users gate at
+// the set / push site; the RenderSystem extract entry holds the second
+// defensive (AC-06: detail carries `{ expectedStride: 16, actualLength }`).
+// The instance count is the live snapshot length / 16.
+//
+// ===== (c) error code consumption (typed property access, no message regex) =====
+//
+//   // Stride violation surfaces through the engine-ecs Layer-3 ErrorHandler
+//   // when extract reads a malformed snapshot:
+//   //   on('error', (err) => {
+//   //     if (err.code === 'instance-transforms-stride-mismatch') {
+//   //       // err.detail.expectedStride === 16
+//   //       // err.detail.actualLength === <user-supplied length>
+//   //     }
+//   //   });
+//   //
+//   // RenderSystem cap-gate (D-5) -> RhiError 'feature-not-enabled' on the
+//   // RhiErrorListenerRegistry channel:
+//   //   on('error', (err) => {
+//   //     if (err.code === 'feature-not-enabled') {
+//   //       console.warn(err.expected, err.hint);
+//   //     }
+//   //   });
+//
+// charter mapping: proposition 1 (single import surface
+// `import { Instances, type InstancesData } from '@forgeax/engine-render'`);
+// proposition 3 (machine-readable schema > prose:
+// `{ transforms: 'array<f32>' }` is the SSOT, stride 16 documented here +
+// enforced at the RenderSystem entry);
+// proposition 4 (explicit failure: stride violation routes a structured
+// EcsError, not a silent half-row); proposition 5 (consistent abstraction:
+// Instances mirrors Children -- both ride the array-vocab path).
+//
+// Anchors: requirements §AC-06 (stride 16 + RenderSystem upload path);
+// plan-strategy §2.3 (stride responsibility migration to RenderSystem entry
+// defensive + AI user set site) + §3.3 stride error path; plan-decisions
+// D-1 / D-5.
+// OOS-09 (no addChild Commands API) does not apply here; OOS-01 (no
+// dangling-entity sweep) does not apply (Instances stores f32 not entity).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Per-entity instanced-draw transforms (ECS component).
+ *
+ * Carries a variable-length `array<f32>` of column-major mat4 instance
+ * transforms (16 f32 per instance, stride = 16; documented above and
+ * enforced at the RenderSystem extract entry, NOT at the ECS write paths).
+ *
+ * The runtime RenderSystem consumer materialises a fresh `Float32Array`
+ * snapshot on every `world.get(e, Instances).transforms` access (D-4
+ * no-cache), reads the live count from the snapshot's `length`, and
+ * uploads the bytes to a per-entity GPU storage buffer in the record stage
+ * (`render-system-record.ts`).
+ *
+ * @example Spawn an entity rendering 10000 instanced cubes:
+ *   const transforms = new Float32Array(10000 * 16);
+ *   // ... fill column-major mat4 columns ...
+ *   world.spawn(
+ *     { component: MeshFilter,   data: { assetHandle: cubeMesh } },
+ *     { component: MeshRenderer, data: { ... } },
+ *     { component: Instances,    data: { transforms } },
+ *   );
+ */
+export const Instances = defineComponent('Instances', {
+  transforms: { type: 'array<f32>' },
+});
+
+/**
+ * Type-level hint for `data` at the `Instances` spawn site.
+ *
+ * The runtime ECS column shape for `array<f32>` accepts a `Float32Array`
+ * payload at spawn / set time (the bytes are copied into the BufferPool
+ * slot). The `transforms` field is documented as `Float32Array` here so
+ * AI-user IDE autocomplete picks up the typed-array shape.
+ *
+ * @example
+ *   import type { InstancesData } from '@forgeax/engine-render';
+ *   const data: InstancesData = { transforms: new Float32Array(N * 16) };
+ */
+export type InstancesData = {
+  readonly transforms: Float32Array;
+};

package/src/components/layer.ts

@@ -0,0 +1,69 @@
+// @forgeax/engine-render - Layer (render-order layer index, signed 32-bit).
+//
+// Schema: 1 i32 column (value). Signed two's complement so negatives travel
+// through the spawn payload unchanged — background sprites live at negative
+// values (e.g. -100), the default game layer at 0, foreground at 100, UI at
+// 1000. Layer is consumed at sort time by `transparent-sort.ts` (M-3 w23)
+// as the primary key in the (layer asc, sortValue asc) composite ordering.
+//
+// Naming convention: bare entity name (no Component suffix; single-semantic
+// component idiom aligned with Bevy ECS conventions — Transform / Camera /
+// DirectionalLight follow the same shape, see AGENTS.md §Component naming).
+//
+// Layer is a generic ECS renderer component — NOT a 2D-only special. 3D
+// entities may also carry Layer to bias their bucket placement (charter
+// P4 consistent abstraction: same component drives both pipelines).
+//
+// AC-18 path (1): an entity spawned without an explicit Layer reads back
+// 0 via the existing 4-layer spawn fallback chain
+// (feat-20260517-spawn-default-fallback). This feat does NOT introduce a
+// fifth fallback layer; the silent default flows through layer-3
+// `typeDefault('i32') === 0`.
+//
+// @derives defineComponent factory (packages/ecs/src/component.ts) — i32
+//   is a legacy scalar type; its intrinsic properties (byteSize / viewCtor
+//   / storage) live in TYPE_METADATA['i32'] (feat-20260602 M1).
+// @reuses spawn 4-layer fallback chain (feat-20260517-spawn-default-fallback)
+//   — layer-3 typeDefault('i32') returns 0, no fifth layer.
+//
+// charter mapping: F1 (single-import barrel discovery — Layer joins
+// Transform / MeshFilter / MeshRenderer / Camera / DirectionalLight)
+// + P3 (explicit default — 0 surfaces as a read-back value, not undefined)
+// + P4 (consistent abstraction — Layer is a generic render component, not
+// a 2D-only special).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Render-order layer index.
+ *
+ * Convention (non-binding; conveys intent, not enforced):
+ *   - negative (e.g. -100): background layers (sky / parallax tiles).
+ *   - 0: default game layer.
+ *   - positive (e.g. 100): foreground layers (overlays, FX).
+ *   - 1000+: UI / HUD.
+ *
+ * Signed i32 (two's complement, range \u00b12\u00b3\u00b9). Negatives round-trip
+ * through the spawn payload unchanged — no schema-layer mutate. i32 lives in
+ * the CPU sort path (transparent-sort.ts M-3 w23); no GPU-side stride
+ * compatibility risk.
+ *
+ * @example Minimal spawn (defaults to game layer 0):
+ *   world.spawn({ component: Layer, data: {} }); // yields value=0
+ *
+ * @example Spawn 4 sprites across the conventional layer band:
+ *   world.spawn({ component: Layer, data: { value: -100 } }); // background
+ *   world.spawn({ component: Layer, data: { value: 0 } });    // default
+ *   world.spawn({ component: Layer, data: { value: 100 } });  // foreground
+ *   world.spawn({ component: Layer, data: { value: 1000 } }); // UI
+ *
+ * @example Spawn payload omitting Layer — the 4-layer fallback fills 0:
+ *   const e = world.spawn(
+ *     { component: Transform, data: { pos: [0, 0, 0],
+ *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+ *   );
+ *   // Layer is not on the entity; query joins must check membership.
+ */
+export const Layer = defineComponent('Layer', {
+  value: { type: 'i32', default: 0 },
+});