@flighthq/materials 0.1.0

package/dist/surfaceMaterial.js

@@ -0,0 +1,41 @@
+import { BlendMode } from '@flighthq/types';
+import { createMaterial } from './material';
+// Builds a SurfaceMaterial carrying `kind` and the shared trailer at its defaults: opaque,
+// single-sided, straight alpha, Normal blend, a 0.5 mask cutoff. Every 3D material constructor
+// starts from this and adds its own maps and scalars. The result is a plain entity; callers
+// mutate the returned object to set their fields before returning it.
+export function createSurfaceMaterial(kind) {
+    const material = createMaterial(kind);
+    material.alphaCutoff = DEFAULT_ALPHA_CUTOFF;
+    material.alphaMode = DEFAULT_ALPHA_MODE;
+    material.alphaType = DEFAULT_ALPHA_TYPE;
+    material.blendMode = BlendMode.Normal;
+    material.doubleSided = DEFAULT_DOUBLE_SIDED;
+    return material;
+}
+// Returns the alpha mode of the material. The alpha mode controls how a material resolves
+// coverage: 'opaque' ignores base-color alpha, 'mask' hard-cuts at `alphaCutoff`, 'blend'
+// alpha-blends. Callers typically branch on this to configure blend state.
+export function getMaterialAlphaMode(source) {
+    return source.alphaMode;
+}
+// Returns true when the material's alpha mode is 'blend'. Blended materials require a
+// sorted draw order and a GPU blend equation.
+export function isMaterialBlended(source) {
+    return source.alphaMode === 'blend';
+}
+// Returns true when the material's alpha mode is 'mask'. Masked materials discard fragments
+// whose alpha is below `alphaCutoff`; no blend state is required.
+export function isMaterialMasked(source) {
+    return source.alphaMode === 'mask';
+}
+// Returns true when the material's alpha mode is 'opaque'. Opaque materials ignore the
+// base-color alpha channel; no blend state or discard is required.
+export function isMaterialOpaque(source) {
+    return source.alphaMode === 'opaque';
+}
+const DEFAULT_ALPHA_CUTOFF = 0.5;
+const DEFAULT_ALPHA_MODE = 'opaque';
+const DEFAULT_ALPHA_TYPE = 'straight';
+const DEFAULT_DOUBLE_SIDED = false;
+//# sourceMappingURL=surfaceMaterial.js.map

package/dist/surfaceMaterial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceMaterial.js","sourceRoot":"","sources":["../src/surfaceMaterial.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,2FAA2F;AAC3F,+FAA+F;AAC/F,4FAA4F;AAC5F,sEAAsE;AACtE,MAAM,UAAU,qBAAqB,CAAC,IAAU;IAC9C,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAoB,CAAC;IACzD,QAAQ,CAAC,WAAW,GAAG,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,SAAS,GAAG,kBAAkB,CAAC;IACxC,QAAQ,CAAC,SAAS,GAAG,kBAAkB,CAAC;IACxC,QAAQ,CAAC,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC;IACtC,QAAQ,CAAC,WAAW,GAAG,oBAAoB,CAAC;IAC5C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,0FAA0F;AAC1F,0FAA0F;AAC1F,2EAA2E;AAC3E,MAAM,UAAU,oBAAoB,CAAC,MAAiC;IACpE,OAAO,MAAM,CAAC,SAAS,CAAC;AAC1B,CAAC;AAED,sFAAsF;AACtF,8CAA8C;AAC9C,MAAM,UAAU,iBAAiB,CAAC,MAAiC;IACjE,OAAO,MAAM,CAAC,SAAS,KAAK,OAAO,CAAC;AACtC,CAAC;AAED,4FAA4F;AAC5F,kEAAkE;AAClE,MAAM,UAAU,gBAAgB,CAAC,MAAiC;IAChE,OAAO,MAAM,CAAC,SAAS,KAAK,MAAM,CAAC;AACrC,CAAC;AAED,uFAAuF;AACvF,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,MAAiC;IAChE,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC;AACvC,CAAC;AAED,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,kBAAkB,GAAsB,QAAQ,CAAC;AACvD,MAAM,kBAAkB,GAAc,UAAU,CAAC;AACjD,MAAM,oBAAoB,GAAG,KAAK,CAAC"}

package/dist/unlitMaterials.d.ts

@@ -0,0 +1,10 @@
+import type { DepthMaterial, EmissiveMaterial, MatcapMaterial, NormalMaterial, ToonMaterial, UnlitMaterial, VertexColorMaterial, WireframeMaterial } from '@flighthq/types';
+export declare function createDepthMaterial(opts?: Readonly<Partial<DepthMaterial>>): DepthMaterial;
+export declare function createEmissiveMaterial(opts?: Readonly<Partial<EmissiveMaterial>>): EmissiveMaterial;
+export declare function createMatcapMaterial(opts?: Readonly<Partial<MatcapMaterial>>): MatcapMaterial;
+export declare function createNormalMaterial(opts?: Readonly<Partial<NormalMaterial>>): NormalMaterial;
+export declare function createToonMaterial(opts?: Readonly<Partial<ToonMaterial>>): ToonMaterial;
+export declare function createUnlitMaterial(opts?: Readonly<Partial<UnlitMaterial>>): UnlitMaterial;
+export declare function createVertexColorMaterial(opts?: Readonly<Partial<VertexColorMaterial>>): VertexColorMaterial;
+export declare function createWireframeMaterial(opts?: Readonly<Partial<WireframeMaterial>>): WireframeMaterial;
+//# sourceMappingURL=unlitMaterials.d.ts.map

package/dist/unlitMaterials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlitMaterials.d.ts","sourceRoot":"","sources":["../src/unlitMaterials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAgBzB,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,aAAa,CAK1F;AAID,wBAAgB,sBAAsB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,GAAG,gBAAgB,CAMnG;AAID,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG,cAAc,CAK7F;AAGD,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG,cAAc,CAK7F;AAID,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,YAAY,CAOvF;AAID,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,aAAa,CAK1F;AAGD,wBAAgB,yBAAyB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAAG,mBAAmB,CAI5G;AAGD,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,GAAG,iBAAiB,CAKtG"}

package/dist/unlitMaterials.js

@@ -0,0 +1,66 @@
+import { DepthMaterialKind, EmissiveMaterialKind, MatcapMaterialKind, NormalMaterialKind, ToonMaterialKind, UnlitMaterialKind, VertexColorMaterialKind, WireframeMaterialKind, } from '@flighthq/types';
+import { createSurfaceMaterial } from './surfaceMaterial';
+// Depth-output pass material. `near`/`far` default to a unit range; the depth pass overrides
+// them with the camera's range when used as pass infrastructure.
+export function createDepthMaterial(opts) {
+    const material = createSurfaceMaterial(DepthMaterialKind);
+    material.far = opts?.far ?? 1;
+    material.near = opts?.near ?? 0;
+    return material;
+}
+// Self-illuminating, lighting-independent material. `emissive` defaults to white,
+// `emissiveStrength` to 1 (> 1 drives bloom on GPU backends), the map to null.
+export function createEmissiveMaterial(opts) {
+    const material = createSurfaceMaterial(EmissiveMaterialKind);
+    material.emissive = opts?.emissive ?? 0xffffffff;
+    material.emissiveMap = opts?.emissiveMap ?? null;
+    material.emissiveStrength = opts?.emissiveStrength ?? 1;
+    return material;
+}
+// Material-capture (matcap) material: a prebaked lit sphere sampled by the view-space normal.
+// `matcap` defaults to null, `tint` to white. Lighting-independent.
+export function createMatcapMaterial(opts) {
+    const material = createSurfaceMaterial(MatcapMaterialKind);
+    material.matcap = opts?.matcap ?? null;
+    material.tint = opts?.tint ?? 0xffffffff;
+    return material;
+}
+// Normal-output pass material. `normalMap` defaults to null, `normalScale` to 1.
+export function createNormalMaterial(opts) {
+    const material = createSurfaceMaterial(NormalMaterialKind);
+    material.normalMap = opts?.normalMap ?? null;
+    material.normalScale = opts?.normalScale ?? 1;
+    return material;
+}
+// Cel-shaded material: diffuse N·L quantized through a 1D ramp into stepped bands. `baseColor`
+// defaults to white, maps to null, `steps` to 3 (the band count used when no ramp is bound).
+export function createToonMaterial(opts) {
+    const material = createSurfaceMaterial(ToonMaterialKind);
+    material.baseColor = opts?.baseColor ?? 0xffffffff;
+    material.baseColorMap = opts?.baseColorMap ?? null;
+    material.ramp = opts?.ramp ?? null;
+    material.steps = opts?.steps ?? 3;
+    return material;
+}
+// Lighting-independent flat-color material. `baseColor` defaults to white, `baseColorMap` to
+// null. Full fidelity on every backend including Canvas2D.
+export function createUnlitMaterial(opts) {
+    const material = createSurfaceMaterial(UnlitMaterialKind);
+    material.baseColor = opts?.baseColor ?? 0xffffffff;
+    material.baseColorMap = opts?.baseColorMap ?? null;
+    return material;
+}
+// Uses the mesh's `color0` vertex attribute as unlit surface color. `tint` defaults to white.
+export function createVertexColorMaterial(opts) {
+    const material = createSurfaceMaterial(VertexColorMaterialKind);
+    material.tint = opts?.tint ?? 0xffffffff;
+    return material;
+}
+// Edge-only debug material. `color` defaults to white, `thickness` to 1 pixel. No maps.
+export function createWireframeMaterial(opts) {
+    const material = createSurfaceMaterial(WireframeMaterialKind);
+    material.color = opts?.color ?? 0xffffffff;
+    material.thickness = opts?.thickness ?? 1;
+    return material;
+}
+//# sourceMappingURL=unlitMaterials.js.map

package/dist/unlitMaterials.js.map

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

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/materials",
+  "version": "0.1.0",
+  "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.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Color transform and material utilities",
+  "sideEffects": false
+}

package/src/classicMaterials.test.ts

@@ -0,0 +1,48 @@
+import { BlinnPhongMaterialKind, LambertMaterialKind, PhongMaterialKind } from '@flighthq/types';
+
+import { createBlinnPhongMaterial, createLambertMaterial, createPhongMaterial } from './classicMaterials';
+
+describe('createBlinnPhongMaterial', () => {
+  it('creates a white Blinn-Phong material with a shininess of 32', () => {
+    const material = createBlinnPhongMaterial();
+    expect(material.kind).toBe(BlinnPhongMaterialKind);
+    expect(material.diffuse).toBe(0xffffffff);
+    expect(material.specular).toBe(0xffffffff);
+    expect(material.shininess).toBe(32);
+    expect(material.normalMap).toBeNull();
+  });
+
+  it('applies overrides', () => {
+    expect(createBlinnPhongMaterial({ shininess: 8 }).shininess).toBe(8);
+  });
+});
+
+describe('createLambertMaterial', () => {
+  it('creates a white diffuse material with no emission', () => {
+    const material = createLambertMaterial();
+    expect(material.kind).toBe(LambertMaterialKind);
+    expect(material.diffuse).toBe(0xffffffff);
+    expect(material.emissive).toBe(0x000000ff);
+    expect(material.diffuseMap).toBeNull();
+    expect(material.emissiveMap).toBeNull();
+  });
+
+  it('applies overrides', () => {
+    expect(createLambertMaterial({ diffuse: 0xff0000ff }).diffuse).toBe(0xff0000ff);
+  });
+});
+
+describe('createPhongMaterial', () => {
+  it('creates a white Phong material with a shininess of 32', () => {
+    const material = createPhongMaterial();
+    expect(material.kind).toBe(PhongMaterialKind);
+    expect(material.diffuse).toBe(0xffffffff);
+    expect(material.specular).toBe(0xffffffff);
+    expect(material.shininess).toBe(32);
+    expect(material.normalScale).toBe(1);
+  });
+
+  it('applies overrides', () => {
+    expect(createPhongMaterial({ specular: 0x808080ff }).specular).toBe(0x808080ff);
+  });
+});

package/src/color.test.ts

@@ -0,0 +1,383 @@
+import {
+  computeRgbHexString,
+  createHslColor,
+  createHsvColor,
+  createLinearColor,
+  getColorContrastRatio,
+  getColorLuminance,
+  hslToRgb,
+  hsvToRgb,
+  lerpColor,
+  lerpLinearColor,
+  linearChannelToSrgb,
+  packColor,
+  packLinearToColor,
+  premultiplyColorAlpha,
+  rgbToHsl,
+  rgbToHsv,
+  unpackColorRgba,
+  unpackColorToLinear,
+  unpremultiplyColorAlpha,
+} from './color';
+
+describe('computeRgbHexString', () => {
+  it('returns a 6-digit hex string of the lower 24 bits', () => {
+    expect(computeRgbHexString(0x00ff0000)).toBe('#ff0000');
+    expect(computeRgbHexString(0x0000ff00)).toBe('#00ff00');
+    expect(computeRgbHexString(0x000000ff)).toBe('#0000ff');
+    expect(computeRgbHexString(0x00000000)).toBe('#000000');
+    expect(computeRgbHexString(0x00ffffff)).toBe('#ffffff');
+  });
+});
+
+describe('createHslColor', () => {
+  it('allocates a zeroed three-component HSL color', () => {
+    expect(createHslColor()).toEqual([0, 0, 0]);
+  });
+});
+
+describe('createHsvColor', () => {
+  it('allocates a zeroed three-component HSV color', () => {
+    expect(createHsvColor()).toEqual([0, 0, 0]);
+  });
+});
+
+describe('createLinearColor', () => {
+  it('allocates a zeroed four-component color', () => {
+    expect(createLinearColor()).toEqual([0, 0, 0, 0]);
+  });
+});
+
+describe('getColorContrastRatio', () => {
+  it('returns 21 for black on white', () => {
+    expect(getColorContrastRatio(0xffffffff, 0x000000ff)).toBeCloseTo(21, 0);
+  });
+  it('returns 1 for identical colors', () => {
+    expect(getColorContrastRatio(0x808080ff, 0x808080ff)).toBeCloseTo(1, 3);
+  });
+  it('is symmetric — order of arguments does not matter', () => {
+    const ratio1 = getColorContrastRatio(0xffffffff, 0x808080ff);
+    const ratio2 = getColorContrastRatio(0x808080ff, 0xffffffff);
+    expect(ratio1).toBeCloseTo(ratio2, 8);
+  });
+});
+
+describe('getColorLuminance', () => {
+  it('returns 1 for white', () => {
+    expect(getColorLuminance(0xffffffff)).toBeCloseTo(1, 5);
+  });
+  it('returns 0 for black', () => {
+    expect(getColorLuminance(0x000000ff)).toBeCloseTo(0, 5);
+  });
+  it('ignores the alpha channel', () => {
+    expect(getColorLuminance(0xffffffff)).toBe(getColorLuminance(0xffffff00));
+  });
+  it('matches expected Rec. 709 value for mid-gray sRGB', () => {
+    // sRGB 0x808080 → linear ≈ 0.21586; Rec.709: 0.2126*R + 0.7152*G + 0.0722*B = R (equal channels)
+    expect(getColorLuminance(0x808080ff)).toBeCloseTo(0.21586, 4);
+  });
+});
+
+describe('hslToRgb', () => {
+  it('produces achromatic RGB for saturation = 0', () => {
+    const out: [number, number, number, number] = [0, 0, 0, 1];
+    hslToRgb(out, 0, 0, 0.5);
+    expect(out[0]).toBeCloseTo(0.5);
+    expect(out[1]).toBeCloseTo(0.5);
+    expect(out[2]).toBeCloseTo(0.5);
+  });
+  it('round-trips with rgbToHsl for a primary color', () => {
+    // Red: hue=0, s=1, l=0.5 → RGB (1, 0, 0)
+    const out: [number, number, number, number] = [0, 0, 0, 1];
+    hslToRgb(out, 0, 1, 0.5);
+    expect(out[0]).toBeCloseTo(1, 5);
+    expect(out[1]).toBeCloseTo(0, 5);
+    expect(out[2]).toBeCloseTo(0, 5);
+  });
+  it('does not modify out[3] (alpha)', () => {
+    const out: [number, number, number, number] = [0, 0, 0, 0.75];
+    hslToRgb(out, 120, 1, 0.5);
+    expect(out[3]).toBe(0.75);
+  });
+});
+
+describe('hsvToRgb', () => {
+  it('produces achromatic RGB for saturation = 0', () => {
+    const out: [number, number, number, number] = [0, 0, 0, 1];
+    hsvToRgb(out, 0, 0, 0.6);
+    expect(out[0]).toBeCloseTo(0.6);
+    expect(out[1]).toBeCloseTo(0.6);
+    expect(out[2]).toBeCloseTo(0.6);
+  });
+  it('produces pure red for h=0, s=1, v=1', () => {
+    const out: [number, number, number, number] = [0, 0, 0, 1];
+    hsvToRgb(out, 0, 1, 1);
+    expect(out[0]).toBeCloseTo(1, 5);
+    expect(out[1]).toBeCloseTo(0, 5);
+    expect(out[2]).toBeCloseTo(0, 5);
+  });
+  it('round-trips with rgbToHsv for a pure green', () => {
+    const out: [number, number, number, number] = [0, 0, 0, 1];
+    hsvToRgb(out, 120, 1, 1);
+    expect(out[0]).toBeCloseTo(0, 5);
+    expect(out[1]).toBeCloseTo(1, 5);
+    expect(out[2]).toBeCloseTo(0, 5);
+  });
+});
+
+describe('lerpColor', () => {
+  it('returns start at t=0', () => {
+    expect(lerpColor(0xff0000ff, 0x0000ffff, 0)).toBe(0xff0000ff);
+  });
+  it('returns end at t=1', () => {
+    expect(lerpColor(0xff0000ff, 0x0000ffff, 1)).toBe(0x0000ffff);
+  });
+  it('clamps t below 0 to 0', () => {
+    expect(lerpColor(0xff0000ff, 0x0000ffff, -1)).toBe(0xff0000ff);
+  });
+  it('clamps t above 1 to 1', () => {
+    expect(lerpColor(0xff0000ff, 0x0000ffff, 2)).toBe(0x0000ffff);
+  });
+  it('midpoint between black and white is approximately mid-gray', () => {
+    // Black (linear 0) and white (linear 1) — midpoint in linear is 0.5, which in sRGB ≈ 0xbc
+    const mid = lerpColor(0x000000ff, 0xffffffff, 0.5);
+    const r = (mid >>> 24) & 0xff;
+    // linear 0.5 → sRGB ≈ 0xbc (188)
+    expect(r).toBeCloseTo(0xbc, -1);
+  });
+});
+
+describe('lerpLinearColor', () => {
+  it('returns start at t=0', () => {
+    const out = createLinearColor();
+    const start: [number, number, number, number] = [1, 0, 0, 1];
+    const end: [number, number, number, number] = [0, 0, 1, 1];
+    lerpLinearColor(out, start, end, 0);
+    expect(out).toEqual(start);
+  });
+  it('returns end at t=1', () => {
+    const out = createLinearColor();
+    const start: [number, number, number, number] = [1, 0, 0, 1];
+    const end: [number, number, number, number] = [0, 0, 1, 1];
+    lerpLinearColor(out, start, end, 1);
+    expect(out).toEqual(end);
+  });
+  it('is alias-safe when out is the same object as start', () => {
+    const start: [number, number, number, number] = [1, 0, 0, 1];
+    const end: [number, number, number, number] = [0, 0, 1, 1];
+    const out = start;
+    lerpLinearColor(out, out, end, 0.5);
+    expect(out[0]).toBeCloseTo(0.5, 8);
+    expect(out[2]).toBeCloseTo(0.5, 8);
+  });
+  it('returns the out instance', () => {
+    const out = createLinearColor();
+    const start: [number, number, number, number] = [0, 0, 0, 0];
+    const end: [number, number, number, number] = [1, 1, 1, 1];
+    expect(lerpLinearColor(out, start, end, 0.5)).toBe(out);
+  });
+});
+
+describe('linearChannelToSrgb', () => {
+  it('maps 0 → 0', () => {
+    expect(linearChannelToSrgb(0)).toBe(0);
+  });
+  it('maps 1 → 1', () => {
+    expect(linearChannelToSrgb(1)).toBeCloseTo(1, 8);
+  });
+  it('is the inverse of the sRGB decode for a round-trip', () => {
+    // A known linear value near the breakpoint.
+    const linear = 0.5;
+    const srgb = linearChannelToSrgb(linear);
+    // Re-encode: sRGB(linear(x)) should round-trip within floating-point tolerance.
+    const roundTrip = srgb <= 0.04045 ? srgb / 12.92 : ((srgb + 0.055) / 1.055) ** 2.4;
+    expect(roundTrip).toBeCloseTo(linear, 5);
+  });
+});
+
+describe('packColor', () => {
+  it('packs white components to 0xffffffff', () => {
+    expect(packColor(1, 1, 1, 1)).toBe(0xffffffff);
+  });
+  it('packs black components to 0x000000ff', () => {
+    expect(packColor(0, 0, 0, 1)).toBe(0x000000ff);
+  });
+  it('clamps out-of-range values', () => {
+    expect(packColor(2, -1, 0.5, 1)).toBe(packColor(1, 0, 0.5, 1));
+  });
+});
+
+describe('packLinearToColor', () => {
+  it('is the inverse of unpackColorToLinear for white', () => {
+    const out = createLinearColor();
+    unpackColorToLinear(out, 0xffffffff);
+    expect(packLinearToColor(out)).toBe(0xffffffff);
+  });
+  it('is the inverse of unpackColorToLinear for black (opaque)', () => {
+    const out = createLinearColor();
+    unpackColorToLinear(out, 0x000000ff);
+    expect(packLinearToColor(out)).toBe(0x000000ff);
+  });
+  it('passes alpha through without gamma encoding', () => {
+    // Alpha 0x80 / 0xff ≈ 0.502; should round-trip through linear-space alpha.
+    const color = 0x000000_80 >>> 0;
+    const out = createLinearColor();
+    unpackColorToLinear(out, color);
+    const repacked = packLinearToColor(out);
+    expect(repacked & 0xff).toBe(0x80);
+  });
+  it('round-trips a mid-gray color within 1 LSB', () => {
+    const color = 0x808080ff >>> 0;
+    const out = createLinearColor();
+    unpackColorToLinear(out, color);
+    const repacked = packLinearToColor(out);
+    const origR = (color >>> 24) & 0xff;
+    const repR = (repacked >>> 24) & 0xff;
+    expect(Math.abs(repR - origR)).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('premultiplyColorAlpha', () => {
+  it('returns fully-opaque color unchanged (alpha=1)', () => {
+    expect(premultiplyColorAlpha(0xff0000ff)).toBe(0xff0000ff);
+  });
+  it('multiplies RGB by alpha and preserves the alpha channel', () => {
+    // Red at 50% alpha: R=255*0.502≈128, A unchanged=0x80
+    const result = premultiplyColorAlpha(0xff00007f);
+    expect((result >>> 24) & 0xff).toBeCloseTo(0x7f, -1);
+    expect(result & 0xff).toBe(0x7f);
+  });
+  it('returns black-with-alpha-0 for fully transparent color', () => {
+    const result = premultiplyColorAlpha(0xff000000);
+    expect(result & 0xff).toBe(0);
+    expect((result >>> 24) & 0xff).toBe(0);
+  });
+  it('round-trips with unpremultiplyColorAlpha for fully-opaque', () => {
+    const color = 0xab3456ff;
+    expect(unpremultiplyColorAlpha(premultiplyColorAlpha(color))).toBe(color);
+  });
+});
+
+describe('rgbToHsl', () => {
+  it('converts pure red to hue=0, s=1, l=0.5', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    rgbToHsl(out, 0xff0000ff);
+    expect(out[0]).toBeCloseTo(0, 3);
+    expect(out[1]).toBeCloseTo(1, 5);
+    expect(out[2]).toBeCloseTo(0.5, 5);
+  });
+  it('converts white to hue=0, s=0, l=1', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    rgbToHsl(out, 0xffffffff);
+    expect(out[0]).toBe(0);
+    expect(out[1]).toBe(0);
+    expect(out[2]).toBeCloseTo(1, 5);
+  });
+  it('converts black to hue=0, s=0, l=0', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    rgbToHsl(out, 0x000000ff);
+    expect(out[0]).toBe(0);
+    expect(out[1]).toBe(0);
+    expect(out[2]).toBeCloseTo(0, 5);
+  });
+  it('returns the out instance', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    expect(rgbToHsl(out, 0xff0000ff)).toBe(out);
+  });
+  it('round-trips with hslToRgb within 1 LSB', () => {
+    const hsl: [number, number, number] = [0, 0, 0];
+    rgbToHsl(hsl, 0x3c8ab5ff);
+    const rgb: [number, number, number, number] = [0, 0, 0, 1];
+    hslToRgb(rgb, hsl[0], hsl[1], hsl[2]);
+    const repacked =
+      (Math.round(rgb[0] * 0xff) << 24) | (Math.round(rgb[1] * 0xff) << 16) | (Math.round(rgb[2] * 0xff) << 8) | 0xff;
+    const orig = 0x3c8ab5ff >>> 0;
+    expect(Math.abs(((repacked >>> 24) & 0xff) - ((orig >>> 24) & 0xff))).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('rgbToHsv', () => {
+  it('converts pure red to hue=0, s=1, v=1', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    rgbToHsv(out, 0xff0000ff);
+    expect(out[0]).toBeCloseTo(0, 3);
+    expect(out[1]).toBeCloseTo(1, 5);
+    expect(out[2]).toBeCloseTo(1, 5);
+  });
+  it('converts black to s=0, v=0', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    rgbToHsv(out, 0x000000ff);
+    expect(out[1]).toBe(0);
+    expect(out[2]).toBeCloseTo(0, 5);
+  });
+  it('converts white to s=0, v=1', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    rgbToHsv(out, 0xffffffff);
+    expect(out[1]).toBe(0);
+    expect(out[2]).toBeCloseTo(1, 5);
+  });
+  it('returns the out instance', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    expect(rgbToHsv(out, 0xff0000ff)).toBe(out);
+  });
+});
+
+describe('unpackColorRgba', () => {
+  it('extracts white as all-ones', () => {
+    const out: [number, number, number, number] = [0, 0, 0, 0];
+    unpackColorRgba(out, 0xffffffff);
+    expect(out[0]).toBeCloseTo(1, 5);
+    expect(out[1]).toBeCloseTo(1, 5);
+    expect(out[2]).toBeCloseTo(1, 5);
+    expect(out[3]).toBeCloseTo(1, 5);
+  });
+  it('does NOT gamma-decode — mid sRGB stays above the linear midpoint', () => {
+    const out: [number, number, number, number] = [0, 0, 0, 0];
+    unpackColorRgba(out, 0x808080ff);
+    // Without gamma decode, 0x80/0xff ≈ 0.502 — above the linear midpoint.
+    expect(out[0]).toBeCloseTo(0x80 / 0xff, 4);
+  });
+});
+
+describe('unpackColorToLinear', () => {
+  it('decodes white and black exactly at the endpoints', () => {
+    const out = createLinearColor();
+    expect(unpackColorToLinear(out, 0xffffffff)).toEqual([1, 1, 1, 1]);
+    expect(unpackColorToLinear(out, 0x000000ff)).toEqual([0, 0, 0, 1]);
+  });
+
+  it('passes alpha through linearly without gamma decode', () => {
+    const out = createLinearColor();
+    unpackColorToLinear(out, 0x00000080);
+    expect(out[3]).toBeCloseTo(0x80 / 0xff, 6);
+  });
+
+  it('gamma-decodes RGB so mid sRgb is below the linear midpoint', () => {
+    const out = createLinearColor();
+    unpackColorToLinear(out, 0x808080ff);
+    expect(out[0]).toBeCloseTo(0.21586, 4);
+    expect(out[0]).toBe(out[1]);
+    expect(out[1]).toBe(out[2]);
+  });
+
+  it('returns the same out instance it was given', () => {
+    const out = createLinearColor();
+    expect(unpackColorToLinear(out, 0xff0000ff)).toBe(out);
+  });
+});
+
+describe('unpremultiplyColorAlpha', () => {
+  it('returns fully-opaque color unchanged', () => {
+    expect(unpremultiplyColorAlpha(0xff0000ff)).toBe(0xff0000ff);
+  });
+  it('divides RGB by alpha and preserves the alpha channel', () => {
+    // Premultiplied: R=128 (≈0x80), A=0x80 → straight: R ≈ 255
+    const premul = premultiplyColorAlpha((0xff0000ff & (0xffffff80 >>> 0)) | 0x80);
+    const result = unpremultiplyColorAlpha(premul);
+    expect(result & 0xff).toBe(0x80);
+  });
+  it('returns the input unchanged for alpha=0', () => {
+    const color = 0xff000000;
+    expect(unpremultiplyColorAlpha(color)).toBe(color);
+  });
+});