@ankhorage/zora 0.12.0 → 0.12.2

package/src/internal/color/harmony.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraHexColor } from '../../theme/types';
+import { normalizeHueDegrees } from './hue';
+import {
+  computeZoraHarmony,
+  parseHexToOklch,
+  type ZoraComputedHarmony,
+  type ZoraHarmonySlot,
+  type ZoraHarmonySlotId,
+} from './index';
+
+function hueDeltaDegrees(a: number, b: number): number {
+  const raw = Math.abs(a - b) % 360;
+  return Math.min(raw, 360 - raw);
+}
+
+function expectNormalizedHue(hue: number) {
+  expect(hue).toBeGreaterThanOrEqual(0);
+  expect(hue).toBeLessThan(360);
+}
+
+function getSlotIds(slots: readonly ZoraHarmonySlot[]): ZoraHarmonySlotId[] {
+  return slots.map((slot) => slot.id);
+}
+
+describe('computeZoraHarmony', () => {
+  test('monochromatic returns 1 slot', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'monochromatic');
+
+    expect(harmony.orderedSlots).toHaveLength(1);
+    expect(harmony.orderedSlots[0].id).toBe('base');
+  });
+
+  test('complementary returns 2 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'complementary');
+
+    expect(harmony.orderedSlots).toHaveLength(2);
+    expect(harmony.orderedSlots[0].id).toBe('base');
+    expect(harmony.orderedSlots[1].id).toBe('a');
+  });
+
+  test('analogous returns 3 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'analogous');
+
+    expect(harmony.orderedSlots).toHaveLength(3);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
+  });
+
+  test('splitComplementary returns 3 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'splitComplementary');
+
+    expect(harmony.orderedSlots).toHaveLength(3);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
+  });
+
+  test('triadic returns 3 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'triadic');
+
+    expect(harmony.orderedSlots).toHaveLength(3);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
+  });
+
+  test('tetradic returns 4 slots', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'tetradic');
+
+    expect(harmony.orderedSlots).toHaveLength(4);
+    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b', 'c']);
+  });
+
+  test('every computed hue is normalized to [0, 360)', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const harmonies = [
+      'monochromatic',
+      'complementary',
+      'analogous',
+      'splitComplementary',
+      'triadic',
+      'tetradic',
+    ] as const;
+
+    for (const kind of harmonies) {
+      const computed = computeZoraHarmony(seed, kind);
+      for (const slot of computed.orderedSlots) {
+        expectNormalizedHue(slot.hue);
+      }
+    }
+  });
+
+  test('base slot approximately matches parsed seed hue for a non-neutral seed', () => {
+    const seed: ZoraHexColor = '#ff00ff';
+    const seedOklch = parseHexToOklch(seed);
+
+    const computed = computeZoraHarmony(seed, 'complementary');
+    const [base] = computed.orderedSlots;
+
+    expect(base).toBeDefined();
+    if (!base) {
+      throw new Error('Expected a base harmony slot.');
+    }
+
+    expect(base.id).toBe('base');
+    expect(hueDeltaDegrees(seedOklch.h, base.hue)).toBeLessThan(0.5);
+  });
+
+  test('neutral/low-chroma seed uses a stable fallback hue', () => {
+    const seed: ZoraHexColor = '#808080';
+    const computed = computeZoraHarmony(seed, 'monochromatic');
+
+    expect(computed.orderedSlots).toHaveLength(1);
+    expect(computed.orderedSlots[0].hue).toBe(260);
+  });
+
+  test('is deterministic for the same seed/harmony', () => {
+    const seed: ZoraHexColor = '#0f766e';
+
+    expect(computeZoraHarmony(seed, 'triadic')).toEqual(computeZoraHarmony(seed, 'triadic'));
+  });
+
+  test('complementary slots are based on base hue + 180', () => {
+    const seed: ZoraHexColor = '#0f766e';
+    const computed = computeZoraHarmony(seed, 'complementary');
+    const [base, a] = computed.orderedSlots;
+
+    expect(base).toBeDefined();
+    expect(a).toBeDefined();
+    if (!base || !a) {
+      throw new Error('Expected complementary harmony slots.');
+    }
+
+    expect(hueDeltaDegrees(a.hue, normalizeHueDegrees(base.hue + 180))).toBeLessThan(0.0001);
+  });
+
+  test('throws on invalid seed in test/development', () => {
+    const invalid: ZoraHexColor = '#nope';
+
+    expect(() => computeZoraHarmony(invalid, 'triadic')).toThrow();
+  });
+});

package/src/internal/color/harmony.ts

@@ -0,0 +1,96 @@
+import type { ZoraColorHarmony, ZoraHexColor } from '../../theme/types';
+import { normalizeHueDegrees, rotateHueDegrees } from './hue';
+import { parseHexToOklch } from './oklch';
+
+export type ZoraHarmonySlotId = 'base' | 'a' | 'b' | 'c';
+
+export interface ZoraHarmonySlot {
+  id: ZoraHarmonySlotId;
+  hue: number;
+}
+
+export interface ZoraComputedHarmony {
+  kind: ZoraColorHarmony;
+  orderedSlots: readonly ZoraHarmonySlot[];
+}
+
+const DEFAULT_HARMONY_HUE_DEGREES = 260;
+const MIN_SEED_CHROMA_FOR_HARMONY_HUE = 0.03;
+
+function createSlot(id: ZoraHarmonySlotId, hue: number): ZoraHarmonySlot {
+  return { id, hue: normalizeHueDegrees(hue) };
+}
+
+function resolveSeedHueDegrees(seed: ZoraHexColor): number {
+  const parsed = parseHexToOklch(seed);
+
+  if (!Number.isFinite(parsed.h) || parsed.c < MIN_SEED_CHROMA_FOR_HARMONY_HUE) {
+    return DEFAULT_HARMONY_HUE_DEGREES;
+  }
+
+  return normalizeHueDegrees(parsed.h);
+}
+
+export function computeZoraHarmony(
+  seed: ZoraHexColor,
+  harmony: ZoraColorHarmony,
+): ZoraComputedHarmony {
+  const baseHue = resolveSeedHueDegrees(seed);
+
+  if (harmony === 'monochromatic') {
+    return {
+      kind: harmony,
+      orderedSlots: [createSlot('base', baseHue)],
+    };
+  }
+
+  if (harmony === 'complementary') {
+    return {
+      kind: harmony,
+      orderedSlots: [createSlot('base', baseHue), createSlot('a', rotateHueDegrees(baseHue, 180))],
+    };
+  }
+
+  if (harmony === 'analogous') {
+    return {
+      kind: harmony,
+      orderedSlots: [
+        createSlot('base', baseHue),
+        createSlot('a', rotateHueDegrees(baseHue, -30)),
+        createSlot('b', rotateHueDegrees(baseHue, 30)),
+      ],
+    };
+  }
+
+  if (harmony === 'splitComplementary') {
+    return {
+      kind: harmony,
+      orderedSlots: [
+        createSlot('base', baseHue),
+        createSlot('a', rotateHueDegrees(baseHue, 150)),
+        createSlot('b', rotateHueDegrees(baseHue, 210)),
+      ],
+    };
+  }
+
+  if (harmony === 'triadic') {
+    return {
+      kind: harmony,
+      orderedSlots: [
+        createSlot('base', baseHue),
+        createSlot('a', rotateHueDegrees(baseHue, 120)),
+        createSlot('b', rotateHueDegrees(baseHue, 240)),
+      ],
+    };
+  }
+
+  return {
+    kind: harmony,
+    orderedSlots: [
+      createSlot('base', baseHue),
+      createSlot('a', rotateHueDegrees(baseHue, 90)),
+      createSlot('b', rotateHueDegrees(baseHue, 180)),
+      createSlot('c', rotateHueDegrees(baseHue, 270)),
+    ],
+  };
+}

package/src/internal/color/hue.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'bun:test';
+
+import { normalizeHueDegrees, rotateHueDegrees } from './hue';
+
+describe('normalizeHueDegrees', () => {
+  test('normalizes negative hues into [0, 360)', () => {
+    expect(normalizeHueDegrees(-30)).toBe(330);
+    expect(normalizeHueDegrees(-390)).toBe(330);
+  });
+
+  test('normalizes hues >= 360 into [0, 360)', () => {
+    expect(normalizeHueDegrees(390)).toBe(30);
+    expect(normalizeHueDegrees(720)).toBe(0);
+  });
+
+  test('preserves in-range hues', () => {
+    expect(normalizeHueDegrees(0)).toBe(0);
+    expect(normalizeHueDegrees(12.5)).toBe(12.5);
+    expect(normalizeHueDegrees(359.99)).toBe(359.99);
+  });
+});
+
+describe('rotateHueDegrees', () => {
+  test('rotates and normalizes', () => {
+    expect(rotateHueDegrees(350, 30)).toBe(20);
+    expect(rotateHueDegrees(10, -30)).toBe(340);
+  });
+});

package/src/internal/color/hue.ts

@@ -0,0 +1,7 @@
+export function normalizeHueDegrees(hue: number): number {
+  return ((hue % 360) + 360) % 360;
+}
+
+export function rotateHueDegrees(hue: number, delta: number): number {
+  return normalizeHueDegrees(hue + delta);
+}

package/src/internal/color/index.ts

@@ -1,2 +1,22 @@
+export {
+  computeZoraHarmony,
+  type ZoraComputedHarmony,
+  type ZoraHarmonySlot,
+  type ZoraHarmonySlotId,
+} from './harmony';
 export { parseHexToOklch } from './oklch';
 export { resolveModePrimaryColor } from './primary';
+export {
+  assignZoraHarmonyRoleHues,
+  getZoraHueRoleAssignment,
+  type ZoraComputedHueRoles,
+  type ZoraHueRoleAssignment,
+  type ZoraHueRoleId,
+} from './roleHues';
+export {
+  createZoraColorScale,
+  type CreateZoraColorScaleOptions,
+  createZoraNeutralScale,
+  createZoraPrimaryScale,
+} from './scales';
+export { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';

package/src/internal/color/oklch.ts

@@ -1,16 +1,12 @@
 import { converter, formatHex, parse, toGamut } from 'culori';
 
 import type { ZoraHexColor } from '../../theme/types';
+import { normalizeHueDegrees } from './hue';
 import type { ZoraOklchColor } from './types';
 
 const toOklch = converter('oklch');
 const gamutMapToSrgb = toGamut('rgb', 'oklch');
 
-function normalizeHueDegrees(hue: number): number {
-  const normalized = ((hue % 360) + 360) % 360;
-  return normalized;
-}
-
 function isSixDigitHexColor(value: string): value is ZoraHexColor {
   return /^#[0-9a-fA-F]{6}$/.test(value);
 }

package/src/internal/color/roleHues.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  assignZoraHarmonyRoleHues,
+  getZoraHueRoleAssignment,
+  type ZoraComputedHarmony,
+  type ZoraComputedHueRoles,
+  type ZoraHueRoleAssignment,
+  type ZoraHueRoleId,
+} from './index';
+
+function expectNormalizedHue(hue: number) {
+  expect(Number.isFinite(hue)).toBe(true);
+  expect(hue).toBeGreaterThanOrEqual(0);
+  expect(hue).toBeLessThan(360);
+}
+
+const ROLE_ORDER: readonly ZoraHueRoleId[] = [
+  'primary',
+  'secondary',
+  'accent',
+  'highlight',
+  'surfaceTint',
+];
+
+function expectEveryRoleOnce(roles: ReturnType<typeof assignZoraHarmonyRoleHues>) {
+  expect(roles.assignments).toHaveLength(ROLE_ORDER.length);
+  expect(roles.assignments.map((assignment) => assignment.role)).toEqual(ROLE_ORDER);
+}
+
+describe('assignZoraHarmonyRoleHues', () => {
+  test('monochromatic assigns every role to base', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'monochromatic',
+      orderedSlots: [{ id: 'base', hue: 100 }],
+    };
+
+    const roles: ZoraComputedHueRoles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    for (const assignment of roles.assignments) {
+      expect(assignment.sourceSlotId).toBe('base');
+      expect(assignment.hue).toBe(100);
+      expectNormalizedHue(assignment.hue);
+    }
+  });
+
+  test('complementary assigns accent/highlight to a', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'complementary',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 280 },
+      ],
+    };
+
+    const roles: ZoraComputedHueRoles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    const accent: ZoraHueRoleAssignment = getZoraHueRoleAssignment(roles, 'accent');
+    const highlight: ZoraHueRoleAssignment = getZoraHueRoleAssignment(roles, 'highlight');
+
+    expect(accent.sourceSlotId).toBe('a');
+    expect(highlight.sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'primary').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('base');
+  });
+
+  test('analogous assigns secondary/surfaceTint to a and accent/highlight to b', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'analogous',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 70 },
+        { id: 'b', hue: 130 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'secondary').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('b');
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('b');
+  });
+
+  test('splitComplementary assigns primary/surfaceTint to base and accent/highlight to b', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'splitComplementary',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 250 },
+        { id: 'b', hue: 310 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'primary').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('b');
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('b');
+  });
+
+  test('triadic assigns primary/surfaceTint to base and secondary/accent across a/b', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'triadic',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 220 },
+        { id: 'b', hue: 340 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'primary').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'secondary').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('b');
+  });
+
+  test('tetradic assigns highlight to c', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'tetradic',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 190 },
+        { id: 'b', hue: 280 },
+        { id: 'c', hue: 10 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('c');
+  });
+
+  test('every assignment hue is normalized to [0, 360)', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'complementary',
+      orderedSlots: [
+        { id: 'base', hue: -10 },
+        { id: 'a', hue: 370 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    for (const assignment of roles.assignments) {
+      expectNormalizedHue(assignment.hue);
+    }
+  });
+
+  test('is deterministic for the same computed harmony', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'analogous',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 70 },
+        { id: 'b', hue: 130 },
+      ],
+    };
+
+    expect(assignZoraHarmonyRoleHues(harmony)).toEqual(assignZoraHarmonyRoleHues(harmony));
+  });
+
+  test('falls back when a preferred non-base slot is missing', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'analogous',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 70 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('a');
+  });
+
+  test('throws a clear error when the base slot is missing', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'complementary',
+      orderedSlots: [{ id: 'a', hue: 200 }],
+    };
+
+    expect(() => assignZoraHarmonyRoleHues(harmony)).toThrow('base');
+  });
+});

package/src/internal/color/roleHues.ts

@@ -0,0 +1,142 @@
+import type { ZoraColorHarmony } from '../../theme/types';
+import type { ZoraComputedHarmony, ZoraHarmonySlot, ZoraHarmonySlotId } from './harmony';
+import { normalizeHueDegrees } from './hue';
+
+export type ZoraHueRoleId = 'primary' | 'secondary' | 'accent' | 'highlight' | 'surfaceTint';
+
+export interface ZoraHueRoleAssignment {
+  role: ZoraHueRoleId;
+  hue: number;
+  sourceSlotId: ZoraHarmonySlotId;
+}
+
+export interface ZoraComputedHueRoles {
+  harmony: ZoraColorHarmony;
+  assignments: readonly ZoraHueRoleAssignment[];
+}
+
+function findSlot(
+  harmony: ZoraComputedHarmony,
+  id: ZoraHarmonySlotId,
+): ZoraHarmonySlot | undefined {
+  return harmony.orderedSlots.find((slot) => slot.id === id);
+}
+
+function requireBaseSlot(harmony: ZoraComputedHarmony): ZoraHarmonySlot {
+  const base = findSlot(harmony, 'base');
+  if (!base) {
+    throw new Error(`[zora] Expected harmony to include a base slot (kind: ${harmony.kind}).`);
+  }
+  return base;
+}
+
+function assignRole(
+  role: ZoraHueRoleId,
+  harmony: ZoraComputedHarmony,
+  preferred: ZoraHarmonySlotId,
+  fallback: ZoraHarmonySlotId = 'base',
+): ZoraHueRoleAssignment {
+  const base = requireBaseSlot(harmony);
+  const preferredSlot = findSlot(harmony, preferred);
+  const fallbackSlot = findSlot(harmony, fallback);
+  const chosenSlot = preferredSlot ?? fallbackSlot ?? base;
+
+  return {
+    role,
+    hue: normalizeHueDegrees(chosenSlot.hue),
+    sourceSlotId: chosenSlot.id,
+  };
+}
+
+export function assignZoraHarmonyRoleHues(harmony: ZoraComputedHarmony): ZoraComputedHueRoles {
+  const { kind } = harmony;
+
+  if (kind === 'monochromatic') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'base'),
+        assignRole('accent', harmony, 'base'),
+        assignRole('highlight', harmony, 'base'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  if (kind === 'complementary') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'base'),
+        assignRole('accent', harmony, 'a'),
+        assignRole('highlight', harmony, 'a'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  if (kind === 'analogous') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'a'),
+        assignRole('accent', harmony, 'b', 'a'),
+        assignRole('highlight', harmony, 'b', 'a'),
+        assignRole('surfaceTint', harmony, 'a'),
+      ],
+    };
+  }
+
+  if (kind === 'splitComplementary') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'a'),
+        assignRole('accent', harmony, 'b', 'a'),
+        assignRole('highlight', harmony, 'b', 'a'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  if (kind === 'triadic') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'a'),
+        assignRole('accent', harmony, 'b', 'a'),
+        assignRole('highlight', harmony, 'b', 'a'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  return {
+    harmony: kind,
+    assignments: [
+      assignRole('primary', harmony, 'base'),
+      assignRole('secondary', harmony, 'a'),
+      assignRole('accent', harmony, 'b', 'a'),
+      assignRole('highlight', harmony, 'c', 'b'),
+      assignRole('surfaceTint', harmony, 'base'),
+    ],
+  };
+}
+
+export function getZoraHueRoleAssignment(
+  roles: ZoraComputedHueRoles,
+  role: ZoraHueRoleId,
+): ZoraHueRoleAssignment {
+  const found = roles.assignments.find((assignment) => assignment.role === role);
+  if (!found) {
+    throw new Error(
+      `[zora] Expected a hue-role assignment for "${role}" (harmony: ${roles.harmony}).`,
+    );
+  }
+  return found;
+}