@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/scene-utils/mount-override-fold.ts

@@ -0,0 +1,213 @@
+// feat-20260713-mount-override-component-add-and-shared-ref-round M5 / w20 —
+// collect fold: derive the runtime-authored MountOverride[] for one nested
+// SceneInstance anchor (plan-strategy D-3).
+//
+// ── What it does ──
+// Given a nested anchor's SceneInstanceState, walk each live member entity and
+// diff its live component columns against the member's authored baseline (the
+// source SceneAsset's layer-1 values, filled with schema defaults so the
+// comparison is against a fully-populated row). Every difference becomes a
+// MountOverride the collect step splices into the parent's `mounts[].overrides`:
+//   - a component present live but absent in source  -> component-ADD override
+//     ({ localId, comp, value }) whose value is the whole filled component map;
+//   - a field whose live value differs from baseline -> field-PATCH override
+//     ({ localId, comp, field, value }) for that single field;
+//   - a component present in source but absent live   -> NOT emitted (OOS-6:
+//     component-remove deltas do not fold back this feat).
+//
+// ── Value domain ──
+// The fold emits values in the LIVE domain: shared<T> fields carry numeric
+// handles, not GUID strings. The caller (rootsToSceneAsset / serialize wiring,
+// w21) performs the handle->GUID reverse-lookup with the two-state NULL-sentinel
+// handling (scalar handle 0 -> omit, array handle 0 -> keep positional 0),
+// reusing the same classifier the owned-entity serialization uses. Keeping the
+// fold registry-free means it stays a pure World+state read (D-3 / §2.5).
+//
+// ── localId namespace ──
+// Emitted `localId` is in the CHILD scene's namespace (0-based, exactly what
+// `state.entityToLocalId` maps to). The collect caller rebases it into the
+// parent namespace by adding the mount window's `memberFirst`, so the override
+// addresses the same slot the apply path validates against
+// (`_validateMountOverrides`: [memberFirst, memberFirst + memberCount)).
+//
+// ── Idempotency (AC-04) ──
+// A parent-authored mount-time override is applied to the child member's LIVE
+// column at instantiate time, and the child's source SceneAsset does not carry
+// it — so `live - source` re-derives it every round. Emitting it exactly once
+// (never separately re-passing state.mountTimeOverrides on top) keeps the
+// override entry set stable across save->load->save cycles: lossless without
+// doubling. (Runtime fact grounding this: parent-authored overrides on a nested
+// member land in the PARENT anchor's state, not the folded child anchor's; the
+// child anchor's own mountTimeOverrides is empty. See the M5 implement report.)
+
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import {
+  componentDefinition,
+  type Component as EcsComponent,
+  type EntityHandle,
+  type World,
+} from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { fillComponentDefaults } from '@forgeax/engine-ecs/projection';
+import type {
+  Handle,
+  LocalEntityId,
+  MountOverride,
+  SceneAsset,
+  SceneEntity,
+} from '@forgeax/engine-types';
+
+/** Minimal structural view of a SceneInstanceState the fold reads (D-4 boundary:
+ * `world.getSceneInstanceState(root).value` is structurally assignable). */
+export interface FoldSceneInstanceState {
+  readonly source: Handle<'SceneAsset', 'shared'>;
+  readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
+}
+
+/** Component names that never participate in an authored baseline diff: the
+ * essential row-identity column, and structural hierarchy relationship
+ * holders/mirrors (ChildOf/Children) whose live values are re-wired by
+ * instantiate, not authored. */
+function excludedComponentNames(): Set<string> {
+  return new Set<string>(['Entity', 'ChildOf', 'Children']);
+}
+
+/** Normalize an array-like (typed array or Array) to a plain array for
+ * structural comparison; pass non-array values through unchanged. */
+function normalize(value: unknown): unknown {
+  if (
+    Array.isArray(value) ||
+    value instanceof Uint32Array ||
+    value instanceof Float32Array ||
+    value instanceof Int32Array ||
+    value instanceof Float64Array ||
+    value instanceof Uint8Array ||
+    value instanceof Int16Array ||
+    value instanceof Uint16Array
+  ) {
+    return Array.from(value as ArrayLike<unknown>);
+  }
+  return value;
+}
+
+/** Structural value equality after array normalization (handles Float32Array vs
+ * number[] and nested arrays via JSON). Both inputs are column-shape values. */
+function valuesEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(normalize(a)) === JSON.stringify(normalize(b));
+}
+
+/** Build the per-field baseline map for a member from its source node, filled
+ * with schema defaults so it matches the fully-populated live row. Transient
+ * fields are dropped (they are never authored / never serialized, D-5). */
+function baselineFields(
+  comp: EcsComponent<string>,
+  sourceRaw: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const filled = fillComponentDefaults(comp, sourceRaw ?? {});
+  const out: Record<string, unknown> = {};
+  const fields = componentDefinition(comp).fields;
+  for (const fieldName of Object.keys(componentSchema(comp))) {
+    if (fields[fieldName]?.transient) continue;
+    out[fieldName] = filled[fieldName];
+  }
+  return out;
+}
+
+/** Read the live, non-transient, non-entity field values of a component on an
+ * entity into a plain map. Entity-type fields are dropped: their live value is a
+ * live EntityHandle while the source carries a LocalEntityId, so they cannot be
+ * diffed without remap — entity-ref override deltas are out of scope this feat
+ * (the AC set centers on shared/asset fields + component-add). */
+function liveFields(
+  world: World,
+  entity: EntityHandle,
+  comp: EcsComponent<string>,
+): Record<string, unknown> | undefined {
+  const res = world.get(entity, comp);
+  if (!res.ok) return undefined;
+  const val = res.value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  const fields = componentDefinition(comp).fields;
+  const schema = componentSchema(comp) as Record<string, string>;
+  for (const fieldName of Object.keys(schema)) {
+    if (fields[fieldName]?.transient) continue;
+    const fieldType = schema[fieldName];
+    if (fieldType === 'entity' || fieldType === 'array<entity>') continue;
+    out[fieldName] = normalize(val[fieldName]);
+  }
+  return out;
+}
+
+/**
+ * Fold one nested anchor's live member state into the runtime-authored
+ * MountOverride[] (child-namespace localIds, live value domain). See file
+ * header for the full contract. Returns [] when nothing differs from source.
+ */
+export function foldMountOverrides(world: World, state: FoldSceneInstanceState): MountOverride[] {
+  const sourceRes = resolveAssetHandle<SceneAsset>(
+    world,
+    state.source as unknown as Handle<string, 'shared'>,
+  );
+  if (!sourceRes.ok) return [];
+  const source = sourceRes.value as SceneAsset;
+
+  // Index source entities by localId for O(1) baseline lookup.
+  const sourceByLid = new Map<number, SceneEntity>();
+  for (const node of source.entities) {
+    sourceByLid.set(node.localId as unknown as number, node);
+  }
+
+  const excluded = excludedComponentNames();
+  const registered = world.components.entries();
+  const overrides: MountOverride[] = [];
+
+  // Deterministic member order (localId ascending) so collect output is a pure
+  // function of the graph (mirrors rootsToSceneAsset D-7 ordering discipline).
+  const members: Array<[EntityHandle, number]> = [];
+  for (const [entity, lid] of state.entityToLocalId) {
+    members.push([entity, lid as unknown as number]);
+  }
+  members.sort((a, b) => a[1] - b[1]);
+
+  for (const [entity, lid] of members) {
+    const sourceNode = sourceByLid.get(lid);
+    const sourceComps = (sourceNode?.components ?? {}) as Record<string, Record<string, unknown>>;
+
+    for (const [compName, compToken] of registered) {
+      if (excluded.has(compName)) continue;
+      if (componentDefinition(compToken).policy.transient) continue;
+      const comp = compToken as EcsComponent<string>;
+      if (Object.keys(componentSchema(comp)).length === 0) continue;
+
+      const live = liveFields(world, entity, comp);
+      if (live === undefined) continue; // component absent live
+
+      const sourceRaw = sourceComps[compName];
+      if (sourceRaw === undefined) {
+        // Component present live but absent in source -> component-ADD override.
+        // Emit the whole live component value map (apply upserts with defaults).
+        overrides.push({
+          localId: lid as unknown as LocalEntityId,
+          comp: compName,
+          value: live,
+        });
+        continue;
+      }
+
+      // Component present in both -> per-field diff (field-PATCH overrides).
+      const baseline = baselineFields(comp, sourceRaw);
+      for (const fieldName of Object.keys(live)) {
+        if (!valuesEqual(live[fieldName], baseline[fieldName])) {
+          overrides.push({
+            localId: lid as unknown as LocalEntityId,
+            comp: compName,
+            field: fieldName,
+            value: live[fieldName],
+          });
+        }
+      }
+    }
+  }
+
+  return overrides;
+}

package/src/sprite-param-values.ts

@@ -0,0 +1,61 @@
+/**
+ * Type-only helper mirroring the `forgeax::sprite` shader's paramSchema
+ * (sprite.material.json). Field set is 1:1 with paramSchema entries; field
+ * order matches schema order so the std140 UBO layout (slot 0..3 = colorTint
+ * / region / pivotAndSize / slicesAndMode) reads top-to-bottom.
+ *
+ * feat-20260625-refactor-sprite-as-transparent-mesh M3 / w11 (D-4, D-6,
+ * F-3): paramSchema is now UBO-aligned (the 4 vec4 fields match the WGSL
+ * Material struct field names 1:1 so the generic std140 UBO writer
+ * `applyParamSnapshotToUbo` walks `derive(paramSchema).uboLayout.entries`
+ * and writes each field at its declared offset, no sprite-specific path).
+ *
+ * AI-user discoverability: annotate a sprite material's `values`
+ * literal as `SpriteParamValues` to get autocomplete on `slicesAndMode`,
+ * `pivotAndSize`, etc. Without the annotation the literal binds to
+ * `MaterialAsset.values: Record<string, unknown>` and field
+ * autocomplete is unavailable.
+ *
+ * Required fields:
+ * - `baseColorTexture`: AssetGuid string of a registered TextureAsset
+ *   (renamed from the pre-w11 `texture` field for cross-material name
+ *   consistency, D-4).
+ *
+ * Optional UBO fields (omit for identity defaults):
+ * - `colorTint`: vec4 `[r, g, b, a]` — texture sample multiplier
+ *   (rgb * colorTint.rgb, alpha * colorTint.a). Default `[1, 1, 1, 1]`.
+ * - `region`: vec4 `[uMin, vMin, uW, vH]` — atlas sub-region. Default
+ *   `[0, 0, 1, 1]`. Host pre-folds flipX / flipY into this vec4 (D-8):
+ *   `flipX -> region.x += region.z; region.z = -region.z` (analog for Y).
+ *   When composing with {@link SpriteRegionOverride}, the override
+ *   replaces this asset-side region.
+ * - `pivotAndSize`: vec4 `[pivotX, pivotY, sizeX, sizeY]` — `.xy` is the
+ *   pivot (0..1 normalised); `.zw` is the DEAD SLOT post-w11 (D-6 unit-
+ *   quad: world scale flows entirely through Transform.world, no longer
+ *   double-applied via the UBO). Default `[0.5, 0.5, 1, 1]`.
+ * - `slicesAndMode`: vec4 `[left, top, right, bottom-signed]` — 9-slice
+ *   border widths in UV (0..1) on the source texture region. Sum of
+ *   opposite borders must be < 1 (left+right < region width, top+bottom
+ *   < region height); register-time validation surfaces structured
+ *   `AssetError`. The `.w` carries the sliceMode sentinel: positive (or 0)
+ *   = stretch (middle band stretches with the entity's scale, default);
+ *   NEGATIVE = tile (middle band tiles via sampler `addressMode='repeat'`).
+ *   Default `[0, 0, 0, 0]` (no 9-slice). Authoring tip: callers who want
+ *   to keep the legacy `slices` + `sliceMode` split can compute
+ *   `slicesAndMode = [l, t, r, mode===1 ? -b : b]` at the call site.
+ *
+ * Composes with {@link SpriteRegionOverride}: when both are present, the
+ * `slicesAndMode` are interpreted relative to the per-entity `region`
+ * override (AC-14), not the material's `values.region`.
+ *
+ * Sibling type, not a sibling asset kind: `MaterialAsset` is the only
+ * material asset shape; using `SpriteParamValues` as an annotation does
+ * not branch the closed `AssetUnion` (plan-strategy section D-1).
+ */
+export type SpriteParamValues = {
+  baseColorTexture: string;
+  colorTint?: readonly [number, number, number, number];
+  region?: readonly [number, number, number, number];
+  pivotAndSize?: readonly [number, number, number, number];
+  slicesAndMode?: readonly [number, number, number, number];
+};

package/src/systems/__tests__/_xorshift.ts

@@ -0,0 +1,83 @@
+// @forgeax/engine-runtime — deterministic 32-bit xorshift PRNG (M-4 / w26).
+//
+// Scope: M-4 transparent-sort.bench.ts (w27) needs reproducible 10k-entity
+// fixtures across runs / hosts / CI nodes. The vitest-bench iterations
+// repeatedly hash the same comparator path; a seeded PRNG turns the bench
+// number into a function of the algorithm rather than of the test data,
+// so a regression shows up as a clean delta in ns/op rather than noise.
+//
+// Why a hand-rolled xorshift instead of `seedrandom` (plan-strategy D-3):
+//   - zero new npm dep, zero lockfile drift, zero dependabot bun.lock
+//     parity churn
+//   - 32-bit xorshift is a 10-line industry-standard primitive
+//     (Marsaglia 2003); same deterministic guarantee for our use case
+//     (uniform-ish 32-bit ints feeding a JS-side floor / map)
+//   - bundle-size + bench gates stay pinned to the runtime surface that
+//     ships to AI users; a test-only helper that lives under `__tests__/`
+//     does not change either gate
+//
+// Algorithm (Marsaglia "Xorshift RNGs", 2003 §3, the 13/17/5 triplet):
+//   state := state XOR (state << 13)
+//   state := state XOR (state >>> 17)
+//   state := state XOR (state << 5)
+// The triplet (13, 17, 5) survives the BigCrush 32-bit suite for this
+// scope (uniform sampling of int32 ranges). Period 2^32 - 1; we only
+// need ~10^6 draws per bench iteration (10k entries x O(1) fields), so
+// the period is comfortably out of reach.
+//
+// charter mapping:
+//   F1 — JSDoc head + algorithm comment block keep the SSOT in the file
+//     header so future AI users see why this exists without a wiki round
+//     trip (charter "limited context" — the rationale lives inline)
+//   P3 — `seed === 0` is explicitly remapped (xorshift is a fixed point
+//     at 0, which would silently emit a constant 0 stream); the remap
+//     fails-loud at construction time rather than silently producing a
+//     degenerate sequence
+//
+// @new-surface — hand-rolled xorshift replaces the seedrandom dep
+//   (plan-strategy D-3); the helper lives under `__tests__/` so it never
+//   ships in the runtime bundle.
+// @derives — 32-bit xorshift industry-standard primitive (Marsaglia
+//   2003, "Xorshift RNGs", Journal of Statistical Software §3 triplet
+//   13/17/5).
+
+/**
+ * Deterministic 32-bit xorshift PRNG factory. Returns a closure that
+ * advances the internal state once per call and returns a uniform-ish
+ * `[0, 1)` float (the 32-bit state divided by `0x100000000`).
+ *
+ * Same seed -> same sequence on every host / runtime / Node version
+ * (the algorithm uses only 32-bit bitwise ops and Math-free arithmetic).
+ *
+ * @param seed - Initial 32-bit state. Defaults to `0xCAFE2026` (plan-
+ *   strategy D-3 SSOT). `seed === 0` is remapped to `1` because xorshift
+ *   is a fixed point at 0 (would emit a constant `0` stream forever);
+ *   the remap is the smallest deterministic perturbation that preserves
+ *   the period.
+ * @returns A `() => number` closure; each call returns one `[0, 1)`
+ *   sample and advances the internal state.
+ *
+ * @example deterministic bench fixture (w27 / transparent-sort.bench.ts)
+ *   const rng = createXorshift32(0xCAFE2026);
+ *   const layer = Math.floor(rng() * 2000) - 1000;  // [-1000, 1000]
+ *   const posY  = rng() * 100;                       // [0, 100)
+ *
+ * @example reproducibility check
+ *   const a = createXorshift32(42);
+ *   const b = createXorshift32(42);
+ *   a() === b();  // true — pure function of seed
+ */
+export function createXorshift32(seed = 0xcafe2026): () => number {
+  // `| 0` coerces to int32; the algorithm is defined over int32. The
+  // remap of seed=0 keeps the period definition (2^32 - 1) honest:
+  // xorshift's only degenerate fixed point is at 0.
+  let state = (seed | 0) === 0 ? 1 : seed | 0;
+  return (): number => {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    // `>>> 0` reinterprets the int32 as a uint32 (0 .. 2^32 - 1);
+    // dividing by `0x100000000` (2^32) lands the result in [0, 1).
+    return (state >>> 0) / 0x100000000;
+  };
+}

package/src/systems/__tests__/argsort-in-place.test.ts

@@ -0,0 +1,155 @@
+// argsortInPlace unit tests (feat-20260608-tilemap-object-layer-rendering
+// M3 / m3-t1). The named export will land in m3-t2; until then every
+// import below resolves to `undefined` and the suite is red.
+//
+// Spec (plan-strategy §D-3 + reference backup commit 31d96d75):
+//   `argsortInPlace(keys: Float64Array, indices: Int32Array): void` reorders
+//   `indices` in place so that `keys[indices[i]]` is non-decreasing. The key
+//   array is treated as immutable; only `indices` is mutated. The sort is:
+//
+//     - stable (equal-key entries preserve their original `indices` order),
+//     - NaN-safe (NaN keys land at the tail in stable order),
+//     - IEEE-754 unsigned-monotonic encoded so `+0` and `-0` compare equal,
+//     - zero-allocation per call (module-scoped scratch buffers grow on
+//       demand; AC-17 budget is a separate bench, not this suite),
+//     - safe at the empty / single-entry boundaries.
+//
+// Charter mapping: P3 (NaN / out-of-range entries deterministic, no silent
+// throws) + P4 (single sort primitive shared with the sprite bucket via
+// `transparent-sort.ts`).
+
+import { describe, expect, it } from 'vitest';
+import { argsortInPlace } from '../transparent-sort';
+
+describe('argsortInPlace - 11-bit radix LSD over IEEE-754 unsigned-monotonic', () => {
+  it('basic ascending: distinct positive keys land in ascending key order', () => {
+    const keys = new Float64Array([3.1, 1.2, 2.7, 0.5, 9.0]);
+    const indices = new Int32Array([0, 1, 2, 3, 4]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([3, 1, 2, 0, 4]);
+  });
+
+  it('all-equal keys: stable sort preserves the original index order', () => {
+    const keys = new Float64Array([5, 5, 5, 5, 5]);
+    const indices = new Int32Array([0, 1, 2, 3, 4]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  it('negative + zero + positive: IEEE-754 unsigned-monotonic sorts correctly', () => {
+    const keys = new Float64Array([-3.5, 0, 2.1, -1.0, 7.2, -0.0]);
+    const indices = new Int32Array([0, 1, 2, 3, 4, 5]);
+
+    argsortInPlace(keys, indices);
+
+    // -3.5, -1.0, 0/-0 (stable -> [1, 5]), 2.1, 7.2
+    expect(Array.from(indices)).toEqual([0, 3, 1, 5, 2, 4]);
+  });
+
+  it('-0 and +0 are equal under the unsigned-monotonic encoding (stable tie)', () => {
+    const keys = new Float64Array([0, -0, 0, -0]);
+    const indices = new Int32Array([0, 1, 2, 3]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([0, 1, 2, 3]);
+  });
+
+  it('NaN keys land at the tail in stable order', () => {
+    const keys = new Float64Array([2, Number.NaN, 0, Number.NaN, -1]);
+    const indices = new Int32Array([0, 1, 2, 3, 4]);
+
+    argsortInPlace(keys, indices);
+
+    expect(indices[0]).toBe(4);
+    expect(indices[1]).toBe(2);
+    expect(indices[2]).toBe(0);
+    expect(indices[3]).toBe(1);
+    expect(indices[4]).toBe(3);
+  });
+
+  it('n=0: no-op, returns immediately without throwing', () => {
+    const keys = new Float64Array(0);
+    const indices = new Int32Array(0);
+
+    expect(() => argsortInPlace(keys, indices)).not.toThrow();
+    expect(indices.length).toBe(0);
+  });
+
+  it('n=1: no-op, single-entry indices unchanged', () => {
+    const keys = new Float64Array([42]);
+    const indices = new Int32Array([0]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual([0]);
+  });
+
+  it('mutates indices in place, does not reallocate the caller buffer', () => {
+    const keys = new Float64Array([5, 2, 9, 1]);
+    const indices = new Int32Array([0, 1, 2, 3]);
+    const indicesBuffer = indices.buffer;
+    const indicesByteLength = indices.byteLength;
+
+    argsortInPlace(keys, indices);
+
+    expect(indices.buffer).toBe(indicesBuffer);
+    expect(indices.byteLength).toBe(indicesByteLength);
+    expect(Array.from(indices)).toEqual([3, 1, 0, 2]);
+  });
+
+  it('does not mutate the keys input', () => {
+    const keys = new Float64Array([3, 1, 2]);
+    const original = Array.from(keys);
+    const indices = new Int32Array([0, 1, 2]);
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(keys)).toEqual(original);
+  });
+
+  it('large N (5000): radix LSD result equals comparator-based reference', () => {
+    const n = 5000;
+    const keys = new Float64Array(n);
+    const indices = new Int32Array(n);
+    let seed = 1337;
+    const next = (): number => {
+      seed = (seed * 1664525 + 1013904223) | 0;
+      return ((seed >>> 0) / 0xffffffff) * 200 - 100;
+    };
+    for (let i = 0; i < n; i++) {
+      keys[i] = next();
+      indices[i] = i;
+    }
+
+    const referenceIndices = Array.from(indices).sort((a, b) => {
+      const ka = keys[a] as number;
+      const kb = keys[b] as number;
+      if (ka < kb) return -1;
+      if (ka > kb) return 1;
+      return a - b;
+    });
+
+    argsortInPlace(keys, indices);
+
+    expect(Array.from(indices)).toEqual(referenceIndices);
+  });
+
+  it('subarray slice as indices: sorts only the visible window', () => {
+    const keys = new Float64Array([10, 20, 5, 15, 30]);
+    const buffer = new Int32Array([0, 1, 2, 3, 4]);
+    const window = buffer.subarray(1, 4); // entries 1, 2, 3 (keys 20, 5, 15)
+
+    argsortInPlace(keys, window);
+
+    // Original entries by key ascending: 5 (->2), 15 (->3), 20 (->1)
+    expect(Array.from(window)).toEqual([2, 3, 1]);
+    // Outside-window slots untouched.
+    expect(buffer[0]).toBe(0);
+    expect(buffer[4]).toBe(4);
+  });
+});