@nodaro/prompts 1.38.0 → 1.39.0

package/src/__tests__/user-direction-refs.test.ts

@@ -0,0 +1,180 @@
+/**
+ * User-owned direction references: `direction.colorLook: "palette:<id>"` and
+ * `direction.style: "moodboard:<id>"`. The grammar, the wording of the
+ * resolved clauses, and how a resolved clause takes its row's place in the
+ * fold — without changing a single byte of a fold that carries none.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  parseUserDirectionRef,
+  userDirectionRefValue,
+  renderPaletteClause,
+  renderMoodboardClause,
+  styleReferenceDescription,
+} from "../user-direction-refs.js"
+import { nearestColorName } from "../color-names.js"
+import {
+  DIRECTION_FIELDS,
+  directionKeyForUserRef,
+  userRefKindOfDirectionKey,
+  renderDirectionHints,
+  renderDirectionHintClauses,
+} from "../direction-registry.js"
+import { partitionStyleClauses } from "../prompt-style-section.js"
+import { getColorLookPromptHint } from "../color-look.js"
+import { getStylePromptHint } from "../style.js"
+
+const UUID = "0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f"
+const PALETTE = `palette:${UUID}`
+const MOODBOARD = `moodboard:${UUID}`
+const IMAGE = { surface: "image" as const }
+
+describe("parseUserDirectionRef", () => {
+  it("reads a palette and a moodboard reference", () => {
+    expect(parseUserDirectionRef(PALETTE)).toEqual({ kind: "palette", id: UUID, wellFormed: true })
+    expect(parseUserDirectionRef(MOODBOARD)).toEqual({ kind: "moodboard", id: UUID, wellFormed: true })
+  })
+
+  it("marks a prefix followed by anything but a uuid as malformed, not as a catalog id", () => {
+    expect(parseUserDirectionRef("palette:warm")).toEqual({ kind: "palette", id: "warm", wellFormed: false })
+    expect(parseUserDirectionRef("moodboard:")).toEqual({ kind: "moodboard", id: "", wellFormed: false })
+  })
+
+  it("is null for a catalog id, an empty string and a non-string", () => {
+    expect(parseUserDirectionRef("teal-orange")).toBeNull()
+    expect(parseUserDirectionRef("")).toBeNull()
+    expect(parseUserDirectionRef(undefined)).toBeNull()
+    expect(parseUserDirectionRef(["palette:x"])).toBeNull()
+  })
+
+  it("builds the wire value back", () => {
+    expect(userDirectionRefValue("palette", UUID)).toBe(PALETTE)
+    expect(userDirectionRefValue("moodboard", UUID)).toBe(MOODBOARD)
+  })
+})
+
+describe("which direction keys take a reference", () => {
+  it("colorLook takes a palette and style takes a moodboard", () => {
+    expect(directionKeyForUserRef("palette")).toBe("colorLook")
+    expect(directionKeyForUserRef("moodboard")).toBe("style")
+    expect(userRefKindOfDirectionKey("colorLook")).toBe("palette")
+    expect(userRefKindOfDirectionKey("style")).toBe("moodboard")
+    expect(userRefKindOfDirectionKey("mood")).toBeUndefined()
+    expect(userRefKindOfDirectionKey("not-a-key")).toBeUndefined()
+  })
+
+  it("only single-pick rows take one, so a reference is never sliced away by a pick budget", () => {
+    const rows = DIRECTION_FIELDS.filter((f) => "userRef" in f)
+    expect(rows.map((f) => f.key).sort()).toEqual(["colorLook", "style"])
+    for (const row of rows) expect(row.maxPicks, row.key).toBe(1)
+  })
+})
+
+describe("nearestColorName", () => {
+  it("names the primaries and the neutrals plainly", () => {
+    expect(nearestColorName("#000000")).toBe("black")
+    expect(nearestColorName("#FFFFFF")).toBe("white")
+    expect(nearestColorName("#FF0000")).toBe("red")
+    expect(nearestColorName("#0000FF")).toBe("blue")
+    expect(nearestColorName("#808080")).toBe("gray")
+  })
+
+  it("accepts lowercase hex and answers the same name", () => {
+    expect(nearestColorName("#ff0000")).toBe(nearestColorName("#FF0000"))
+  })
+
+  it("answers a name for any valid colour and nothing for an invalid one", () => {
+    expect(nearestColorName("#0F4C5C").length).toBeGreaterThan(0)
+    expect(nearestColorName("#E3B23C").length).toBeGreaterThan(0)
+    expect(nearestColorName("teal")).toBe("")
+    expect(nearestColorName("#12345")).toBe("")
+  })
+
+  it("puts a dark blue-green near teal, not near a warm colour", () => {
+    expect(nearestColorName("#0F4C5C")).toMatch(/teal|petrol|blue|green/)
+  })
+})
+
+describe("renderPaletteClause", () => {
+  it("names every colour with its hex, in the palette's order", () => {
+    const clause = renderPaletteClause(["#0f4c5c", "#E3B23C"])
+    expect(clause).toBe(`color palette: ${nearestColorName("#0F4C5C")} #0F4C5C, ${nearestColorName("#E3B23C")} #E3B23C`)
+  })
+
+  it("skips an entry that is not a #RRGGBB colour, and renders nothing for none", () => {
+    expect(renderPaletteClause(["#FF0000", "red", "#00FF00"])).toBe("color palette: red #FF0000, " + `${nearestColorName("#00FF00")} #00FF00`)
+    expect(renderPaletteClause([])).toBe("")
+    expect(renderPaletteClause(["nope"])).toBe("")
+  })
+})
+
+describe("renderMoodboardClause", () => {
+  it("is the description, on one line, trimmed", () => {
+    expect(renderMoodboardClause("  Moody Nordic interiors,\n\nsoft   daylight  ")).toBe("Moody Nordic interiors, soft daylight")
+  })
+
+  it("cannot open a section of its own: newlines collapse", () => {
+    expect(renderMoodboardClause("calm\n\n[style]:\nloud")).not.toContain("\n")
+  })
+
+  it("renders nothing without a description", () => {
+    expect(renderMoodboardClause(null)).toBe("")
+    expect(renderMoodboardClause(undefined)).toBe("")
+    expect(renderMoodboardClause("   ")).toBe("")
+  })
+})
+
+describe("styleReferenceDescription", () => {
+  it("tells the model what to take from the first style reference, and keeps the rest short", () => {
+    expect(styleReferenceDescription(0)).toMatch(/style reference/)
+    expect(styleReferenceDescription(0)).toMatch(/not its subject/)
+    expect(styleReferenceDescription(1)).toBe("another style reference")
+  })
+
+  it("carries the image's caption, on one line", () => {
+    expect(styleReferenceDescription(1, "  linen\nand oak ")).toBe("another style reference (linen and oak)")
+    expect(styleReferenceDescription(0, "soft daylight")).toContain("(soft daylight)")
+  })
+})
+
+describe("the fold with resolved references", () => {
+  const refs = new Map([
+    [PALETTE, "color palette: deep teal #0F4C5C"],
+    [MOODBOARD, "Moody Nordic interiors"],
+  ])
+
+  it("renders a resolved palette in the colorLook row and a moodboard in the style row", () => {
+    expect(renderDirectionHints({ colorLook: PALETTE, style: MOODBOARD }, { ...IMAGE, refs })).toEqual([
+      "color palette: deep teal #0F4C5C",
+      "Moody Nordic interiors",
+    ])
+  })
+
+  it("keeps the table's fold order around a resolved clause", () => {
+    const hints = renderDirectionHints({ style: MOODBOARD, colorLook: "warm", era: "1970s" }, { ...IMAGE, refs })
+    expect(hints[0]).toBe(getColorLookPromptHint("warm"))
+    expect(hints[1]).toBe("Moody Nordic interiors")
+  })
+
+  it("lands both on the film line of the [style] section", () => {
+    const slots = partitionStyleClauses({ colorLook: PALETTE, style: MOODBOARD }, { ...IMAGE, refs })
+    expect(slots.map((c) => c.slot)).toEqual(["film", "film"])
+    const clauses = renderDirectionHintClauses({ colorLook: PALETTE }, { ...IMAGE, refs })
+    expect(clauses[0]).toMatchObject({ key: "colorLook", family: "look", styleGroup: "film" })
+  })
+
+  it("renders nothing for a reference it was not handed, like an unknown catalog id", () => {
+    expect(renderDirectionHints({ colorLook: PALETTE }, IMAGE)).toEqual([])
+    expect(renderDirectionHints({ colorLook: PALETTE }, { ...IMAGE, refs: new Map() })).toEqual([])
+  })
+
+  it("renders nothing for a reference on a row that does not take that kind", () => {
+    expect(renderDirectionHints({ style: PALETTE, colorLook: MOODBOARD, mood: PALETTE }, { ...IMAGE, refs })).toEqual([])
+  })
+
+  it("leaves a fold with no reference byte-identical, refs or not", () => {
+    const direction = { colorLook: "warm", style: "anime", mood: ["happy", "joyful"] }
+    expect(renderDirectionHints(direction, { ...IMAGE, refs })).toEqual(renderDirectionHints(direction, IMAGE))
+    expect(renderDirectionHints({ style: "anime" }, { ...IMAGE, refs })).toEqual([getStylePromptHint("anime")])
+  })
+})

package/src/assemble-image-input.ts

@@ -60,6 +60,8 @@ import {
   type SlottedPromptClause,
 } from "./prompt-style-section.js"
 import { keepableDirectionHints } from "./hint-shedding.js"
+import { styleReferenceDescription, type StyleReferenceInput } from "./user-direction-refs.js"
+import { imageReferenceLimit } from "@nodaro/shared/models"
 import type { CharacterDef, ConnectedReference, DescribedReference, IdentityMeta } from "@nodaro/shared/types"
 
 /**
@@ -112,6 +114,23 @@ export interface AssembleImageInput {
    * is a no-op for it and the result is byte-identical to today).
    */
   direction?: DirectionFields
+  /**
+   * Rendered clauses for the caller's OWN saved resources named in `direction`
+   * (`colorLook: "palette:<id>"`, `style: "moodboard:<id>"`), keyed by the
+   * direction value. Resolving them is a database read, so the platform does it
+   * BEFORE this pure assembly and hands the clauses in; each one folds in its
+   * row's slot exactly like a catalog clause (the `[style]` film line), sheds
+   * like one, and a reference missing from the map folds nothing.
+   */
+  directionRefs?: ReadonlyMap<string, string>
+  /**
+   * Style reference images (a moodboard's images). They only FILL the
+   * reference seats the caller's own references leave free — after them, never
+   * displacing, renumbering or evicting one — up to the model's reference
+   * limit; the rest are not sent. `styleReferencesSent` on the result says how
+   * many went. Each carries a short style line (`styleReferenceDescription`).
+   */
+  styleReferences?: readonly StyleReferenceInput[]
   /**
    * Flat subject ids (Person / Styling / props) → folded into the prompt AHEAD
    * of the direction clauses: the subject is the noun phrase the cinematography
@@ -216,6 +235,7 @@ function renderImageHintPieces(
   subject: SubjectFields | undefined,
   direction: DirectionFields | undefined,
   structured: StructuredPromptFields | undefined,
+  directionRefs: ReadonlyMap<string, string> | undefined,
 ): ImageHintPieces {
   return {
     hintClauses: [
@@ -228,6 +248,7 @@ function renderImageHintPieces(
       ...partitionStyleClauses(direction, {
         surface: "image",
         mode: IMAGE_HINT_MODE_DEFAULT,
+        ...(directionRefs !== undefined ? { refs: directionRefs } : {}),
       }),
     ].filter((c) => c.text.length > 0),
     structuredFragment: structured ? renderStructuredFields(structured) : "",
@@ -275,7 +296,9 @@ function composePromptText(
  * Order: (1) compose the prompt text (no-op when no subject/direction/structured),
  * (2) `buildImagePrompt(...)` — exactly the call the three sites make today,
  * (3) shed hint clauses and re-assemble while the provider cap overflows,
- * (4) optional post-assembly empty-prompt throw (gated by `throwOnEmpty`).
+ * (4) with `styleReferences`, fill the free reference seats with them
+ *     (`fillStyleReferences`; absent = this step does not run at all),
+ * (5) optional post-assembly empty-prompt throw (gated by `throwOnEmpty`).
  *
  * TRUNCATION ORDERING (step 3): `buildImagePrompt`'s cap clamp cuts the TAIL,
  * which is ORDER-BLIND — on a low-cap provider (seedream = 3000) a maximal
@@ -293,8 +316,96 @@ function composePromptText(
  */
 export function assembleImageInput(
   input: AssembleImageInput,
-): BuildImagePromptResult {
-  const pieces = renderImageHintPieces(input.subject, input.direction, input.structured)
+): AssembleImageResult {
+  const style = input.styleReferences
+  const result = style !== undefined && style.length > 0
+    ? fillStyleReferences(input, style)
+    : assembleOnce(input)
+
+  // Post-assembly empty-prompt check (opt-in): a bound entity / `@`-mention /
+  // subject or direction chip — or a style reference's line — could have
+  // filled the assembled prompt even if the user typed nothing, so only reject
+  // when the FINAL prompt is truly empty.
+  if (input.throwOnEmpty && !result.prompt.trim()) {
+    throw new Error(
+      "No prompt — type one, bind a character, or pick a cinematography direction",
+    )
+  }
+
+  return result
+}
+
+/** `assembleImageInput`'s result: the builder's, plus the style-reference count. */
+export interface AssembleImageResult extends BuildImagePromptResult {
+  /**
+   * How many of `styleReferences` were sent (they follow the caller's own
+   * references at the end of `referenceImageUrls`). Present only when
+   * `styleReferences` were given, so every other result is unchanged.
+   */
+  styleReferencesSent?: number
+}
+
+/**
+ * Fill the reference seats the caller's own references leave free with style
+ * references, without touching the caller's own.
+ *
+ * PASS 1 assembles the caller's input alone: its `referenceImageUrls` are the
+ * references the caller's request really sends (after the per-provider cap,
+ * mention resolution and dedupe). The free seats are the model's limit minus
+ * those. PASS 2 appends k style references as manual extra references — the
+ * builder's own mechanism, so they get its numbered/lettered lines in either
+ * reference format — for the LARGEST k that leaves the caller's references
+ * exactly where pass 1 put them, followed by the k style images. Why a check
+ * and not arithmetic: the builder caps the RAW reference list with an
+ * attach-priority slice (non-variants first), so extra entries can push out a
+ * character variant the prompt mentions even when seats looked free. Assembly
+ * is pure and k ≤ 12, so trying each k downward is cheap and exact.
+ */
+function fillStyleReferences(
+  input: AssembleImageInput,
+  style: readonly StyleReferenceInput[],
+): AssembleImageResult {
+  const base = assembleOnce(input)
+  const own = base.referenceImageUrls ?? []
+  const seats = imageReferenceLimit(input.provider) - own.length
+  const seen = new Set(own)
+  const candidates: StyleReferenceInput[] = []
+  for (const s of style) {
+    if (typeof s.url !== "string" || s.url.length === 0 || seen.has(s.url)) continue
+    seen.add(s.url)
+    candidates.push(s)
+  }
+  for (let k = Math.min(seats, candidates.length); k > 0; k--) {
+    const extras = candidates.slice(0, k).map(styleConnectedReference)
+    const filled = assembleOnce({
+      ...input,
+      connectedReferences: [...(input.connectedReferences ?? []), ...extras],
+    })
+    const urls = filled.referenceImageUrls ?? []
+    const keepsOwn = urls.length === own.length + k
+      && own.every((url, i) => urls[i] === url)
+      && extras.every((ref, j) => urls[own.length + j] === ref.url)
+    if (keepsOwn) return { ...filled, styleReferencesSent: k }
+  }
+  return { ...base, styleReferencesSent: 0 }
+}
+
+/** A style reference as the builder's manual extra reference. */
+function styleConnectedReference(s: StyleReferenceInput, index: number): ConnectedReference {
+  return {
+    id: `style-reference-${index + 1}`,
+    defaultName: `Style reference ${index + 1}`,
+    source: "manual",
+    url: s.url,
+    isExtraRef: true,
+    defaultRole: "style",
+    description: styleReferenceDescription(index, s.caption),
+  }
+}
+
+/** One assembly of `input` as given (no style-reference fill, no empty check). */
+function assembleOnce(input: AssembleImageInput): BuildImagePromptResult {
+  const pieces = renderImageHintPieces(input.subject, input.direction, input.structured, input.directionRefs)
 
   const assembleWith = (keptHintClauses: number) => buildImagePromptWithOverflow({
     prompt: composePromptText(input.userPrompt, pieces, keptHintClauses),
@@ -359,15 +470,5 @@ export function assembleImageInput(
   }
   // `overflowChars` is assembly bookkeeping, not part of the callers' contract.
   const { overflowChars, ...result } = fitted
-
-  // Post-assembly empty-prompt check (opt-in): a bound entity / `@`-mention /
-  // subject or direction chip could have filled the assembled prompt even if the user
-  // typed nothing — so only reject when the FINAL prompt is truly empty.
-  if (input.throwOnEmpty && !result.prompt.trim()) {
-    throw new Error(
-      "No prompt — type one, bind a character, or pick a cinematography direction",
-    )
-  }
-
   return result
 }

package/src/catalog-id-guard.ts

@@ -1,5 +1,7 @@
 import { PICKER_CATALOGS, getPickerCatalog } from "./picker-catalogs.js"
 import { getRegisteredCatalogPacks, catalogPacksVersion } from "./catalog-packs.js"
+import { userRefKindOfDirectionKey } from "./direction-registry.js"
+import { parseUserDirectionRef } from "./user-direction-refs.js"
 
 /**
  * THE WALL: refuse work that names a catalog id this deployment does not
@@ -113,18 +115,32 @@ export function catalogGuardActive(): boolean {
   return getRegisteredCatalogPacks().length > 0
 }
 
+/**
+ * A `direction` value that names the caller's OWN saved resource on the key
+ * that takes that kind (`colorLook: "palette:<id>"`, `style: "moodboard:<id>"`)
+ * is not a catalog id, so curation has nothing to say about it — the platform
+ * resolves it against the caller's rows instead. On any other key, and in a
+ * parameter node's own fields, the same value is still an unknown id.
+ */
+function isOwnUserRef(field: string, id: string): boolean {
+  const ref = parseUserDirectionRef(id)
+  return ref !== null && userRefKindOfDirectionKey(field) === ref.kind
+}
+
 function checkRecord(
   nodeType: string,
   nodeId: string | undefined,
   data: Record<string, unknown>,
   fields: ReadonlyMap<string, string>,
   out: ForeignCatalogId[],
+  skip?: (field: string, id: string) => boolean,
 ): void {
   for (const [field, catalogId] of fields) {
     const raw = data[field]
     if (raw === undefined || raw === null) continue
     const offered = composedIds(catalogId)
     for (const id of values(raw)) {
+      if (skip?.(field, id)) continue
       if (!offered.has(id)) out.push({ nodeId, nodeType, field, id, catalogId })
     }
   }
@@ -152,7 +168,7 @@ export function findForeignCatalogIds(
     for (const key of ["direction", "subject"] as const) {
       const rec = data[key]
       if (rec && typeof rec === "object" && !Array.isArray(rec)) {
-        checkRecord(type, nodeId, rec as Record<string, unknown>, table.byField, out)
+        checkRecord(type, nodeId, rec as Record<string, unknown>, table.byField, out, key === "direction" ? isOwnUserRef : undefined)
       }
     }
   }
@@ -170,7 +186,7 @@ export function findForeignCatalogIdsInBody(
   for (const key of ["direction", "subject"] as const) {
     const rec = body[key]
     if (rec && typeof rec === "object" && !Array.isArray(rec)) {
-      checkRecord(nodeType, undefined, rec as Record<string, unknown>, table.byField, out)
+      checkRecord(nodeType, undefined, rec as Record<string, unknown>, table.byField, out, key === "direction" ? isOwnUserRef : undefined)
     }
   }
   return out

package/src/color-names.ts

@@ -0,0 +1,192 @@
+/**
+ * Plain colour names for a hex value — what a saved colour palette reads as
+ * in a prompt ("deep teal #0F4C5C"). A model follows a named colour more
+ * reliably than a bare hex code, and the hex keeps the exact value.
+ *
+ * NEAREST NAME, NOT A CLASSIFIER: a fixed table of everyday colour names, each
+ * with a representative value, and the one closest to the input in CIE Lab
+ * (ΔE 1976 — Euclidean distance in Lab, which tracks perceived difference far
+ * better than RGB). Deterministic, dependency-free, and a name is always one a
+ * person would say. Ties go to the earlier row.
+ */
+
+/** Everyday colour names and a representative sRGB value for each. */
+const NAMED: ReadonlyArray<readonly [name: string, hex: string]> = [
+  // Neutrals
+  ["black", "#000000"],
+  ["charcoal", "#36454F"],
+  ["dark gray", "#555555"],
+  ["slate gray", "#708090"],
+  ["gray", "#808080"],
+  ["warm gray", "#9A9088"],
+  ["silver", "#C0C0C0"],
+  ["light gray", "#D3D3D3"],
+  ["off-white", "#F2F0EB"],
+  ["white", "#FFFFFF"],
+  ["ivory", "#FFFFF0"],
+  ["cream", "#FFFDD0"],
+  ["eggshell", "#F0EAD6"],
+  ["linen", "#FAF0E6"],
+  ["champagne", "#F7E7CE"],
+  ["wheat", "#F5DEB3"],
+  // Earth tones and browns
+  ["sand", "#C2B280"],
+  ["tan", "#D2B48C"],
+  ["khaki", "#C3B091"],
+  ["taupe", "#8B8589"],
+  ["camel", "#C19A6B"],
+  ["caramel", "#C68E17"],
+  ["brown", "#964B00"],
+  ["chocolate", "#7B3F00"],
+  ["coffee", "#6F4E37"],
+  ["espresso", "#4E312D"],
+  ["walnut", "#773F1A"],
+  ["chestnut", "#954535"],
+  ["mahogany", "#C04000"],
+  ["rust", "#B7410E"],
+  ["terracotta", "#E2725B"],
+  ["copper", "#B87333"],
+  ["bronze", "#CD7F32"],
+  ["ochre", "#CC7722"],
+  // Oranges
+  ["burnt orange", "#CC5500"],
+  ["orange", "#FFA500"],
+  ["tangerine", "#F28500"],
+  ["apricot", "#FBCEB1"],
+  ["peach", "#FFCBA4"],
+  ["coral", "#FF7F50"],
+  ["salmon", "#FA8072"],
+  // Reds
+  ["red", "#FF0000"],
+  ["scarlet", "#FF2400"],
+  ["crimson", "#DC143C"],
+  ["cherry red", "#D2042D"],
+  ["brick red", "#CB4154"],
+  ["burgundy", "#800020"],
+  ["maroon", "#800000"],
+  ["wine red", "#722F37"],
+  ["oxblood", "#4A0000"],
+  // Pinks
+  ["raspberry", "#E30B5C"],
+  ["rose", "#FF007F"],
+  ["hot pink", "#FF69B4"],
+  ["pink", "#FFC0CB"],
+  ["blush pink", "#E8B4B8"],
+  ["dusty rose", "#C08081"],
+  ["mauve", "#B784A7"],
+  // Purples
+  ["magenta", "#FF00FF"],
+  ["orchid", "#DA70D6"],
+  ["plum", "#8E4585"],
+  ["eggplant", "#614051"],
+  ["dusty purple", "#6E5A7E"],
+  ["lilac", "#C8A2C8"],
+  ["lavender", "#B57EDC"],
+  ["pale lavender", "#E6E6FA"],
+  ["amethyst", "#9966CC"],
+  ["violet", "#8F00FF"],
+  ["purple", "#800080"],
+  ["indigo", "#4B0082"],
+  // Blues
+  ["navy blue", "#000080"],
+  ["midnight blue", "#191970"],
+  ["prussian blue", "#003153"],
+  ["dusky blue", "#4B5E7D"],
+  ["royal blue", "#4169E1"],
+  ["cobalt blue", "#0047AB"],
+  ["blue", "#0000FF"],
+  ["cornflower blue", "#6495ED"],
+  ["denim blue", "#1560BD"],
+  ["steel blue", "#4682B4"],
+  ["slate blue", "#6A5ACD"],
+  ["periwinkle", "#CCCCFF"],
+  ["sky blue", "#87CEEB"],
+  ["baby blue", "#89CFF0"],
+  ["powder blue", "#B0E0E6"],
+  ["ice blue", "#D6ECEF"],
+  ["azure", "#007FFF"],
+  ["cerulean", "#007BA7"],
+  ["petrol blue", "#005F6A"],
+  // Cyans and teals
+  ["cyan", "#00FFFF"],
+  ["turquoise", "#40E0D0"],
+  ["aquamarine", "#7FFFD4"],
+  ["teal", "#008080"],
+  ["dark teal", "#014D4E"],
+  ["dark slate gray", "#2F4F4F"],
+  // Greens
+  ["sea green", "#2E8B57"],
+  ["emerald green", "#50C878"],
+  ["jade green", "#00A86B"],
+  ["mint green", "#98FF98"],
+  ["seafoam green", "#93E9BE"],
+  ["sage green", "#9CAF88"],
+  ["olive green", "#708238"],
+  ["olive", "#808000"],
+  ["moss green", "#8A9A5B"],
+  ["forest green", "#228B22"],
+  ["hunter green", "#355E3B"],
+  ["bottle green", "#006A4E"],
+  ["dark green", "#013220"],
+  ["green", "#008000"],
+  ["kelly green", "#4CBB17"],
+  ["lime green", "#32CD32"],
+  ["chartreuse", "#7FFF00"],
+  ["pistachio", "#93C572"],
+  // Yellows and golds
+  ["yellow", "#FFFF00"],
+  ["lemon yellow", "#FFF44F"],
+  ["pale yellow", "#FDFD96"],
+  ["canary yellow", "#FFEF00"],
+  ["mustard yellow", "#E1AD01"],
+  ["gold", "#FFD700"],
+  ["amber", "#FFBF00"],
+  ["honey", "#F0A830"],
+  ["saffron", "#F4C430"],
+]
+
+const HEX_RE = /^#[0-9a-f]{6}$/i
+
+type Lab = readonly [l: number, a: number, b: number]
+
+function channel(v: number): number {
+  const c = v / 255
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+}
+
+function labPivot(t: number): number {
+  return t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 * t + 16) / 116
+}
+
+/** sRGB hex → CIE Lab (D65). Only called with a value that passed `HEX_RE`. */
+function toLab(hex: string): Lab {
+  const r = channel(parseInt(hex.slice(1, 3), 16))
+  const g = channel(parseInt(hex.slice(3, 5), 16))
+  const b = channel(parseInt(hex.slice(5, 7), 16))
+  const x = labPivot((0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / 0.95047)
+  const y = labPivot(0.2126729 * r + 0.7151522 * g + 0.072175 * b)
+  const z = labPivot((0.0193339 * r + 0.119192 * g + 0.9503041 * b) / 1.08883)
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)]
+}
+
+let namedLab: ReadonlyArray<readonly [string, Lab]> | null = null
+
+/**
+ * The everyday name nearest to `hex` (`#RRGGBB`, any case), or `""` when the
+ * value is not a `#RRGGBB` colour.
+ */
+export function nearestColorName(hex: string): string {
+  if (!HEX_RE.test(hex)) return ""
+  namedLab ??= NAMED.map(([name, value]) => [name, toLab(value)] as const)
+  const [l, a, b] = toLab(hex)
+  let best = ""
+  let bestDistance = Infinity
+  for (const [name, [nl, na, nb]] of namedLab) {
+    const d = (l - nl) ** 2 + (a - na) ** 2 + (b - nb) ** 2
+    if (d < bestDistance) {
+      bestDistance = d
+      best = name
+    }
+  }
+  return best
+}