tweakit 0.5.2 → 0.6.0

package/src/tweaks/controls/gradient.ts

@@ -0,0 +1,240 @@
+// ── Gradient — a wide-gamut OKLCH gradient editor. Lazy; depends on the color
+// module (reuses its picker body, parseColor, and oklchStr).
+import { el, btn, clamp, popover, registerControl, icon } from "../shared.js";
+import { dragGesture, triggerRow, arrowStep } from "../heavy.js";
+import { createPickerBody, parseColor, isColor, oklchStr, CHECKER } from "./color.js";
+import { modeInterpolation, interpolationMode } from "../../wide-gamut.js";
+import { gradientCss, parseEasing, easingSamples } from "../easing.js";
+import type { Bez } from "../easing.js";
+import type { Oklcha } from "./color.js";
+import type { OnChange } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control, GradientStop, GradientEasing } from "../types.js";
+
+const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+/** The name an easing is stored under: trimmed and lowercased when parseEasing knows it, else "linear". */
+const easingName = (e: unknown): GradientEasing => (parseEasing(e) ? (e as string).trim().toLowerCase() as GradientEasing : "linear");
+
+/** The blend progress at a position, linear between samples exactly as the browser draws the
+ *  stops, so a stop inserted at x takes the color the ramp really shows. Null is the identity. */
+function easingAt(b: Bez | null, x: number): number {
+  x = clamp01(x); // outside the segment is its end; never extrapolate
+  if (!b) return x;
+  const s = easingSamples(b);
+  for (let k = 1; k < s.length; k++) {
+    if (x <= s[k][0]) { const [x0, y0] = s[k - 1], [x1, y1] = s[k]; return x1 > x0 ? y0 + (y1 - y0) * (x - x0) / (x1 - x0) : y1; }
+  }
+  return 1;
+}
+
+/** A stop handle on the rail, carrying the stop it moves. */
+interface StopHandle extends HTMLButtonElement { _stop?: GradientStop }
+
+// ICON_PLUS — adapted from Hugeicons `add-01` (MIT), two paths merged. See ../../../THIRD-PARTY-NOTICES.md.
+const ICON_PLUS = icon('<path d="M12 5v14m7-7H5"/>', "", 2.5);
+
+// ── Gradient — a Figma-style editor: a swatch-trigger row opens a popover holding the stop bar
+// over a reused color picker body; selecting a stop re-points the body at it. The bar blends in
+// the space of the editor's mode, which rides along as `interpolation`, and `easing` likewise, so a
+// host's `linear-gradient(in …)` through gradientCss() gets the same pixels. ──
+// A value's blend space / easing: an explicit string on the object form, else null (the array
+// shorthand carries none). Inspected field by field, so the normalizers take `any`.
+const field = (value: any, key: string): string | null => (value && !Array.isArray(value) && typeof value[key] === "string" ? value[key] : null);
+const parseInterp = (value: any) => field(value, "interpolation");
+const parseEase = (value: any) => field(value, "easing");
+// The easing menu; a stored cubic-bezier() not among them shows as a "Custom" option while it's the value.
+const EASINGS: Array<[GradientEasing, string]> = [["linear", "Linear"], ["ease", "Ease"], ["ease-in", "Ease in"], ["ease-out", "Ease out"], ["ease-in-out", "Ease in-out"]];
+function normalizeStops(value: any): GradientStop[] {
+  const DEF: GradientStop[] = [{ color: "oklch(0.72 0.19 25)", pos: 0 }, { color: "oklch(0.72 0.16 280)", pos: 1 }];
+  const arr = Array.isArray(value) ? value : (value && Array.isArray(value.stops) ? value.stops : null);
+  // A stop's color must be a single color token: stop text goes straight into the preview's
+  // `linear-gradient(…)`, where an unparsed string could splice in further layers (a url() fetch
+  // from persisted state). A non-finite pos → 0, clamped into [0,1]; fewer than two usable stops → the default pair.
+  // Trimmed as the gate trims it: the CSS tokenizer reads a non-ASCII space as part of a name.
+  const stop = (color: string, pos: unknown): GradientStop | null => (isColor(color) ? { color: String(color).trim(), pos: clamp(+pos || 0, 0, 1) } : null);
+  const out = (arr || []).map((s: any) => {
+    if (Array.isArray(s)) return stop(s[0], s[1]);
+    if (s && typeof s === "object") return stop(s.color, s.pos);
+    return null;
+  }).filter(Boolean);
+  return out.length >= 2 ? out : DEF;
+}
+function createGradient(meta: Meta, onChange: OnChange): Control {
+  meta.value ??= meta.stops; // the verbose form's `stops` aliases `value`
+  // The blend and easing read off `value: {…}` first, else the verbose form's top level, where a pasted value's fields land.
+  const interp0 = parseInterp(meta.value) ?? parseInterp(meta), ease0 = parseEase(meta.value) ?? parseEase(meta);
+  let stops = normalizeStops(meta.value);
+  let selStop = stops[0];
+  let easing = easingName(ease0); // unrecognized reads as linear
+
+  // ── Trigger row — the strip is the readout; the stop count rides along for the accessibility tree. ──
+  const { root, trigger, right } = triggerRow("tw-gradient", meta.label ?? "Gradient"); // ??: an explicit "" label renders none
+  const preview = el("span", "tw-trigger-chip tw-gradient-preview"); preview.setAttribute("role", "img");
+  right.append(preview);
+
+  // ── Editor popover — carries the color popover's class so it inherits its tokens and shell. ──
+  const pop = el("div", "tw-color-pop tw-gradient-pop");
+  const barRow = el("div", "tw-gradient-bar-row");
+  const bar = el("div", "tw-gradient-bar");
+  const grad = el("div", "tw-gradient-grad");
+  const rail = el("div", "tw-gradient-rail");
+  bar.append(grad, rail);
+  const addBtn = btn("tw-gradient-add", ICON_PLUS); addBtn.title = "Add a stop after the selected one"; addBtn.setAttribute("aria-label", "Add a color stop after the selected one");
+  barRow.append(bar, addBtn);
+
+  const sorted = () => [...stops].sort((a, b) => a.pos - b.pos);
+  // body.mode() is the single source of truth for the blend space, so the bar, preview and emitted
+  // interpolation can't drift. (Stops keep their own notation; CSS lets `in srgb` carry oklch() stops.)
+  const interp = () => modeInterpolation(body.mode());
+  const value = () => ({ stops: sorted().map((s) => ({ color: s.color, pos: +s.pos.toFixed(4) })), interpolation: interp(), easing });
+  // Both draw gradientCss(value()), so the editor can't show a ramp a host templating through it won't get.
+  const paint = () => { const css = gradientCss(value()); grad.style.background = css; preview.style.background = `${css}, ${CHECKER}`; };
+  const reflectCount = () => { preview.setAttribute("aria-label", `${stops.length} stop${stops.length === 1 ? "" : "s"}`); };
+  const emit = () => onChange(value());
+
+  const handleFor = (s: GradientStop) => [...(rail.children as HTMLCollectionOf<StopHandle>)].find((h) => h._stop === s); // the rail holds only stop handles
+  // Unlike the standalone color control, a mode switch here IS a change to the gradient's output, so it repaints and re-emits.
+  const body = createPickerBody({ value: selStop.color, mode: interpolationMode(interp0 || "oklch"), onMode: () => { paint(); emit(); } }, (c) => { // oklch: the documented default and colorAt's blend space
+    selStop.color = c;
+    handleFor(selStop)?.style.setProperty("--stop", c);
+    paint(); emit();
+  });
+  // Easing sits beside the mode: both are "how the ramp blends".
+  const easeSel = el("select", "tw-color-mode tw-gradient-ease"); easeSel.setAttribute("aria-label", "Easing between stops"); easeSel.title = "How the ramp blends between stops";
+  for (const [v, label] of EASINGS) { const o = document.createElement("option"); o.value = v; o.textContent = label; easeSel.append(o); }
+  const reflectEase = () => {
+    let custom = easeSel.querySelector<HTMLOptionElement>("option[data-custom]");
+    if (EASINGS.some(([v]) => v === easing)) custom?.remove();
+    else { if (!custom) { custom = document.createElement("option"); custom.dataset.custom = ""; custom.textContent = "Custom"; easeSel.append(custom); } custom.value = easing; }
+    easeSel.value = easing;
+  };
+  easeSel.addEventListener("change", () => { easing = easeSel.value as GradientEasing; reflectEase(); paint(); emit(); }); // reflect: picking a keyword retires the Custom option
+  body.el.querySelector(".tw-color-mode")!.after(easeSel); // after the mode select, before the gamut tag
+  reflectEase();
+  pop.append(barRow, body.el);
+  root.append(pop);
+
+  // A stop's accessible name carries its position and selection, the state the ring shows sighted users.
+  const labelStop = (h: StopHandle) => h.setAttribute("aria-label", `Color stop at ${Math.round(h._stop.pos * 100)}%${h._stop === selStop ? ", selected" : ""}`);
+  const reflectSel = () => { for (const h of rail.children as HTMLCollectionOf<StopHandle>) { h.dataset.sel = String(h._stop === selStop); labelStop(h); } };
+  // A drag or an arrow moving a stop: its spot on the rail, its name, the ramp and the value follow.
+  const moveStop = (h: StopHandle, pos: number) => { h._stop.pos = clamp(pos, 0, 1); h.style.left = h._stop.pos * 100 + "%"; labelStop(h); paint(); emit(); };
+  const renderHandles = () => {
+    rail.replaceChildren();
+    for (const s of stops) {
+      const h: StopHandle = btn("tw-gradient-stop"); h._stop = s;
+      h.style.left = s.pos * 100 + "%"; h.style.setProperty("--stop", s.color);
+      h.dataset.sel = String(s === selStop); labelStop(h);
+      // Focus is selection: tabbing onto a stop points the picker at it.
+      h.addEventListener("focus", () => select(s, false));
+      let offBar = false;
+      dragGesture(h, {
+        // preventDefault suppresses click-to-focus, so focus explicitly (ringless); that also blurs
+        // a dirty channel field while the old stop is still selected, so its commit lands there.
+        onDown: (e) => { e.preventDefault(); e.stopPropagation(); h.focus({ focusVisible: false }); select(s, false); offBar = false; },
+        onMove: (e) => {
+          // One rail rect for X and the off-bar Y test; the X math is posFromX inlined.
+          const r = rail.getBoundingClientRect();
+          moveStop(h, (e.clientX - r.left) / (r.width || 1));
+          // Dragging ~24px clear of the bar removes the stop (floored at two).
+          offBar = stops.length > 2 && (e.clientY < r.top - 24 || e.clientY > r.bottom + 24);
+          h.dataset.removing = String(offBar);
+        },
+        onEnd: () => { if (offBar) removeStop(s); else h.dataset.removing = "false"; },
+      });
+      h.addEventListener("dblclick", (e) => { e.preventDefault(); removeStop(s); });
+      // Arrows nudge by 0.01 (⇧ = 0.1); Delete stays on the popover.
+      h.addEventListener("keydown", (e) => {
+        const [d] = arrowStep(e); if (!d) return;
+        e.preventDefault(); moveStop(h, s.pos + d * (e.shiftKey ? 0.1 : 0.01));
+      });
+      rail.append(h);
+    }
+  };
+  // A drag only flips the selected flag, so the dragged handle stays live. body.set runs before
+  // selStop switches: re-pointing blurs a dirty channel field, whose commit must land on the old stop.
+  const select = (s: GradientStop, rerender: boolean) => { if (s !== selStop) { body.set(s.color); selStop = s; } rerender ? renderHandles() : reflectSel(); };
+
+  const posFromX = (x: number) => { const r = rail.getBoundingClientRect(); return clamp((x - r.left) / (r.width || 1), 0, 1); };
+
+  // A new stop's color: the bracketing stops interpolated in OKLCH at the EASED progress, so it lands invisibly on the ramp the bar draws.
+  const colorAt = (pos: number) => {
+    const ss = sorted(); let lo = ss[0], hi = ss[ss.length - 1];
+    for (let k = 0; k < ss.length - 1; k++) if (pos >= ss[k].pos && pos <= ss[k + 1].pos) { lo = ss[k]; hi = ss[k + 1]; break; }
+    const t = easingAt(parseEasing(easing), hi.pos > lo.pos ? clamp((pos - lo.pos) / (hi.pos - lo.pos), 0, 1) : 0); // a pos outside the outermost stops never extrapolates
+    const a = parseColor(lo.color), b = parseColor(hi.color);
+    // CSS missing-hue: a ~zero-chroma stop carries no hue, so the other's holds (white→red stays red).
+    const ach = (c: Oklcha) => c[1] < 1e-4;
+    let dh = b[2] - a[2]; if (dh > 180) dh -= 360; else if (dh < -180) dh += 360;
+    if (ach(a) || ach(b)) dh = 0;
+    const H = ((((ach(a) && !ach(b) ? b[2] : a[2]) + dh * t) % 360) + 360) % 360; // normalize to [0,360) so the picker reads it cleanly
+    return oklchStr(a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, H, a[3] + (b[3] - a[3]) * t);
+  };
+  const removeStop = (s: GradientStop) => {
+    if (stops.length <= 2) return;
+    const i = stops.indexOf(s); if (i < 0) return; // a stale reference (rebuilt via set) must not splice(-1)
+    stops.splice(i, 1);
+    const next = selStop === s ? stops[Math.max(0, i - 1)] : selStop;
+    paint(); select(next, true); reflectCount(); emit();
+    handleFor(selStop)?.focus(); // keep focus on a handle so Delete can chain
+  };
+  // Insert a stop at `pos`, colored by sampling the gradient there, and select it. Shared by the +
+  // button (midway toward the selected stop's neighbor, so where it lands is predictable) and double-click on the bar.
+  const insertStopAt = (pos: number) => {
+    const s = { color: colorAt(pos), pos: clamp(pos, 0, 1) };
+    stops.push(s); paint(); select(s, true); reflectCount(); emit();
+  };
+  // Midway toward the next stop, or toward the previous from the last. There are always two stops at least (the
+  // normalizer's default pair, removeStop's floor), and the selected one is always among them.
+  const addStop = () => {
+    const ss = sorted(), i = ss.indexOf(selStop);
+    insertStopAt(i < ss.length - 1 ? (ss[i].pos + ss[i + 1].pos) / 2 : (ss[i - 1].pos + ss[i].pos) / 2);
+  };
+  addBtn.addEventListener("click", (e) => { e.stopPropagation(); addStop(); });
+  // Double-click, not single, so it never fights grabbing a stop; a double-click on a stop falls through to its own handler.
+  bar.addEventListener("dblclick", (e) => {
+    if ((e.target as Element).closest(".tw-gradient-stop")) return;
+    e.preventDefault();
+    insertStopAt(posFromX(e.clientX));
+  });
+
+  // Delete / Backspace removes the selected stop, ignored while typing in a field and with Alt held (the panel's reset chord).
+  pop.tabIndex = -1;
+  pop.addEventListener("keydown", (e) => {
+    if ((e.key === "Delete" || e.key === "Backspace") && !e.altKey && !/^(input|textarea|select)$/i.test((e.target as Element).tagName) && stops.length > 2) { e.preventDefault(); removeStop(selStop); }
+  });
+
+  // Focus lands on the selected stop, not the first: focus is selection, so that would re-point the picker on every open.
+  popover(root, trigger, pop, { fallbackH: 392, onOpen: body.reflow, onReflow: body.reflow, initialFocus: () => handleFor(selStop) });
+
+  renderHandles(); paint(); reflectCount();
+  return {
+    el: root,
+    set: (v: unknown) => {
+      // Named → applied; absent → left as the user set it, never reset to OKLCH on a stops-only set.
+      const ip = parseInterp(v); if (ip) body.setMode(interpolationMode(ip));
+      const es = parseEase(v); if (es !== null) { easing = easingName(es); reflectEase(); } // same rule as the blend
+      const next = normalizeStops(v).sort((a, b) => a.pos - b.pos);
+      if (next.length === stops.length) {
+        // Same count (a host mirroring values back): update the stop objects in place, paired in
+        // position order, so a live drag keeps its handle and the picker its stop.
+        sorted().forEach((s, i) => {
+          s.color = next[i].color; s.pos = next[i].pos;
+          const h = handleFor(s); if (h) { h.style.left = s.pos * 100 + "%"; h.style.setProperty("--stop", s.color); }
+        });
+      } else {
+        const selPos = selStop.pos;
+        stops = next;
+        selStop = stops.reduce((b, s) => (Math.abs(s.pos - selPos) < Math.abs(b.pos - selPos) ? s : b), stops[0]); // re-select the nearest position, not index 0
+        renderHandles();
+      }
+      paint(); reflectCount(); body.set(selStop.color);
+    },
+    get: () => value(),
+  };
+}
+
+registerControl("gradient", createGradient);
+
+// For test/gradient-css.test.mjs, which checks them beside the easing parser.
+export { easingName, easingAt };

package/src/tweaks/controls/image.ts

@@ -0,0 +1,299 @@
+// ── Image — a drop zone / file pick that yields a data URL; with `options`, a gallery of supplied URLs over the upload. Lazy.
+import { el, txt, btn, icon, optValue, radioButton, navIndex, popover, registerControl } from "../shared.js";
+import { triggerRow } from "../heavy.js";
+import type { OnChange, RadioBtn } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control } from "../types.js";
+
+// Escape for a CSS string literal: the quote, the backslash and control characters (a raw newline ends a CSS string),
+// so a stored `a.png"), url("https://x/p.png` is one broken image, not a second background layer and a fetch.
+const cssString = (s: string) => String(s).replace(/[\\"]/g, "\\$&").replace(/[\x00-\x1f\x7f]/g, (c) => "\\" + c.charCodeAt(0).toString(16) + " ");
+const urlCss = (s: string) => `url("${cssString(s)}")`;
+const MB = 1 << 20;
+const size = (n: number) => (n >= MB ? `${Math.round((n / MB) * 10) / 10} MB` : n >= 1024 ? `${Math.round(n / 1024)} KB` : `${n} B`);
+// A tile's accessible name when its option has no label: the URL's file stem; a data URL has none.
+const stem = (url: string) => { if (/^data:/i.test(url)) return ""; const s = url.split(/[?#]/)[0].split("/").pop()!.replace(/\.\w+$/, ""); try { return decodeURIComponent(s); } catch { return s; } };
+// Pixels, not bytes, are what make an upload heavy: a phone photo is ~4 MB as a data URL, and storage holds ~5 MB an origin,
+// so one upload could keep every value from saving. A picture longer than `fit` on its long side is drawn down to it before
+// it becomes the param, and one within `fit` but heavier than 1.5 MB is redrawn at its size. A JPEG stays a JPEG, at `quality`. Anything else is tried as a PNG first, so a screenshot or text
+// isn't smudged, and kept as one up to 1.5 MB: a photo's PNG at 2560px is several times that, while a screenshot's is not.
+// (It's weighed by size, not against the JPEG: drawn down, even a screenshot's PNG runs about twice its JPEG.) Past that it
+// is a JPEG, or with transparency a WebP where the browser writes one, whichever is smaller than the PNG. An SVG has no
+// pixels to fit, and a GIF, an animated WebP or an APNG would keep only its first frame, so they are taken as they are.
+// Resolves "" to take the file as it is: it fits and is light, its format is kept, the browser can't decode or draw it, or
+// the redraw came out no smaller.
+const KEEP = /^image\/(gif|svg\+xml)$/i;
+const PNG_BUDGET = 1.5 * MB;
+const PNG_SIG = "\x89PNG\r\n\x1a\n";
+const ascii = (b: Uint8Array, at: number, s: string) => { for (let k = 0; k < s.length; k++) if (b[at + k] !== s.charCodeAt(k)) return false; return true; };
+// The file says it's animated before its first frame: WebP in VP8X's animation flag or an ANIM chunk, a PNG in an acTL
+// chunk ahead of its first IDAT. Only chunk headers are read, never the frames, however many chunks come first.
+export const animated = async (file: Blob) => {
+  const at = async (i: number, n: number) => new Uint8Array(await file.slice(i, i + n).arrayBuffer());
+  const h = await at(0, 21), webp = ascii(h, 0, "RIFF") && ascii(h, 8, "WEBP");
+  if (webp && ascii(h, 12, "VP8X") && h[20] & 2) return true;
+  if (!webp && !ascii(h, 0, PNG_SIG)) return false;
+  for (let i = webp ? 12 : 8; ; ) {
+    const c = await at(i, 8); if (c.length < 8) return false;
+    const type = String.fromCharCode(...c.subarray(webp ? 0 : 4, webp ? 4 : 8));
+    if (type === (webp ? "ANIM" : "acTL")) return true;
+    if (webp ? /^(VP8 |VP8L|ANMF)$/.test(type) : type === "IDAT") return false; // the picture has begun
+    const n = new DataView(c.buffer).getUint32(webp ? 4 : 0, webp); // a WebP chunk's size is little-endian and padded to even
+    i += webp ? 8 + n + (n & 1) : 12 + n; // at least a header on, so the end of the file comes
+  }
+};
+// A picture taken as it is keeps its bytes, and a phone's carry where it was taken: Exif's GPS, and XMP, which can repeat
+// it. The value is stored and copied as JSON into source, so those blocks are cut from the bytes, losslessly: the ICC
+// profile, which carries a wide gamut, and everything else stays. Exif's Orientation decides which way up the picture
+// shows, so a turned one gets a bare Exif back holding only that tag. A redraw needs none of this: a canvas writes no Exif.
+// Each parser hands back the bytes left, or null to keep the file whole: nothing to cut, or a block it can't read.
+const orientation = (t: Uint8Array) => {
+  const le = ascii(t, 0, "II"), v = new DataView(t.buffer, t.byteOffset, t.byteLength); if (!le && !ascii(t, 0, "MM")) return null;
+  try {
+    const ifd = v.getUint32(4, le);
+    for (let k = 0, n = v.getUint16(ifd, le); k < n; k++) if (v.getUint16(ifd + 2 + k * 12, le) === 0x112) { const o = v.getUint16(ifd + 10 + k * 12, le); return o > 1 && o <= 8 ? o : 1; }
+    return 1;
+  } catch { return null; } // an offset past the end
+};
+// A big-endian TIFF header and one IFD with the one entry: Orientation, a SHORT.
+const bareExif = (o: number) => new Uint8Array([77, 77, 0, 42, 0, 0, 0, 8, 0, 1, 1, 0x12, 0, 3, 0, 0, 0, 1, 0, o, 0, 0, 0, 0, 0, 0]);
+type Bytes = Uint8Array<ArrayBuffer>; // what a Blob takes: never a SharedArrayBuffer
+const crc32 = (b: Uint8Array) => { let c = ~0; for (const x of b) { c ^= x; for (let k = 0; k < 8; k++) c = (c >>> 1) ^ (0xedb88320 & -(c & 1)); } return ~c >>> 0; };
+// An Ultra HDR JPEG's XMP carries its gain map (hdrgm:), the HDR itself, so it stays when every namespace it declares and
+// every prefix it uses is the gain map's or its container's: nothing there can say where or who. Anything more, and it's cut.
+const XMP = "http://ns.adobe.com/xap/1.0/\0";
+const GAIN_NS = ["adobe:ns:meta/", "http://www.w3.org/1999/02/22-rdf-syntax-ns#", "http://ns.adobe.com/hdr-gain-map/1.0/", "http://ns.google.com/photos/1.0/container/", "http://ns.google.com/photos/1.0/container/item/"];
+const gainMapOnly = (b: Uint8Array) => {
+  const x = new TextDecoder("latin1").decode(b), ok = new Set(["xmlns", "xml"]);
+  if (!x.includes(GAIN_NS[2])) return false;
+  for (const [, p, ns] of x.matchAll(/xmlns(?::([\w.-]+))?\s*=\s*["']([^"']*)["']/g)) { if (!GAIN_NS.includes(ns)) return false; if (p) ok.add(p); }
+  for (const [, p] of x.matchAll(/[<\s/]([\w.-]+):[\w.-]/g)) if (!ok.has(p)) return false;
+  return true;
+};
+// An MPF JPEG (Ultra HDR's gain map, a camera's preview) indexes the images after the first by their offset from its MP
+// header, so a cut between that header and the first image's end moves them all up by the bytes cut. A list that doesn't
+// read is left as it was. The images after the first are left whole, their own Exif or XMP with them: the MP index and
+// the gain-map XMP's Item:Length both record their sizes, so cutting into them means rewriting both, and a gain map's XMP
+// is its HDR.
+const mpfShift = (seg: Uint8Array, by: number) => {
+  const le = ascii(seg, 0, "II"), v = new DataView(seg.buffer, seg.byteOffset, seg.byteLength); if (!le && !ascii(seg, 0, "MM")) return;
+  try {
+    const ifd = v.getUint32(4, le);
+    for (let k = 0, n = v.getUint16(ifd, le); k < n; k++) {
+      const e = ifd + 2 + k * 12; if (v.getUint16(e, le) !== 0xb002) continue; // MPEntry: 16 bytes an image, its offset at 8
+      const list = v.getUint32(e + 8, le), count = v.getUint32(e + 4, le) >>> 4;
+      if (count) v.getUint32(list + count * 16 - 4, le); // the whole list is in the segment, or nothing is written
+      for (let j = 0; j < count; j++) { const o = list + j * 16 + 8, off = v.getUint32(o, le); if (off > by) v.setUint32(o, off - by, le); }
+    }
+  } catch { /* an offset past the segment */ }
+};
+const jpegCut = (b: Bytes) => {
+  if (b[0] !== 0xff || b[1] !== 0xd8) return null;
+  const out: Bytes[] = []; let i = 2, from = 0, turned = 0, mpf: Uint8Array | null = null, moved = 0;
+  for (;;) {
+    while (b[i] === 0xff && b[i + 1] === 0xff) i++; // fill bytes before a marker (T.81 B.1.1.2) stay with what's kept
+    const m = b[i + 1], end = i + 2 + ((b[i + 2] << 8) | b[i + 3]);
+    if (b[i] !== 0xff || m === 0xff || m === 1 || (m >= 0xd0 && m <= 0xd9) || end < i + 4 || end > b.length) return null; // a marker out of place
+    if (m === 0xda) break; // start of scan: the picture itself, kept to the end
+    if (m === 0xe2 && ascii(b, i + 4, "MPF\0")) mpf = b.subarray(i + 8, end);
+    const exif = m === 0xe1 && ascii(b, i + 4, "Exif\0");
+    if (exif || (m === 0xe1 && ascii(b, i + 4, "http://ns.adobe.com/x") && !(ascii(b, i + 4, XMP) && gainMapOnly(b.subarray(i + 4 + XMP.length, end))))) { // XMP, and its extension
+      const o = exif ? orientation(b.subarray(i + 10, end)) : 1; if (o === null) return null;
+      out.push(b.subarray(from, i)); from = end;
+      const bare = o > 1 && !turned++; if (bare) out.push(new Uint8Array([0xff, 0xe1, 0, 34, 69, 120, 105, 102, 0, 0, ...bareExif(o)]));
+      if (mpf) moved += end - i - (bare ? 36 : 0);
+    }
+    i = end;
+  }
+  if (mpf && moved > 0) mpfShift(mpf, moved); // in place: these are strip()'s own bytes, and they go out as parts of it
+  return out.length ? [...out, b.subarray(from)] : null;
+};
+const pngCut = (b: Bytes) => {
+  if (!ascii(b, 0, PNG_SIG)) return null;
+  const v = new DataView(b.buffer, b.byteOffset, b.byteLength), out: Bytes[] = [];
+  let i = 8, from = 0, turned = 0;
+  for (let type = ""; type !== "IEND"; ) {
+    const end = i + 12 > b.length ? Infinity : i + 12 + v.getUint32(i); if (end > b.length) return null;
+    type = String.fromCharCode(...b.subarray(i + 4, i + 8));
+    // A text chunk is metadata by its keyword: XMP's, or ImageMagick's raw Exif and XMP. Other text stays.
+    const key = /^[tiz]TXt$/.test(type) ? String.fromCharCode(...b.subarray(i + 8, Math.min(end - 4, i + 88))).split("\0")[0] : "";
+    if (type === "eXIf" || /^(XML:com\.adobe\.xmp|Raw profile type (exif|app1|xmp))$/i.test(key)) {
+      const o = type === "eXIf" ? orientation(b.subarray(i + 8, end - 4)) : 1; if (o === null) return null;
+      out.push(b.subarray(from, i)); from = end;
+      if (o > 1 && !turned++) {
+        const c = new Uint8Array(38), cv = new DataView(c.buffer);
+        cv.setUint32(0, 26); c.set([101, 88, 73, 102], 4); c.set(bareExif(o), 8); cv.setUint32(34, crc32(c.subarray(4, 34)));
+        out.push(c);
+      }
+    }
+    i = end;
+  }
+  return out.length ? [...out, b.subarray(from)] : null;
+};
+export const strip = async (file: File): Promise<Blob> => {
+  try { const b = new Uint8Array(await file.arrayBuffer()), parts = jpegCut(b) || pngCut(b); return parts ? new Blob(parts, { type: file.type }) : file; } catch { return file; }
+};
+const hasAlpha = (ctx: CanvasRenderingContext2D, w: number, h: number) => { const d = ctx.getImageData(0, 0, w, h).data; for (let i = 3; i < d.length; i += 4) if (d[i] < 255) return true; return false; };
+// toBlob encodes off the main thread where the browser can. null when it can't write that type (it hands back a PNG instead).
+const encode = (c: HTMLCanvasElement, type: string, q?: number) => new Promise<Blob | null>((r) => c.toBlob((b) => r(b && b.type === type ? b : null), type, q));
+const dataUrl = (b: Blob) => new Promise<string>((r, j) => { const fr = new FileReader(); fr.onload = () => r(String(fr.result)); fr.onerror = j; fr.readAsDataURL(b); });
+// A 2D context is sRGB unless asked, and a Display P3 photo (every iPhone's) drawn into it is flattened to sRGB. A P3
+// canvas keeps the gamut, and toBlob tags what it writes with the P3 profile. A browser that doesn't know the option
+// ignores it and hands back sRGB, as before; one that refuses the value throws, and gets the plain context.
+const context = (c: HTMLCanvasElement) => { try { const ctx = c.getContext("2d", { colorSpace: "display-p3" }); if (ctx) return ctx; } catch { /* the plain context */ } return c.getContext("2d"); };
+const shrink = async (file: File, fit: number, quality: number): Promise<string> => {
+  if (!fit || KEEP.test(file.type) || typeof Image === "undefined" || typeof URL.createObjectURL !== "function") return "";
+  let src = "";
+  try {
+    if (await animated(file)) return "";
+    src = URL.createObjectURL(file);
+    const img = new Image(); img.src = src; await img.decode();
+    const iw = img.naturalWidth, ih = img.naturalHeight, k = Math.min(1, fit / Math.max(iw, ih));
+    if (!(iw > 0 && ih > 0) || (k === 1 && file.size <= PNG_BUDGET)) return ""; // within fit and light: a picture already shrunk is never redrawn
+    const c = document.createElement("canvas"), w = (c.width = Math.max(1, Math.round(iw * k))), h = (c.height = Math.max(1, Math.round(ih * k)));
+    const ctx = context(c); if (!ctx) return "";
+    ctx.imageSmoothingQuality = "high"; ctx.drawImage(img, 0, 0, w, h);
+    const jpeg = /^image\/jpe?g$/i.test(file.type);
+    let out = jpeg ? null : await encode(c, "image/png");
+    if (!out || out.size > PNG_BUDGET) {
+      const alt = await encode(c, !jpeg && hasAlpha(ctx, w, h) ? "image/webp" : "image/jpeg", quality);
+      if (alt && (!out || alt.size < out.size)) out = alt;
+    }
+    return out && out.size < file.size ? await dataUrl(out) : "";
+  } catch { return ""; } finally { if (src) URL.revokeObjectURL(src); }
+};
+const ICON_UPLOAD = icon('<path d="M12 15V4m-4.5 4.5L12 4l4.5 4.5M4 15v3a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-3"/>');
+
+function createImage(meta: Meta, onChange: OnChange): Control {
+  let value = typeof meta.value === "string" ? meta.value : "";
+  // Options: URLs, or { value, label }; anything but a non-empty string value is skipped, and a repeated URL keeps its first.
+  const seen = new Set<string>();
+  const options = (Array.isArray(meta.options) ? meta.options : []).map((o) => ({ value: optValue(o), label: o && typeof o === "object" && o.label != null ? String(o.label) : "" })).filter((o): o is { value: string; label: string } => typeof o.value === "string" && !!o.value && !seen.has(o.value) && !!seen.add(o.value));
+  const canUpload = meta.upload !== false || !options.length; // the plain row is the upload: there is nothing else to leave
+  const canClear = meta.clear !== false; // false: a required choice, with no Clear and no Delete to empty it
+  const maxSize = +meta.maxSize! > 0 ? +meta.maxSize! : 10 * MB;
+  // A number only: `fit: true` would read as 1 and draw every upload as one pixel.
+  const fit = meta.fit === false || meta.fit === 0 ? 0 : typeof meta.fit === "number" && meta.fit >= 1 ? Math.round(meta.fit) : 2560; // false or 0: uploads as they are
+  const quality = typeof meta.quality === "number" && meta.quality > 0 && meta.quality <= 1 ? meta.quality : 0.85;
+  const input = el("input", "tw-image-input"); input.type = "file"; input.accept = "image/*";
+  // A refused file's reason takes the button text's place for a moment. It is spoken from a status region beside the
+  // button, not inside it: a button's children are presentational, so a live region there is never read.
+  const note = el("span", "tw-image-note"), live = el("span", "tw-image-live"); live.setAttribute("role", "status");
+  const notes = [note, live]; // a gallery adds its row's note, so a file refused on the closed row still shows why
+  let noteTimer: ReturnType<typeof setTimeout>;
+  const say = (msg: string) => { for (const n of notes) n.textContent = msg; clearTimeout(noteTimer); noteTimer = setTimeout(() => { for (const n of notes) n.textContent = ""; }, 2600); };
+  // An off-list value's name: its file stem, else what it is. A blob: URL's stem is a UUID, so it counts as an upload.
+  const customName = (v: string) => (/^blob:/i.test(v) ? "" : stem(v)) || (/^(data|blob):/i.test(v) ? "Uploaded image" : "Custom image");
+  let render: () => void;
+  // Every commit bumps gen, so a file read that lands after a tile was picked, a reset or a host set() is dropped.
+  let gen = 0;
+  const commit = (v: string, fire = true) => { gen++; value = v; render(); if (fire) onChange(value); };
+  const load = (file: File | undefined) => {
+    if (!file) return;
+    if (!file.type.startsWith("image/")) return say("Not an image");
+    if (file.size > maxSize) return say(`${size(file.size)}, max ${size(maxSize)}`);
+    // One commit, of the shrunk picture when there is one, else of the file as it is less its metadata: one change event, one save.
+    const at = ++gen;
+    shrink(file, fit, quality).then(async (url) => {
+      if (gen !== at) return;
+      if (url) return commit(url);
+      const fr = new FileReader();
+      fr.onload = () => { if (gen === at) commit(String(fr.result)); };
+      fr.onerror = () => say("Couldn't read the file");
+      fr.readAsDataURL(await strip(file));
+    });
+  };
+  // `zone` takes the drop and `over` wears [data-over] meanwhile. dragover re-asserts each tick, so crossing the children doesn't drop the outline.
+  // A disabled control's root stays hit-testable (only its children go inert), so the zone checks for itself; on the
+  // control's root, since the gallery's pane is portaled out of the panel while open.
+  const dropZone = (zone: HTMLElement, over: HTMLElement) => {
+    const off = () => !!root.closest(".is-disabled");
+    zone.addEventListener("dragover", (e) => { if (off()) return; e.preventDefault(); over.dataset.over = "true"; });
+    zone.addEventListener("dragleave", () => { over.dataset.over = "false"; });
+    zone.addEventListener("drop", (e) => { over.dataset.over = "false"; if (off()) return; e.preventDefault(); load(e.dataTransfer?.files[0]); });
+  };
+  input.addEventListener("change", () => { load(input.files?.[0]); input.value = ""; }); // cleared, so the same file picked again fires change
+  // Both forms are a trigger row with the chosen image's thumb first, as every chip row.
+  const row = triggerRow("tw-image", meta.label), root = row.root;
+  const thumb = el("span", "tw-trigger-chip tw-image-thumb");
+  const paintThumb = () => { thumb.dataset.set = value ? "true" : "false"; thumb.style.backgroundImage = value ? urlCss(value) : ""; };
+
+  if (!options.length) {
+    // The plain row: the whole trigger is the target, a click opens the file dialog and the row is also the drop zone.
+    row.trigger.removeAttribute("aria-expanded"); // opens a file dialog, not an expandable popover
+    row.trigger.setAttribute("aria-label", `${meta.label}: choose an image`);
+    const text = el("span", "tw-image-text");
+    row.right.append(thumb, note, text);
+    root.append(input, live);
+    render = () => { paintThumb(); text.textContent = value ? "Replace" : "Drop or choose"; };
+    row.trigger.addEventListener("click", () => input.click());
+    dropZone(row.trigger, row.trigger);
+  } else {
+    // The gallery: the row, with the chosen image's name, opens a pane of the tiles, as one radio group, over a foot with
+    // the upload button and Clear. The row names the control, so the pane doesn't repeat it. The row and the pane both
+    // take a dropped file.
+    const name = el("span", "tw-trigger-value"), rowNote = el("span", "tw-image-note");
+    row.right.append(thumb, rowNote, name);
+    notes.push(rowNote);
+    // The pane is the gallery, with no wrapper: its padding and the gaps between tiles and foot are its drag edge.
+    const pop = el("div", "tw-color-pop tw-image-pop tw-image-gallery");
+    const upload = canUpload ? btn("tw-button tw-image-upload", ICON_UPLOAD) : null;
+    const clear = txt("button", "tw-image-clear", "Clear"); clear.type = "button"; clear.setAttribute("aria-label", `${meta.label}: clear the image`);
+    // The foot folds like a folder: a row track holds the upload button and a column track holds Clear, so either can
+    // ease shut without measuring. Clear folds away when there's nothing to clear; the foot folds when it's empty.
+    const foot = el("div", "tw-image-foot"), footRow = el("div", "tw-image-foot-row"), slot = el("div", "tw-image-clear-slot");
+    foot.append(footRow); slot.append(clear);
+    const grid = el("div", "tw-image-grid"); grid.setAttribute("role", "radiogroup"); grid.setAttribute("aria-label", meta.label);
+    const n = options.length;
+    const cols = Math.min(6, Math.max(1, (meta.cols! | 0) || (n <= 3 ? Math.max(2, n) : n === 4 ? 2 : 3)));
+    grid.style.setProperty("--tw-img-cols", String(cols));
+    const tile = (v: string, label: string) => { const b = radioButton("tw-image-tile", v, () => commit(v)); b.textContent = ""; b.setAttribute("aria-label", label); b.style.backgroundImage = urlCss(v); return b; };
+    const names = options.map((o, i) => o.label || stem(o.value) || `Image ${i + 1}`);
+    const tiles = options.map((o, i) => { const b = tile(o.value, names[i]); grid.append(b); return b; });
+    // A value that is none of the options (an upload, or a host-set URL) shows as a last tile, selected. Its URL rides
+    // on _twVal, not data-value: the inline style already holds one copy of a data URL, and data-value would be a second.
+    const custom: RadioBtn = btn("tw-image-tile tw-image-custom"); custom.setAttribute("role", "radio");
+    const all = () => (custom.parentNode ? [...tiles, custom] : tiles); // parentNode, not isConnected: a panel not yet in the document has no connected nodes
+    render = () => {
+      const k = tiles.findIndex((b) => b._twVal === value);
+      if (value && k < 0) {
+        custom._twVal = value; custom.style.backgroundImage = urlCss(value); custom.setAttribute("aria-label", customName(value));
+        if (!custom.parentNode) grid.append(custom); // re-appending an attached node moves it, and a move blurs it
+      } else {
+        // The focused tile is leaving (undo, a preset, set()): focus moves on first, since removing a focused node blurs
+        // it to <body>, and that blur closes the pane.
+        if (custom.matches(":focus")) tiles[Math.max(0, k)].focus();
+        custom.remove();
+      }
+      const btns = all(), stop = Math.max(0, btns.findIndex((b) => b._twVal === value)); // the roving tab stop: the chosen tile, else the first
+      btns.forEach((b, j) => { const on = !!value && b._twVal === value; b.dataset.active = String(on); b.setAttribute("aria-checked", String(on)); b.tabIndex = j === stop ? 0 : -1; });
+      slot.dataset.open = String(!!value); slot.inert = !value; // nothing to clear: Clear folds away, out of the tab order
+      foot.dataset.open = String(!!upload || (canClear && !!value)); foot.inert = foot.dataset.open === "false"; // an empty foot folds to nothing
+      paintThumb();
+      name.textContent = !value ? "None" : k >= 0 ? names[k] : customName(value);
+    };
+    grid.addEventListener("keydown", (e) => {
+      const btns = all(), i = btns.indexOf(e.target as RadioBtn); if (i < 0) return;
+      // Focus moves before the commit: the commit can remove the focused tile (the custom one) or hide Clear.
+      if (canClear && (e.key === "Delete" || e.key === "Backspace") && !e.altKey && !e.metaKey && !e.ctrlKey) { e.preventDefault(); tiles[0].focus(); commit(""); return; } // a modifier+Delete is the panel's reset, not a clear
+      const j = navIndex(e.key, i, btns.length, cols); if (j < 0) return;
+      e.preventDefault(); if (j !== i) { btns[j].focus(); commit(btns[j]._twVal as string); } // a tile holds its URL
+    });
+    clear.addEventListener("click", () => { (upload || tiles[0]).focus(); commit(""); }); // Clear hides itself: hand focus on first, not to the body
+    pop.append(grid, foot);
+    root.append(pop, live);
+    if (upload) {
+      upload.setAttribute("aria-label", `${meta.label}: upload an image`);
+      upload.append(note, txt("span", "tw-image-text", "Upload image"));
+      upload.addEventListener("click", () => input.click());
+      footRow.append(upload); root.append(input);
+      dropZone(row.trigger, row.trigger); dropZone(pop, pop);
+    }
+    if (canClear) footRow.append(slot);
+    popover(root, row.trigger, pop, { fallbackH: 220, initialFocus: () => all().find((b) => b.tabIndex === 0) });
+  }
+  render();
+  return { el: root, set: (v: string | null | undefined) => { if (v != null && typeof v !== "string") return; commit(v || "", false); }, get: () => value, note: say };
+}
+
+registerControl("image", createImage);