@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/imagery.mjs

@@ -0,0 +1,1280 @@
+// `palate imagery "<query>"` and `palate texture <name>`: real imagery and material for a page, never a
+// placeholder and never a flat colour where the design wants something to look at.
+//   1. Photos come from museum open-access collections that publish a licence flag per object: The Met
+//      (collectionapi.metmuseum.org, /public/collection/v1.1/search then /v1/objects/{id}; kept only when
+//      isPublicDomain === true) and the Cleveland Museum of Art (openaccess-api.clevelandart.org; kept only when
+//      share_license_status === "CC0"). The flag is read from the API for every single item and anything not
+//      explicitly CC0 / public domain is dropped; palate never infers a licence. No key, no login.
+//   2. Politely: a few requests at a time per host, a shared pause and a retry with backoff when a museum says
+//      403 / 429 / 5xx, timeouts on every call, a User-Agent that names palate, no scraping, no bot-wall or
+//      Referer tricks (that is why the Art Institute of Chicago is not a source). Answers are cached for two hours
+//      in the project's .palate folder, so a repeated or overlapping search costs nothing. Unsplash and Pexels
+//      need the user's own key and their attribution / hotlinking rules, so they are not built in yet.
+//   3. The agent sees contact sheets of the candidates (thumbnails with ids and pixel sizes, 12 to a sheet),
+//      picks by eye, and `pickImages` downloads the chosen files into the project's own public folder
+//      (self-hosted, never hotlinked) as web-sized JPEGs, with a museum mount trimmed when one is found and a
+//      credits.json beside them. CC0 needs no credit; palate credits anyway (title, artist, date, museum).
+//   4. One treatment for every photo on the page (duotone, tone or grain, in CSS with no dependencies) so museum
+//      objects read as the site's material, not as a gallery of borrowed pictures.
+//   5. Material drawn in code (grain, paper, speckle, halftone, linen): deterministic SVG from a seeded PRNG,
+//      written to public/textures/ — no licence question at all, because palate drew it.
+// Everything palate keeps for itself lives in <project>/.palate/imagery/ (gitignored): per search
+// <slug>/candidates.json, the thumbnails and contact sheets; .cache/ (API answers); originals/ (full files).
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const UA = "palate-imagery/0.2 (open-licence image search a person asked for, a few requests at a time; https://github.com/Garvit1000/palate)";
+export const SOURCES = {
+  met: { name: "The Met", search: "https://collectionapi.metmuseum.org/public/collection/v1.1/search", object: "https://collectionapi.metmuseum.org/public/collection/v1/objects/" },
+  cleveland: { name: "Cleveland Museum of Art", search: "https://openaccess-api.clevelandart.org/api/artworks/" },
+  commons: { name: "Wikimedia Commons", search: "https://commons.wikimedia.org/w/api.php" },
+};
+const ALIASES = { met: "met", metmuseum: "met", cleveland: "cleveland", cma: "cleveland", commons: "commons", wikimedia: "commons", wiki: "commons" };
+const FUTURE = { unsplash: "Unsplash (needs the user's own key; hotlinked URLs, photographer credit and a download ping)", pexels: "Pexels (needs the user's own key and a visible Pexels link)" };
+// The Met's medium filter for a Cleveland-style type, where the two agree.
+const MET_MEDIUM = { Ceramic: "Ceramics", Painting: "Paintings", Textile: "Textiles", Photograph: "Photographs", Glass: "Glass", Sculpture: "Sculpture", Drawing: "Drawings", Print: "Prints" };
+export const TYPES = Object.keys(MET_MEDIUM);
+// The command names the CLI exposes (kept here so every line palate prints agrees with the CLI wiring).
+export const CMD = { search: "palate imagery", pick: "palate imagery pick", texture: "palate texture" };
+// Per sheet: 4 across, 3 down, so a sheet stays readable at any count.
+export const SHEET_SIZE = 12;
+
+const sleep = (ms) => (ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve());
+export const slugify = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "images";
+const clean = (s) => String(s ?? "").replace(/\s+/g, " ").trim();
+const num = (v) => (v == null || v === "" || !Number.isFinite(Number(v)) ? undefined : Number(v));
+const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+// Lower case without accents, for comparing names ("Käsebier" and "Kasebier").
+const fold = (s) => String(s ?? "").normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase();
+
+// A person's name rather than a subject: two to four words, every one capitalised or an initial
+// ("Clarence H. White", "Julia Margaret Cameron"). Only decides whether the Met is asked for a maker first.
+export const looksLikeName = (q) => /^(\p{Lu}[\p{L}'’-]*\.?|\p{Lu}\.)(\s+(\p{Lu}[\p{L}'’-]*\.?|\p{Lu}\.|van|von|de|der|du|la|le|da|di)){1,3}$/u.test(clean(q));
+
+function normaliseSources(sources) {
+  const list = (Array.isArray(sources) ? sources : String(sources).split(",")).map((s) => String(s).trim().toLowerCase()).filter(Boolean);
+  const known = [];
+  const notes = [];
+  for (const s of list) {
+    if (ALIASES[s]) known.includes(ALIASES[s]) || known.push(ALIASES[s]);
+    else if (FUTURE[s]) notes.push(`${FUTURE[s]} is not built in yet; skipped.`);
+    else notes.push(`Unknown image source "${s}"; skipped (sources: met, cleveland, commons).`);
+  }
+  return { known, notes };
+}
+
+// ---- requests: a gate per host, retries with backoff, timeouts, and the reason in plain words.
+export class FetchError extends Error {
+  constructor({ status, kind, url, tries, wall, until }) {
+    const host = (() => {
+      try {
+        return new URL(url).host;
+      } catch {
+        return url;
+      }
+    })();
+    const time = (t) => new Date(t).toTimeString().slice(0, 8);
+    const why = until
+      ? `skipped: its bot wall turned palate away a moment ago, so it is left alone until ${time(until)}`
+      : wall
+        ? `403 Forbidden from ${host}: its bot wall turned palate away (too many requests from this machine lately); left alone for ${WALL_MS / 60_000} minutes`
+        : `${status ? statusReason(status) : kind} from ${host}${tries > 1 ? ` after ${tries} tries` : ""}`;
+    super(why);
+    this.status = status;
+    this.kind = status ? String(status) : kind;
+    this.wall = Boolean(wall || until);
+    this.url = url;
+  }
+}
+export function statusReason(status) {
+  if (status === 403) return "403 Forbidden (a rate limit or bot block)";
+  if (status === 429) return "429 Too Many Requests (a rate limit)";
+  if (status === 404) return "404 Not Found";
+  if (status >= 500) return `${status} (the museum's server is down or busy)`;
+  return String(status);
+}
+const RETRYABLE = (s) => s === 403 || s === 408 || s === 425 || s === 429 || s >= 500;
+const BACKOFF = [1000, 3000];
+
+// The least time between two request starts per host. The Met sits behind a bot wall (Imperva) that turned
+// palate away for about a minute after ~33 requests in 3 s, and again after ~100 in 20 s at 5 a second; once
+// it has, it turns a client away again within a few requests for minutes after (measured Nov 2026). The old
+// one-at-a-time search ran at ~2 a second and never met it, so palate stays near 2.5 a second there.
+// Cleveland has no such wall.
+export const PACE = { "collectionapi.metmuseum.org": 400, "images.metmuseum.org": 250, "commons.wikimedia.org": 300, "upload.wikimedia.org": 200 };
+
+// ---- licences palate accepts. Museums: CC0 only. Commons: CC0, public domain and CC BY (any version), read from
+// the file's own licence field. Never share-alike (palate tones and crops photos, and a changed share-alike photo
+// would have to carry that licence), never non-commercial, no-derivatives, GFDL-only or fair use, and never a file
+// marked with restrictions (personality rights, trademarks, insignia).
+const BY = /^CC BY \d(\.\d)?$/;
+export const openLicence = (licence) => licence === "CC0" || licence === "Public domain" || BY.test(licence ?? "");
+export const needsCredit = (licence) => BY.test(licence ?? "");
+export function commonsLicence(meta = {}) {
+  const v = (k) => clean(String(meta[k]?.value ?? "").replace(/<[^>]+>/g, " "));
+  if (v("Restrictions") || /^true$/i.test(v("NonFree"))) return null;
+  const code = v("License").toLowerCase();
+  if (code === "cc0" || code === "cc-zero") return "CC0";
+  if (code === "pd" || /^pd[-_]/.test(code)) return "Public domain";
+  const by = /^cc-by-(\d(?:\.\d)?)$/.exec(code);
+  if (by) return `CC BY ${by[1]}`;
+  return null; // cc-by-sa-*, cc-by-nc-*, gfdl, fair use, anything unknown
+}
+// How long a bot wall is left alone once it has answered (asking again only keeps it up).
+export const WALL_MS = 2 * 60_000;
+
+// At most n requests in flight per host, starts spaced by the host's pace, and one shared pause after a
+// 429 or a plain 403 so every worker backs off together.
+function hostGate(n, pace = 0) {
+  let active = 0;
+  let pauseUntil = 0;
+  let nextStart = 0;
+  const waiting = [];
+  return {
+    async run(fn) {
+      if (active < n) active++;
+      else await new Promise((r) => waiting.push(r)); // the slot is handed over, active stays
+      try {
+        const at = Math.max(Date.now(), nextStart, pauseUntil);
+        nextStart = at + pace;
+        await sleep(at - Date.now());
+        return await fn();
+      } finally {
+        const next = waiting.shift();
+        if (next) next();
+        else active--;
+      }
+    },
+    pause(ms) {
+      pauseUntil = Math.max(pauseUntil, Date.now() + ms);
+    },
+  };
+}
+
+// The shared state of one search or pick: fetch, the host gates, the backoff, the cache, and the bot walls met
+// (kept in the cache too, so the next search in the session leaves that host alone as well).
+export function context({ fetchImpl = fetch, concurrency = 4, backoff = BACKOFF, cache = null, pace = PACE } = {}) {
+  const gates = new Map();
+  const walls = new Map();
+  return {
+    fetchImpl,
+    backoff,
+    cache,
+    gate(url) {
+      const host = new URL(url).host;
+      if (!gates.has(host)) gates.set(host, hostGate(concurrency, pace[host] ?? 0));
+      return gates.get(host);
+    },
+    wallUntil(host) {
+      if (!walls.has(host)) walls.set(host, cache?.get(`wall:${host}`)?.until ?? 0);
+      const t = walls.get(host);
+      return t > Date.now() ? t : 0;
+    },
+    markWall(host) {
+      const until = Date.now() + WALL_MS;
+      walls.set(host, until);
+      cache?.set(`wall:${host}`, { until });
+    },
+  };
+}
+
+// One request, retried after a 429, a 5xx, a plain 403, a timeout or a dropped connection: 1 s then 3 s (or the
+// server's Retry-After, at most 10 s). A bot wall's 403 (an HTML page, not the API's JSON) is not retried: it is
+// remembered for WALL_MS and that host is skipped meanwhile. Resolves { body, headers, status }; body is parsed
+// JSON or a Buffer.
+async function request(ctx, url, { as = "json", timeout = 12_000, range } = {}) {
+  const host = new URL(url).host;
+  const until = ctx.wallUntil?.(host);
+  if (until) throw new FetchError({ status: 403, url, until });
+  const gate = ctx.gate(url);
+  const headers = { "user-agent": UA, accept: as === "json" ? "application/json" : "image/*" };
+  if (range) headers.range = range;
+  for (let i = 0; ; i++) {
+    let out;
+    try {
+      out = await gate.run(async () => {
+        if (ctx.wallUntil?.(host)) return { wall: true };
+        const res = await ctx.fetchImpl(url, { headers, signal: AbortSignal.timeout(timeout) });
+        if (!res.ok) return { status: res.status, headers: res.headers };
+        const body = as === "json" ? await res.json() : Buffer.from(await res.arrayBuffer());
+        return { ok: true, status: res.status, headers: res.headers, body };
+      });
+    } catch (e) {
+      const m = String(e?.name ?? "") + " " + String(e?.message ?? e);
+      const kind = /timeout|abort/i.test(m) ? `timed out after ${Math.round(timeout / 1000)} s` : `network error (${clean(e?.cause?.code ?? e?.message ?? e).slice(0, 60)})`;
+      out = { kind };
+    }
+    if (out.ok) return out;
+    if (out.wall) throw new FetchError({ status: 403, url, until: ctx.wallUntil(host) });
+    if (out.status === 403 && /html/i.test(out.headers?.get?.("content-type") ?? "")) {
+      ctx.markWall?.(host);
+      throw new FetchError({ status: 403, url, wall: true });
+    }
+    const retry = out.kind || RETRYABLE(out.status);
+    if (!retry || i >= ctx.backoff.length) throw new FetchError({ status: out.status, kind: out.kind, url, tries: i + 1 });
+    const after = num(out.headers?.get?.("retry-after"));
+    const wait = after ? Math.min(10_000, after * 1000) : ctx.backoff[i];
+    if (out.status === 403 || out.status === 429) gate.pause(wait);
+    await sleep(wait);
+  }
+}
+
+// A short on-disk cache of API answers in the project (two hours): the same search, or an overlapping one,
+// costs nothing the second time. Only successful answers are kept.
+export function diskCache(dir, ttl = 2 * 3600_000) {
+  if (!dir) return null;
+  const file = (key) => path.join(dir, crypto.createHash("sha1").update(key).digest("hex").slice(0, 24) + ".json");
+  return {
+    get(key) {
+      try {
+        const f = file(key);
+        if (Date.now() - fs.statSync(f).mtimeMs > ttl) return undefined;
+        return JSON.parse(fs.readFileSync(f, "utf8")).body;
+      } catch {
+        return undefined;
+      }
+    },
+    set(key, body) {
+      try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file(key), JSON.stringify({ key, body }));
+      } catch {}
+    },
+    // Drops answers past their time, so the folder never grows for long.
+    prune() {
+      try {
+        for (const f of fs.readdirSync(dir)) {
+          const p = path.join(dir, f);
+          if (Date.now() - fs.statSync(p).mtimeMs > ttl) fs.rmSync(p, { force: true });
+        }
+      } catch {}
+    },
+  };
+}
+
+async function getJson(ctx, url) {
+  const hit = ctx.cache?.get(url);
+  if (hit !== undefined) return hit;
+  const { body } = await request(ctx, url);
+  ctx.cache?.set(url, body);
+  return body;
+}
+
+// Pixel size (and file size) of a remote image from its first bytes: a Range request, since JPEG keeps its
+// size in the header. A second, longer read when a large EXIF / colour profile pushes the size further in.
+export async function remoteSize(ctx, url) {
+  const key = `size:${url}`;
+  const hit = ctx.cache?.get(key);
+  if (hit !== undefined) return hit;
+  for (const end of [32_767, 262_143]) {
+    const res = await request(ctx, url, { as: "buffer", timeout: 10_000, range: `bytes=0-${end}` });
+    const s = imageSize(res.body);
+    const total = num(/\/(\d+)\s*$/.exec(res.headers?.get?.("content-range") ?? "")?.[1]) ?? (res.status === 200 ? res.body.length : undefined);
+    if (s) {
+      const out = { width: s.width, height: s.height, bytes: total ?? null };
+      ctx.cache?.set(key, out);
+      return out;
+    }
+    if (res.status === 200) break; // the server ignored the range: the whole file was read and holds no size
+  }
+  return null;
+}
+
+// Runs fn over items with at most n in flight; fn gets (item, index, stop) and stop() ends the dispatch.
+async function eachLimit(items, n, fn) {
+  let next = 0;
+  let stopped = false;
+  const stop = () => {
+    stopped = true;
+  };
+  await Promise.all(
+    Array.from({ length: Math.max(1, Math.min(n, items.length)) }, async () => {
+      while (!stopped && next < items.length) {
+        const i = next++;
+        await fn(items[i], i, stop);
+      }
+    }),
+  );
+}
+
+const tally = (stats, e) => {
+  const k = e?.status ? statusReason(e.status) : e?.kind ?? "error";
+  stats.failed[k] = (stats.failed[k] ?? 0) + 1;
+};
+
+// One credit line: "Title, Artist, Date. The Met, CC0" or "Title, Author. Wikimedia Commons, CC BY 4.0".
+export function creditLine({ title, artist, culture, date, source, licence = "CC0" }) {
+  const who = clean(artist) || clean(culture);
+  const parts = [clean(title) || "Untitled", who, clean(date)].filter(Boolean);
+  return `${parts.join(", ")}. ${SOURCES[source]?.name ?? source}, ${licence}`;
+}
+
+// ---- Wikimedia Commons: one search call returns files with their licence metadata. Photos only (JPEG), the
+// licence read per file (commonsLicence), a CC BY file kept only when it names its author (the credit needs one).
+export async function searchCommons({ query = "", artist, count = 12, minWidth = 0, fetchImpl = fetch, ctx, stats = {} } = {}) {
+  ctx ??= context({ fetchImpl });
+  Object.assign(stats, { matched: 0, looked: 0, publicDomain: 0, small: 0, failed: {}, by: clean(artist) || null, restricted: 0 });
+  const words = [clean(query), clean(artist) && `"${clean(artist)}"`].filter(Boolean).join(" ");
+  const params = new URLSearchParams({
+    action: "query",
+    format: "json",
+    generator: "search",
+    gsrsearch: `${words} filetype:bitmap${minWidth ? ` filew:>${minWidth - 1}` : ""}`,
+    gsrnamespace: "6",
+    gsrlimit: String(Math.min(50, Math.max(20, count * 4))),
+    prop: "imageinfo",
+    iiprop: "url|size|mime|extmetadata",
+    iiurlwidth: "600",
+    iiextmetadatafilter: "License|LicenseShortName|LicenseUrl|Artist|ObjectName|DateTimeOriginal|Restrictions|NonFree",
+  });
+  const data = await getJson(ctx, `${SOURCES.commons.search}?${params}`);
+  const pages = Object.values(data?.query?.pages ?? {}).sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+  stats.matched = num(data?.query?.searchinfo?.totalhits) ?? pages.length;
+  const out = [];
+  const text = (v) => clean(String(v ?? "").replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ");
+  for (const p of pages) {
+    if (out.length >= count) break;
+    const i = p.imageinfo?.[0];
+    if (!i?.url) continue;
+    stats.looked++;
+    if (!/^image\/jpeg$/i.test(i.mime ?? "")) continue;
+    const licence = commonsLicence(i.extmetadata);
+    if (!licence) {
+      if (text(i.extmetadata?.Restrictions?.value)) stats.restricted++;
+      continue;
+    }
+    const author = text(i.extmetadata?.Artist?.value).slice(0, 80);
+    if (needsCredit(licence) && (!author || /^unknown/i.test(author))) continue;
+    stats.publicDomain++;
+    if (minWidth && num(i.width) && num(i.width) < minWidth) {
+      stats.small++;
+      continue;
+    }
+    const name = text(i.extmetadata?.ObjectName?.value) || clean(String(p.title).replace(/^File:/, "").replace(/\.[a-z]+$/i, "").replace(/_/g, " "));
+    // The year is enough for a credit ("2023-03-01 09:13:55", "Taken on 4 May 2019" → 2023, 2019).
+    const when = text(i.extmetadata?.DateTimeOriginal?.value);
+    const date = /\b(1[6-9]\d\d|20\d\d)\b/.exec(when)?.[1] ?? (when.slice(0, 20) || undefined);
+    // The 2400 px rendition when the original is bigger (a Commons thumb URL differs only in its width).
+    const big = num(i.width) > 2400 && /\/\d+px-[^/]+$/.test(i.thumburl ?? "") ? i.thumburl.replace(/\/\d+px-([^/]+)$/, "/2400px-$1") : i.url;
+    const c = {
+      id: `wc-${p.pageid}`,
+      source: "commons",
+      title: name.slice(0, 90),
+      artist: author || undefined,
+      date,
+      page: i.descriptionurl || `https://commons.wikimedia.org/wiki/${encodeURIComponent(p.title)}`,
+      full: big,
+      thumb: i.thumburl || i.url,
+      width: num(i.width),
+      height: num(i.height),
+      ...(num(i.size) ? { bytes: num(i.size) } : {}),
+      licence,
+      ...(text(i.extmetadata?.LicenseUrl?.value) ? { licenceUrl: text(i.extmetadata.LicenseUrl.value) } : {}),
+    };
+    c.credit = creditLine(c);
+    out.push(c);
+  }
+  return out;
+}
+
+
+// ---- the Met: search (v1.1; v1 search was retired 2026-10-01), then the objects a few at a time. A maker's name
+// is asked as a maker first (artistOrCulture), since a keyword search for a name mostly finds other people's work.
+// Pixel sizes come from the image header (the API has none), so small images can be dropped like Cleveland's.
+export async function searchMet({ query = "", artist, count = 12, type, minWidth = 0, fetchImpl = fetch, gap = 0, ctx, concurrency = 4, maxLookups, sizes = true, budget = 30_000, stats = {} } = {}) {
+  ctx ??= context({ fetchImpl, concurrency });
+  Object.assign(stats, { matched: 0, looked: 0, publicDomain: 0, small: 0, failed: {}, by: null });
+  const params = (q, extra = {}) => {
+    const p = new URLSearchParams({ q, hasImages: "true", limit: String(Math.min(200, Math.max(20, count * 5))), ...extra });
+    if (type && MET_MEDIUM[type]) p.set("medium", MET_MEDIUM[type]);
+    return p;
+  };
+  let found = null;
+  const maker = clean(artist) || (looksLikeName(query) ? clean(query) : "");
+  if (maker) {
+    found = await getJson(ctx, `${SOURCES.met.search}?${params(maker, { artistOrCulture: "true" })}`);
+    if (found?.objectIDs?.length) stats.by = maker;
+  }
+  if (!found?.objectIDs?.length && clean(query)) found = await getJson(ctx, `${SOURCES.met.search}?${params(clean(query))}`);
+  const all = found?.objectIDs ?? [];
+  stats.matched = num(found?.total) ?? all.length;
+  const ids = all.slice(0, maxLookups ?? Math.min(120, Math.max(40, count * 5)));
+  const kept = [];
+  const t0 = Date.now();
+  let refused = 0;
+  await eachLimit(ids, concurrency, async (id, i, stop) => {
+    if (kept.length >= count || stats.blocked) return stop();
+    if (Date.now() - t0 > budget) {
+      stats.outOfTime = true;
+      return stop();
+    }
+    await sleep(gap);
+    let o;
+    try {
+      o = await getJson(ctx, SOURCES.met.object + id);
+      refused = 0;
+    } catch (e) {
+      if (e.status === 404) return; // an id the search still lists but the collection has withdrawn
+      tally(stats, e);
+      // Its bot wall, or three refusals in a row: the Met is blocking for now; stop asking.
+      if (e.wall || ((e.status === 403 || e.status === 429) && ++refused >= 3)) {
+        stats.blocked = e.message;
+        stop();
+      }
+      return;
+    }
+    // A maker search also matches cultures and other fields: keep only that maker's own work (every word of the
+    // name but initials appears among the object's makers).
+    if (stats.by) {
+      const makers = fold([o.artistDisplayName, ...(o.constituents ?? []).map((k) => k?.name)].join(" "));
+      if (!fold(stats.by).split(/[\s.]+/).filter((w) => w.length > 2).every((w) => makers.includes(w))) return;
+    }
+    stats.looked++;
+    // The licence flag, read from the API for this object. Non-public-domain objects also come without images.
+    if (o?.isPublicDomain !== true || !o.primaryImage) return;
+    stats.publicDomain++;
+    const c = {
+      id: `met-${o.objectID ?? id}`,
+      source: "met",
+      title: clean(o.title) || clean(o.objectName),
+      artist: clean(o.artistDisplayName) || undefined,
+      culture: clean(o.culture) || undefined,
+      date: clean(o.objectDate) || undefined,
+      medium: clean(o.medium) || undefined,
+      page: o.objectURL || `https://www.metmuseum.org/art/collection/search/${id}`,
+      full: o.primaryImage,
+      thumb: o.primaryImageSmall || o.primaryImage,
+      licence: "CC0",
+    };
+    if (sizes) {
+      try {
+        const s = await remoteSize(ctx, o.primaryImage);
+        if (s) Object.assign(c, { width: s.width, height: s.height, ...(s.bytes ? { bytes: s.bytes } : {}) });
+      } catch {} // size unknown: kept, shown as such
+    }
+    if (minWidth && c.width && c.width < minWidth) {
+      stats.small++;
+      return;
+    }
+    c.credit = creditLine(c);
+    kept.push([i, c]);
+  });
+  return kept.sort((a, b) => a[0] - b[0]).slice(0, count).map(([, c]) => c);
+}
+
+// ---- Cleveland: one search call; images.print (~3400 px) is the full image, images.web (~900 px) the thumb.
+// A maker goes in artists=, the query words in q= (a name in q= works too: Cleveland searches its creators).
+export async function searchCleveland({ query = "", artist, count = 12, type, minWidth = 0, fetchImpl = fetch, ctx, stats = {} } = {}) {
+  ctx ??= context({ fetchImpl });
+  Object.assign(stats, { matched: 0, looked: 0, publicDomain: 0, small: 0, failed: {}, by: clean(artist) || null });
+  const params = new URLSearchParams({ has_image: "1", limit: String(Math.min(100, Math.max(20, count * 3))) });
+  if (clean(query)) params.set("q", clean(query));
+  if (clean(artist)) params.set("artists", clean(artist));
+  if (type) params.set("type", type);
+  const data = await getJson(ctx, `${SOURCES.cleveland.search}?cc0&${params}`);
+  stats.matched = num(data?.info?.total) ?? data?.data?.length ?? 0;
+  const out = [];
+  for (const a of data?.data ?? []) {
+    if (out.length >= count) break;
+    stats.looked++;
+    // The literal "CC0" (the docs say "Open Access"; the API says CC0). Anything else is dropped.
+    if (a?.share_license_status !== "CC0") continue;
+    stats.publicDomain++;
+    const big = a.images?.print?.url ? a.images.print : a.images?.web;
+    if (!big?.url) continue;
+    const width = num(big.width);
+    if (minWidth && width && width < minWidth) {
+      stats.small++;
+      continue;
+    }
+    const creator = clean(a.creators?.[0]?.description).replace(/\s*\(.*\)\s*$/, "");
+    const c = {
+      id: `cma-${a.id}`,
+      source: "cleveland",
+      title: clean(a.title),
+      artist: creator || undefined,
+      culture: clean(a.culture?.[0]).split(",")[0] || undefined,
+      date: clean(a.creation_date) || undefined,
+      medium: clean(a.technique) || undefined,
+      page: a.url || `https://clevelandart.org/art/${a.accession_number}`,
+      full: big.url,
+      thumb: a.images?.web?.url || big.url,
+      width,
+      height: num(big.height),
+      ...(num(big.filesize) ? { bytes: num(big.filesize) } : {}),
+      licence: "CC0",
+    };
+    c.credit = creditLine(c);
+    out.push(c);
+  }
+  return out;
+}
+
+const SEARCH = { met: searchMet, cleveland: searchCleveland, commons: searchCommons };
+
+// What a source did, in one line, when it needs saying: it failed (and why), was blocked part-way, matched
+// nothing, or matched only work that isn't public domain.
+export function sourceNote(name, st, { query, artist, error } = {}) {
+  const what = artist ? `works by "${artist}"` : `"${query}"`;
+  if (error) return `${name} failed: ${error}. ${name === "The Met" ? "Showing the other source's results; it lets palate in again after a minute or two, or use --sources cleveland." : "Showing the other source's results."}`;
+  const failed = Object.entries(st.failed ?? {});
+  const fails = failed.reduce((n, [, k]) => n + k, 0);
+  const parts = [];
+  if (st.blocked) parts.push(`${name} stopped answering part-way (${st.blocked}); ${plural(st.kept ?? 0, "candidate")} from it. It lets palate in again after a minute or two.`);
+  else if (fails) parts.push(`${name}: ${fails} of ${fails + st.looked} lookups failed (${failed.map(([k, n]) => `${n}× ${k}`).join(", ")}), even after retrying.`);
+  if (!st.matched) parts.push(`${name}: nothing matches ${what}.${!artist && clean(query).split(" ").length > 1 ? " Fewer words find more (each word must match)." : ""}`);
+  else if (!st.kept && st.looked && !st.publicDomain) parts.push(`${name}: ${plural(st.matched, "work")} match${st.matched === 1 ? "es" : ""} ${what}${st.by && !artist ? " (by that maker)" : ""}, but none of the ${st.looked} looked at is public domain.`);
+  if (st.small) parts.push(`${name}: ${st.small} too small (narrower than the minimum width) left out.`);
+  if (st.outOfTime) parts.push(`${name}: stopped looking after ${st.looked} objects to stay quick.`);
+  return parts.join(" ");
+}
+
+// Candidates from every source at once, interleaved (one of each in turn) so no single museum fills the sheet.
+// The returned array carries .notes (sources that failed, were blocked or found nothing) and .stats.
+export async function searchImages({ query = "", artist, sources = ["met", "cleveland"], count = 12, minWidth = 1600, type, fetchImpl = fetch, gap = 0, ctx, cache = null, concurrency = 4, backoff, pace } = {}) {
+  if (!clean(query) && !clean(artist)) throw new Error('searchImages needs a query, e.g. "stoneware bowl" (or an artist).');
+  ctx ??= context({ fetchImpl, cache, concurrency, ...(backoff ? { backoff } : {}), ...(pace ? { pace } : {}) });
+  const { known, notes } = normaliseSources(sources);
+  const each = known.length ? Math.ceil(count / known.length) + 2 : 0;
+  const stats = {};
+  const lists = await Promise.all(
+    known.map(async (s) => {
+      stats[s] = {};
+      try {
+        const l = await SEARCH[s]({ query, artist, count: each, type, minWidth, fetchImpl, gap, ctx, concurrency, stats: stats[s] });
+        stats[s].kept = l.length;
+        return l;
+      } catch (e) {
+        stats[s].error = e.message;
+        return [];
+      }
+    }),
+  );
+  known.forEach((s) => {
+    const n = sourceNote(SOURCES[s].name, stats[s], { query, artist, error: stats[s].error });
+    if (n) notes.push(n);
+  });
+  const out = [];
+  for (let i = 0; out.length < count && lists.some((l) => i < l.length); i++) for (const l of lists) if (i < l.length && out.length < count) out.push(l[i]);
+  // Belt and braces: nothing leaves this function without a licence palate accepts (openLicence).
+  const kept = out.filter((c) => openLicence(c.licence));
+  kept.notes = notes;
+  kept.stats = stats;
+  return kept;
+}
+
+// ---- image sizes from the file header (JPEG, PNG, GIF, WebP); no image library. Works on the first bytes alone.
+export function imageSize(buf) {
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+  if (b.length >= 24 && b.readUInt32BE(0) === 0x89504e47) return { width: b.readUInt32BE(16), height: b.readUInt32BE(20), type: "png" };
+  if (b.length >= 10 && b.toString("ascii", 0, 3) === "GIF") return { width: b.readUInt16LE(6), height: b.readUInt16LE(8), type: "gif" };
+  if (b.length >= 30 && b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP") {
+    const kind = b.toString("ascii", 12, 16);
+    if (kind === "VP8X") return { width: 1 + b.readUIntLE(24, 3), height: 1 + b.readUIntLE(27, 3), type: "webp" };
+    if (kind === "VP8 ") return { width: b.readUInt16LE(26) & 0x3fff, height: b.readUInt16LE(28) & 0x3fff, type: "webp" };
+    if (kind === "VP8L") {
+      const bits = b.readUInt32LE(21);
+      return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >> 14) & 0x3fff), type: "webp" };
+    }
+  }
+  if (b.length >= 4 && b[0] === 0xff && b[1] === 0xd8) {
+    let i = 2;
+    while (i + 9 < b.length) {
+      if (b[i] !== 0xff) return null;
+      const m = b[i + 1];
+      if (m === 0xff) {
+        i++;
+        continue;
+      }
+      if (m === 0xd8 || m === 0x01 || (m >= 0xd0 && m <= 0xd7)) {
+        i += 2;
+        continue;
+      }
+      if ((m >= 0xc0 && m <= 0xcf) && m !== 0xc4 && m !== 0xc8 && m !== 0xcc) return { width: b.readUInt16BE(i + 7), height: b.readUInt16BE(i + 5), type: "jpeg" };
+      i += 2 + b.readUInt16BE(i + 2);
+    }
+  }
+  return null;
+}
+
+const EXT = { jpeg: "jpg", png: "png", gif: "gif", webp: "webp" };
+function extOf(url, contentType, buf) {
+  const t = imageSize(buf)?.type;
+  if (t) return EXT[t];
+  if (/png/.test(contentType ?? "")) return "png";
+  if (/webp/.test(contentType ?? "")) return "webp";
+  const m = /\.(jpe?g|png|webp|gif)(?:$|\?)/i.exec(url);
+  return m ? m[1].toLowerCase().replace("jpeg", "jpg") : "jpg";
+}
+
+async function download(ctx, url, timeout = 90_000) {
+  const res = await request(ctx, url, { as: "buffer", timeout });
+  return { buf: res.body, type: res.headers?.get?.("content-type") ?? "" };
+}
+
+// ---- museum mounts: the card an old photograph is pasted on, scanned with it (often on a backdrop as well).
+// Pure, deterministic, and run on a small copy of the image (RGBA pixels, w × h). It must stay self-contained:
+// the browser runs its source. A border line is one that is mostly a single colour (its own median: a card's
+// tone drifts with age and light, and a backdrop and a card are two colours), scanned inward from each side to
+// the print's edge. It is a mount only when all four sides have a band and every edge is sharp and straight
+// (just inside it, the print is mostly not border); an object on a plain backdrop (a bowl) has no straight
+// edge on its sides, so it is never cropped.
+// Returns null (no border), { trim: false, sides, colour } (a border on some sides only: flagged, not cut) or
+// { trim: true, top, right, bottom, left, colour } (pixels to cut from each side, a small inset included).
+export function findMount(px, w, h) {
+  const TOL = 34; // per channel: card texture, foxing and scan noise
+  const MOUNT = 0.9; // a line is border when this share of it is within TOL of its own colour
+  const CONTENT = 0.5; // just inside the edge, at most this share may still be the border's colour
+  if (w < 40 || h < 40) return null;
+  const median = (a) => a.slice().sort((x, y) => x - y)[a.length >> 1];
+  const near = (p, c) => Math.abs(px[p] - c[0]) <= TOL && Math.abs(px[p + 1] - c[1]) <= TOL && Math.abs(px[p + 2] - c[2]) <= TOL;
+  const at = (horiz, i, j) => (horiz ? i * w + j : j * w + i) * 4;
+  // Row i (horiz) or column i, over [a, b): the share of it within TOL of colour c.
+  const share = (horiz, i, a, b, c) => {
+    let n = 0;
+    for (let j = a; j < b; j++) if (near(at(horiz, i, j), c)) n++;
+    return b > a ? n / (b - a) : 1;
+  };
+  const colourOf = (horiz, i, a, b) => {
+    const ch = [[], [], []];
+    const step = Math.max(1, Math.floor((b - a) / 200));
+    for (let j = a; j < b; j += step) for (let k = 0; k < 3; k++) ch[k].push(px[at(horiz, i, j) + k]);
+    return ch.map(median);
+  };
+  const isBorder = (horiz, i, span) => {
+    const c = colourOf(horiz, i, span[0], span[1]);
+    return share(horiz, i, span[0], span[1], c) >= MOUNT ? c : null;
+  };
+  // From one side inward while the line is border; a thin interruption (a pencil rule, a blind stamp) is
+  // stepped over. Returns the band's depth and the colour of its innermost line.
+  const scan = (horiz, from, dir, len, span) => {
+    const n = Math.floor(len / 2);
+    const skip = Math.max(2, Math.round(len * 0.006));
+    let d = 0;
+    let colour = null;
+    while (d < n) {
+      const c = isBorder(horiz, from + dir * d, span);
+      if (c) {
+        colour = c;
+        d++;
+        continue;
+      }
+      let again = 0;
+      for (let k = 1; k <= skip && d + k < n && !again; k++) if (isBorder(horiz, from + dir * (d + k), span)) again = k;
+      if (!again) break;
+      d += again;
+    }
+    return { d: Math.min(d, n), colour };
+  };
+  // Twice: first across whole lines, then across the span left between the other two sides' bands.
+  let top, right, bottom, left;
+  let T = 0, R = 0, B = 0, L = 0;
+  for (let pass = 0; pass < 2; pass++) {
+    const hx = [L, w - R];
+    const vy = [T, h - B];
+    top = scan(true, 0, 1, h, hx);
+    bottom = scan(true, h - 1, -1, h, hx);
+    left = scan(false, 0, 1, w, vy);
+    right = scan(false, w - 1, -1, w, vy);
+    [T, R, B, L] = [top.d, right.d, bottom.d, left.d];
+  }
+  const bands = [top, right, bottom, left];
+  const depth = [T / h, R / w, B / h, L / w];
+  const hexOf = (c) => "#" + c.map((v) => v.toString(16).padStart(2, "0")).join("");
+  const sides = depth.filter((x) => x >= 0.012).length;
+  if (!sides) return null;
+  // The edge must be sharp: a few lines inside it the print is mostly not the border's colour.
+  const k = (len) => Math.max(2, Math.round(len * 0.015));
+  const inside = [
+    top.colour && share(true, Math.min(h - 1, T + k(h)), L, w - R, top.colour),
+    right.colour && share(false, Math.max(0, w - 1 - R - k(w)), T, h - B, right.colour),
+    bottom.colour && share(true, Math.max(0, h - 1 - B - k(h)), L, w - R, bottom.colour),
+    left.colour && share(false, Math.min(w - 1, L + k(w)), T, h - B, left.colour),
+  ];
+  const sharp = inside.every((s) => s !== null && s <= CONTENT);
+  const area = ((w - L - R) * (h - T - B)) / (w * h);
+  if (sides < 4 || !sharp || area < 0.3) {
+    // Flagged, not cut: deep bands of one colour on two or more sides (a card cut unevenly, a caption below).
+    const deep = bands.filter((b, i) => depth[i] >= 0.03 && b.colour);
+    const agree = deep.length >= 2 && deep.every((b) => b.colour.every((v, j) => Math.abs(v - deep[0].colour[j]) <= TOL));
+    return agree ? { trim: false, sides: deep.length, colour: hexOf(deep[0].colour) } : null;
+  }
+  // A little past the edge, so no sliver of card or the print's soft border is left.
+  const ix = Math.round(w * 0.006);
+  const iy = Math.round(h * 0.006);
+  return { trim: true, top: T + iy, right: R + ix, bottom: B + iy, left: L + ix, colour: hexOf(top.colour) };
+}
+
+// One canvas pass in the browser palate already uses (no image library): finds a mount (and trims it unless
+// trim is false), scales the longest side down to maxSide and encodes a JPEG at quality. Returns
+// { buf, width, height, mount } or null when it can't (no browser, or a file the browser can't decode).
+export async function processImage(buf, type, { maxSide = 2400, quality = 0.82, trim = true, browser } = {}) {
+  let release = async () => {};
+  try {
+    if (!browser) {
+      const { acquireBrowser } = await import("../pool.mjs");
+      ({ browser, release } = await acquireBrowser());
+    }
+    const page = await browser.newPage();
+    try {
+      const r = await page.evaluate(
+        async ([src, maxSide, quality, trim, finder]) => {
+          const img = new Image();
+          img.src = src;
+          await img.decode();
+          const W = img.naturalWidth;
+          const H = img.naturalHeight;
+          let crop = { x: 0, y: 0, w: W, h: H };
+          // The mount is looked for on a copy at most 800 px long: quick, and it evens out the card's grain.
+          const a = Math.min(1, 800 / Math.max(W, H));
+          const aw = Math.max(1, Math.round(W * a));
+          const ah = Math.max(1, Math.round(H * a));
+          const sc = document.createElement("canvas");
+          sc.width = aw;
+          sc.height = ah;
+          const sx = sc.getContext("2d", { willReadFrequently: true });
+          sx.drawImage(img, 0, 0, aw, ah);
+          const find = new Function(`return (${finder})`)();
+          const mount = find(sx.getImageData(0, 0, aw, ah).data, aw, ah);
+          if (trim && mount?.trim) {
+            const x = Math.round(mount.left / a);
+            const y = Math.round(mount.top / a);
+            crop = { x, y, w: Math.max(1, Math.round((aw - mount.right) / a) - x), h: Math.max(1, Math.round((ah - mount.bottom) / a) - y) };
+          }
+          const s = Math.min(1, maxSide / Math.max(crop.w, crop.h));
+          const c = document.createElement("canvas");
+          c.width = Math.round(crop.w * s);
+          c.height = Math.round(crop.h * s);
+          const ctx = c.getContext("2d");
+          ctx.imageSmoothingQuality = "high";
+          ctx.drawImage(img, crop.x, crop.y, crop.w, crop.h, 0, 0, c.width, c.height);
+          return { data: c.toDataURL("image/jpeg", quality), width: c.width, height: c.height, mount, crop: trim && mount?.trim ? crop : null };
+        },
+        [`data:${type || "image/jpeg"};base64,${buf.toString("base64")}`, maxSide, quality, trim, findMount.toString()],
+      );
+      return { buf: Buffer.from(r.data.split(",")[1], "base64"), width: r.width, height: r.height, mount: r.mount, crop: r.crop };
+    } finally {
+      await page.close();
+    }
+  } catch {
+    return null;
+  } finally {
+    await release();
+  }
+}
+
+// Kept for callers of the old name: scales to maxWidth, no trim.
+export async function resizeImage(buf, type, maxWidth) {
+  return (await processImage(buf, type, { maxSide: maxWidth, trim: false, quality: 0.86 }))?.buf ?? null;
+}
+
+export const imageryRoot = (dir) => path.join(dir, ".palate", "imagery");
+
+const sizeLabel = (c) => (c.width && c.height ? `${c.width}×${c.height}` : "size ?");
+
+// ---- `palate imagery "<query>"`: candidates.json + contact sheets, and text telling the agent what's next.
+// Museum and Commons answers barely change: one cache for every project on this machine, kept a week, so the same
+// search in the next project (or the next round) costs nothing. Thumbnails stay in each project's own search folder.
+export const IMAGERY_CACHE_TTL = 7 * 24 * 3600_000;
+export const imageryCacheDir = () => process.env.PALATE_IMAGERY_CACHE || path.join(process.env.PALATE_HOME ?? path.join(os.homedir(), ".palate"), "cache", "imagery");
+
+export async function imagery(dir, query, { count = 12, sources = ["met", "cleveland"], name, type, artist, minWidth = 1600, fetchImpl = fetch, gap = 0, sheet = true, refresh = false, backoff, pace, concurrency = 4, ctx: shared } = {}) {
+  query = clean(query);
+  artist = clean(artist) || undefined;
+  if (type && !TYPES.includes(type)) {
+    const t = TYPES.find((x) => x.toLowerCase() === String(type).toLowerCase().replace(/s$/, ""));
+    if (!t) throw new Error(`Unknown --type "${type}" (${TYPES.join(", ")}).`);
+    type = t;
+  }
+  const slug = slugify(name || [query, artist].filter(Boolean).join(" ") || "images");
+  const root = path.join(imageryRoot(dir), slug);
+  fs.mkdirSync(path.join(root, "thumbs"), { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  const cache = shared ? null : refresh ? null : diskCache(imageryCacheDir(), IMAGERY_CACHE_TTL);
+  cache?.prune();
+  const ctx = shared ?? context({ fetchImpl, cache, concurrency, ...(backoff ? { backoff } : {}), ...(pace ? { pace } : {}) });
+  // The browser starts while the museums answer.
+  const pool = sheet ? import("../pool.mjs").then((p) => p.acquireBrowser()).catch((e) => ({ error: e })) : null;
+  let candidates;
+  try {
+    candidates = await searchImages({ query, artist, sources, count, minWidth, type, fetchImpl, gap, ctx });
+  } catch (e) {
+    pool?.then((p) => p.release?.());
+    throw e;
+  }
+  const notes = [...(candidates.notes ?? [])];
+  fs.writeFileSync(path.join(root, "candidates.json"), JSON.stringify({ query, artist, sources, type, at: new Date().toISOString(), candidates: [...candidates] }, null, 2));
+
+  const sheets = [];
+  if (pool) {
+    const got = await pool;
+    try {
+      if (candidates.length) {
+        // Thumbnails a few at a time per host, each with a timeout; a failed one leaves a labelled gap.
+        const thumbs = new Array(candidates.length);
+        await eachLimit(candidates, concurrency * 2, async (c, i) => {
+          const f = path.join(root, "thumbs", `${c.id}.jpg`);
+          const caption = `${c.id} · ${sizeLabel(c)} · ${c.title.slice(0, 26)}`;
+          try {
+            if (!fs.existsSync(f)) fs.writeFileSync(f, (await download(ctx, c.thumb, 20_000)).buf);
+            thumbs[i] = { caption, file: f };
+          } catch (e) {
+            thumbs[i] = { caption, note: `thumbnail failed: ${e.message}` };
+          }
+        });
+        for (const f of fs.readdirSync(root)) if (/^contact(-\d+)?\.png$/.test(f)) fs.rmSync(path.join(root, f), { force: true });
+        if (got.error) throw got.error;
+        const { contactSheet } = await import("../look.mjs");
+        for (let p = 0; p < thumbs.length; p += SHEET_SIZE) {
+          const page = thumbs.slice(p, p + SHEET_SIZE);
+          const rows = [];
+          for (let i = 0; i < page.length; i += 4) rows.push({ cells: page.slice(i, i + 4) });
+          const file = path.join(root, p ? `contact-${p / SHEET_SIZE + 1}.png` : "contact.png");
+          sheets.push(await contactSheet(got.browser, rows, file, { cell: 260, maxCell: 260 }));
+        }
+      }
+    } catch (e) {
+      notes.push(`Contact sheet skipped (${String(e.message).split("\n")[0]}); the thumbnails are in ${path.join(root, "thumbs")}.`);
+    } finally {
+      await got.release?.();
+    }
+  }
+
+  const label = [query && `"${query}"`, artist && `--artist "${artist}"`, type && `--type ${type}`].filter(Boolean).join(" ");
+  const bySource = Object.keys(SOURCES).map((s) => [SOURCES[s].name, candidates.filter((c) => c.source === s).length]).filter(([, n]) => n);
+  const out = [`${CMD.search} ${label}: ${candidates.length} open-licence candidate${candidates.length === 1 ? "" : "s"}${bySource.length ? ` (${bySource.map(([n, k]) => `${k} ${n}`).join(", ")})` : ""}.`];
+  // What went wrong with a source comes first, where it can't be missed.
+  for (const n of notes) out.push(`Note: ${n}`);
+  if (!candidates.length) {
+    out.push(`Nothing CC0 matched. Try a plainer object word ("bowl", "vase", "textile", "landscape"), --type (${TYPES.join(", ")}), --artist "<name>" for one maker, or the other source.`);
+  } else {
+    if (sheets.length === 1) out.push(`Contact sheet: ${sheets[0]} — open it and choose by eye: the subject, room to crop, the light, one family of colour across every pick.`);
+    else if (sheets.length) out.push(`Contact sheets (${SHEET_SIZE} to a sheet): ${sheets.join(" , ")} — open them and choose by eye: the subject, room to crop, the light, one family of colour across every pick.`);
+    out.push("");
+    for (const c of candidates) out.push(`  ${c.id.padEnd(12)} ${c.credit}  [${sizeLabel(c)}${c.bytes ? `, ${(c.bytes / 1048576).toFixed(1)} MB` : ""}]`);
+    out.push("");
+    out.push(`Next: ${CMD.pick} <id> [<id> …] --from ${slug}  (downloads into the project's public folder as web-sized JPEGs, longest side 2400 px, a museum mount trimmed; records credits.json)`);
+    out.push("Every candidate carries its source's own licence flag (museums: CC0; Commons: CC0, public domain or CC BY). Use one treatment for every photo on the page (duotone, tone or grain).");
+    if (candidates.some((c) => needsCredit(c.licence))) out.push("CC BY photos need their credit on the page (title, author, licence, and that it was changed): palate imagery pick writes the line, and palate guard checks it is there.");
+  }
+  out.push(`Candidates: ${path.join(root, "candidates.json")}`);
+  return out.join("\n");
+}
+
+// ---- `palate imagery "a | b | c"`: every search a page needs, in one call. The searches run side by side on one
+// shared context (so the museums' pacing and bot walls are respected across all of them, not per search) and one
+// cache; each keeps its own folder, candidates and contact sheet. On a benchmark page the planner ran 60 searches
+// one at a time (about 37 minutes); one or two batches of 6 to 12 cover a page.
+export const splitQueries = (q) => (Array.isArray(q) ? q : String(q).split(/\s*\|\s*|\n+/)).map((x) => clean(x)).filter(Boolean);
+export async function imageryMany(dir, queries, { count = 8, sources, type, minWidth, fetchImpl = fetch, refresh = false, backoff, pace, concurrency = 4, sheet = true, parallel = 3 } = {}) {
+  queries = [...new Set(splitQueries(queries))].slice(0, 16);
+  if (!queries.length) throw new Error('Give the searches, e.g. palate imagery "wedding party | street at dusk | hands"');
+  if (queries.length === 1) return imagery(dir, queries[0], { count, sources, type, minWidth, fetchImpl, refresh, backoff, pace, concurrency, sheet });
+  const cache = refresh ? null : diskCache(imageryCacheDir(), IMAGERY_CACHE_TTL);
+  cache?.prune();
+  const ctx = context({ fetchImpl, cache, concurrency, ...(backoff ? { backoff } : {}), ...(pace ? { pace } : {}) });
+  const t0 = Date.now();
+  const results = new Array(queries.length);
+  await eachLimit(queries, parallel, async (q, i) => {
+    try {
+      results[i] = await imagery(dir, q, { count, sources, type, minWidth, fetchImpl, ctx, sheet });
+    } catch (e) {
+      results[i] = `${CMD.search} "${q}": failed (${e.message})`;
+    }
+  });
+  const found = results.map((r) => Number(/: (\d+) open-licence candidate/.exec(r)?.[1] ?? 0));
+  const head = [
+    `${queries.length} searches in one go, ${Math.round((Date.now() - t0) / 1000)} s: ${found.reduce((a, b) => a + b, 0)} candidates (${queries.map((q, i) => `"${q}" ${found[i]}`).join(", ")}).`,
+    "Open each search's contact sheet and pick across all of them at once (one family of colour and light for the whole page); a second batch only for a slot that is still empty. Then one pick for everything:",
+    `  ${CMD.pick} <id> [<id> …]   (ids from any of these searches)`,
+    "",
+  ];
+  return [...head, ...results.map((r) => r.replace(/\nNext: [^\n]*/, ""))].join("\n\n");
+}
+
+// The project's static folder: public/ (Next, Vite, Astro, Nuxt …) or static/ (SvelteKit); public/ by default.
+export function publicDir(dir) {
+  for (const d of ["public", "static"]) if (fs.existsSync(path.join(dir, d))) return d;
+  return "public";
+}
+
+function findCandidates(dir, ids, slug) {
+  const root = imageryRoot(dir);
+  const slugs = slug ? [slug] : fs.existsSync(root) ? fs.readdirSync(root).filter((s) => fs.existsSync(path.join(root, s, "candidates.json"))).sort((a, b) => fs.statSync(path.join(root, b, "candidates.json")).mtimeMs - fs.statSync(path.join(root, a, "candidates.json")).mtimeMs) : [];
+  const found = new Map();
+  for (const s of slugs) {
+    const f = path.join(root, s, "candidates.json");
+    if (!fs.existsSync(f)) continue;
+    for (const c of JSON.parse(fs.readFileSync(f, "utf8")).candidates ?? []) if (ids.includes(c.id) && !found.has(c.id)) found.set(c.id, c);
+  }
+  return found;
+}
+
+// A one-line credits paragraph for the whole page: "Images: Bowl (China, 14th century), The Met; … Public domain (CC0)."
+// A CC BY photo's item names its author, the licence and that it was changed (resized, toned), as CC BY asks.
+export function creditsParagraph(entries) {
+  if (!entries.length) return "";
+  const items = entries.map((e) => {
+    const who = [e.artist || e.culture, e.date].filter(Boolean).join(", ");
+    const by = needsCredit(e.licence) ? `, ${e.licence}${e.changed ? `, ${e.changed}` : ""}` : "";
+    return `${e.title}${who ? ` (${who})` : ""}, ${SOURCES[e.source]?.name ?? e.source}${by}`;
+  });
+  const credited = entries.filter((e) => needsCredit(e.licence)).length;
+  return `Images: ${items.join("; ")}.${!credited ? " Public domain (CC0)." : credited < entries.length ? " The rest public domain." : ""}`;
+}
+
+// A file ships as it came only when it is already a modest JPEG with nothing to trim.
+const SHIP_AS_IS = 1.2 * 1048576;
+
+// ---- `palate imagery pick <ids>`: download, trim a mount, web-size, self-host, record credits.
+export async function pickImages(dir, ids, { out, maxWidth = 2400, quality = 0.82, trim = true, slug, fetchImpl = fetch, gap = 0, backoff, pace, processImage: proc = processImage } = {}) {
+  ids = [...new Set((Array.isArray(ids) ? ids : String(ids).split(/[\s,]+/)).map((s) => s.trim()).filter(Boolean))];
+  if (!ids.length) throw new Error(`Name the candidates to keep, e.g. ${CMD.pick} met-49209 cma-125978.`);
+  const found = findCandidates(dir, ids, slug);
+  const missing = ids.filter((id) => !found.has(id));
+  if (missing.length) throw new Error(`Not in ${slug ? `.palate/imagery/${slug}` : "any .palate/imagery search"}: ${missing.join(", ")}. Run ${CMD.search} "<query>" first and use the ids it prints.`);
+
+  const pub = publicDir(dir);
+  const outRel = out ?? `${pub}/images/palate`;
+  const outDir = path.resolve(dir, outRel);
+  fs.mkdirSync(outDir, { recursive: true });
+  const pubAbs = path.resolve(dir, pub);
+  const webPath = (f) => {
+    const rel = path.relative(pubAbs, f);
+    return rel.startsWith("..") || path.isAbsolute(rel) ? path.relative(dir, f).split(path.sep).join("/") : "/" + rel.split(path.sep).join("/");
+  };
+  const ctx = context({ fetchImpl, concurrency: 3, ...(backoff ? { backoff } : {}), ...(pace ? { pace } : {}) });
+  const keep = path.join(imageryRoot(dir), "originals");
+
+  // Downloads in parallel (a few per host); then one canvas pass each, in order.
+  const jobs = ids.map((id) => {
+    const c = found.get(id);
+    if (!openLicence(c.licence)) return { id, c, skip: true };
+    const existing = fs.readdirSync(outDir).find((f) => f.startsWith(`${id}.`) && /\.(jpe?g|png|webp|gif)$/i.test(f));
+    return { id, c, existing };
+  });
+  await eachLimit(jobs.filter((j) => !j.skip && !j.existing), 6, async (j) => {
+    await sleep(gap);
+    try {
+      j.got = await download(ctx, j.c.full);
+    } catch (e) {
+      j.error = e.message;
+    }
+  });
+
+  const lines = [];
+  const picked = [];
+  for (const j of jobs) {
+    const { id, c } = j;
+    if (j.skip) {
+      lines.push(`  ${id}: skipped, its licence (${c.licence ?? "none"}) isn't one palate uses.`);
+      continue;
+    }
+    if (j.error) {
+      lines.push(`  ${id}: download failed (${j.error}); try again in a minute.`);
+      continue;
+    }
+    let file, buf, mount = null, original = null;
+    if (j.existing) {
+      file = path.join(outDir, j.existing);
+      buf = fs.readFileSync(file);
+    } else {
+      buf = j.got.buf;
+      const ext = extOf(c.full, j.got.type, buf);
+      const orig = imageSize(buf);
+      original = { width: orig?.width ?? null, height: orig?.height ?? null, bytes: buf.length };
+      const done = process.env.PALATE_NO_RESIZE ? null : await proc(buf, j.got.type, { maxSide: maxWidth, quality, trim });
+      const trimmed = done?.mount?.trim && trim;
+      mount = done?.mount ?? null;
+      const changed = done && (trimmed || Math.max(orig?.width ?? 0, orig?.height ?? 0) > maxWidth || buf.length > SHIP_AS_IS || ext !== "jpg");
+      if (changed) {
+        // The original stays in .palate (gitignored); the project gets the web-sized JPEG.
+        fs.mkdirSync(keep, { recursive: true });
+        fs.writeFileSync(path.join(keep, `${id}.${ext}`), buf);
+        buf = done.buf;
+        file = path.join(outDir, `${id}.jpg`);
+      } else file = path.join(outDir, `${id}.${ext}`);
+      fs.writeFileSync(file, buf);
+    }
+    const size = imageSize(buf) ?? { width: c.width, height: c.height };
+    const mb = (buf.length / 1048576).toFixed(1);
+    const long = Math.max(size.width ?? 0, size.height ?? 0) > maxWidth ? ` — longer than ${maxWidth}px and couldn't be resized here: resize it before shipping` : "";
+    const was = original && (original.width !== size.width || original.bytes !== buf.length) ? ` (from ${original.width ?? "?"}×${original.height ?? "?"}, ${(original.bytes / 1048576).toFixed(1)} MB)` : "";
+    lines.push(`  ${webPath(file)}  ${size.width ?? "?"}×${size.height ?? "?"}, ${mb} MB${was}${j.existing ? " (already here)" : ""}${long}`);
+    let mountNote = null;
+    if (mount?.trim && trim) mountNote = `museum mount (${mount.colour}) trimmed`;
+    else if (mount?.trim) mountNote = `museum mount (${mount.colour}) found, kept (--no-trim)`;
+    else if (mount) mountNote = `a border on ${mount.sides} sides looks like a museum mount but has no straight edge all round; not trimmed (crop it with object-fit / object-position)`;
+    if (mountNote) lines.push(`    ${mountNote}`);
+    lines.push(`    ${c.credit}  ${c.page}`);
+    const prev = (() => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(outDir, "credits.json"), "utf8")).find((e) => e.file === webPath(file));
+      } catch {
+        return undefined;
+      }
+    })();
+    picked.push({
+      file: webPath(file),
+      title: c.title,
+      artist: c.artist ?? null,
+      culture: c.culture ?? null,
+      date: c.date ?? null,
+      source: c.source,
+      page: c.page,
+      licence: c.licence,
+      ...(c.licenceUrl ? { licenceUrl: c.licenceUrl } : {}),
+      ...(needsCredit(c.licence) ? { attribution: true, changed: "resized" } : {}),
+      credit: c.credit,
+      width: size.width ?? null,
+      height: size.height ?? null,
+      ...(j.existing ? { original: prev?.original, mount: prev?.mount } : { original: original ?? undefined, mount: mountNote ?? undefined }),
+    });
+  }
+
+  // Merge into credits.json by file; earlier picks stay.
+  const creditsFile = path.join(outDir, "credits.json");
+  let credits = [];
+  try {
+    credits = JSON.parse(fs.readFileSync(creditsFile, "utf8"));
+    if (!Array.isArray(credits)) credits = [];
+  } catch {}
+  for (const p of picked) {
+    const i = credits.findIndex((e) => e.file === p.file);
+    if (i >= 0) credits[i] = p;
+    else credits.push(p);
+  }
+  fs.writeFileSync(creditsFile, JSON.stringify(credits, null, 2) + "\n");
+
+  return [
+    `Kept ${picked.length} image${picked.length === 1 ? "" : "s"} in ${path.relative(dir, outDir).split(path.sep).join("/")}/ (self-hosted; never hotlink the museum; originals in .palate/imagery/originals):`,
+    ...lines,
+    "",
+    `Credits (${path.relative(dir, creditsFile).split(path.sep).join("/")}), ready to paste in the footer or a colophon:`,
+    `  ${creditsParagraph(credits)}`,
+    "Give every <img> real alt text (what the object is, not \"image\"), width and height, and one shared treatment.",
+  ].join("\n");
+}
+
+// ---- treatments: one for every photo on the page. Pure CSS (an SVG filter as a data URI for duotone).
+function hex(c) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(c).trim());
+  if (!m) throw new Error(`Expected a hex colour like #2b1d14, got "${c}".`);
+  const h = m[1].length === 3 ? [...m[1]].map((x) => x + x).join("") : m[1];
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+}
+const r3 = (n) => Math.round(n * 1000) / 1000;
+const svgUrl = (svg) => `url("data:image/svg+xml,${encodeURIComponent(svg).replace(/'/g, "%27")}")`;
+
+export function duotoneFilter(shadow, highlight) {
+  const s = hex(shadow);
+  const h = hex(highlight);
+  const L = [0.2126, 0.7152, 0.0722];
+  const rows = [0, 1, 2].map((i) => [...L.map((w) => r3((h[i] - s[i]) * w)), 0, r3(s[i])].join(" "));
+  return `<svg xmlns='http://www.w3.org/2000/svg'><filter id='palate-duotone' color-interpolation-filters='sRGB'><feColorMatrix type='matrix' values='${rows.join("  ")}  0 0 0 1 0'/></filter></svg>`;
+}
+
+// treatmentCss("duotone" | "tone" | "natural" | "grain" | "duotone+grain", { shadow, highlight, colour, opacity, selector })
+// One treatment for every photo on the page: wrap each photo in <figure class="palate-photo"><img …></figure>.
+export function treatmentCss(name, { shadow = "#1f1a17", highlight = "#f3ece2", colour, opacity = 0.35, selector = ".palate-photo" } = {}) {
+  const parts = String(name).split("+").map((s) => s.trim()).filter(Boolean);
+  const css = [`/* palate treatment: ${parts.join(" + ")}. One treatment for every photo on the page: wrap each photo as <figure class="${selector.replace(/^\./, "")}"><img …></figure>. */`];
+  css.push(`${selector} { position: relative; overflow: hidden; margin: 0; isolation: isolate; }`, `${selector} img { display: block; width: 100%; height: 100%; object-fit: cover; }`);
+  for (const p of parts) {
+    // Blend modes, not an SVG filter: Chrome drew no photo at all for a filter referenced by a data URI. The duotone:
+    // a grey photo multiplied onto the highlight (its darks go black), then the shadow colour lightened over it
+    // (black becomes the shadow). Its own layers, so a darker figure background set elsewhere can't turn it black.
+    if (p === "duotone") {
+      hex(shadow);
+      hex(highlight);
+      css.push(`${selector} { background: ${highlight} !important; }`, `${selector} img { filter: grayscale(1) contrast(1.08); mix-blend-mode: multiply; }`, `${selector}::before { content: ""; position: absolute; inset: 0; z-index: 1; pointer-events: none; background: ${shadow}; mix-blend-mode: lighten; }`);
+    } else if (p === "tone") {
+      // Grey, then one colour laid over as hue only: the photo keeps its light and dark whatever is behind it.
+      hex(colour ?? highlight);
+      css.push(`${selector} img { filter: grayscale(1) contrast(1.06); }`, `${selector}::before { content: ""; position: absolute; inset: 0; z-index: 1; pointer-events: none; background: ${colour ?? highlight}; mix-blend-mode: color; opacity: 0.6; }`);
+    } else if (p === "natural") {
+      // The photo's own colours, evened out: for objects whose colour is the point (a glaze, a dish, a garment).
+      css.push(`${selector} img { filter: saturate(0.92) contrast(1.03); }`);
+    } else if (p === "grain") {
+      css.push(`${selector}::after { content: ""; position: absolute; inset: 0; pointer-events: none; background-image: ${svgUrl(texture("grain", { colour: "#000000", opacity: 1, seed: 7 }))}; background-size: 200px; opacity: ${opacity}; mix-blend-mode: overlay; }`);
+    } else throw new Error(`Unknown treatment "${p}" (duotone, tone, natural, grain; combine with +, e.g. duotone+grain).`);
+  }
+  return css.join("\n") + "\n";
+}
+
+// ---- textures drawn in code: seeded, deterministic, tileable SVG.
+function seedOf(seed) {
+  if (typeof seed === "number") return seed >>> 0;
+  let h = 2166136261;
+  for (const ch of String(seed)) h = Math.imul(h ^ ch.charCodeAt(0), 16777619);
+  return h >>> 0;
+}
+// mulberry32: a tiny seeded PRNG; the same seed always draws the same texture.
+export function prng(seed = 1) {
+  let a = seedOf(seed) || 1;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const f2 = (n) => String(Math.round(n * 100) / 100);
+
+export const TEXTURES = {
+  grain: "fine film grain (feTurbulence); over photos and flat fills",
+  paper: "paper fibre: soft mottling and short fibres; for warm, printed surfaces",
+  speckle: "seeded dots of varied size, like a glaze speckle or terrazzo; for crafts and ceramics",
+  halftone: "a halftone dot screen with a slow tonal swell; for print and editorial looks",
+  linen: "woven threads crossing; for textile, bookbinding, quiet luxury",
+};
+
+// texture(name, { colour, opacity, seed, size }) → SVG markup (a tile that repeats seamlessly).
+export function texture(name, { colour = "#000000", opacity = 0.12, seed = 1, size } = {}) {
+  hex(colour);
+  const rand = prng(`${name}:${seedOf(seed)}`);
+  const S = size ?? (name === "grain" ? 200 : 240);
+  const [r, g, b] = hex(colour).map(r3);
+  const head = `<svg xmlns='http://www.w3.org/2000/svg' width='${S}' height='${S}' viewBox='0 0 ${S} ${S}'>`;
+  const tSeed = Math.floor(rand() * 1000);
+  // Copies of a shape across the tile edges, so the pattern repeats with no seam.
+  const wrap = (x, y, pad, draw) => {
+    let s = "";
+    for (const dx of [0, -S, S]) for (const dy of [0, -S, S]) {
+      const X = x + dx;
+      const Y = y + dy;
+      if (X > -pad && X < S + pad && Y > -pad && Y < S + pad) s += draw(X, Y);
+    }
+    return s;
+  };
+  if (name === "grain") {
+    return `${head}<filter id='g' x='0' y='0' width='100%' height='100%'><feTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='3' seed='${tSeed}' stitchTiles='stitch'/><feColorMatrix type='matrix' values='0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0 0 0 2.2 -0.9'/></filter><rect width='100%' height='100%' filter='url(#g)' opacity='${f2(opacity)}'/></svg>`;
+  }
+  if (name === "paper") {
+    let fibres = "";
+    for (let i = 0; i < 70; i++) {
+      const x = rand() * S;
+      const y = rand() * S;
+      const a = rand() * Math.PI * 2;
+      const len = 6 + rand() * 18;
+      const bend = (rand() - 0.5) * 6;
+      const w = 0.3 + rand() * 0.5;
+      const o = 0.25 + rand() * 0.5;
+      const dx = Math.cos(a) * len;
+      const dy = Math.sin(a) * len;
+      fibres += wrap(x, y, len + 6, (X, Y) => `<path d='M${f2(X)} ${f2(Y)}q${f2(dx / 2 - dy * bend * 0.05)} ${f2(dy / 2 + dx * bend * 0.05)} ${f2(dx)} ${f2(dy)}' stroke-width='${f2(w)}' stroke-opacity='${f2(o)}'/>`);
+    }
+    return `${head}<filter id='m' x='0' y='0' width='100%' height='100%'><feTurbulence type='fractalNoise' baseFrequency='0.035' numOctaves='4' seed='${tSeed}' stitchTiles='stitch'/><feColorMatrix type='matrix' values='0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0 0 0 1.4 -0.55'/></filter><g opacity='${f2(opacity)}'><rect width='100%' height='100%' filter='url(#m)'/><g fill='none' stroke='${colour}' stroke-linecap='round'>${fibres}</g></g></svg>`;
+  }
+  if (name === "speckle") {
+    let dots = "";
+    for (let i = 0; i < 140; i++) {
+      const x = rand() * S;
+      const y = rand() * S;
+      const rad = 0.35 + Math.pow(rand(), 3) * 2.6; // mostly fine, a few large flecks
+      const o = 0.35 + rand() * 0.65;
+      dots += wrap(x, y, rad + 1, (X, Y) => `<circle cx='${f2(X)}' cy='${f2(Y)}' r='${f2(rad)}' fill-opacity='${f2(o)}'/>`);
+    }
+    return `${head}<g fill='${colour}' opacity='${f2(opacity)}'>${dots}</g></svg>`;
+  }
+  if (name === "halftone") {
+    const step = S / 24;
+    const p1 = rand() * Math.PI * 2;
+    const p2 = rand() * Math.PI * 2;
+    let dots = "";
+    for (let j = 0; j < 24; j++) {
+      for (let i = 0; i < 24; i++) {
+        const x = (i + 0.5 + (j % 2) * 0.5) * step;
+        const y = (j + 0.5) * step;
+        // A periodic tone field (whole sine periods across the tile) so the swell tiles too.
+        const tone = 0.5 + 0.25 * Math.sin((2 * Math.PI * x) / S + p1) + 0.25 * Math.sin((4 * Math.PI * y) / S + p2);
+        const rad = step * 0.5 * Math.sqrt(Math.max(0.04, tone));
+        dots += wrap(x, y, rad + 1, (X, Y) => `<circle cx='${f2(X)}' cy='${f2(Y)}' r='${f2(rad)}'/>`);
+      }
+    }
+    return `${head}<g fill='${colour}' opacity='${f2(opacity)}'>${dots}</g></svg>`;
+  }
+  if (name === "linen") {
+    const n = 60;
+    const step = S / n;
+    let lines = "";
+    for (let i = 0; i < n; i++) {
+      const p = (i + 0.5) * step;
+      const wv = f2(step * (0.35 + rand() * 0.45));
+      const wh = f2(step * (0.35 + rand() * 0.45));
+      lines += `<line x1='${f2(p)}' y1='0' x2='${f2(p)}' y2='${S}' stroke-width='${wv}' stroke-opacity='${f2(0.3 + rand() * 0.6)}'/>`;
+      lines += `<line x1='0' y1='${f2(p)}' x2='${S}' y2='${f2(p)}' stroke-width='${wh}' stroke-opacity='${f2(0.3 + rand() * 0.6)}'/>`;
+    }
+    // Slubs: a few thicker runs of thread, as in real linen.
+    for (let i = 0; i < 18; i++) {
+      const horiz = rand() < 0.5;
+      const at = (Math.floor(rand() * n) + 0.5) * step;
+      const from = rand() * S;
+      const len = 8 + rand() * 30;
+      const w = f2(step * 0.9);
+      lines += wrap(from, at, len + 2, (X, Y) => (horiz ? `<line x1='${f2(X)}' y1='${f2(Y)}' x2='${f2(X + len)}' y2='${f2(Y)}' stroke-width='${w}' stroke-opacity='0.45'/>` : `<line x1='${f2(Y)}' y1='${f2(X)}' x2='${f2(Y)}' y2='${f2(X + len)}' stroke-width='${w}' stroke-opacity='0.45'/>`));
+    }
+    return `${head}<g stroke='${colour}' opacity='${f2(opacity)}'>${lines}</g></svg>`;
+  }
+  throw new Error(`Unknown texture "${name}" (${Object.keys(TEXTURES).join(", ")}).`);
+}
+
+// Writes <public>/textures/<file>.svg and returns the CSS (as a background, or as an overlay on anything).
+export function writeTexture(dir, name, opts = {}) {
+  const svg = texture(name, opts);
+  const pub = publicDir(dir);
+  const file = opts.file ?? name;
+  const abs = path.join(dir, pub, "textures", `${file}.svg`);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, svg + "\n");
+  const url = `/textures/${file}.svg`;
+  const tile = (svg.match(/width='(\d+)'/) ?? [])[1];
+  return [
+    `Wrote ${pub}/textures/${file}.svg (${TEXTURES[name]}; seed ${opts.seed ?? 1}, drawn by palate, no licence needed).`,
+    "",
+    `/* as a surface */`,
+    `.texture-${file} { background-image: url("${url}"); background-size: ${tile}px; background-repeat: repeat; }`,
+    `/* as an overlay on a coloured section or a photo */`,
+    `.texture-${file}-over { position: relative; isolation: isolate; }`,
+    `.texture-${file}-over::after { content: ""; position: absolute; inset: 0; pointer-events: none; background: url("${url}") repeat; background-size: ${tile}px; mix-blend-mode: multiply; }`,
+  ].join("\n");
+}
+
+// ---- the build plan's imagery slots → the exact palate command for each. Pure.
+// plan: [{ section, imagery: "photo:met ceramics bowl" | "texture:speckle" | "product-ui" | "illustration:<what>" | "type" }]
+export function imageryPlanLines(plan = []) {
+  const lines = [];
+  let photos = 0;
+  for (const { section, imagery: spec } of plan) {
+    const s = clean(spec);
+    const [kind, ...restParts] = s.split(":");
+    const rest = clean(restParts.join(":"));
+    const k = kind.toLowerCase();
+    let line;
+    if (k === "photo") {
+      photos++;
+      const words = rest.split(" ");
+      const src = ALIASES[words[0]?.toLowerCase()];
+      const query = src ? words.slice(1).join(" ") : rest;
+      line = query
+        ? `photo — ${CMD.search} "${query}"${src ? ` --sources ${src}` : ""} (--type Photograph for real photographs, or ${TYPES.filter((t) => t !== "Photograph").join("/")}; --artist "<name>" for one maker), open the contact sheet, then ${CMD.pick} <id>; wrap it in .palate-photo; write the page's one treatment once with palate imagery treatment duotone|tone|natural --shadow <ink> --highlight <paper> (natural when the object's own colour matters)`
+        : `photo — needs a subject: ${CMD.search} "<object or scene>" [--type Photograph] [--artist "<name>"]`;
+    } else if (k === "texture") {
+      const name = rest.split(" ")[0]?.toLowerCase();
+      line = TEXTURES[name] ? `texture — ${CMD.texture} ${name} --colour <the section's ink> (writes public/textures/${name}.svg; use the CSS it prints)` : `texture — unknown "${rest}"; one of ${Object.keys(TEXTURES).join(", ")}`;
+    } else if (k === "product-ui") {
+      line = "product UI — build the real interface in code (a live component, or a framed screenshot of the running app); no stock photo";
+    } else if (k === "illustration") {
+      line = `illustration — draw ${rest || "it"} yourself as inline SVG in the page's palette; never copy an existing illustration`;
+    } else if (k === "type" || k === "none") {
+      line = "type only — no image: scale, weight and measure carry this section";
+    } else {
+      line = `unknown imagery "${s}" — use photo:<query>, texture:<${Object.keys(TEXTURES).join("|")}>, product-ui, illustration:<what> or type`;
+    }
+    lines.push(`- ${section}: ${line}`);
+  }
+  if (photos) lines.push(`- every photo: one treatment for the whole page (treatmentCss duotone | tone | natural | grain, from the page's ink and paper colours; natural keeps an object's own colour), real alt text, credits from credits.json in the footer`);
+  return lines;
+}