@forgeax/engine-runtime 0.1.2

package/src/__tests__/sprite-lit-extract-branch.test.ts

@@ -0,0 +1,117 @@
+// @forgeax/engine-runtime / __tests__ / sprite-lit-extract-branch.test.ts
+//
+// feat-20260624-sprite-lit-shading-model-pure-2d-lighting M1' / t2.
+//
+// Tests for the AC-02 (D-9 remap) extract branch: when the first pass
+// shader id is 'forgeax::sprite-lit' the snapshot must carry
+// `materialShaderId === 'forgeax::sprite-lit'` and `transparent === true`
+// (derived from renderState.blend presence). The branch mirrors
+// `'forgeax::sprite'` without adding any material-kind discriminant.
+//
+// tweak-20260701-remove-vestigial-shadingmodel-concept M1 reality:
+//   - MaterialSnapshot no longer carries a `shadingModel` field at all —
+//     the surface-response discriminant responsibility was fully absorbed
+//     by shader identity (`materialShaderId`). This is the strongest form
+//     of the original D-10 invariant: sprite-lit cannot be added to a
+//     shadingModel union because there is no such union.
+//   - sprite carries `materialShaderId` only
+//   - transparent derives from `renderState.blend !== undefined`
+//   - sprite-lit walks the SAME schema-driven path as sprite
+//
+// SSOTs:
+//   - plan-strategy D-1 (materialShaderId string routing mirror sprite)
+//   - plan-strategy D-9 (AC-02 remap: no 'sprite-lit' inferredShadingModel case)
+//   - plan-strategy D-10 (AC-01 remap: no new narrowing type guard)
+//   - render-system-extract.ts MaterialSnapshot (no shadingModel field)
+//   - requirements AC-01 / AC-02 (post-rewrite)
+
+import { fileURLToPath } from 'node:url';
+import type { MaterialSnapshot } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+describe('sprite-lit extract branch (D-9 remap, AC-02 + AC-01)', () => {
+  describe('sprite-lit routes via materialShaderId (AC-01 D-10 remap)', () => {
+    it('MaterialSnapshot carries no shadingModel field (union retired)', () => {
+      // tweak-20260701 M1: the shadingModel discriminant is gone entirely.
+      // A snapshot's material kind is derived solely from materialShaderId.
+      const snapshot = {
+        baseColor: [1, 1, 1],
+        metallic: 0,
+        roughness: 1,
+        materialShaderId: 'forgeax::sprite-lit',
+      } as unknown as MaterialSnapshot;
+      expect('shadingModel' in snapshot).toBe(false);
+    });
+
+    it('sprite-lit shading is recognised via materialShaderId string routing', () => {
+      // Mirror sprite's pattern (post-PR-#520 D-3): the consumer reads
+      // `material.materialShaderId === 'forgeax::sprite-lit'` for any
+      // sprite-lit-specific routing.
+      const snapshot = {
+        materialShaderId: 'forgeax::sprite-lit',
+        transparent: true,
+      } as const;
+      expect(snapshot.materialShaderId === 'forgeax::sprite-lit').toBe(true);
+      expect(snapshot.transparent).toBe(true);
+    });
+  });
+
+  describe('sprite-lit snapshot shape (D-9 remap, AC-02 SSOT)', () => {
+    it('firstPassShader = "forgeax::sprite-lit" produces materialShaderId + transparent=true', () => {
+      // TS port of the expected extract-stage result for a sprite-lit
+      // material with `renderState.blend` set (sprite-lit.material.json
+      // mirrors sprite blend declaration after t4 lands). transparent is
+      // derived from `renderState.blend !== undefined` per the post-#520
+      // SSOT (no longer carried on MaterialPass.transparent).
+      const fakeFirstPass = {
+        program: { module: 'forgeax::sprite-lit' },
+        renderState: { blend: { color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' } } },
+      } as const;
+      const snapshot = {
+        materialShaderId: fakeFirstPass.program.module,
+        transparent: fakeFirstPass.renderState.blend !== undefined,
+      };
+      expect(snapshot.materialShaderId).toBe('forgeax::sprite-lit');
+      expect(snapshot.transparent).toBe(true);
+    });
+
+    it('sprite vs sprite-lit produce identical snapshot SHAPE (only materialShaderId differs)', () => {
+      // D-1: sprite-lit walks the EXACT SAME schema-driven generic path
+      // as sprite. The only field that differs is materialShaderId.
+      const spriteSnap = {
+        materialShaderId: 'forgeax::sprite' as string,
+        transparent: true as const,
+      };
+      const spriteLitSnap = {
+        materialShaderId: 'forgeax::sprite-lit' as string,
+        transparent: true as const,
+      };
+      // Field-set congruence: identical keys, identical types.
+      const keysSprite = Object.keys(spriteSnap).sort();
+      const keysSpriteLit = Object.keys(spriteLitSnap).sort();
+      expect(keysSpriteLit).toEqual(keysSprite);
+      // Only `materialShaderId` differs in value.
+      expect(spriteSnap.transparent).toBe(spriteLitSnap.transparent);
+      expect(spriteSnap.materialShaderId === spriteLitSnap.materialShaderId).toBe(false);
+    });
+  });
+
+  describe('source-side guarantees (post-rewrite render-system-extract.ts)', () => {
+    it('render-system-extract.ts must NOT branch on `shadingModel === "sprite-lit"` (D-10)', async () => {
+      // Dynamic node:fs / node:module pattern reused from sibling shader
+      // tests. The extract-stage source must NOT carry a literal
+      // `'sprite-lit'` arm under `shadingModel === ...` — sprite-lit
+      // identifies via materialShaderId string only. (Post tweak-20260701
+      // M1 the shadingModel field is gone, so this is trivially true, but
+      // the guard stays to catch a reintroduction.)
+      const fs = await import('node:fs');
+      const src = fs.readFileSync(
+        fileURLToPath(new URL('../../../render/src/render-system-extract.ts', import.meta.url)),
+        'utf8',
+      );
+      // The narrowing point must not check shadingModel against a string
+      // literal 'sprite-lit'.
+      expect(/shadingModel\s*===\s*['"]sprite-lit['"]/.test(src)).toBe(false);
+    });
+  });
+});

package/src/__tests__/sprite-lit-pipeline-cache-key.test.ts

@@ -0,0 +1,123 @@
+// @forgeax/engine-runtime / __tests__ / sprite-lit-pipeline-cache-key.test.ts
+//
+// feat-20260624-sprite-lit-shading-model-pure-2d-lighting M1' / t2.
+//
+// Red-stage tests for the sprite-lit pipeline cache-key STRING ISOLATION
+// (D-11 remap, AC-08 post-rewrite).
+//
+// post-PR-#520 reality: pipeline cache lives inside createRenderer behind
+// `getMaterialShaderPipeline(materialShaderId, isHdr, renderState?, topology?,
+// indexFormat?, variantSet?, passKind?, meshAttributes?, sampleCount?,
+// colorFormatOverride?)`. The cache key is keyed FIRST by the
+// `materialShaderId` string, so the addition of `forgeax::sprite-lit`
+// strictly grows the cache by net-new keys without colliding with the
+// pre-existing `forgeax::sprite` family of PSOs.
+//
+// This test exercises the STRING shape of the cache key prefix (without
+// booting WebGPU). The full PSO build path is exercised by t11 smoke +
+// t12 pixel-parity.
+//
+// SSOTs:
+//   - render-system.ts getMaterialShaderPipeline 9-arg signature SSOT
+//   - plan-strategy D-11 (AC-08 remap: cache key string isolation)
+//   - plan-strategy D-1 (D-6 mirror sprite, NO shared registration)
+//   - requirements AC-08 / AC-12
+
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const SPRITE_ID: string = 'forgeax::sprite';
+const SPRITE_LIT_ID: string = 'forgeax::sprite-lit';
+
+/**
+ * Lower bound TS port of the per-shader cache key. The real key in
+ * createRenderer concatenates more fields (renderState, topology,
+ * indexFormat, variantSet, passKind, meshAttributes, sampleCount,
+ * colorFormatOverride), but the FIRST segment is always
+ * `materialShaderId` — D-11 string isolation is established by that
+ * leading segment alone, regardless of the suffix shape.
+ *
+ * For test purposes we model the 9-arg key flatly with `::` separators.
+ */
+interface PipelineKeyParts {
+  readonly materialShaderId: string;
+  readonly isHdr: boolean;
+  readonly variantSet?: string;
+  readonly passKind?: 'forward' | 'shadow-caster';
+  readonly sampleCount?: number;
+}
+
+function deriveCacheKey(p: PipelineKeyParts): string {
+  return [
+    p.materialShaderId,
+    p.isHdr ? 'hdr' : 'ldr',
+    p.variantSet ?? '',
+    p.passKind ?? 'forward',
+    String(p.sampleCount ?? 1),
+  ].join('::');
+}
+
+describe('sprite-lit pipeline cache-key string isolation (D-11 remap, AC-08)', () => {
+  it('cache key prefix begins with materialShaderId (D-11 leading segment SSOT)', () => {
+    const key = deriveCacheKey({ materialShaderId: SPRITE_LIT_ID, isHdr: false });
+    expect(key.startsWith(`${SPRITE_LIT_ID}::`)).toBe(true);
+  });
+
+  it('sprite-lit key NEVER prefix-collides with sprite key (D-11 string isolation)', () => {
+    // The post-PR-#520 cache is keyed on the full string, but the
+    // `materialShaderId` leading segment is the critical isolator: if
+    // it changes, the suffix can never produce a collision. Validate
+    // that the two shader id strings are PREFIX-incomparable (neither
+    // is a prefix of the other, even at the `::` separator).
+    expect(SPRITE_LIT_ID.startsWith(`${SPRITE_ID}::`)).toBe(false);
+    expect(SPRITE_ID.startsWith(`${SPRITE_LIT_ID}::`)).toBe(false);
+    // And the shader ids differ outright.
+    expect(SPRITE_ID === SPRITE_LIT_ID).toBe(false);
+  });
+
+  it('product of (sprite, sprite-lit) x (ldr, hdr) yields 4 distinct keys', () => {
+    const keys = new Set<string>();
+    for (const id of [SPRITE_ID, SPRITE_LIT_ID]) {
+      for (const isHdr of [false, true]) {
+        keys.add(deriveCacheKey({ materialShaderId: id, isHdr }));
+      }
+    }
+    expect(keys.size).toBe(4);
+  });
+
+  it('product of (sprite, sprite-lit) x (ldr, hdr) x (msaa 1/4) yields 8 distinct keys', () => {
+    // AC-12 anchor: sprite's pre-existing 4 PSO family (sampleCount 1/4 x
+    // isHdr false/true) is preserved; sprite-lit adds a parallel 4 PSO
+    // family, NOT sharing slots.
+    const keys = new Set<string>();
+    for (const id of [SPRITE_ID, SPRITE_LIT_ID]) {
+      for (const isHdr of [false, true]) {
+        for (const sampleCount of [1, 4]) {
+          keys.add(deriveCacheKey({ materialShaderId: id, isHdr, sampleCount }));
+        }
+      }
+    }
+    expect(keys.size).toBe(8);
+  });
+
+  it('cache key changes when isHdr flips (negative gate vs key collapse)', () => {
+    const ldr = deriveCacheKey({ materialShaderId: SPRITE_LIT_ID, isHdr: false });
+    const hdr = deriveCacheKey({ materialShaderId: SPRITE_LIT_ID, isHdr: true });
+    expect(ldr).not.toBe(hdr);
+  });
+
+  it('createRenderer wiring contract: sprite-lit must be registered alongside sprite', async () => {
+    // Static source gate: createRenderer.ts must mention both shader
+    // identifiers in its registration code path. The literal must
+    // appear in source for the runtime to ship sprite-lit as a
+    // recognised material shader.
+    const fs = await import('node:fs');
+    const src = fs.readFileSync(
+      fileURLToPath(new URL('../../../render/src/renderer/renderer-factory.ts', import.meta.url)),
+      'utf8',
+    );
+    // Once t7 wires it, both literals appear (sprite already in tree).
+    expect(src.includes("'forgeax::sprite'")).toBe(true);
+    expect(src.includes("'forgeax::sprite-lit'")).toBe(true);
+  });
+});

package/src/__tests__/sprite-param-values.test-d.ts

@@ -0,0 +1,104 @@
+// w1 / M1 — sprite values type-level fixture (feat-20260527-sprite-nineslice).
+// feat-20260625-refactor-sprite-as-transparent-mesh M3 / w11 update (D-4, D-6,
+// F-3): paramSchema is UBO-aligned (4 vec4 + baseColorTexture); SpriteParamValues
+// mirrors this 1:1.
+//
+// Type-level fixture for the sprite material `values` literal at the
+// MaterialAsset construction call-site. This is the AI-user-facing
+// autocomplete + ts-expect-error surface for the post-w11 sprite paramSchema.
+//
+// SpriteParamValues is a local helper type — it is NOT a public sibling
+// type of MaterialAsset (plan-strategy section D-1: do not introduce a
+// SpriteMaterialAsset variant). It mirrors the field set of
+// `packages/shader/src/sprite.material.json#paramSchema` 1:1 so AI users
+// get the right autocomplete and the right ts-expect-error when they pass
+// the wrong shape.
+//
+// Field set must match paramSchema name set: colorTint / region /
+// pivotAndSize / slicesAndMode (UBO vec4 fields) + baseColorTexture
+// (texture2d). Bidirectional diff check is the implementer's responsibility
+// at commit time (plan-strategy R-7 fixture-schema alignment).
+//
+// slicesAndMode encodes sliceMode in the .w sign (D-3 sentinel): positive
+// or zero -> stretch; NEGATIVE -> tile. The wire format on the GPU side
+// reads `slicesAndMode.w < 0` as the tile dispatch (sprite.wgsl uses
+// abs() to recover the magnitude). The pre-w11 fixture's `sliceMode: 0|1`
+// split is replaced by this single vec4 with sentinel encoding.
+//
+// 4 ts-expect-error assertions:
+//   (a) slicesAndMode as 3-tuple [1, 2, 3] is rejected — must be 4-tuple
+//   (b) region as 3-tuple [0, 0, 1] is rejected — must be 4-tuple
+//   (c) baseColorTexture as a number is rejected — must be string GUID
+//   (d) missing required `baseColorTexture` field is rejected
+
+import { describe, it } from 'vitest';
+
+// Local helper type — paramSchema field set 1:1, no public re-export.
+// `baseColorTexture` is required (paramSchema entry has no default); the
+// 4 UBO vec4 fields are optional (paramSchema entries carry defaults so
+// the writer falls back to identity bytes via std140 zero-fill).
+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];
+};
+
+describe('w11 type-level - sprite values UBO-aligned schema (M3)', () => {
+  it('accepts a fully-specified literal with slicesAndMode + pivotAndSize', () => {
+    const _ok: SpriteParamValues = {
+      baseColorTexture: 'tex-guid',
+      colorTint: [1, 1, 1, 1],
+      region: [0, 0, 1, 1],
+      pivotAndSize: [0.5, 0.5, 1, 1],
+      // Stretch (positive .w): slicesAndMode = [l, t, r, b].
+      slicesAndMode: [0.25, 0.25, 0.75, 0.75],
+    };
+    void _ok;
+  });
+
+  it('accepts the tile sentinel encoding (negative .w) on slicesAndMode', () => {
+    const _ok: SpriteParamValues = {
+      baseColorTexture: 'tex-guid',
+      // Tile (negative .w): the shader reads abs() for the magnitude and
+      // the sign for tile vs stretch (plan-strategy D-3 sentinel).
+      slicesAndMode: [0.25, 0.25, 0.25, -0.25],
+    };
+    void _ok;
+  });
+
+  it('rejects slicesAndMode with wrong arity', () => {
+    const _bad: SpriteParamValues = {
+      baseColorTexture: 'tex-guid',
+      // @ts-expect-error - slicesAndMode must be a 4-tuple, not a 3-tuple
+      slicesAndMode: [1, 2, 3],
+    };
+    void _bad;
+  });
+
+  it('rejects region with wrong arity', () => {
+    const _bad: SpriteParamValues = {
+      baseColorTexture: 'tex-guid',
+      // @ts-expect-error - region must be a 4-tuple, not a 3-tuple
+      region: [0, 0, 1],
+    };
+    void _bad;
+  });
+
+  it('rejects baseColorTexture as a non-string handle', () => {
+    const _bad: SpriteParamValues = {
+      // @ts-expect-error - baseColorTexture must be a string AssetGuid
+      baseColorTexture: 42,
+    };
+    void _bad;
+  });
+
+  it('rejects literal missing the required `baseColorTexture` field', () => {
+    // @ts-expect-error - `baseColorTexture` is required (paramSchema entry has no default)
+    const _bad: SpriteParamValues = {
+      slicesAndMode: [0, 0, 1, 1],
+    };
+    void _bad;
+  });
+});