@flighthq/shading 0.2.1-next.410.a23f189

package/dist/modifierRegistry.js

@@ -0,0 +1,18 @@
+// Allocates an empty modifier registry. The only allocating registry function; register and resolve
+// read or mutate an existing registry in place.
+export function createModifierRegistry() {
+    return { definitions: new Map() };
+}
+// Registers (or replaces) the definition for `definition.kind`. Last-write-wins: a later
+// registration of the same kind overrides the earlier one, so a user can shadow a built-in with a
+// vendor-prefixed override. Kind collisions are avoided by the vendor-prefix convention (bare names
+// reserved for built-ins), not by a guard here.
+export function registerModifier(registry, definition) {
+    registry.definitions.set(definition.kind, definition);
+}
+// Returns the registered definition for `kind`, or `null` when no definition is registered — the
+// expected-miss sentinel a caller checks before composing an unknown kind.
+export function resolveModifier(registry, kind) {
+    return registry.definitions.get(kind) ?? null;
+}
+//# sourceMappingURL=modifierRegistry.js.map

package/dist/modifierRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modifierRegistry.js","sourceRoot":"","sources":["../src/modifierRegistry.ts"],"names":[],"mappings":"AA4BA,oGAAoG;AACpG,gDAAgD;AAChD,MAAM,UAAU,sBAAsB;IACpC,OAAO,EAAE,WAAW,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;AACpC,CAAC;AAED,yFAAyF;AACzF,kGAAkG;AAClG,oGAAoG;AACpG,gDAAgD;AAChD,MAAM,UAAU,gBAAgB,CAAC,QAAoC,EAAE,UAAwC;IAC7G,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACxD,CAAC;AAED,iGAAiG;AACjG,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAAC,QAAoC,EAAE,IAAkB;IACtF,OAAO,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAChD,CAAC"}

package/dist/orderModifierStack.d.ts

@@ -0,0 +1,3 @@
+import type { Modifier } from '@flighthq/types';
+export declare function orderModifierStack(stack: readonly Modifier[]): readonly Modifier[];
+//# sourceMappingURL=orderModifierStack.d.ts.map

package/dist/orderModifierStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderModifierStack.d.ts","sourceRoot":"","sources":["../src/orderModifierStack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAehD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,CAOlF"}

package/dist/orderModifierStack.js

@@ -0,0 +1,36 @@
+import { ModifierSlot } from '@flighthq/types';
+// Orders a modifier stack into the deterministic feature-set the compile path assembles: modifiers
+// are grouped by the canonical slot pipeline order (Vertex deforms the geometry first, then Normal
+// perturbs the normal before lighting, then Diffuse/Specular contribute at shading, then Emissive
+// adds, then Effect runs last on the shaded output), and within one slot the caller's authoring order
+// is preserved. Because the result depends
+// only on the SET of modifiers and their per-slot order — never on cross-slot authoring order — two
+// stacks with the same features produce the same feature-set and therefore the same define-key, so
+// they batch together. Reserved and vendor-prefixed slots outside the built-in taxonomy sort after
+// the known slots, in stable authoring order.
+//
+// Allocates a new array (a compile-time composition step, not a hot-loop write); the input stack is
+// not mutated.
+export function orderModifierStack(stack) {
+    const indexed = stack.map((modifier, index) => ({ index, modifier }));
+    indexed.sort((a, b) => {
+        const rankDelta = getModifierSlotRank(a.modifier.slot) - getModifierSlotRank(b.modifier.slot);
+        return rankDelta !== 0 ? rankDelta : a.index - b.index;
+    });
+    return indexed.map((entry) => entry.modifier);
+}
+// The canonical slot pipeline rank. Unknown slots (reserved Ambient/Shadow, vendor-prefixed) sort
+// after every built-in slot while staying stable relative to one another via the index tie-break.
+function getModifierSlotRank(slot) {
+    const rank = SLOT_RANK.get(slot);
+    return rank !== undefined ? rank : SLOT_RANK.size;
+}
+const SLOT_RANK = new Map([
+    [ModifierSlot.Vertex, 0],
+    [ModifierSlot.Normal, 1],
+    [ModifierSlot.Diffuse, 2],
+    [ModifierSlot.Specular, 3],
+    [ModifierSlot.Emissive, 4],
+    [ModifierSlot.Effect, 5],
+]);
+//# sourceMappingURL=orderModifierStack.js.map

package/dist/orderModifierStack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderModifierStack.js","sourceRoot":"","sources":["../src/orderModifierStack.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,mGAAmG;AACnG,mGAAmG;AACnG,kGAAkG;AAClG,sGAAsG;AACtG,2CAA2C;AAC3C,oGAAoG;AACpG,mGAAmG;AACnG,mGAAmG;AACnG,8CAA8C;AAC9C,EAAE;AACF,oGAAoG;AACpG,eAAe;AACf,MAAM,UAAU,kBAAkB,CAAC,KAA0B;IAC3D,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,MAAM,SAAS,GAAG,mBAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9F,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;IACzD,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,kGAAkG;AAClG,kGAAkG;AAClG,SAAS,mBAAmB,CAAC,IAAkB;IAC7C,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;AACpD,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAuB;IAC9C,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IACxB,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IACxB,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC;IACzB,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1B,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1B,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;CACzB,CAAC,CAAC"}

package/dist/registerBuiltInModifiers.d.ts

@@ -0,0 +1,11 @@
+import type { ModifierDefinition, ModifierRegistry } from './modifierRegistry';
+export declare const animatedNormalModifierDefinition: ModifierDefinition;
+export declare const dissolveModifierDefinition: ModifierDefinition;
+export declare const emissiveModifierDefinition: ModifierDefinition;
+export declare const envReflectModifierDefinition: ModifierDefinition;
+export declare const fogModifierDefinition: ModifierDefinition;
+export declare function registerBuiltInModifiers(registry: Readonly<ModifierRegistry>): void;
+export declare const rimModifierDefinition: ModifierDefinition;
+export declare const toonModifierDefinition: ModifierDefinition;
+export declare const vertexDisplaceModifierDefinition: ModifierDefinition;
+//# sourceMappingURL=registerBuiltInModifiers.d.ts.map

package/dist/registerBuiltInModifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerBuiltInModifiers.d.ts","sourceRoot":"","sources":["../src/registerBuiltInModifiers.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAQ/E,eAAO,MAAM,gCAAgC,EAAE,kBAQ9C,CAAC;AAKF,eAAO,MAAM,0BAA0B,EAAE,kBAMxC,CAAC;AAMF,eAAO,MAAM,0BAA0B,EAAE,kBAUxC,CAAC;AAKF,eAAO,MAAM,4BAA4B,EAAE,kBAG1C,CAAC;AAKF,eAAO,MAAM,qBAAqB,EAAE,kBASnC,CAAC;AAMF,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI,CASnF;AAID,eAAO,MAAM,qBAAqB,EAAE,kBAGnC,CAAC;AAIF,eAAO,MAAM,sBAAsB,EAAE,kBAGpC,CAAC;AAMF,eAAO,MAAM,gCAAgC,EAAE,kBAS9C,CAAC"}

package/dist/registerBuiltInModifiers.js

@@ -0,0 +1,108 @@
+import { AnimatedNormalModifierKind, DissolveModifierKind, EmissiveModifierFacing, EmissiveModifierKind, EnvReflectModifierKind, FogModifierKind, FogModifierMode, ModifierSlot, RimModifierKind, ToonModifierKind, VertexDisplaceModifierKind, VertexDisplaceModifierSource, } from '@flighthq/types';
+import { registerModifier } from './modifierRegistry';
+// The substrate-agnostic AnimatedNormal built-in definition (slot: Normal). Its signature keys the
+// layer count from map structure — `0` disabled (no map), `1` single-layer, `2` dual-layer
+// (secondaryMap present) — the only compile-time-affecting choices; scroll/strength are uniforms.
+// A backend snippet reuses this definition (kind/slot/signature) rather than re-deriving it, so the
+// framework-computed batch key and the compiled variant can never drift.
+export const animatedNormalModifierDefinition = {
+    kind: AnimatedNormalModifierKind,
+    slot: ModifierSlot.Normal,
+    getDefineSignature(modifier) {
+        const animated = modifier;
+        if (animated.map === null)
+            return '0';
+        return animated.secondaryMap !== undefined ? '2' : '1';
+    },
+};
+// The substrate-agnostic Dissolve built-in definition (slot: Effect). Its signature is `m` when a
+// mask/noise texture is supplied (a sampled-noise program) and `''` for the procedural-noise variant
+// — the one compile-time-affecting choice; threshold/edge width/scale are uniforms.
+export const dissolveModifierDefinition = {
+    kind: DissolveModifierKind,
+    slot: ModifierSlot.Effect,
+    getDefineSignature(modifier) {
+        return modifier.map !== undefined ? 'm' : '';
+    },
+};
+// The substrate-agnostic Emissive built-in definition (slot: Emissive). Its signature encodes the
+// two compile-time-affecting options — `m` when masked, `g` when facing-gated (facing set and not
+// Ignore), combined `mg` — never the uniform-fed color/strength. Shared by every backend snippet so
+// the batch key and the compiled program variant stay single-sourced.
+export const emissiveModifierDefinition = {
+    kind: EmissiveModifierKind,
+    slot: ModifierSlot.Emissive,
+    getDefineSignature(modifier) {
+        const emissive = modifier;
+        let signature = '';
+        if (emissive.mask !== undefined)
+            signature += 'm';
+        if (emissive.facing !== undefined && emissive.facing !== EmissiveModifierFacing.Ignore)
+            signature += 'g';
+        return signature;
+    },
+};
+// The substrate-agnostic EnvReflect built-in definition (slot: Effect). One program shape, so no
+// signature — tint/intensity/fresnelBias/roughness are all uniforms and never split a variant. It
+// samples the shared baked environment cubemap the lit block already binds.
+export const envReflectModifierDefinition = {
+    kind: EnvReflectModifierKind,
+    slot: ModifierSlot.Effect,
+};
+// The substrate-agnostic Fog built-in definition (slot: Effect). Its signature is the distance-curve
+// mode — `l` Linear, `e` Exponential, `x` Exponential2 — the only compile-time-affecting choice; the
+// near/far/density scalars and color are uniforms.
+export const fogModifierDefinition = {
+    kind: FogModifierKind,
+    slot: ModifierSlot.Effect,
+    getDefineSignature(modifier) {
+        const fog = modifier;
+        if (fog.mode === FogModifierMode.Exponential)
+            return 'e';
+        if (fog.mode === FogModifierMode.Exponential2)
+            return 'x';
+        return 'l';
+    },
+};
+// Registers the eight built-in modifiers into `registry` with their slots and define-key signatures
+// (the eight exported built-in definitions). Not called at module load (packages are import
+// side-effect-free); a caller opts in once, alongside any vendor-prefixed kinds, before composing.
+// Last-write-wins, so calling it after a custom override re-installs the built-ins.
+export function registerBuiltInModifiers(registry) {
+    registerModifier(registry, animatedNormalModifierDefinition);
+    registerModifier(registry, dissolveModifierDefinition);
+    registerModifier(registry, emissiveModifierDefinition);
+    registerModifier(registry, envReflectModifierDefinition);
+    registerModifier(registry, fogModifierDefinition);
+    registerModifier(registry, rimModifierDefinition);
+    registerModifier(registry, toonModifierDefinition);
+    registerModifier(registry, vertexDisplaceModifierDefinition);
+}
+// The substrate-agnostic Rim built-in definition (slot: Effect). One program shape, so no signature —
+// power/intensity/bias are all uniforms and never split a variant.
+export const rimModifierDefinition = {
+    kind: RimModifierKind,
+    slot: ModifierSlot.Effect,
+};
+// The substrate-agnostic Toon built-in definition (slot: Effect). One program shape, so no signature —
+// steps/smoothness are uniforms and never split a variant.
+export const toonModifierDefinition = {
+    kind: ToonModifierKind,
+    slot: ModifierSlot.Effect,
+};
+// The substrate-agnostic VertexDisplace built-in definition (slot: Vertex — the one vertex-stage
+// built-in). Its signature keys the two compile-time-affecting choices: the noise `source` (`s` Sine,
+// `h` HeightMap) and whether a fixed `axis` replaces the surface-normal push (`+a`); amplitude/
+// frequency/speed/direction are uniforms.
+export const vertexDisplaceModifierDefinition = {
+    kind: VertexDisplaceModifierKind,
+    slot: ModifierSlot.Vertex,
+    getDefineSignature(modifier) {
+        const displace = modifier;
+        let signature = displace.source === VertexDisplaceModifierSource.HeightMap ? 'h' : 's';
+        if (displace.axis !== undefined)
+            signature += 'a';
+        return signature;
+    },
+};
+//# sourceMappingURL=registerBuiltInModifiers.js.map

package/dist/registerBuiltInModifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerBuiltInModifiers.js","sourceRoot":"","sources":["../src/registerBuiltInModifiers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@flighthq/shading",
+  "version": "0.2.1-next.410.a23f189",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/shading"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.2.1-next.410.a23f189",
+    "@flighthq/types": "0.2.1-next.410.a23f189"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Material Feature / Modifier tier — compiled shader augmentations that inject into a ShadedMaterial's shading and produce batchable variants. A composable base lit material carrying an ordered Modifier stack, an open registry keyed by feature kind over the diffuse/specular/normal/emissive/effect slot taxonomy, the composition/ordering contract that turns a stack into a deterministic ordered feature-set plus a stable define-key, seed emissive/rim/animated-normal modifier constructors, and sentinel-returning validation; substrate-agnostic and tree-shakable, the tier between complete materials and post-output adjustments",
+  "sideEffects": false
+}

package/src/createAnimatedNormalModifier.test.ts

@@ -0,0 +1,49 @@
+import type { Texture, Vector2Like } from '@flighthq/types';
+import { AnimatedNormalModifierKind, ModifierSlot } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createAnimatedNormalModifier } from './createAnimatedNormalModifier';
+
+describe('createAnimatedNormalModifier', () => {
+  const scroll: Vector2Like = { x: 0.1, y: 0 };
+
+  it('sets the kind and Normal slot', () => {
+    const modifier = createAnimatedNormalModifier({ map: null, scroll });
+    expect(modifier.kind).toBe(AnimatedNormalModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Normal);
+  });
+
+  it('accepts a null map (the disabled variant)', () => {
+    const modifier = createAnimatedNormalModifier({ map: null, scroll });
+    expect(modifier.map).toBeNull();
+  });
+
+  it('keeps the map and scroll by reference and defaults strength to 1', () => {
+    const map = {} as Texture;
+    const modifier = createAnimatedNormalModifier({ map, scroll });
+    expect(modifier.map).toBe(map);
+    expect(modifier.scroll).toBe(scroll);
+    expect(modifier.strength).toBe(1);
+  });
+
+  it('leaves the second layer absent when not provided', () => {
+    const modifier = createAnimatedNormalModifier({ map: {} as Texture, scroll });
+    expect(modifier.secondaryMap).toBeUndefined();
+    expect(modifier.secondaryScroll).toBeUndefined();
+  });
+
+  it('carries the second dual-scroll layer when provided', () => {
+    const secondaryMap = {} as Texture;
+    const secondaryScroll: Vector2Like = { x: -0.05, y: 0.02 };
+    const modifier = createAnimatedNormalModifier({
+      map: {} as Texture,
+      scroll,
+      strength: 0.5,
+      secondaryMap,
+      secondaryScroll,
+    });
+    expect(modifier.strength).toBe(0.5);
+    expect(modifier.secondaryMap).toBe(secondaryMap);
+    expect(modifier.secondaryScroll).toBe(secondaryScroll);
+  });
+});

package/src/createDissolveModifier.test.ts

@@ -0,0 +1,30 @@
+import type { Texture } from '@flighthq/types';
+import { DissolveModifierKind, ModifierSlot } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createDissolveModifier } from './createDissolveModifier';
+
+describe('createDissolveModifier', () => {
+  it('sets the kind and Effect slot', () => {
+    const modifier = createDissolveModifier({ threshold: 0.5 });
+    expect(modifier.kind).toBe(DissolveModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Effect);
+  });
+
+  it('carries the threshold through and defaults the edge and noise scale', () => {
+    const modifier = createDissolveModifier({ threshold: 0.3 });
+    expect(modifier.threshold).toBe(0.3);
+    expect(modifier.edgeColor).toBe(0xff6600ff);
+    expect(modifier.edgeWidth).toBe(0.05);
+    expect(modifier.scale).toBe(8);
+    expect(modifier.map).toBeUndefined();
+  });
+
+  it('keeps a noise map by reference when provided', () => {
+    const map = {} as Texture;
+    const modifier = createDissolveModifier({ threshold: 0.5, map, edgeColor: 0x00ffddff, edgeWidth: 0.1 });
+    expect(modifier.map).toBe(map);
+    expect(modifier.edgeColor).toBe(0x00ffddff);
+    expect(modifier.edgeWidth).toBe(0.1);
+  });
+});

package/src/createEmissiveModifier.test.ts

@@ -0,0 +1,44 @@
+import type { Texture } from '@flighthq/types';
+import { EmissiveModifierFacing, EmissiveModifierKind, ModifierSlot } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createEmissiveModifier } from './createEmissiveModifier';
+
+describe('createEmissiveModifier', () => {
+  it('sets the kind and Emissive slot', () => {
+    const modifier = createEmissiveModifier({ color: 0xffaa00ff });
+    expect(modifier.kind).toBe(EmissiveModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Emissive);
+  });
+
+  it('carries the packed RGBA color through', () => {
+    const modifier = createEmissiveModifier({ color: 0x1234abff });
+    expect(modifier.color).toBe(0x1234abff);
+  });
+
+  it('defaults strength to 1, facing to Ignore, softness to 0, and leaves the mask absent', () => {
+    const modifier = createEmissiveModifier({ color: 0xffffffff });
+    expect(modifier.strength).toBe(1);
+    expect(modifier.facing).toBe(EmissiveModifierFacing.Ignore);
+    expect(modifier.facingSoftness).toBe(0);
+    expect(modifier.mask).toBeUndefined();
+  });
+
+  it('applies provided scalars and a facing gate', () => {
+    const modifier = createEmissiveModifier({
+      color: 0xffffffff,
+      strength: 4,
+      facing: EmissiveModifierFacing.AwayFromLight,
+      facingSoftness: 0.25,
+    });
+    expect(modifier.strength).toBe(4);
+    expect(modifier.facing).toBe(EmissiveModifierFacing.AwayFromLight);
+    expect(modifier.facingSoftness).toBe(0.25);
+  });
+
+  it('keeps the mask by reference when provided', () => {
+    const mask = {} as Texture;
+    const modifier = createEmissiveModifier({ color: 0xffffffff, mask });
+    expect(modifier.mask).toBe(mask);
+  });
+});

package/src/createEnvReflectModifier.test.ts

@@ -0,0 +1,28 @@
+import { EnvReflectModifierKind, ModifierSlot } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createEnvReflectModifier } from './createEnvReflectModifier';
+
+describe('createEnvReflectModifier', () => {
+  it('sets the kind and Effect slot', () => {
+    const modifier = createEnvReflectModifier();
+    expect(modifier.kind).toBe(EnvReflectModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Effect);
+  });
+
+  it('defaults to a mirror-sharp opaque-white dielectric reflection', () => {
+    const modifier = createEnvReflectModifier();
+    expect(modifier.tint).toBe(0xffffffff);
+    expect(modifier.intensity).toBe(1);
+    expect(modifier.fresnelBias).toBe(0.04);
+    expect(modifier.roughness).toBe(0);
+  });
+
+  it('applies provided scalars', () => {
+    const modifier = createEnvReflectModifier({ tint: 0x88ccffff, intensity: 0.5, fresnelBias: 0.1, roughness: 0.6 });
+    expect(modifier.tint).toBe(0x88ccffff);
+    expect(modifier.intensity).toBe(0.5);
+    expect(modifier.fresnelBias).toBe(0.1);
+    expect(modifier.roughness).toBe(0.6);
+  });
+});

package/src/createFogModifier.test.ts

@@ -0,0 +1,31 @@
+import { FogModifierKind, FogModifierMode, ModifierSlot } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createFogModifier } from './createFogModifier';
+
+describe('createFogModifier', () => {
+  it('sets the kind and Effect slot', () => {
+    const modifier = createFogModifier({ color: 0xaabbccff });
+    expect(modifier.kind).toBe(FogModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Effect);
+  });
+
+  it('carries the packed RGBA color through', () => {
+    const modifier = createFogModifier({ color: 0x1122ddff });
+    expect(modifier.color).toBe(0x1122ddff);
+  });
+
+  it('defaults to a linear ramp from 0 to 1 with density 1', () => {
+    const modifier = createFogModifier({ color: 0xffffffff });
+    expect(modifier.mode).toBe(FogModifierMode.Linear);
+    expect(modifier.near).toBe(0);
+    expect(modifier.far).toBe(1);
+    expect(modifier.density).toBe(1);
+  });
+
+  it('applies provided mode and scalars', () => {
+    const modifier = createFogModifier({ color: 0xffffffff, mode: FogModifierMode.Exponential2, density: 0.05 });
+    expect(modifier.mode).toBe(FogModifierMode.Exponential2);
+    expect(modifier.density).toBe(0.05);
+  });
+});

package/src/createRimModifier.test.ts

@@ -0,0 +1,31 @@
+import { ModifierSlot, RimModifierKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createRimModifier } from './createRimModifier';
+
+describe('createRimModifier', () => {
+  it('sets the kind and Effect slot', () => {
+    const modifier = createRimModifier({ color: 0x88ccffff });
+    expect(modifier.kind).toBe(RimModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Effect);
+  });
+
+  it('carries the packed RGBA color through', () => {
+    const modifier = createRimModifier({ color: 0x010203ff });
+    expect(modifier.color).toBe(0x010203ff);
+  });
+
+  it('defaults power to 3, intensity to 1, bias to 0', () => {
+    const modifier = createRimModifier({ color: 0xffffffff });
+    expect(modifier.power).toBe(3);
+    expect(modifier.intensity).toBe(1);
+    expect(modifier.bias).toBe(0);
+  });
+
+  it('applies provided falloff scalars', () => {
+    const modifier = createRimModifier({ color: 0xffffffff, power: 5, intensity: 2, bias: 0.1 });
+    expect(modifier.power).toBe(5);
+    expect(modifier.intensity).toBe(2);
+    expect(modifier.bias).toBe(0.1);
+  });
+});

package/src/createShadedMaterial.test.ts

@@ -0,0 +1,45 @@
+import { EntityRuntimeKey, ShadedMaterialKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createEmissiveModifier } from './createEmissiveModifier';
+import { createShadedMaterial } from './createShadedMaterial';
+
+describe('createShadedMaterial', () => {
+  it('builds an entity with the ShadedMaterial kind', () => {
+    const material = createShadedMaterial();
+    expect(material.kind).toBe(ShadedMaterialKind);
+    expect(EntityRuntimeKey in material).toBe(true);
+  });
+
+  it('defaults the lit base to white diffuse/specular, shininess 32, unit normal scale, no maps', () => {
+    const material = createShadedMaterial();
+    expect(material.diffuse).toBe(0xffffffff);
+    expect(material.specular).toBe(0xffffffff);
+    expect(material.shininess).toBe(32);
+    expect(material.normalScale).toBe(1);
+    expect(material.diffuseMap).toBeNull();
+    expect(material.specularMap).toBeNull();
+    expect(material.normalMap).toBeNull();
+  });
+
+  it('defaults the SurfaceMaterial trailer to opaque single-sided straight-alpha', () => {
+    const material = createShadedMaterial();
+    expect(material.alphaMode).toBe('opaque');
+    expect(material.alphaType).toBe('straight');
+    expect(material.alphaCutoff).toBe(0.5);
+    expect(material.doubleSided).toBe(false);
+  });
+
+  it('defaults to an empty modifier stack', () => {
+    const material = createShadedMaterial();
+    expect(material.modifiers).toEqual([]);
+  });
+
+  it('applies provided base values and modifier stack', () => {
+    const modifiers = [createEmissiveModifier({ color: 0xffaa00ff })];
+    const material = createShadedMaterial({ diffuse: 0x102030ff, shininess: 8, modifiers });
+    expect(material.diffuse).toBe(0x102030ff);
+    expect(material.shininess).toBe(8);
+    expect(material.modifiers).toBe(modifiers);
+  });
+});

package/src/createToonModifier.test.ts

@@ -0,0 +1,23 @@
+import { ModifierSlot, ToonModifierKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createToonModifier } from './createToonModifier';
+
+describe('createToonModifier', () => {
+  it('sets the kind and Effect slot', () => {
+    const modifier = createToonModifier({ steps: 3 });
+    expect(modifier.kind).toBe(ToonModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Effect);
+  });
+
+  it('carries the step count through and defaults smoothness to 0', () => {
+    const modifier = createToonModifier({ steps: 4 });
+    expect(modifier.steps).toBe(4);
+    expect(modifier.smoothness).toBe(0);
+  });
+
+  it('applies a provided smoothness', () => {
+    const modifier = createToonModifier({ steps: 2, smoothness: 0.2 });
+    expect(modifier.smoothness).toBe(0.2);
+  });
+});

package/src/createVertexDisplaceModifier.test.ts

@@ -0,0 +1,36 @@
+import type { Texture, Vector3Like } from '@flighthq/types';
+import { ModifierSlot, VertexDisplaceModifierKind, VertexDisplaceModifierSource } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createVertexDisplaceModifier } from './createVertexDisplaceModifier';
+
+describe('createVertexDisplaceModifier', () => {
+  it('sets the kind and the Vertex slot', () => {
+    const modifier = createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.Sine, amplitude: 0.1 });
+    expect(modifier.kind).toBe(VertexDisplaceModifierKind);
+    expect(modifier.slot).toBe(ModifierSlot.Vertex);
+  });
+
+  it('defaults the Sine wave params and leaves axis/map absent', () => {
+    const modifier = createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.Sine, amplitude: 0.2 });
+    expect(modifier.frequency).toBe(1);
+    expect(modifier.speed).toBe(1);
+    expect(modifier.direction).toEqual({ x: 1, y: 0, z: 0 });
+    expect(modifier.axis).toBeUndefined();
+    expect(modifier.map).toBeUndefined();
+  });
+
+  it('keeps a fixed axis and a height map by reference when provided', () => {
+    const axis: Vector3Like = { x: 0, y: 1, z: 0 };
+    const map = {} as Texture;
+    const modifier = createVertexDisplaceModifier({
+      source: VertexDisplaceModifierSource.HeightMap,
+      amplitude: 1,
+      axis,
+      map,
+    });
+    expect(modifier.source).toBe(VertexDisplaceModifierSource.HeightMap);
+    expect(modifier.axis).toBe(axis);
+    expect(modifier.map).toBe(map);
+  });
+});

package/src/getModifierDefineKey.test.ts

@@ -0,0 +1,74 @@
+import type { Texture } from '@flighthq/types';
+import { EmissiveModifierFacing } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createAnimatedNormalModifier } from './createAnimatedNormalModifier';
+import { createEmissiveModifier } from './createEmissiveModifier';
+import { createRimModifier } from './createRimModifier';
+import { getModifierDefineKey } from './getModifierDefineKey';
+import { createModifierRegistry } from './modifierRegistry';
+import { registerBuiltInModifiers } from './registerBuiltInModifiers';
+
+describe('getModifierDefineKey', () => {
+  const registry = createModifierRegistry();
+  registerBuiltInModifiers(registry);
+
+  it('returns the empty string for an empty stack', () => {
+    expect(getModifierDefineKey([], registry)).toBe('');
+  });
+
+  it('joins slot-ordered kinds with the plus separator', () => {
+    const normal = createAnimatedNormalModifier({ map: {} as Texture, scroll: { x: 0, y: 0 } });
+    const emissive = createEmissiveModifier({ color: 0xffffffff });
+    const rim = createRimModifier({ color: 0xffffffff });
+    const key = getModifierDefineKey([rim, emissive, normal], registry);
+    expect(key).toBe('AnimatedNormalModifier:1+EmissiveModifier+RimModifier');
+  });
+
+  it('is stable regardless of cross-slot authoring order', () => {
+    const normal = createAnimatedNormalModifier({ map: {} as Texture, scroll: { x: 0, y: 0 } });
+    const rim = createRimModifier({ color: 0xffffffff });
+    expect(getModifierDefineKey([normal, rim], registry)).toBe(getModifierDefineKey([rim, normal], registry));
+  });
+
+  it('captures compile-time variants but not uniform-fed scalars', () => {
+    const plain = createEmissiveModifier({ color: 0xffffffff });
+    const strongerButSameProgram = createEmissiveModifier({ color: 0x00ff00ff, strength: 9 });
+    const masked = createEmissiveModifier({ color: 0xffffffff, mask: {} as Texture });
+    const gated = createEmissiveModifier({ color: 0xffffffff, facing: EmissiveModifierFacing.AwayFromLight });
+    const maskedAndGated = createEmissiveModifier({
+      color: 0xffffffff,
+      mask: {} as Texture,
+      facing: EmissiveModifierFacing.TowardLight,
+    });
+    expect(getModifierDefineKey([plain], registry)).toBe('EmissiveModifier');
+    expect(getModifierDefineKey([strongerButSameProgram], registry)).toBe('EmissiveModifier');
+    expect(getModifierDefineKey([masked], registry)).toBe('EmissiveModifier:m');
+    expect(getModifierDefineKey([gated], registry)).toBe('EmissiveModifier:g');
+    expect(getModifierDefineKey([maskedAndGated], registry)).toBe('EmissiveModifier:mg');
+  });
+
+  it('distinguishes single, dual, and disabled animated-normal variants', () => {
+    const disabled = createAnimatedNormalModifier({ map: null, scroll: { x: 0, y: 0 } });
+    const single = createAnimatedNormalModifier({ map: {} as Texture, scroll: { x: 0, y: 0 } });
+    const dual = createAnimatedNormalModifier({
+      map: {} as Texture,
+      scroll: { x: 0, y: 0 },
+      secondaryMap: {} as Texture,
+    });
+    expect(getModifierDefineKey([disabled], registry)).toBe('AnimatedNormalModifier:0');
+    expect(getModifierDefineKey([single], registry)).toBe('AnimatedNormalModifier:1');
+    expect(getModifierDefineKey([dual], registry)).toBe('AnimatedNormalModifier:2');
+  });
+
+  it('falls back to bare kinds without a registry', () => {
+    const masked = createEmissiveModifier({ color: 0xffffffff, mask: {} as Texture });
+    expect(getModifierDefineKey([masked])).toBe('EmissiveModifier');
+  });
+
+  it('reflects per-slot count and order in the key', () => {
+    const rimA = createRimModifier({ color: 0x111111ff });
+    const rimB = createRimModifier({ color: 0x222222ff });
+    expect(getModifierDefineKey([rimA, rimB], registry)).toBe('RimModifier+RimModifier');
+  });
+});