@forgeax/engine-runtime 0.1.2

package/src/components/__tests__/camera.test-d.ts

@@ -0,0 +1,57 @@
+// M2 / w11: Camera factory type-level tests
+// (feat-20260525-boilerplate-reduction-pod-defaults-factories)
+//
+// Covers AC-05 type-level requirements: perspective() fov/aspect
+// required, type-only checks. Plan-strategy section 5.2 type-test requirement.
+//
+// Charter P3: required-field omission must produce compile-time error,
+// not runtime silent fallback.
+
+import { orthographic, perspective } from '@forgeax/engine-render/internal';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('perspective factory type-level', () => {
+  it('perspective({ fov: 60, aspect: 4/3 }) type-checks OK', () => {
+    // Positive: fov + aspect present => compile OK.
+    const pod = perspective({ fov: 60, aspect: 4 / 3 });
+    expectTypeOf(pod.fov).toBeNumber();
+  });
+
+  it('perspective({ fov: 60 }) should be a TS error (aspect required)', () => {
+    // @ts-expect-error aspect is required
+    const _pod = perspective({ fov: 60 });
+    // If this line is reached without TS error, the assertion fails.
+    expectTypeOf(_pod).toBeObject();
+  });
+
+  it('perspective({}) should be a TS error (fov + aspect required)', () => {
+    // @ts-expect-error fov + aspect required
+    const _pod = perspective({});
+    expectTypeOf(_pod).toBeObject();
+  });
+
+  it('perspective return value is assignable to world.spawn data slot', () => {
+    // The factory returns a plain object matching Camera column shape.
+    const pod = perspective({ fov: 60, aspect: 4 / 3 });
+    // All 12 Camera fields present with correct types.
+    expectTypeOf(pod.fov).toBeNumber();
+    expectTypeOf(pod.aspect).toBeNumber();
+    expectTypeOf(pod.near).toBeNumber();
+    expectTypeOf(pod.far).toBeNumber();
+    expectTypeOf(pod.projection).toBeNumber();
+    expectTypeOf(pod.left).toBeNumber();
+    expectTypeOf(pod.right).toBeNumber();
+    expectTypeOf(pod.bottom).toBeNumber();
+    expectTypeOf(pod.top).toBeNumber();
+    expectTypeOf(pod.tonemap).toBeNumber();
+    expectTypeOf(pod.exposure).toBeNumber();
+    expectTypeOf(pod.whitePoint).toBeNumber();
+  });
+});
+
+describe('orthographic factory type-level', () => {
+  it('orthographic({ left: -1, right: 1, bottom: -1, top: 1 }) type-checks OK', () => {
+    const pod = orthographic({ left: -1, right: 1, bottom: -1, top: 1 });
+    expectTypeOf(pod.projection).toBeNumber();
+  });
+});

package/src/components/__tests__/camera.test.ts

@@ -0,0 +1,95 @@
+// feat-20260617 M3 / w8: Camera.autoAspect bool-column storage.
+//
+// The `autoAspect` field is a `bool` column on the Camera schema. The bool
+// column tier already exists (component.ts:53/736/763/868, used by
+// AnimationPlayer.paused / AudioSource.playing); Camera reuses it (plan
+// D-4: zero ECS infrastructure change).
+//
+// Read-path contract (research Finding 2 / D-5): the `world.get(e, Camera)`
+// readRow path narrows a bool column to a JS boolean. The query-bundle path
+// returns the raw 0/1 number instead -- the aspect-sync sidecar therefore
+// reads autoAspect via world.get, never via the bundle (avoids the
+// `bundle.autoAspect[i] !== 0` always-true trap; memory
+// bool-field-compared-with-not-equal-zero-always-true). This file only
+// exercises the world.get path.
+
+import { World } from '@forgeax/engine-ecs';
+import { Camera, perspective } from '@forgeax/engine-render/internal';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('camera.ts autoAspect bool column (w8)', () => {
+  it('world.get(cam, Camera).autoAspect reads a JS boolean, not a number', () => {
+    const world = new World();
+    const cam = world
+      .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1 }) })
+      .unwrap();
+
+    const r = world.get(cam, Camera);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(typeof r.value.autoAspect).toBe('boolean');
+  });
+
+  it('defaults to true when autoAspect is not supplied', () => {
+    const world = new World();
+    const cam = world
+      .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1 }) })
+      .unwrap();
+
+    const r = world.get(cam, Camera);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.autoAspect).toBe(true);
+  });
+
+  it('world.set(cam, Camera, { autoAspect: false }) takes effect and reads back false', () => {
+    const world = new World();
+    const cam = world
+      .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1 }) })
+      .unwrap();
+
+    world.set(cam, Camera, { autoAspect: false }).unwrap();
+
+    const r = world.get(cam, Camera);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.autoAspect).toBe(false);
+  });
+});
+
+// feat-20260617 M3 / w9: perspective({ autoAspect }) factory opt-out + the
+// AC-09 type-inference surface (autoAspect resolves to `boolean` without an
+// `as` cast; CameraPerspectiveOpts.autoAspect is `boolean | undefined`).
+describe('camera.ts perspective autoAspect opt-out (w9)', () => {
+  it('perspective() leaves autoAspect at the schema default (true)', () => {
+    const world = new World();
+    const cam = world
+      .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1 }) })
+      .unwrap();
+
+    const r = world.get(cam, Camera);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.autoAspect).toBe(true);
+  });
+
+  it('perspective({ autoAspect: false }) yields a CameraPod with autoAspect=false', () => {
+    const pod = perspective({ fov: 1, aspect: 1, autoAspect: false });
+    expect(pod.autoAspect).toBe(false);
+
+    const world = new World();
+    const cam = world.spawn({ component: Camera, data: pod }).unwrap();
+    const r = world.get(cam, Camera);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.autoAspect).toBe(false);
+  });
+
+  it('AC-09: autoAspect inference is boolean on both the POD and the opts', () => {
+    const pod = perspective({ fov: 1, aspect: 1 });
+    expectTypeOf(pod.autoAspect).toEqualTypeOf<boolean>();
+    expectTypeOf<Parameters<typeof perspective>[0]['autoAspect']>().toEqualTypeOf<
+      boolean | undefined
+    >();
+  });
+});

package/src/components/__tests__/child-of.test.ts

@@ -0,0 +1,35 @@
+// AC-08: cascade-despawn — when ChildOf default linkedSpawn=true,
+// world.despawn(parent) recursively despawns child entities that hold
+// the default-constructed ChildOf (no explicit linkedSpawn override).
+//
+// The test uses the actual exported runtime ChildOf component (default
+// linkedSpawn=true post flip) directly, not a test-specific fixture.
+//
+// Children must be imported before ChildOf: ChildOf.defineComponent resolves
+// the mirror component 'Children' by name at module evaluation time.
+
+import { Entity, type EntityHandle, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+// Side-effect: loads the canonical scene barrel before ChildOf is consumed.
+import '@forgeax/engine-scene';
+import { ChildOf } from '@forgeax/engine-scene';
+
+function alive(world: World, entity: EntityHandle): boolean {
+  const r = world.get(entity, Entity);
+  if (r.ok) return true;
+  return r.error.code !== 'stale-entity';
+}
+
+describe('child-of.ts cascade-despawn (AC-08)', () => {
+  it('despawn(parent) cascade-despawns child when ChildOf uses default linkedSpawn', () => {
+    const world = new World();
+    const parent = world.spawn().unwrap();
+    const child = world.spawn({ component: ChildOf, data: { parent } }).unwrap();
+
+    expect(alive(world, child)).toBe(true);
+
+    world.despawn(parent).unwrap();
+
+    expect(alive(world, child)).toBe(false);
+  });
+});

package/src/components/__tests__/sprite-animation.test-d.ts

@@ -0,0 +1,160 @@
+// feat-20260521-sprite-atlas-animation / M2 / T-09.
+//
+// TDD red phase: packages/runtime/src/components/sprite-animation.ts does
+// not yet exist; this test-d stays red (TS module-resolution failure)
+// until T-12 lands the SSOT (plan-strategy section 2 D-5 + D-6 + section
+// 3.1 SAC node). After T-12 the import resolves and the type-level
+// assertions turn green. AC-02 schema lock + AC-08 IDE-autocomplete
+// affordance are the consumer-side guarantees these checks defend.
+//
+// Schema decision lineage (six fields locked, 1:1 with requirements
+// section 2.3 table):
+//   1. frameCount    : 'u32'         total frame count, >= 1.
+//   2. frameDuration : 'f32'         per-frame seconds, > 0.
+//   3. currentFrame  : 'u32'         live frame index, runtime mutable.
+//   4. accumDt       : 'f32'         dt accumulator, persists across ticks.
+//   5. regions       : 'array<f32>'  flat [uMin, vMin, uW, vH] per frame
+//                                     (length = frameCount * 4 invariant
+//                                      enforced by the M4 tick system).
+//   6. playbackMode  : 'u32'         numeric encoding of SpritePlaybackMode
+//                                     (SPRITE_PLAYBACK_MODE_LOOP=0 /
+//                                      SPRITE_PLAYBACK_MODE_CLAMP=1; M1 SSOT
+//                                      sprite-playback-mode.ts; D-5).
+//
+// Why u32 for playbackMode (and not a string-literal union)? research F-2
+// + F-5: the ECS schema whitelist (`SchemaFieldType`) is closed and rejects
+// string-literal unions; the M1 Tonemap path (`tonemap: f32` +
+// TONEMAP_NONE/TONEMAP_REINHARD_EXTENDED constants + `tonemapFromF32`
+// mapper) is the SSOT shape this feat reuses (D-5 same charter P4 mental
+// model — one encoding rule across all closed-union schema columns).
+//
+// Why array<f32> (and not array<f32, N>) for `regions`? The length
+// `frameCount * 4` is a runtime value (frameCount itself is a column read
+// per entity); the variable-capacity `array<f32>` mirrors `Instances.transforms`
+// (M1 feat-20260514) where the runtime length is also data-dependent. The
+// length invariant is enforced by the M4 sprite-animation-tick system at
+// first observation (AC-09 fail-fast path; D-1 + D-6).
+//
+// Anchors: plan-tasks.json T-09 (acceptanceCheck: vitest --typecheck on
+// sprite-animation.test-d turns green after T-12, six fields 1:1 with
+// requirements section 2.3); plan-strategy section 2 D-5 + D-6 + section
+// 3.1 PR/SAC + section 4 risks R-SCHEMA-1 + R-SCHEMA-2; research F-2 + F-5;
+// requirements section AC-02 + section 2.3 field semantics table; charter
+// F1 (single-import surface), P3 (schema fail-fast at TS edge), P4
+// (consistent abstraction with M1 Tonemap encoding).
+
+import type { Component, SchemaOf, ShapeOf } from '@forgeax/engine-ecs';
+import type { SpriteAnimation } from '@forgeax/engine-render/authoring';
+import {
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+} from '@forgeax/engine-render/authoring';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('SpriteAnimation — Component token shape (AC-02 schema lock)', () => {
+  it("name literal type is 'SpriteAnimation'", () => {
+    expectTypeOf<typeof SpriteAnimation.name>().toEqualTypeOf<'SpriteAnimation'>();
+  });
+
+  it('schema is exactly the 6-field record from requirements section 2.3', () => {
+    expectTypeOf<SchemaOf<typeof SpriteAnimation>>().toEqualTypeOf<
+      Readonly<{
+        readonly frameCount: 'u32';
+        readonly frameDuration: 'f32';
+        readonly currentFrame: 'u32';
+        readonly accumDt: 'f32';
+        readonly regions: 'array<f32>';
+        readonly playbackMode: 'u32';
+      }>
+    >();
+  });
+
+  it('SpriteAnimation matches Component<"SpriteAnimation", {6 fields}>', () => {
+    type Expected = Component<
+      'SpriteAnimation',
+      {
+        readonly frameCount: 'u32';
+        readonly frameDuration: 'f32';
+        readonly currentFrame: 'u32';
+        readonly accumDt: 'f32';
+        readonly regions: 'array<f32>';
+        readonly playbackMode: 'u32';
+      }
+    >;
+    expectTypeOf<typeof SpriteAnimation>().toMatchTypeOf<Expected>();
+  });
+
+  it('schema field literals narrow to their exact tier-2 vocab keywords', () => {
+    expectTypeOf<SchemaOf<typeof SpriteAnimation>['frameCount']>().toEqualTypeOf<'u32'>();
+    expectTypeOf<SchemaOf<typeof SpriteAnimation>['frameDuration']>().toEqualTypeOf<'f32'>();
+    expectTypeOf<SchemaOf<typeof SpriteAnimation>['currentFrame']>().toEqualTypeOf<'u32'>();
+    expectTypeOf<SchemaOf<typeof SpriteAnimation>['accumDt']>().toEqualTypeOf<'f32'>();
+    expectTypeOf<SchemaOf<typeof SpriteAnimation>['regions']>().toEqualTypeOf<'array<f32>'>();
+    expectTypeOf<SchemaOf<typeof SpriteAnimation>['playbackMode']>().toEqualTypeOf<'u32'>();
+  });
+});
+
+describe('SpriteAnimation — data shape via ShapeOf (AC-02 + AC-08)', () => {
+  it('ShapeOf<schema> exposes 6 fields with the documented JS types', () => {
+    type Data = ShapeOf<SchemaOf<typeof SpriteAnimation>>;
+    expectTypeOf<keyof Data>().toEqualTypeOf<
+      'frameCount' | 'frameDuration' | 'currentFrame' | 'accumDt' | 'regions' | 'playbackMode'
+    >();
+    expectTypeOf<Data['frameCount']>().toEqualTypeOf<number>();
+    expectTypeOf<Data['frameDuration']>().toEqualTypeOf<number>();
+    expectTypeOf<Data['currentFrame']>().toEqualTypeOf<number>();
+    expectTypeOf<Data['accumDt']>().toEqualTypeOf<number>();
+    expectTypeOf<Data['regions']>().toEqualTypeOf<Float32Array>();
+    expectTypeOf<Data['playbackMode']>().toEqualTypeOf<number>();
+  });
+
+  it('world.spawn data is Partial<ShapeOf<schema>> — every field optional at consumer', () => {
+    type SpawnData = Partial<ShapeOf<SchemaOf<typeof SpriteAnimation>>>;
+
+    // Empty payload type-checks (consumer surface accepts omission).
+    const empty: SpawnData = {};
+    void empty;
+
+    // Full payload — playback-mode constant flows in via SPRITE_PLAYBACK_MODE_*
+    // numeric literal (T-07 SSOT). AI users grep `SPRITE_PLAYBACK_MODE_LOOP`
+    // and find one symbol with one numeric encoding; charter F1 single-symbol
+    // discovery.
+    const full: SpawnData = {
+      frameCount: 4,
+      frameDuration: 0.1,
+      currentFrame: 0,
+      accumDt: 0,
+      regions: new Float32Array(4 * 4),
+      playbackMode: SPRITE_PLAYBACK_MODE_LOOP,
+    };
+    void full;
+
+    const clampMode: SpawnData = { playbackMode: SPRITE_PLAYBACK_MODE_CLAMP };
+    void clampMode;
+  });
+});
+
+describe('SpriteAnimation — @ts-expect-error negative assertions (AC-08)', () => {
+  it('1. plain number[] is not assignable to data.regions (Float32Array nominal)', () => {
+    type SpawnData = Partial<ShapeOf<SchemaOf<typeof SpriteAnimation>>>;
+    // @ts-expect-error number[] lacks the Float32Array brand.
+    const wrong: SpawnData = { regions: [0, 0, 1, 1] };
+    void wrong;
+  });
+
+  it("2. string-literal 'loop' is not assignable to data.playbackMode (numeric u32)", () => {
+    type SpawnData = Partial<ShapeOf<SchemaOf<typeof SpriteAnimation>>>;
+    // @ts-expect-error playbackMode is a u32 numeric column (D-5);
+    // string-literal 'loop' is the type-level alias only — runtime
+    // narrowing flows through `spritePlaybackModeFromU32`.
+    const wrong: SpawnData = { playbackMode: 'loop' };
+    void wrong;
+  });
+
+  it('3. mismatched scalar field types are TS errors', () => {
+    type SpawnData = Partial<ShapeOf<SchemaOf<typeof SpriteAnimation>>>;
+    // @ts-expect-error frameCount is `number`; assigning a string is a TS error.
+    const wrong: SpawnData = { frameCount: '4' };
+    void wrong;
+  });
+});

package/src/components/__tests__/sprite-instances.unit.test.ts

@@ -0,0 +1,108 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M1 / w3.
+//
+// Schema + AI-discoverability lock for the SpriteInstances component. Three
+// surfaces under test (plan-tasks.json w3 description):
+//   (a) defineComponent registration: getRegisteredComponents() enumerates
+//       'SpriteInstances'.
+//   (b) SpriteInstancesData type assertion: { transforms: Float32Array,
+//       regions: Float32Array }, both readonly. The AC-09 type-inference
+//       check happens inside system / QueryRow paths (not test-d) —
+//       a `world.get` callback context is the canonical AI-user touchpoint.
+//   (c) barrel re-export from @forgeax/engine-runtime compiles, exposing both
+//       the component value and the data shape type.
+//
+// Boundary (plan-strategy section 7 M1 edge): this file does NOT test extract-
+// entry validation (M3 w12), the stride mismatch fire path (M3 w13), or the
+// render-system-* / shader/ touchpoints. Only the schema-level positive surface
+// + IDE-autocomplete discoverability.
+//
+// Charter mapping: F1 (single-import surface via @forgeax/engine-runtime),
+// P3 (schema fail-fast at TS edge), P4 (consistent abstraction — peer to
+// Instances).
+
+import { type Component, type SchemaOf, type ShapeOf, World } from '@forgeax/engine-ecs';
+import {
+  SpriteInstances,
+  type SpriteInstancesData,
+  type SpriteInstancesData as SpriteInstancesDataFromBarrel,
+  SpriteInstances as SpriteInstancesFromBarrel,
+} from '@forgeax/engine-render/authoring';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('SpriteInstances — defineComponent registration (w3 a)', () => {
+  it('the token name remains the discoverable component identity', () => {
+    expect(SpriteInstances.name).toBe('SpriteInstances');
+  });
+
+  it("Component.name literal is 'SpriteInstances'", () => {
+    expect(SpriteInstances.name).toBe('SpriteInstances');
+    expectTypeOf<typeof SpriteInstances.name>().toEqualTypeOf<'SpriteInstances'>();
+  });
+
+  it('schema is the 2-field {transforms, regions} array<f32> record', () => {
+    expectTypeOf<SchemaOf<typeof SpriteInstances>>().toEqualTypeOf<
+      Readonly<{
+        readonly transforms: 'array<f32>';
+        readonly regions: 'array<f32>';
+      }>
+    >();
+  });
+
+  it('schema field literals narrow to array<f32>', () => {
+    expectTypeOf<SchemaOf<typeof SpriteInstances>['transforms']>().toEqualTypeOf<'array<f32>'>();
+    expectTypeOf<SchemaOf<typeof SpriteInstances>['regions']>().toEqualTypeOf<'array<f32>'>();
+  });
+});
+
+describe('SpriteInstances — SpriteInstancesData type assertion (w3 b)', () => {
+  it('SpriteInstancesData is { readonly transforms: Float32Array, readonly regions: Float32Array }', () => {
+    expectTypeOf<SpriteInstancesData>().toEqualTypeOf<{
+      readonly transforms: Float32Array;
+      readonly regions: Float32Array;
+    }>();
+  });
+
+  it('ShapeOf<schema> matches SpriteInstancesData (single SSOT type)', () => {
+    type ShapeData = ShapeOf<SchemaOf<typeof SpriteInstances>>;
+    expectTypeOf<ShapeData['transforms']>().toEqualTypeOf<Float32Array>();
+    expectTypeOf<ShapeData['regions']>().toEqualTypeOf<Float32Array>();
+  });
+
+  it('AC-09: world.get(e, SpriteInstances) callback path infers Float32Array without `as`', () => {
+    const world = new World();
+    const transforms = new Float32Array(2 * 16);
+    const regions = new Float32Array(2 * 4);
+    const e = world.spawn({ component: SpriteInstances, data: { transforms, regions } }).unwrap();
+
+    const r = world.get(e, SpriteInstances);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expectTypeOf(r.value.transforms).toEqualTypeOf<Float32Array>();
+    expectTypeOf(r.value.regions).toEqualTypeOf<Float32Array>();
+    expect(r.value.transforms.length).toBe(32);
+    expect(r.value.regions.length).toBe(8);
+  });
+
+  it('SpriteInstances matches Component<"SpriteInstances", {transforms, regions}>', () => {
+    type Expected = Component<
+      'SpriteInstances',
+      {
+        readonly transforms: 'array<f32>';
+        readonly regions: 'array<f32>';
+      }
+    >;
+    expectTypeOf<typeof SpriteInstances>().toMatchTypeOf<Expected>();
+  });
+});
+
+describe('SpriteInstances — barrel re-export (w3 c)', () => {
+  it('@forgeax/engine-runtime barrel exports SpriteInstances (same component identity)', () => {
+    expect(SpriteInstancesFromBarrel).toBe(SpriteInstances);
+  });
+
+  it('@forgeax/engine-runtime barrel exports SpriteInstancesData type (compile assertion)', () => {
+    type FromBarrel = SpriteInstancesDataFromBarrel;
+    type FromModule = SpriteInstancesData;
+    expectTypeOf<FromBarrel>().toEqualTypeOf<FromModule>();
+  });
+});

package/src/components/__tests__/sprite-region-override.test-d.ts

@@ -0,0 +1,101 @@
+// feat-20260521-sprite-atlas-animation / M2 / T-08.
+//
+// TDD red phase: packages/runtime/src/components/sprite-region-override.ts
+// does not yet exist; this test-d stays red (TS module-resolution failure)
+// until T-11 lands the SSOT (plan-strategy section 2 D-6 + section 3.1
+// SRO node). After T-11 the import resolves and the type-level assertions
+// turn green. AC-01 schema lock + AC-08 IDE-autocomplete affordance are
+// the consumer-side guarantees these checks defend.
+//
+// Schema decision lineage:
+//   - requirements section 2.4 names `region: 'vec4'` semantically;
+//     plan-strategy D-6 + research F-5 lock the concrete schema vocab to
+//     `'array<f32, 4>'` because the ECS schema whitelist (`SchemaFieldType`,
+//     packages/ecs/src/component.ts) does not accept `'vec4'`. The
+//     compile-time `length=4` enforcement that `'array<f32, 4>'` provides
+//     is the entire reason this test-d encodes the literal schema
+//     (instead of widening to `'array<f32>'`).
+//   - The `data.region` consumer shape is `Float32Array` (FieldValueType
+//     resolves `array<f32, 4>` -> `TypedArrayFor<'f32'>` -> `Float32Array`).
+//     AI users at the `world.spawn(..., { component: SpriteRegionOverride,
+//     data: { region: ... } })` call site see one branded type, no
+//     widening to `number[]` or `Uint32Array`.
+//
+// Anchors: plan-tasks.json T-08 (acceptanceCheck: vitest --typecheck on
+// sprite-region-override.test-d turns green after T-11); plan-strategy
+// section 2 D-6 + section 3.1 PR/SRO + section 4 risk R-SCHEMA-2 reaction;
+// research F-5; requirements section AC-01 schema lock + section AC-08
+// IDE autocomplete affordance + section 2.4 SpriteRegionOverride field
+// table; charter F1 (single-import surface for AI users), P3 (schema
+// fail-fast at TS edge — `'array<f32, 4>'` rejects mismatched lengths
+// at the ECS storage / runtime boundary).
+
+import type { Component, SchemaOf, ShapeOf } from '@forgeax/engine-ecs';
+import type { SpriteRegionOverride } from '@forgeax/engine-render/authoring';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('SpriteRegionOverride — Component token shape (AC-01 schema lock)', () => {
+  it("name literal type is 'SpriteRegionOverride'", () => {
+    expectTypeOf<typeof SpriteRegionOverride.name>().toEqualTypeOf<'SpriteRegionOverride'>();
+  });
+
+  it("schema is exactly { region: 'array<f32, 4>' } (D-6 fixed-length 4)", () => {
+    expectTypeOf<SchemaOf<typeof SpriteRegionOverride>>().toEqualTypeOf<
+      Readonly<{ readonly region: 'array<f32, 4>' }>
+    >();
+  });
+
+  it("schema field 'region' literal narrows to 'array<f32, 4>' (compile-time length=4)", () => {
+    expectTypeOf<
+      SchemaOf<typeof SpriteRegionOverride>['region']
+    >().toEqualTypeOf<'array<f32, 4>'>();
+  });
+
+  it('SpriteRegionOverride is Component<"SpriteRegionOverride", { region: "array<f32, 4>" }>', () => {
+    type Expected = Component<'SpriteRegionOverride', { readonly region: 'array<f32, 4>' }>;
+    expectTypeOf<typeof SpriteRegionOverride>().toMatchTypeOf<Expected>();
+  });
+});
+
+describe('SpriteRegionOverride — data shape via ShapeOf (AC-08 spawn affordance)', () => {
+  it('ShapeOf<schema> has a single readonly field `region` typed Float32Array', () => {
+    type Data = ShapeOf<SchemaOf<typeof SpriteRegionOverride>>;
+    expectTypeOf<keyof Data>().toEqualTypeOf<'region'>();
+    expectTypeOf<Data['region']>().toEqualTypeOf<Float32Array>();
+  });
+
+  it('world.spawn data is Partial<ShapeOf<schema>> — region optional at consumer surface', () => {
+    type SpawnData = Partial<ShapeOf<SchemaOf<typeof SpriteRegionOverride>>>;
+    expectTypeOf<SpawnData['region']>().toEqualTypeOf<Float32Array | undefined>();
+
+    const empty: SpawnData = {};
+    void empty;
+
+    const filled: SpawnData = { region: new Float32Array([0, 0, 1, 1]) };
+    void filled;
+  });
+});
+
+describe('SpriteRegionOverride — @ts-expect-error negative assertions (AC-08)', () => {
+  it('1. plain number[] is not assignable to data.region (Float32Array nominal)', () => {
+    type SpawnData = Partial<ShapeOf<SchemaOf<typeof SpriteRegionOverride>>>;
+    // @ts-expect-error number[] lacks the Float32Array brand.
+    const wrong: SpawnData = { region: [0, 0, 1, 1] };
+    void wrong;
+  });
+
+  it('2. Uint32Array is not assignable to data.region (TypedArrays do not cross-assign)', () => {
+    type SpawnData = Partial<ShapeOf<SchemaOf<typeof SpriteRegionOverride>>>;
+    // @ts-expect-error TypedArray nominal types do not cross-assign in TS.
+    const wrong: SpawnData = { region: new Uint32Array(4) };
+    void wrong;
+  });
+
+  it('3. extra fields beyond schema (e.g. layer) are not part of ShapeOf', () => {
+    type Data = ShapeOf<SchemaOf<typeof SpriteRegionOverride>>;
+    // The schema is a single-field record; an unknown key has no inferred
+    // entry on Data. Negative assertion: a key the schema does not declare
+    // is not on the type.
+    expectTypeOf<{ layer: number } & Data>().not.toEqualTypeOf<Data>();
+  });
+});

package/src/components/__tests__/tile-layer.test-d.ts

@@ -0,0 +1,33 @@
+// tile-layer.test-d - type-level shape assertions for the TileLayer component
+// schema + markTileLayerDirty signature (feat-20260608 M0 baseline rebuild).
+//
+// Anchors: plan-tasks m0-t3; plan-strategy §M0 targetFiles (tile-layer.ts);
+// AGENTS.md §Component naming.
+
+import type { EcsError, EntityHandle, SchemaOf, World } from '@forgeax/engine-ecs';
+import { markTileLayerDirty, type TileLayer } from '@forgeax/engine-render/authoring';
+import type { Result } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('TileLayer component schema (M0 baseline)', () => {
+  it('type-level: schema fields remain owner-defined and typed', () => {
+    type Schema = SchemaOf<typeof TileLayer>;
+    const schema: Schema = {
+      tiles: 'array<u32>',
+      layerOrder: 'i32',
+      dirty: 'u8',
+      sortScope: 'u8',
+    };
+    expectTypeOf(schema.tiles).toEqualTypeOf<'array<u32>'>();
+    expectTypeOf(schema.layerOrder).toEqualTypeOf<'i32'>();
+    expectTypeOf(schema.dirty).toEqualTypeOf<'u8'>();
+  });
+});
+
+describe('markTileLayerDirty signature (M0 baseline)', () => {
+  it('type-level: markTileLayerDirty(world, layerEntity) returns Result<void, EcsError>', () => {
+    expectTypeOf(markTileLayerDirty).parameter(0).toMatchTypeOf<World>();
+    expectTypeOf(markTileLayerDirty).parameter(1).toMatchTypeOf<EntityHandle>();
+    expectTypeOf(markTileLayerDirty).returns.toMatchTypeOf<Result<void, EcsError>>();
+  });
+});