@roobscoob/vibes 0.0.0-stage → 0.2.0

package/src/parse.ts

@@ -0,0 +1,205 @@
+// Colors from text, read as generously as can be: anything CSS takes (hex
+// codes with or without #, names, rgb(), hsl(), hwb(), oklch(), oklab(),
+// lab(), lch(), color()), color temperatures ("2700K", "candlelight"), the
+// lights' own ("lemtone(265 0.3 40)", or "265° C0.30 · 40 lm" as a color
+// prints itself), and any of those with lumens or a fidelity alongside
+// ("#f80 · 120 lm", "2700K @ 400lm").
+//
+// This only reads the text: what it says comes back as a Spec, and color.ts
+// makes the color.
+
+import type { Vec3 } from "./lemtone.ts";
+import { cssNamed, LIGHT_NAMES } from "./names.ts";
+
+/** What some text says a color is. */
+export type Spec = { alpha?: number; lm?: number; fidelity?: number } & (
+  | { space: "off" }
+  | { space: "srgb" | "srgb-linear" | "display-p3"; rgb: Vec3 }
+  | { space: "xyz" | "xyz-d50"; xyz: Vec3 }
+  | { space: "hsl"; h: number; s: number; l: number }
+  | { space: "hwb"; h: number; w: number; b: number }
+  | { space: "oklab" | "lab"; lab: Vec3 }
+  | { space: "oklch" | "lch"; l: number; c: number; h: number }
+  | { space: "kelvin"; kelvin: number }
+  | { space: "lemtone"; hue: number; chroma: number }
+);
+
+type Unit = "" | "%" | "deg" | "rad" | "grad" | "turn";
+interface Token {
+  value: number;
+  unit: Unit;
+}
+
+const NUMBER = /^([-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)(%|deg|rad|grad|turn)?$/;
+
+function token(text: string): Token | null {
+  if (text === "none") return { value: 0, unit: "" };
+  const m = NUMBER.exec(text);
+  return m ? { value: Number(m[1]), unit: (m[2] ?? "") as Unit } : null;
+}
+
+/** An angle in degrees. */
+function angle(t: Token): number {
+  if (t.unit === "rad") return (t.value * 180) / Math.PI;
+  if (t.unit === "grad") return t.value * 0.9;
+  if (t.unit === "turn") return t.value * 360;
+  return t.value;
+}
+
+/** A number, with 100% as `hundred`. */
+const scaled = (t: Token, hundred: number) => (t.unit === "%" ? (t.value / 100) * hundred : t.value);
+
+/** A fraction 0–1, from a percentage, or a number: 0–1 as it is, past 1 read as a percentage (hsl(240, 100, 50)). */
+const fraction = (t: Token) => (t.unit === "%" || Math.abs(t.value) > 1 ? t.value / 100 : t.value);
+
+/** Lightness 0–1, from a percentage, or a number: 0–1 as it is, past 1 read as a percentage (oklch(70 0.2 265)). */
+const lightness = fraction;
+
+/** What `text` says a color is, or null if it can't be read. */
+export function parseColor(text: string): Spec | null {
+  const s = text.trim().toLowerCase();
+  if (!s) return null;
+  const whole = one(s);
+  if (whole) return whole;
+  // A color, its lumens and its fidelity, in any order: "#f80 · 120 lm", "2700k @ 400lm", "2700k 400lm".
+  const found: Found = {};
+  for (const part of s.split(/\s*[·@]\s*/)) {
+    if (!part || read(part, found)) continue;
+    if (part.includes("(")) return null;
+    // Word by word, a number with the unit after it first ("50 lumens", "fidelity 0.5").
+    const words = part.split(/\s+/);
+    for (let i = 0; i < words.length; i++) {
+      if (i + 1 < words.length && read(`${words[i]} ${words[i + 1]}`, found)) i++;
+      else if (!read(words[i]!, found)) return null;
+    }
+  }
+  if (!found.spec) return null;
+  if (found.lm !== undefined) found.spec.lm = found.lm;
+  if (found.fidelity !== undefined) found.spec.fidelity = found.fidelity;
+  return found.spec;
+}
+
+interface Found {
+  spec?: Spec;
+  lm?: number;
+  fidelity?: number;
+}
+
+/** One part of a longer text, into `found`: lumens ("400 lm"), a fidelity ("F0.50"), or the color. */
+function read(part: string, found: Found): boolean {
+  let m: RegExpExecArray | null;
+  if ((m = /^([-+]?(?:\d+\.?\d*|\.\d+))\s*(?:lm|lumens?)$/.exec(part))) {
+    found.lm = Number(m[1]);
+    return true;
+  }
+  // "f0.5" needs its point, so it isn't taken for a hex code like "f80".
+  if ((m = /^(?:f(\d*\.\d+)|fidelity\s*[:=]?\s*(\d*\.?\d+))$/.exec(part))) {
+    found.fidelity = Number(m[1] ?? m[2]);
+    return true;
+  }
+  const c = one(part);
+  if (!c || found.spec) return false;
+  found.spec = c;
+  return true;
+}
+
+/** One color, alone. */
+function one(s: string): Spec | null {
+  if (s === "off" || s === "none" || s === "dark" || s === "transparent") return { space: "off" };
+  const name = cssNamed(s.replace(/[\s_-]/g, ""));
+  if (name) return hex(name);
+  const kelvin = LIGHT_NAMES[s.replace(/[\s_-]/g, "")];
+  if (kelvin) return { space: "kelvin", kelvin };
+
+  let m: RegExpExecArray | null;
+  if ((m = /^(\d+(?:\.\d+)?)\s*(?:k|kelvin)$/.exec(s))) return { space: "kelvin", kelvin: Number(m[1]) };
+  // As a color prints itself: "265° c0.300".
+  if ((m = /^([-+]?\d+(?:\.\d+)?)\s*(?:°|deg)\s*c\s*(\d*\.?\d+)$/.exec(s))) return { space: "lemtone", hue: Number(m[1]), chroma: Number(m[2]) };
+  if (/^#?(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(s)) return hex(s.replace("#", ""));
+  if ((m = /^([a-z][a-z0-9-]*)\((.*)\)$/.exec(s))) return fn(m[1]!, m[2]!);
+  return null;
+}
+
+/** Hex digits (3, 4, 6 or 8 of them, the last as alpha) as sRGB. */
+function hex(digits: string): Spec {
+  const full = digits.length <= 4 ? [...digits].map((d) => d + d).join("") : digits;
+  const at = (i: number) => parseInt(full.slice(i, i + 2), 16) / 255;
+  const spec: Spec = { space: "srgb", rgb: [at(0), at(2), at(4)] };
+  if (full.length === 8) spec.alpha = at(6);
+  return spec;
+}
+
+/** A function: rgb(…), oklch(…), color(display-p3 …), lemtone(…), … */
+function fn(name: string, inside: string): Spec | null {
+  const [main = "", alphaText] = inside.split("/");
+  const words = main.trim().split(/[\s,]+/).filter(Boolean);
+  let space: string | undefined;
+  if (name === "color") space = words.shift();
+  const t = words.map(token);
+  if (t.some((x) => x === null)) return null;
+  const v = t as Token[];
+  // Old-style rgba(1, 2, 3, 0.5): a fourth number is alpha.
+  let alpha: number | undefined;
+  if (alphaText !== undefined) {
+    const a = token(alphaText.trim());
+    if (!a) return null;
+    alpha = scaled(a, 1);
+  } else if (v.length === 4 && name !== "lemtone") alpha = scaled(v.pop()!, 1);
+
+  const spec = make(name, space, v);
+  if (spec && alpha !== undefined) spec.alpha = alpha;
+  return spec;
+}
+
+function make(name: string, space: string | undefined, v: Token[]): Spec | null {
+  const need = (n: number) => v.length >= n;
+  switch (name) {
+    case "rgb":
+    case "rgba":
+      if (!need(3)) return null;
+      return { space: "srgb", rgb: [scaled(v[0]!, 255) / 255, scaled(v[1]!, 255) / 255, scaled(v[2]!, 255) / 255] };
+    case "hsl":
+    case "hsla":
+      if (!need(3)) return null;
+      return { space: "hsl", h: angle(v[0]!), s: fraction(v[1]!), l: fraction(v[2]!) };
+    case "hwb":
+      if (!need(3)) return null;
+      return { space: "hwb", h: angle(v[0]!), w: fraction(v[1]!), b: fraction(v[2]!) };
+    case "oklab":
+      if (!need(3)) return null;
+      return { space: "oklab", lab: [lightness(v[0]!), scaled(v[1]!, 0.4), scaled(v[2]!, 0.4)] };
+    case "oklch":
+      if (!need(3)) return null;
+      return { space: "oklch", l: lightness(v[0]!), c: scaled(v[1]!, 0.4), h: angle(v[2]!) };
+    case "lab":
+      if (!need(3)) return null;
+      return { space: "lab", lab: [scaled(v[0]!, 100), scaled(v[1]!, 125), scaled(v[2]!, 125)] };
+    case "lch":
+      if (!need(3)) return null;
+      return { space: "lch", l: scaled(v[0]!, 100), c: scaled(v[1]!, 150), h: angle(v[2]!) };
+    case "color": {
+      if (!need(3)) return null;
+      const c: Vec3 = [scaled(v[0]!, 1), scaled(v[1]!, 1), scaled(v[2]!, 1)];
+      if (space === "srgb" || space === "srgb-linear" || space === "display-p3") return { space, rgb: c };
+      if (space === "xyz" || space === "xyz-d65") return { space: "xyz", xyz: c };
+      if (space === "xyz-d50") return { space: "xyz-d50", xyz: c };
+      return null;
+    }
+    case "lemtone": {
+      if (!need(2)) return null;
+      const spec: Spec = { space: "lemtone", hue: angle(v[0]!), chroma: v[1]!.value };
+      if (v[2]) spec.lm = v[2].value;
+      if (v[3]) spec.fidelity = v[3].value;
+      return spec;
+    }
+    case "white":
+    case "kelvin": {
+      if (!need(1)) return null;
+      const spec: Spec = { space: "kelvin", kelvin: v[0]!.value };
+      if (v[1]) spec.lm = v[1].value;
+      return spec;
+    }
+    default:
+      return null;
+  }
+}

package/src/shape.ts

@@ -0,0 +1,109 @@
+// Numbers to numbers: waves, easing, ranges, hashing, noise, and time steps.
+// Waves count in cycles: wave(t / 8) goes round once every 8 seconds. They
+// all run 0 to 1, starting at 0, so they make good brightnesses and mixes.
+
+const TAU = 2 * Math.PI;
+
+/** The fractional part: 2.25 → 0.25, -0.25 → 0.75. */
+export const fract = (x: number) => x - Math.floor(x);
+
+export const clamp = (x: number, lo = 0, hi = 1) => (x < lo ? lo : x > hi ? hi : x);
+
+/** From a (at t = 0) to b (at t = 1). */
+export const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+
+/** x from the range [inLo, inHi] to [outLo, outHi], not clamped. */
+export const remap = (x: number, inLo: number, inHi: number, outLo = 0, outHi = 1) =>
+  outLo + ((x - inLo) / (inHi - inLo || 1)) * (outHi - outLo);
+
+/** 0 below e0, 1 above e1, and a smooth S between. */
+export function smoothstep(e0: number, e1: number, x: number): number {
+  const t = clamp((x - e0) / (e1 - e0 || 1));
+  return t * t * (3 - 2 * t);
+}
+
+/** A smooth wave, one cycle per unit: 0 at whole numbers, 1 halfway between. */
+export const wave = (x: number) => 0.5 - 0.5 * Math.cos(TAU * x);
+
+/** Rises from 0 to 1 over each cycle, then drops back at once. */
+export const saw = (x: number) => fract(x);
+
+/** Rises from 0 to 1 over the first half of each cycle and falls back over the second. */
+export const tri = (x: number) => 1 - Math.abs(2 * fract(x) - 1);
+
+/** 1 for the first `duty` of each cycle, 0 for the rest: a hard on and off. */
+export const square = (x: number, duty = 0.5) => (fract(x) < duty ? 1 : 0);
+
+/** Easings, 0 to 1 onto 0 to 1 (cubic). */
+export const ease = {
+  in: (x: number) => clamp(x) ** 3,
+  out: (x: number) => 1 - (1 - clamp(x)) ** 3,
+  inOut: (x: number) => {
+    const t = clamp(x);
+    return t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+  },
+};
+
+// Each number's exact bits, so any number (not only whole ones) hashes.
+const bits = new Float64Array(1);
+const words = new Uint32Array(bits.buffer);
+
+/** A number from 0 to 1 that looks random but is always the same for the same inputs. */
+export function hash(...ns: number[]): number {
+  let h = 0x9e3779b9;
+  for (const n of ns) {
+    bits[0] = n === 0 ? 0 : n; // -0 and 0 hash the same
+    h = mixBits(h ^ words[0]!);
+    h = mixBits(h ^ words[1]!);
+  }
+  return (h >>> 0) / 4294967296;
+}
+
+function mixBits(h: number): number {
+  h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+  h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+  return h ^ (h >>> 16);
+}
+
+// Whole-number lattice hashing for noise: faster than hash() and as good there.
+function lattice(x: number, y: number, z: number): number {
+  let h = Math.imul(x, 0x27d4eb2d) ^ Math.imul(y, 0x165667b1) ^ Math.imul(z, 0x9e3779b1);
+  h = mixBits(h);
+  return (h >>> 0) / 4294967296;
+}
+
+const fade = (t: number) => t * t * t * (t * (t * 6 - 15) + 10);
+
+/**
+ * Smooth noise from 0 to 1, in up to three dimensions: nearby inputs give
+ * nearby values, and features are about 1 unit apart. noiseAt(x / 4, y / 4,
+ * t / 5) makes blobs about 4 m across that change over about 5 s.
+ */
+export function noiseAt(x: number, y = 0, z = 0): number {
+  const xi = Math.floor(x);
+  const yi = Math.floor(y);
+  const zi = Math.floor(z);
+  const u = fade(x - xi);
+  const v = fade(y - yi);
+  const w = fade(z - zi);
+  const c = (dx: number, dy: number, dz: number) => lattice(xi + dx, yi + dy, zi + dz);
+  const x00 = lerp(c(0, 0, 0), c(1, 0, 0), u);
+  const x10 = lerp(c(0, 1, 0), c(1, 1, 0), u);
+  const x01 = lerp(c(0, 0, 1), c(1, 0, 1), u);
+  const x11 = lerp(c(0, 1, 1), c(1, 1, 1), u);
+  return lerp(lerp(x00, x10, v), lerp(x01, x11, v), w);
+}
+
+/**
+ * How much of something is left after dt seconds, if half goes every
+ * `halfLife` seconds: value *= decay(dt, 2) halves it every 2 s, whatever the
+ * tick rate.
+ */
+export const decay = (dt: number, halfLife: number) => (halfLife > 0 ? 0.5 ** (dt / halfLife) : 0);
+
+/**
+ * True with the chance of something that happens `perSecond` times a second
+ * on average, over the last dt seconds: the same in the room (100 ticks a
+ * second) as in the preview (about 30).
+ */
+export const chance = (perSecond: number, dt: number) => Math.random() < 1 - Math.exp(-perSecond * dt);

package/src/signal.ts

@@ -0,0 +1,65 @@
+// Signals: fields that only read the time, for wiring into any number a field
+// or source takes. A clock counts beats; every(n) marks each n-th one, and
+// from those come envelopes (a flash on each), sequences (a new value each)
+// and ramps (0 to 1 across each).
+//
+//   const beat = clock(96);
+//   osc(4).rotate(beat.every(4).seq([0, 45, 90, 135])).color(palettes.dusk).boost(beat.every(1).env(), 0.8)
+
+import { field, type Field } from "./field.ts";
+import { fract } from "./shape.ts";
+
+export interface Every {
+  /** How many marks so far: 0, 1, 2, … */
+  count: Field<number>;
+  /** 0 to 1 from one mark to the next. */
+  ramp: Field<number>;
+  /** Seconds since the last mark. */
+  since: Field<number>;
+  /** 0, up to 1 in `attack` seconds after each mark (default 0.01), and back to 0 over `release` (default 0.3). */
+  env(options?: { attack?: number; release?: number }): Field<number>;
+  /** The next of these at each mark, round and round. */
+  seq<T>(list: readonly T[]): Field<T>;
+}
+
+export interface Clock {
+  readonly bpm: number;
+  /** Beats so far (not whole: 2.5 is halfway through the third). */
+  beats: Field<number>;
+  /** Marks every n beats: every(1) is each beat, every(4) each bar of four. */
+  every(n: number): Every;
+}
+
+/** A clock at `bpm` beats a minute, starting with the sketch. */
+export function clock(bpm: number): Clock {
+  const beats = field(({ t }) => (t * bpm) / 60);
+  return {
+    bpm,
+    beats,
+    every(n: number): Every {
+      const at = (t: number) => (t * bpm) / 60 / n;
+      const seconds = (60 / bpm) * n;
+      const since = field(({ t }) => fract(at(t)) * seconds);
+      return {
+        count: field(({ t }) => Math.floor(at(t))),
+        ramp: field(({ t }) => fract(at(t))),
+        since,
+        env({ attack = 0.01, release = 0.3 } = {}) {
+          return field((here) => {
+            const s = since(here);
+            if (s < attack) return s / attack;
+            const k = Math.max(0, 1 - (s - attack) / release);
+            return k * k;
+          });
+        },
+        seq<T>(list: readonly T[]) {
+          if (list.length === 0) throw new Error("seq(): give it at least one value");
+          return field(({ t }) => {
+            const i = Math.floor(at(t)) % list.length;
+            return list[i < 0 ? i + list.length : i]!;
+          });
+        },
+      };
+    },
+  };
+}

package/src/sketch.ts

@@ -0,0 +1,172 @@
+// sketch(): your looks as arclamp's update().
+//
+// Color lights and old bulbs are controlled apart, each by a look of its own,
+// named for the kind of light it's for (light.kind):
+//
+//   sketch({ color: osc(3).color(palettes.dusk), switch: osc(1, 0.25).thresh() })
+//
+// The color look is asked about the color bulbs and panels only: a function
+// of here (your own, or a field) giving a color, one color for every light,
+// or a palette laid across the room. Anything that says a color will do (a
+// Color, "#f80", "2700K", { r, g, b }, …). sketch(look) is
+// sketch({ color: look }).
+//
+// The switch look is asked about the old bulbs only, which just switch: true or
+// false, a number (on at 0.5 or more, as arclamp's own `on` channel), "on" or
+// "off", or a function of here (a field too) giving one. Without one, the old
+// bulbs are left as they are; a color never switches them.
+//
+// Null or undefined from either leaves the light as it is below (so does
+// false from a color look). Something that can't be read leaves it as it is
+// too, with a warning (once for each kind of mistake), so one slip doesn't
+// stop the sketch.
+
+import { Color, color, isPalette, type ColorInput } from "./color.ts";
+import type { Out, Prev, Update } from "./arclamp.ts";
+import { colorOf, Here, roomOf, sameLayout, type Room } from "./here.ts";
+
+// Plain V8 (arclamp's sandbox) has only what arclamp's prelude gives it.
+declare const console: { warn(...data: unknown[]): void };
+
+/** What a color light should make, here and now; null, undefined or false leaves it as it is below. */
+export type LookResult = ColorInput | null | undefined | false | void;
+
+/** The color lights' look: a function of here giving a color, one color for every light, or a palette, laid across the room. */
+export type Look = ((here: Here) => LookResult) | ColorInput;
+
+/** Whether an old bulb should be on: true or false, a number (on at 0.5 or more), "on" or "off"; null or undefined leaves it as it is. */
+export type SwitchResult = boolean | number | string | null | undefined | void;
+
+/** The old bulbs' look: a function of here (a field too) saying whether each is on, or one answer for them all. */
+export type SwitchLook = ((here: Here) => SwitchResult) | boolean | number | string;
+
+/** A look for each kind of light (light.kind); either may be left out, and its lights are left as they are. */
+export interface Looks {
+  /** For the color bulbs and panels. */
+  color?: Look;
+  /** For the old bulbs, which only switch. */
+  switch?: SwitchLook;
+}
+
+export interface SketchOptions {
+  /** The old bulbs' look, beside a color look given on its own. */
+  switch?: SwitchLook;
+}
+
+// A tick after a long gap (the sketch paused, or held up) counts as at most this long.
+const MAX_DT = 0.25;
+
+/** Your color look (a function of here, or a field) as arclamp's update(); old bulbs are left alone, unless given `switch`. */
+export function sketch(look: (here: Here) => LookResult, options?: SketchOptions): Update;
+/** A look for each kind of light: { color, switch }. */
+export function sketch(looks: Looks): Update;
+/** One color for every color light, or a palette laid across the room, as arclamp's update(). */
+export function sketch(look: ColorInput, options?: SketchOptions): Update;
+export function sketch(given: Looks | Look, options: SketchOptions = {}): Update {
+  if (options && typeof options === "object" && "on" in options) throw new Error(ON_KEY);
+  const looks: Looks = isLooks(given) ? { switch: options.switch, ...given } : { color: given as Look, switch: options.switch };
+  const askColor = looks.color === undefined ? null : lookOf(looks.color);
+  const askSwitch = looks.switch === undefined ? null : switchLookOf(looks.switch);
+  let room: Room | null = null;
+  let last: number | null = null;
+  const warned = new Set<string>();
+
+  const warn = (kind: string, text: string) => {
+    if (warned.has(kind)) return;
+    warned.add(kind);
+    console.warn(`${text} (warning once)`);
+  };
+
+  return (prev: Prev, nowMs: number, initialMs: number): Out => {
+    const list = Array.isArray(prev?.lights) ? prev.lights : [];
+    if (!room || !sameLayout(prev, room)) room = roomOf(prev, room);
+    const t = (nowMs - initialMs) / 1000;
+    const dt = last === null ? 0 : Math.min(MAX_DT, Math.max(0, (nowMs - last) / 1000));
+    last = nowMs;
+
+    const lights: Out["lights"] = [];
+    for (let i = 0; i < list.length; i++) {
+      const light = room.lights[i]!;
+      light.below = colorOf(list[i]!, light.kind);
+      light.belowOn = light.below.lm > 0;
+      const ask = light.kind === "switch" ? askSwitch : askColor;
+      if (!ask) continue;
+      const v = ask(new Here(light.x, light.y, t, dt, nowMs, light, room));
+
+      if (light.kind === "switch") {
+        const on = readOn(v);
+        if (on === "unreadable") {
+          warn(
+            "on",
+            `light ${light.id} is an old bulb, which only switches: its look gives true or false, a number (on at 0.5 or more), or "on" or "off", not ${describe(v)}; give old bulbs a look of their own, sketch({ color, switch })`,
+          );
+        } else if (on !== null) lights.push({ id: light.id, channels: { on: on ? 1 : 0 } });
+        continue;
+      }
+
+      if (v === null || v === undefined || v === false) continue;
+      let c: Color;
+      try {
+        c = v instanceof Color ? v : color(v as ColorInput);
+      } catch (err) {
+        if (typeof v === "number") {
+          warn("number", `light ${light.id} was given ${v}, and a number is read as a color temperature in kelvin; for a pattern from 0 to 1, color it first, like osc(3).color(palettes.dusk)`);
+        } else {
+          warn("unreadable", `light ${light.id} was given something that isn't a color, so it's left as it is: ${(err as Error).message}`);
+        }
+        continue;
+      }
+      const channels = c.channels;
+      if (!Number.isFinite(channels.a) || !Number.isFinite(channels.b) || !Number.isFinite(channels.brightness) || !Number.isFinite(channels.fidelity)) {
+        warn("nan", `light ${light.id} was given a color that isn't all numbers, ${JSON.stringify(c)}, so it's left as it is`);
+        continue;
+      }
+      lights.push({ id: light.id, channels });
+    }
+    return { lights };
+  };
+}
+
+const ON_KEY = 'old bulbs\' look is `switch`, for the kind of light it\'s for: sketch({ color, switch }), or sketch(look, { switch })';
+
+/** Whether a sketch was given a look for each kind of light ({ color, switch }) rather than one look. */
+function isLooks(v: unknown): v is Looks {
+  if (!v || typeof v !== "object" || v instanceof Color || Array.isArray(v)) return false;
+  const keys = Object.keys(v);
+  // { on } would read as an old bulb's channels, a color: say what's meant instead.
+  if (keys.includes("on")) throw new Error(ON_KEY);
+  return keys.length > 0 && keys.every((k) => k === "color" || k === "switch");
+}
+
+/** The color look as a function of here. One color is the same everywhere (and said wrong, an error now, not each tick). */
+function lookOf(look: Look): (here: Here) => unknown {
+  if (isPalette(look)) return (here) => look(here.u);
+  if (typeof look === "function") return look as (here: Here) => unknown;
+  const c = color(look);
+  return () => c;
+}
+
+/** The switch look as a function of here. One answer is the same everywhere (and said wrong, an error now). */
+function switchLookOf(look: SwitchLook): (here: Here) => unknown {
+  if (typeof look === "function") return look as (here: Here) => unknown;
+  const on = readOn(look);
+  if (on === "unreadable") throw new Error(`${describe(look)} isn't on or off: give true or false, a number (on at 0.5 or more), or "on" or "off"`);
+  return () => on;
+}
+
+/** On (true), off (false), leave it (null), or can't tell. */
+function readOn(v: unknown): boolean | null | "unreadable" {
+  if (v === null || v === undefined) return null;
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return Number.isFinite(v) ? v >= 0.5 : "unreadable";
+  if (typeof v === "string") {
+    const s = v.trim().toLowerCase();
+    if (s === "on" || s === "true" || s === "yes") return true;
+    if (s === "off" || s === "false" || s === "no") return false;
+    return s !== "" && Number.isFinite(Number(s)) ? Number(s) >= 0.5 : "unreadable";
+  }
+  if (typeof v === "object" && !(v instanceof Color) && "on" in v) return readOn((v as { on: unknown }).on);
+  return "unreadable";
+}
+
+const describe = (v: unknown) => (v instanceof Color ? `a color (${v})` : typeof v === "string" ? `"${v}"` : JSON.stringify(v) ?? String(v));

package/src/spaces.ts

@@ -0,0 +1,102 @@
+// The color spaces people know, to and from the light they stand for.
+//
+// They're all screens' spaces, so their brightness is relative to a screen's
+// white. Here that white is a fixed amount of light, 1000 lm (lemtone's
+// brightness 1.0), the same on every light: rgb(1, 1, 1) asks for 1000 lm,
+// and a screen's full blue, #0000ff, for about 72, as dim next to white as on
+// a screen. Everything goes through XYZ (D65, Y = 1 for that white), with the
+// matrices CSS Color 4 uses.
+
+import { lmsToXyz, mul3, xyzToLms, type Vec3 } from "./lemtone.ts";
+
+/** The light a screen's white stands for, in lumens. */
+export const SCREEN_WHITE_LM = 1000;
+
+// Linear sRGB <-> OKLab's LMS (Björn Ottosson's), so sRGB and OKLab agree exactly.
+const SRGB_LMS = [
+  [0.4122214708, 0.5363325363, 0.0514459929],
+  [0.2119034982, 0.6806995451, 0.1073969566],
+  [0.0883024619, 0.2817188376, 0.6299787005],
+];
+const LMS_SRGB = [
+  [4.0767416621, -3.3077115913, 0.2309699292],
+  [-1.2684380046, 2.6097574011, -0.3413193965],
+  [-0.0041960863, -0.7034186147, 1.707614701],
+];
+
+export const linearSrgbToXyz = (rgb: Vec3): Vec3 => lmsToXyz(mul3(SRGB_LMS, rgb));
+export const xyzToLinearSrgb = (X: Vec3): Vec3 => mul3(LMS_SRGB, xyzToLms(X));
+
+/** sRGB's gamma, undone (extended past 0 and 1 the same way both sides, as CSS does). */
+export function decode(v: number): number {
+  const x = Math.abs(v);
+  return Math.sign(v) * (x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4);
+}
+
+/** sRGB's gamma. */
+export function encode(v: number): number {
+  const x = Math.abs(v);
+  return Math.sign(v) * (x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055);
+}
+
+// Linear Display P3 -> XYZ (CSS Color 4).
+const P3_XYZ = [
+  [0.48657094864821626, 0.26566769316909294, 0.1982172852343625],
+  [0.22897456406974884, 0.6917385218365062, 0.079286914093745],
+  [0, 0.045113381858902575, 1.0439443689009757],
+];
+export const linearP3ToXyz = (rgb: Vec3): Vec3 => mul3(P3_XYZ, rgb);
+
+// CIE Lab and LCh are relative to D50; back to D65 by Bradford (CSS Color 4).
+const D50: Vec3 = [0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585];
+const D50_D65 = [
+  [0.955473421488075, -0.02309845494876471, 0.06325924320057072],
+  [-0.0283697093338637, 1.0099953980813041, 0.021041441191917323],
+  [0.012314014864481998, -0.020507649298898964, 1.330365926242124],
+];
+export const xyzD50ToXyz = (X: Vec3): Vec3 => mul3(D50_D65, X);
+
+/** CIE Lab (L 0–100) as XYZ (D65). */
+export function labToXyz(L: number, a: number, b: number): Vec3 {
+  const k = 24389 / 27;
+  const e = 216 / 24389;
+  const f1 = (L + 16) / 116;
+  const f0 = a / 500 + f1;
+  const f2 = f1 - b / 200;
+  const x = f0 ** 3 > e ? f0 ** 3 : (116 * f0 - 16) / k;
+  const y = L > k * e ? f1 ** 3 : L / k;
+  const z = f2 ** 3 > e ? f2 ** 3 : (116 * f2 - 16) / k;
+  return xyzD50ToXyz([x * D50[0], y, z * D50[2]]);
+}
+
+/** HSL (hue in degrees, saturation and lightness 0–1) as gamma-encoded sRGB (CSS Color 4). */
+export function hslToSrgb(h: number, s: number, l: number): Vec3 {
+  const hue = ((h % 360) + 360) % 360;
+  const f = (n: number) => {
+    const k = (n + hue / 30) % 12;
+    return l - s * Math.min(l, 1 - l) * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return [f(0), f(8), f(4)];
+}
+
+/** HWB (hue in degrees, whiteness and blackness 0–1) as gamma-encoded sRGB (CSS Color 4). */
+export function hwbToSrgb(h: number, w: number, b: number): Vec3 {
+  if (w + b >= 1) {
+    const gray = w / (w + b);
+    return [gray, gray, gray];
+  }
+  return hslToSrgb(h, 1, 0.5).map((v) => v * (1 - w - b) + w) as Vec3;
+}
+
+/** Gamma-encoded sRGB as HSL (CSS Color 4): hue in degrees (0 for grays), saturation and lightness 0–1. */
+export function srgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: number } {
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) return { h: 0, s: 0, l };
+  const s = l === 0 || l === 1 ? 0 : (max - l) / Math.min(l, 1 - l);
+  let h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+  h *= 60;
+  return { h, s, l };
+}