@flighthq/shading 0.2.1-next.410.a23f189

package/src/getUnregisteredModifierKinds.test.ts

@@ -0,0 +1,40 @@
+import type { Modifier } from '@flighthq/types';
+import { EmissiveModifierKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createEmissiveModifier } from './createEmissiveModifier';
+import { getUnregisteredModifierKinds } from './getUnregisteredModifierKinds';
+import { createModifierRegistry } from './modifierRegistry';
+import { registerBuiltInModifiers } from './registerBuiltInModifiers';
+
+describe('getUnregisteredModifierKinds', () => {
+  it('returns an empty array when every kind is registered', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const stack = [createEmissiveModifier({ color: 0xffffffff })];
+    expect(getUnregisteredModifierKinds(registry, stack)).toEqual([]);
+  });
+
+  it('returns an empty array for an empty stack', () => {
+    const registry = createModifierRegistry();
+    expect(getUnregisteredModifierKinds(registry, [])).toEqual([]);
+  });
+
+  it('names each unregistered kind once in first-seen order', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const stack: Modifier[] = [
+      { kind: 'acme.Missing', slot: 'Effect' },
+      createEmissiveModifier({ color: 0xffffffff }),
+      { kind: 'acme.Other', slot: 'Normal' },
+      { kind: 'acme.Missing', slot: 'Effect' },
+    ];
+    expect(getUnregisteredModifierKinds(registry, stack)).toEqual(['acme.Missing', 'acme.Other']);
+  });
+
+  it('reports a built-in kind as unregistered when built-ins were not installed', () => {
+    const registry = createModifierRegistry();
+    const stack = [createEmissiveModifier({ color: 0xffffffff })];
+    expect(getUnregisteredModifierKinds(registry, stack)).toEqual([EmissiveModifierKind]);
+  });
+});

package/src/isBuiltInModifierSlot.test.ts

@@ -0,0 +1,25 @@
+import { ModifierSlot } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { isBuiltInModifierSlot } from './isBuiltInModifierSlot';
+
+describe('isBuiltInModifierSlot', () => {
+  it('accepts every built-in slot name', () => {
+    expect(isBuiltInModifierSlot(ModifierSlot.Diffuse)).toBe(true);
+    expect(isBuiltInModifierSlot(ModifierSlot.Specular)).toBe(true);
+    expect(isBuiltInModifierSlot(ModifierSlot.Normal)).toBe(true);
+    expect(isBuiltInModifierSlot(ModifierSlot.Emissive)).toBe(true);
+    expect(isBuiltInModifierSlot(ModifierSlot.Effect)).toBe(true);
+  });
+
+  it('rejects reserved and vendor-prefixed slots', () => {
+    expect(isBuiltInModifierSlot('Ambient')).toBe(false);
+    expect(isBuiltInModifierSlot('Shadow')).toBe(false);
+    expect(isBuiltInModifierSlot('acme.Weird')).toBe(false);
+  });
+
+  it('rejects arbitrary strings', () => {
+    expect(isBuiltInModifierSlot('')).toBe(false);
+    expect(isBuiltInModifierSlot('diffuse')).toBe(false);
+  });
+});

package/src/isModifierStackValid.test.ts

@@ -0,0 +1,27 @@
+import type { Modifier } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createEmissiveModifier } from './createEmissiveModifier';
+import { isModifierStackValid } from './isModifierStackValid';
+import { createModifierRegistry } from './modifierRegistry';
+import { registerBuiltInModifiers } from './registerBuiltInModifiers';
+
+describe('isModifierStackValid', () => {
+  it('is true when every kind is registered', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    expect(isModifierStackValid(registry, [createEmissiveModifier({ color: 0xffffffff })])).toBe(true);
+  });
+
+  it('is true for an empty stack', () => {
+    const registry = createModifierRegistry();
+    expect(isModifierStackValid(registry, [])).toBe(true);
+  });
+
+  it('is false when any kind is unregistered', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const stack: Modifier[] = [createEmissiveModifier({ color: 0xffffffff }), { kind: 'acme.Missing', slot: 'Effect' }];
+    expect(isModifierStackValid(registry, stack)).toBe(false);
+  });
+});

package/src/modifierRegistry.test.ts

@@ -0,0 +1,59 @@
+import type { Modifier } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createModifierRegistry, registerModifier, resolveModifier } from './modifierRegistry';
+
+describe('createModifierRegistry', () => {
+  it('allocates an empty registry', () => {
+    const registry = createModifierRegistry();
+    expect(registry.definitions.size).toBe(0);
+  });
+
+  it('allocates a fresh registry each call', () => {
+    const a = createModifierRegistry();
+    const b = createModifierRegistry();
+    registerModifier(a, { kind: 'acme.Foo', slot: 'Effect' });
+    expect(resolveModifier(b, 'acme.Foo')).toBeNull();
+  });
+});
+
+describe('registerModifier', () => {
+  it('stores a definition retrievable by kind', () => {
+    const registry = createModifierRegistry();
+    registerModifier(registry, { kind: 'acme.Foo', slot: 'Emissive' });
+    expect(resolveModifier(registry, 'acme.Foo')?.slot).toBe('Emissive');
+  });
+
+  it('is last-write-wins for the same kind', () => {
+    const registry = createModifierRegistry();
+    registerModifier(registry, { kind: 'acme.Foo', slot: 'Emissive' });
+    registerModifier(registry, { kind: 'acme.Foo', slot: 'Normal' });
+    expect(resolveModifier(registry, 'acme.Foo')?.slot).toBe('Normal');
+    expect(registry.definitions.size).toBe(1);
+  });
+
+  it('retains a getDefineSignature callback', () => {
+    const registry = createModifierRegistry();
+    registerModifier(registry, {
+      kind: 'acme.Foo',
+      slot: 'Effect',
+      getDefineSignature: (modifier: Readonly<Modifier>) => modifier.slot,
+    });
+    const definition = resolveModifier(registry, 'acme.Foo');
+    expect(definition?.getDefineSignature?.({ kind: 'acme.Foo', slot: 'Effect' })).toBe('Effect');
+  });
+});
+
+describe('resolveModifier', () => {
+  it('returns null for an unregistered kind', () => {
+    const registry = createModifierRegistry();
+    expect(resolveModifier(registry, 'acme.Missing')).toBeNull();
+  });
+
+  it('returns the registered definition', () => {
+    const registry = createModifierRegistry();
+    const definition = { kind: 'acme.Foo', slot: 'Normal' };
+    registerModifier(registry, definition);
+    expect(resolveModifier(registry, 'acme.Foo')).toBe(definition);
+  });
+});

package/src/orderModifierStack.test.ts

@@ -0,0 +1,48 @@
+import type { Modifier } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createAnimatedNormalModifier } from './createAnimatedNormalModifier';
+import { createEmissiveModifier } from './createEmissiveModifier';
+import { createRimModifier } from './createRimModifier';
+import { orderModifierStack } from './orderModifierStack';
+
+describe('orderModifierStack', () => {
+  const normal = createAnimatedNormalModifier({ map: null, scroll: { x: 0, y: 0 } });
+  const emissive = createEmissiveModifier({ color: 0xffffffff });
+  const rim = createRimModifier({ color: 0xffffffff });
+
+  it('groups modifiers into the canonical Normal -> Emissive -> Effect pipeline order', () => {
+    const ordered = orderModifierStack([rim, emissive, normal]);
+    expect(ordered.map((modifier) => modifier.slot)).toEqual(['Normal', 'Emissive', 'Effect']);
+  });
+
+  it('is independent of cross-slot authoring order', () => {
+    const a = orderModifierStack([normal, emissive, rim]);
+    const b = orderModifierStack([rim, normal, emissive]);
+    expect(a).toEqual(b);
+  });
+
+  it('preserves authoring order within one slot', () => {
+    const rimA = createRimModifier({ color: 0x111111ff });
+    const rimB = createRimModifier({ color: 0x222222ff });
+    const ordered = orderModifierStack([rimB, rimA]);
+    expect(ordered).toEqual([rimB, rimA]);
+  });
+
+  it('sorts unknown and reserved slots after every built-in slot, stably', () => {
+    const ambient: Modifier = { kind: 'acme.Ambient', slot: 'Ambient' };
+    const vendor: Modifier = { kind: 'acme.Custom', slot: 'acme.Weird' };
+    const ordered = orderModifierStack([ambient, rim, vendor, normal]);
+    expect(ordered).toEqual([normal, rim, ambient, vendor]);
+  });
+
+  it('does not mutate the input stack', () => {
+    const input = [rim, normal];
+    orderModifierStack(input);
+    expect(input).toEqual([rim, normal]);
+  });
+
+  it('returns an empty array for an empty stack', () => {
+    expect(orderModifierStack([])).toEqual([]);
+  });
+});

package/src/registerBuiltInModifiers.test.ts

@@ -0,0 +1,118 @@
+import type { Texture } from '@flighthq/types';
+import {
+  AnimatedNormalModifierKind,
+  DissolveModifierKind,
+  EmissiveModifierFacing,
+  EmissiveModifierKind,
+  EnvReflectModifierKind,
+  FogModifierKind,
+  FogModifierMode,
+  ModifierSlot,
+  RimModifierKind,
+  ToonModifierKind,
+  VertexDisplaceModifierKind,
+  VertexDisplaceModifierSource,
+} from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createAnimatedNormalModifier } from './createAnimatedNormalModifier';
+import { createDissolveModifier } from './createDissolveModifier';
+import { createEmissiveModifier } from './createEmissiveModifier';
+import { createFogModifier } from './createFogModifier';
+import { createVertexDisplaceModifier } from './createVertexDisplaceModifier';
+import { createModifierRegistry, resolveModifier } from './modifierRegistry';
+import { registerBuiltInModifiers } from './registerBuiltInModifiers';
+
+describe('registerBuiltInModifiers', () => {
+  it('registers all eight built-in kinds against their slots', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    expect(resolveModifier(registry, EmissiveModifierKind)?.slot).toBe(ModifierSlot.Emissive);
+    expect(resolveModifier(registry, RimModifierKind)?.slot).toBe(ModifierSlot.Effect);
+    expect(resolveModifier(registry, AnimatedNormalModifierKind)?.slot).toBe(ModifierSlot.Normal);
+    expect(resolveModifier(registry, EnvReflectModifierKind)?.slot).toBe(ModifierSlot.Effect);
+    expect(resolveModifier(registry, FogModifierKind)?.slot).toBe(ModifierSlot.Effect);
+    expect(resolveModifier(registry, DissolveModifierKind)?.slot).toBe(ModifierSlot.Effect);
+    expect(resolveModifier(registry, ToonModifierKind)?.slot).toBe(ModifierSlot.Effect);
+    expect(resolveModifier(registry, VertexDisplaceModifierKind)?.slot).toBe(ModifierSlot.Vertex);
+  });
+
+  it('gives EnvReflect and Toon no signature (single program shapes)', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    expect(resolveModifier(registry, EnvReflectModifierKind)?.getDefineSignature).toBeUndefined();
+    expect(resolveModifier(registry, ToonModifierKind)?.getDefineSignature).toBeUndefined();
+  });
+
+  it('signals fog mode structurally', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const sign = resolveModifier(registry, FogModifierKind)?.getDefineSignature;
+    expect(sign?.(createFogModifier({ color: 0xffffffff }))).toBe('l');
+    expect(sign?.(createFogModifier({ color: 0xffffffff, mode: FogModifierMode.Exponential }))).toBe('e');
+    expect(sign?.(createFogModifier({ color: 0xffffffff, mode: FogModifierMode.Exponential2 }))).toBe('x');
+  });
+
+  it('signals dissolve mask presence structurally', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const sign = resolveModifier(registry, DissolveModifierKind)?.getDefineSignature;
+    expect(sign?.(createDissolveModifier({ threshold: 0.5 }))).toBe('');
+    expect(sign?.(createDissolveModifier({ threshold: 0.5, map: {} as Texture }))).toBe('m');
+  });
+
+  it('signals vertex-displace source and fixed axis structurally', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const sign = resolveModifier(registry, VertexDisplaceModifierKind)?.getDefineSignature;
+    expect(sign?.(createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.Sine, amplitude: 1 }))).toBe('s');
+    expect(sign?.(createVertexDisplaceModifier({ source: VertexDisplaceModifierSource.HeightMap, amplitude: 1 }))).toBe(
+      'h',
+    );
+    expect(
+      sign?.(
+        createVertexDisplaceModifier({
+          source: VertexDisplaceModifierSource.Sine,
+          amplitude: 1,
+          axis: { x: 0, y: 1, z: 0 },
+        }),
+      ),
+    ).toBe('sa');
+  });
+
+  it('gives Rim no signature (a single program shape)', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    expect(resolveModifier(registry, RimModifierKind)?.getDefineSignature).toBeUndefined();
+  });
+
+  it('signals emissive mask and facing gate structurally', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const sign = resolveModifier(registry, EmissiveModifierKind)?.getDefineSignature;
+    expect(sign?.(createEmissiveModifier({ color: 0xffffffff }))).toBe('');
+    expect(sign?.(createEmissiveModifier({ color: 0xffffffff, mask: {} as Texture }))).toBe('m');
+    expect(sign?.(createEmissiveModifier({ color: 0xffffffff, facing: EmissiveModifierFacing.AwayFromLight }))).toBe(
+      'g',
+    );
+  });
+
+  it('signals animated-normal layer count structurally', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    const sign = resolveModifier(registry, AnimatedNormalModifierKind)?.getDefineSignature;
+    expect(sign?.(createAnimatedNormalModifier({ map: null, scroll: { x: 0, y: 0 } }))).toBe('0');
+    expect(sign?.(createAnimatedNormalModifier({ map: {} as Texture, scroll: { x: 0, y: 0 } }))).toBe('1');
+    expect(
+      sign?.(createAnimatedNormalModifier({ map: {} as Texture, scroll: { x: 0, y: 0 }, secondaryMap: {} as Texture })),
+    ).toBe('2');
+  });
+
+  it('is last-write-wins, reinstalling built-ins over an override', () => {
+    const registry = createModifierRegistry();
+    registerBuiltInModifiers(registry);
+    registry.definitions.set(RimModifierKind, { kind: RimModifierKind, slot: 'Normal' });
+    registerBuiltInModifiers(registry);
+    expect(resolveModifier(registry, RimModifierKind)?.slot).toBe(ModifierSlot.Effect);
+  });
+});