astro-dev-edit 0.11.0

package/src/client/hover.ts

@@ -0,0 +1,485 @@
+import type { ClassifyResult, SourceLoc } from "../shared/protocol.ts";
+import { classifyCached, peekClassification } from "./classify-cache.ts";
+import { buildRulesCard, rulesForToken } from "./css-inspect.ts";
+import { icon, setIcon } from "./icons.ts";
+import { nearestSource, sourceFor } from "./source-map.ts";
+import { isOwnUi, mount } from './shadow.ts';
+import {
+  COLOR,
+  basename,
+  chromeInset,
+  hexToRgba,
+  outlineRect,
+  pillButton,
+  setPillLabel,
+  styled,
+} from "./ui.ts";
+
+/**
+ * Hover behaviour: the outline that tracks the hovered source-mapped element
+ * and the interactive tooltip pill (file:loc · verdict, plus "open ↗" and
+ * "copy ⧉" buttons). Clicking the file:loc label opens the in-browser source
+ * peek; "open ↗" jumps to the editor; "copy ⧉" puts the element's context
+ * (HTML, CSS, source) on the clipboard. Hover state is self-contained
+ * here — it never interacts with the editing slot in state.ts.
+ *
+ * The pill never guesses. It appears instantly in a neutral "checking" state
+ * (no editability claim), and once the pointer has dwelled on one element the
+ * server's AST-truth /classify upgrades it to the verdict a click would get:
+ * editable, image, or dynamic. Verdicts come through classify-cache.ts, so an
+ * element costs one round-trip per file version, not one per mouse pass, and
+ * a re-hover of a known element shows its verdict immediately. (spec §7.3)
+ */
+
+/** What the pill claims about the highlighted element. */
+interface Verdict {
+  word: string;
+  color: string;
+}
+
+/** Neutral pre-verification state — no editability claim yet. */
+const CHECKING: Verdict = { word: "loading…", color: COLOR.mutedFg };
+
+/** Collapse the server's classification onto the pill's word + color,
+ *  mirroring how router.ts will route the eventual click. (spec §16.1) */
+function verdictFor(result: ClassifyResult): Verdict {
+  if (result.kind === "text") return { word: "editable", color: COLOR.brandText };
+  if (result.kind === "image") {
+    const attrs = result.attrs ?? { src: "dynamic", alt: "dynamic" };
+    // Same rule as the click router: when neither src nor alt is patchable
+    // the click ends in a refusal notice, so the pill says dynamic.
+    if (attrs.src !== "static" && attrs.alt === "dynamic") {
+      return { word: "dynamic", color: COLOR.warning };
+    }
+    return { word: "image", color: COLOR.info };
+  }
+  // empty / dynamic / ambiguous / unresolved all route to the refusal notice.
+  return { word: "dynamic", color: COLOR.warning };
+}
+
+// --- Elements (appended to the body by the composition root at boot) --------
+
+const outline = styled("div", "atx-outline", undefined, "atx-outline");
+
+// The pill is interactive: hovering it keeps it open, and its "open source"
+// button jumps to the element's source in the editor. (#3)
+const tooltip = styled("div", "atx-tooltip", undefined, "atx-tooltip");
+
+// Row 1: the file:loc · verdict label and the "open ↗" editor jump, kept on one
+// line regardless of the chips row below.
+const tooltipRow = styled("span", "atx-tooltip-row");
+
+// The label is clickable too — the whole file:loc line opens the in-browser
+// source peek (the "open ↗" button next to it is the editor jump). (#3)
+const tooltipLabel = styled("span", "atx-tooltip-label");
+// The label is two spans so the verdict can sit in a fixed-width slot — see
+// .atx-tooltip-verdict in styles.ts for why that width exists.
+const tooltipLoc = styled("span", "atx-tooltip-loc");
+const tooltipVerdict = styled("span", "atx-tooltip-verdict");
+tooltipLabel.append(tooltipLoc, tooltipVerdict);
+tooltipLabel.title = "Peek at the source code";
+const tooltipOpen = pillButton(
+  "atx-tooltip-open",
+  "open",
+  "Open this location in your editor",
+  {},
+  icon("external", 12),
+);
+
+// The context copy: everything we know about this element as one markdown
+// block, for pasting into an AI assistant. Its label swaps through
+// copying…/copied, so it holds a fixed width — the pill must not resize
+// mid-interaction (the verdict slot next to it exists for the same reason).
+//
+// The width is the widest of the three labels, which is the idle one: 12
+// characters of 11px/600 UI text (~68px) plus the pill's own 12px icon, 4px
+// gap and 2×7px padding, rounded up for a font that measures wider.
+const COPY_IDLE = "copy context";
+const copyIcon = icon("copy", 12);
+const tooltipCopy = pillButton(
+  "atx-tooltip-copy",
+  COPY_IDLE,
+  "Copy this element's source, HTML and CSS as context for an AI assistant",
+  { minWidth: "108px" },
+  copyIcon,
+);
+tooltipRow.append(tooltipLabel, tooltipOpen, tooltipCopy);
+
+let copyResetTimer: number | null = null;
+
+/** Back to the idle label, cancelling any pending flash. Runs on every
+ *  highlight change too, so a "copied" never carries onto another element. */
+function resetCopy(): void {
+  if (copyResetTimer !== null) {
+    clearTimeout(copyResetTimer);
+    copyResetTimer = null;
+  }
+  tooltipCopy.disabled = false;
+  setPillLabel(tooltipCopy, COPY_IDLE);
+  setIcon(copyIcon, "copy", 12);
+}
+
+function flashCopy(label: string): void {
+  setPillLabel(tooltipCopy, label);
+  setIcon(copyIcon, "check", 12);
+  copyResetTimer = window.setTimeout(resetCopy, 1200);
+}
+
+// Row 2: one chip per class + the id. Hovering a chip pops a rules card (see
+// css-inspect.ts). Wraps within a cap; hidden when the element has neither.
+const tooltipChips = styled("div", "atx-tooltip-chips");
+
+tooltip.append(tooltipRow, tooltipChips);
+
+// --- Hover state -------------------------------------------------------------
+
+// Set once by initHover. Notifies an observer (the element-tree panel) whenever
+// the highlighted page element changes, so it can mirror the highlight onto its
+// matching row (page → tree sync). Lives at module scope because clearHighlight
+// — which also changes the target — is exported and runs outside initHover.
+let onTargetCb: ((el: HTMLElement | null) => void) | null = null;
+
+let highlighted: HTMLElement | null = null;
+// Source of the currently-highlighted element, so the pill's "open" button
+// knows what to open.
+let highlightedSrc: SourceLoc | null = null;
+// Grace timer: when the mouse leaves an element we wait briefly before hiding,
+// so the user can travel up to the pill and click it without it vanishing. (#3)
+let hideTimer: number | null = null;
+// Switch timer: travelling from an element up to its pill often crosses a
+// *different* annotated element (the parent, or a sibling the pill overlaps).
+// Retargeting instantly would yank the pill away mid-travel, so a switch to a
+// new element only lands after a short dwell; reaching the pill (or wandering
+// back) cancels it. The first highlight is never delayed.
+const SWITCH_DELAY = 150;
+let switchTimer: number | null = null;
+let switchTarget: HTMLElement | null = null;
+// Verify dwell: the neutral pill upgrades to a server verdict only after the
+// pointer has rested on one element this long — sweeping the mouse across the
+// page must not fire a /classify per element crossed.
+const VERIFY_DELAY = 500;
+let verifyTimer: number | null = null;
+// Monotonic token, bumped whenever the highlight changes or clears, so a
+// /classify response that lands late can tell its element is no longer
+// highlighted and must not repaint the pill.
+let highlightSeq = 0;
+
+function cancelHide(): void {
+  if (hideTimer !== null) {
+    clearTimeout(hideTimer);
+    hideTimer = null;
+  }
+}
+
+function scheduleHide(): void {
+  cancelHide();
+  hideTimer = window.setTimeout(clearHighlight, 220);
+}
+
+function cancelSwitch(): void {
+  if (switchTimer !== null) {
+    clearTimeout(switchTimer);
+    switchTimer = null;
+  }
+  switchTarget = null;
+}
+
+function cancelVerify(): void {
+  if (verifyTimer !== null) {
+    clearTimeout(verifyTimer);
+    verifyTimer = null;
+  }
+}
+
+// The rules card popped from a chip. On-demand (like a toast), never in the boot
+// append list: at most one exists, rebuilt per chip hover and removed on leave.
+let rulesCard: HTMLElement | null = null;
+let cardHideTimer: number | null = null;
+
+function cancelCardHide(): void {
+  if (cardHideTimer !== null) {
+    clearTimeout(cardHideTimer);
+    cardHideTimer = null;
+  }
+}
+
+function removeCard(): void {
+  cancelCardHide();
+  rulesCard?.remove();
+  rulesCard = null;
+}
+
+function scheduleCardHide(): void {
+  cancelCardHide();
+  cardHideTimer = window.setTimeout(removeCard, 200);
+}
+
+export function clearHighlight(): void {
+  cancelHide();
+  cancelSwitch();
+  cancelVerify();
+  removeCard();
+  resetCopy();
+  highlightSeq++; // invalidate any /classify still in flight
+  const had = highlighted;
+  highlighted = null;
+  highlightedSrc = null;
+  outline.toggleAttribute("data-on", false);
+  tooltip.toggleAttribute("data-on", false);
+  if (had) onTargetCb?.(null);
+}
+
+// Keep the pill open while hovered. (#3)
+tooltip.addEventListener("mouseenter", cancelHide);
+tooltip.addEventListener("mouseleave", scheduleHide);
+
+export interface HoverDeps {
+  isEditMode(): boolean;
+  openSource(src: SourceLoc): void;
+  /** Open the in-browser source-peek panel for a loc. */
+  openPeek(src: SourceLoc): void;
+  /** Whether the CSS class/ID inspector is on — the chips row renders only then. */
+  cssInspector(): boolean;
+  /** Open a CSS rule's source file at (near) the rule in the editor. */
+  openRule(file: string, selector: string): void;
+  /** Gather the element's context and put it on the clipboard. Resolves true
+   *  only when it actually landed there — a fallback panel or a failure
+   *  resolves false, and the button returns to its idle label. */
+  copyContext(el: HTMLElement, src: SourceLoc): Promise<boolean>;
+  /** Notified whenever the highlighted element changes (element-tree sync). */
+  onTarget?(el: HTMLElement | null): void;
+}
+
+/** What initHover hands back to the composition root: the DOM nodes to append,
+ *  and a programmatic `highlight` so the element-tree panel can drive the same
+ *  outline + verdict pill from a row hover (tree → page sync). */
+export interface HoverHandle {
+  elements: HTMLElement[];
+  highlight(el: HTMLElement): void;
+}
+
+/** Wire the hover listeners; returns the elements for the boot code to append
+ *  once the server health check passes, plus a programmatic highlight. */
+export function initHover(deps: HoverDeps): HoverHandle {
+  onTargetCb = deps.onTarget ?? null;
+  const onHighlighted = (open: (src: SourceLoc) => void) => (e: MouseEvent): void => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (highlightedSrc) open(highlightedSrc);
+  };
+  tooltipOpen.addEventListener("click", onHighlighted(deps.openSource));
+  tooltipLabel.addEventListener("click", onHighlighted(deps.openPeek));
+
+  tooltipCopy.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    const el = highlighted;
+    const src = highlightedSrc;
+    if (!el || !src) return;
+    // Gathering takes a /peek round-trip; hold the pill open across it. The
+    // element and loc are captured up front, so the copy still completes if the
+    // pointer wanders off and the highlight clears meanwhile.
+    cancelHide();
+    resetCopy();
+    tooltipCopy.disabled = true;
+    setPillLabel(tooltipCopy, "copying…");
+    setIcon(copyIcon, "spinner", 12);
+    void deps.copyContext(el, src).then((copied) => {
+      tooltipCopy.disabled = false;
+      if (copied) flashCopy("copied");
+      else resetCopy();
+    });
+  });
+
+  /** Sit the pill fully above the element, measured by its actual height (so the
+   *  taller chips-row variant never overlaps the element). Only when there's no
+   *  room above does it drop just below. The admin bar's strip counts as "no
+   *  room" — a pill hidden under it is worse than one below the element. Must run
+   *  after the pill's content is in place — including the chips — for
+   *  offsetHeight to be right. */
+  function positionPill(rect: DOMRect): void {
+    const gap = 6;
+    const inset = chromeInset();
+    const minTop = inset.top + 4;
+    const maxBottom = window.innerHeight - inset.bottom - 4;
+    const above = rect.top - tooltip.offsetHeight - gap;
+    const below = rect.bottom + gap;
+    tooltip.style.left = `${Math.max(4, rect.left)}px`;
+    const fitsBelow = below + tooltip.offsetHeight <= maxBottom;
+    tooltip.style.top = `${above >= minTop ? above : fitsBelow ? below : minTop}px`;
+  }
+
+  /** Paint the outline + pill for `el` with the given verdict. */
+  function render(el: HTMLElement, verdict: Verdict): void {
+    const rect = el.getBoundingClientRect();
+
+    outline.toggleAttribute("data-on", true);
+    Object.assign(outline.style, {
+      ...outlineRect(rect),
+      // The verdict picks the colour, so these two cannot live in the sheet.
+      borderColor: verdict.color,
+      background: hexToRgba(verdict.color, 0.08),
+    } as Partial<CSSStyleDeclaration>);
+
+    const file = highlightedSrc?.file ?? "";
+    const loc = highlightedSrc?.loc || "?";
+    tooltipLoc.textContent = `${basename(file)}:${loc} · `;
+    tooltipVerdict.textContent = verdict.word;
+    // The verdict's colour is the outline's alone. Repeating it as an edge on
+    // the pill made two marks claim the same one thing, and cost the pill its
+    // symmetry — it is a label, the box around the element is the highlight.
+    tooltip.toggleAttribute("data-on", true);
+    positionPill(rect);
+  }
+
+  /** Ask the server (through the cache) and, if the pointer is still on the
+   *  same element, upgrade the neutral pill to the real verdict. */
+  async function verify(el: HTMLElement, src: SourceLoc, seq: number): Promise<void> {
+    let result: ClassifyResult;
+    try {
+      result = await classifyCached({ file: src.file, loc: src.loc, tag: el.tagName.toLowerCase() });
+    } catch {
+      return; // hover is passive — stay neutral; the click path surfaces errors
+    }
+    // The mouse may have moved on (or the highlight cleared) mid-round-trip.
+    if (seq !== highlightSeq || highlighted !== el) return;
+    // Chips stay put on a verdict upgrade — only the loc/verdict line repaints.
+    render(el, verdictFor(result));
+  }
+
+  // --- Class/ID chips + rules card ------------------------------------------
+
+  /** Place the card below its chip, flipping above / clamping to stay on-screen. */
+  function positionCard(card: HTMLElement, anchor: HTMLElement): void {
+    const r = anchor.getBoundingClientRect();
+    const cw = card.offsetWidth;
+    const ch = card.offsetHeight;
+    let left = Math.min(r.left, window.innerWidth - 8 - cw);
+    left = Math.max(8, left);
+    let top = r.bottom + 6;
+    if (top + ch > window.innerHeight - 8) top = Math.max(8, r.top - 6 - ch);
+    card.style.left = `${left}px`;
+    card.style.top = `${top}px`;
+  }
+
+  function showCard(anchor: HTMLElement, token: string, kind: "class" | "id", el: HTMLElement): void {
+    removeCard();
+    const selector = (kind === "class" ? "." : "#") + token;
+    const card = buildRulesCard(selector, rulesForToken(el, token, kind), deps.openRule);
+    card.addEventListener("mouseenter", () => {
+      cancelHide();
+      cancelCardHide();
+    });
+    card.addEventListener("mouseleave", () => {
+      scheduleCardHide();
+      scheduleHide();
+    });
+    mount(card);
+    positionCard(card, anchor);
+    rulesCard = card;
+  }
+
+  function makeChip(label: string, token: string, kind: "class" | "id", el: HTMLElement): HTMLElement {
+    const chip = styled("span", "atx-tooltip-chip");
+    chip.textContent = label;
+    chip.title = `Show CSS applied via ${label}`;
+    // The border on hover is CSS; these listeners are here for the card.
+    chip.addEventListener("mouseenter", () => {
+      cancelHide();
+      showCard(chip, token, kind, el);
+    });
+    chip.addEventListener("mouseleave", scheduleCardHide);
+    return chip;
+  }
+
+  /** Rebuild the chips row for `el` (classes, then id). Hidden when the
+   *  inspector is off or the element has neither. Astro's scope class is noise. */
+  function renderChips(el: HTMLElement): void {
+    tooltipChips.replaceChildren();
+    if (!deps.cssInspector()) {
+      tooltipChips.toggleAttribute("data-on", false);
+      return;
+    }
+    const chips: HTMLElement[] = [];
+    el.classList.forEach((c) => {
+      if (/^astro-[\w-]+$/.test(c)) return; // Astro scoping class, not authored
+      chips.push(makeChip(`.${c}`, c, "class", el));
+    });
+    if (el.id) chips.push(makeChip(`#${el.id}`, el.id, "id", el));
+    if (chips.length === 0) {
+      tooltipChips.toggleAttribute("data-on", false);
+      return;
+    }
+    tooltipChips.toggleAttribute("data-on", true);
+    tooltipChips.append(...chips);
+  }
+
+  function highlight(el: HTMLElement): void {
+    cancelSwitch();
+    cancelVerify();
+    removeCard(); // drop any card left over from the previous element
+    resetCopy(); // a "copied ✓" belongs to the element it was clicked on
+    if (!el.isConnected) return; // HMR may have replaced it during the dwell
+    highlighted = el;
+    onTargetCb?.(el); // mirror onto the element-tree row (page → tree)
+    const src = sourceFor(el) ?? null;
+    highlightedSrc = src;
+    const seq = ++highlightSeq;
+
+    // An already-verified element shows its verdict immediately; otherwise
+    // render the neutral state and verify once the pointer has dwelled.
+    const cached = src ? peekClassification({ file: src.file, loc: src.loc, tag: el.tagName.toLowerCase() }) : undefined;
+    render(el, cached ? verdictFor(cached) : CHECKING);
+    renderChips(el);
+    // The chips row changes the pill's height — re-place it so it still clears
+    // the element (render's placement used the pre-chips height).
+    positionPill(el.getBoundingClientRect());
+    if (!src || cached) return;
+    verifyTimer = window.setTimeout(() => {
+      verifyTimer = null;
+      void verify(el, src, seq);
+    }, VERIFY_DELAY);
+  }
+
+  function onMouseMove(e: MouseEvent): void {
+    if (!deps.isEditMode()) return;
+    // Moving onto any of our own overlay UI — the pill, the rules card, or the
+    // element-tree panel driving highlights of its own — must NOT count as
+    // leaving the element, and wins over any pending retarget. (The tree hovers
+    // a row to highlight an element; that move must not then hide the pill.)
+    // composedPath, not e.target: this listener is on document, which sees a
+    // target retargeted to the shadow host for anything inside the overlay.
+    if (isOwnUi(e)) {
+      cancelHide();
+      cancelCardHide();
+      cancelSwitch();
+      return;
+    }
+    const el = nearestSource(e.target);
+    if (!el) {
+      cancelSwitch();
+      scheduleHide(); // grace period instead of instant hide
+      return;
+    }
+    cancelHide();
+    if (el === highlighted) {
+      cancelSwitch(); // wandered back onto the current element
+      return;
+    }
+    // First highlight lands instantly; a *switch* waits out the dwell so the
+    // pill doesn't jump to the parent while the mouse travels up to it.
+    if (highlighted === null) {
+      highlight(el);
+      return;
+    }
+    if (el === switchTarget) return; // countdown to this element already runs
+    cancelSwitch();
+    switchTarget = el;
+    switchTimer = window.setTimeout(() => highlight(el), SWITCH_DELAY);
+  }
+
+  document.addEventListener("mousemove", onMouseMove, { passive: true });
+  window.addEventListener("scroll", clearHighlight, { passive: true });
+
+  return { elements: [outline, tooltip], highlight };
+}

package/src/client/icons.ts

@@ -0,0 +1,160 @@
+import { styled } from "./ui.ts";
+
+/**
+ * The overlay's icon set: stroke paths on a 24px grid, drawn with `currentColor`
+ * so every icon inherits the colour of the control it sits in.
+ *
+ * The paths are adapted from **Lucide** (https://lucide.dev), ISC licensed:
+ *
+ *   Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as
+ *   part of Feather (MIT). All other copyright (c) for Lucide are held by
+ *   Lucide Contributors 2022. Licensed under the ISC License.
+ *
+ * Inlined as one table rather than installed as a package — the overlay has no
+ * runtime dependencies and ships no font file, and copying the paths keeps it
+ * that way. `svgMarkup` below writes Lucide's own wrapper (24-box, 2px stroke,
+ * round caps and joins), so a path pastes in unchanged; four glyphs deviate and
+ * each says why at its entry.
+ *
+ * `icon()` returns a `<span>` built through ui.ts::styled, so an icon is
+ * router-exempt (never treated as an editable page element) and carries the
+ * `atx-ico` theming hook like everything else in the overlay. Size is set by
+ * the caller; 14px is the bar/pill default, 12px suits dense rows.
+ */
+
+export type IconName =
+  | "cursor"
+  | "pencil"
+  | "file"
+  | "pin"
+  | "pinOff"
+  | "panelTop"
+  | "panelBottom"
+  | "sidebar"
+  | "check"
+  | "dot"
+  | "spinner"
+  | "alert"
+  | "x"
+  | "plus"
+  | "trash"
+  | "quote"
+  | "link"
+  | "chevronRight"
+  | "chevronDown"
+  | "copy"
+  | "code"
+  | "external"
+  | "settings"
+  | "collections"
+  | "lock"
+  | "image"
+  | "search"
+  | "upload";
+
+/** Path geometry only — the wrapper `<svg>` supplies stroke, width and caps. */
+const PATHS: Record<IconName, string> = {
+  // The overlay's own mark: a click-to-edit pointer. Lucide's `mouse-pointer-2`
+  // filled — this one is an identity rather than a glyph in a row, and the
+  // solid arrow holds up at the 14px the toggle draws it at.
+  cursor:
+    '<path d="M4.037 4.688a.495.495 0 0 1 .651-.651l16 6.5a.5.5 0 0 1-.063.947l-6.124 1.58a2 2 0 0 0-1.438 1.435l-1.579 6.126a.5.5 0 0 1-.947.063z" fill="currentColor"/>',
+  pencil:
+    '<path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/>',
+  // file-text
+  file: '<path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z"/><path d="M14 2v5a1 1 0 0 0 1 1h5"/><path d="M10 9H8"/><path d="M16 13H8"/><path d="M16 17H8"/>',
+  pin: '<path d="M12 17v5"/><path d="M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z"/>',
+  pinOff:
+    '<path d="M12 17v5"/><path d="M15 9.34V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H7.89"/><path d="m2 2 20 20"/><path d="M9 9v1.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h11"/>',
+  // panel-top / panel-bottom / panel-left, with the band filled. Lucide's three
+  // differ only by where one divider line sits, which is not readable at the
+  // 14px the bar draws them at — the fill is what says which edge is docked.
+  panelTop:
+    '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M5 3h14a2 2 0 0 1 2 2v4H3V5a2 2 0 0 1 2-2z" fill="currentColor" stroke="none"/>',
+  panelBottom:
+    '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M3 15h18v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" fill="currentColor" stroke="none"/>',
+  sidebar:
+    '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M5 3h4v18H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z" fill="currentColor" stroke="none"/>',
+  check: '<path d="M20 6 9 17l-5-5"/>',
+  // Lucide has no filled dot: `circle-small` is a ring at r=6, and filling that
+  // gives a disc a third wider than the mark it replaces, out of weight with
+  // every other glyph here. This one stays hand-drawn.
+  dot: '<circle cx="12" cy="12" r="4.5" fill="currentColor" stroke="none"/>',
+  // Two arcs of one ring rather than Lucide's single `loader-circle` sweep: the
+  // dim half is what makes the rotation readable.
+  spinner:
+    '<path d="M12 3a9 9 0 1 0 9 9" opacity="0.9"/><path d="M12 3a9 9 0 0 1 9 9" opacity="0.25"/>',
+  // triangle-alert
+  alert:
+    '<path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/>',
+  x: '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>',
+  plus: '<path d="M5 12h14"/><path d="M12 5v14"/>',
+  // trash-2
+  trash:
+    '<path d="M10 11v6"/><path d="M14 11v6"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M3 6h18"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/>',
+  quote:
+    '<path d="M16 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h1a2 2 0 0 1 2 2v1a2 2 0 0 1-2 2h-1a1 1 0 0 0-1 1v1a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"/><path d="M5 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h1a2 2 0 0 1 2 2v1a2 2 0 0 1-2 2H5a1 1 0 0 0-1 1v1a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"/>',
+  // link-2
+  link: '<path d="M9 17H7A5 5 0 0 1 7 7h2"/><path d="M15 7h2a5 5 0 1 1 0 10h-2"/><line x1="8" x2="16" y1="12" y2="12"/>',
+  chevronRight: '<path d="m9 18 6-6-6-6"/>',
+  chevronDown: '<path d="m6 9 6 6 6-6"/>',
+  copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
+  // code-xml — the slash is what reads as *source*, not as a pair of brackets.
+  code: '<path d="m18 16 4-4-4-4"/><path d="m6 8-4 4 4 4"/><path d="m14.5 4-5 16"/>',
+  // external-link
+  external:
+    '<path d="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/>',
+  settings:
+    '<path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915"/><circle cx="12" cy="12" r="3"/>',
+  // database: a collection *is* the content store behind the pages, so the
+  // stacked-cylinder mark is the right one.
+  collections:
+    '<ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5V19A9 3 0 0 0 21 19V5"/><path d="M3 12A9 3 0 0 0 21 12"/>',
+  // A closed padlock — marks a setting the project's own config owns.
+  lock: '<rect width="18" height="11" x="3" y="11" rx="2" ry="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/>',
+  image:
+    '<rect width="18" height="18" x="3" y="3" rx="2" ry="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21"/>',
+  search: '<path d="m21 21-4.34-4.34"/><circle cx="11" cy="11" r="8"/>',
+  upload:
+    '<path d="M12 3v12"/><path d="m17 8-5-5-5 5"/><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/>',
+};
+
+const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
+
+function svgMarkup(name: IconName, size: number): string {
+  return (
+    `<svg viewBox="0 0 24 24" width="${size}" height="${size}" fill="none" ` +
+    'stroke="currentColor" stroke-width="2" stroke-linecap="round" ' +
+    `stroke-linejoin="round" aria-hidden="true" focusable="false">${PATHS[name]}</svg>`
+  );
+}
+
+/** An icon element, ready to append into a button, row or label. */
+export function icon(name: IconName, size = 16): HTMLElement {
+  const host = styled("span", "atx-ico");
+  paint(host, name, size);
+  return host;
+}
+
+/** Swap an existing icon element's glyph in place (same node, same styling). */
+export function setIcon(host: HTMLElement, name: IconName, size = 16): void {
+  if (host.dataset.icon === name) return;
+  paint(host, name, size);
+}
+
+function paint(host: HTMLElement, name: IconName, size: number): void {
+  host.dataset.icon = name;
+  // Static, hand-authored markup from the table above — no interpolation of
+  // anything the page or the server supplied.
+  host.innerHTML = svgMarkup(name, size);
+  for (const anim of host.getAnimations()) anim.cancel();
+  if (name === "spinner" && !window.matchMedia(REDUCED_MOTION).matches) {
+    host.animate(
+      [{ transform: "rotate(0deg)" }, { transform: "rotate(360deg)" }],
+      {
+        duration: 850,
+        iterations: Infinity,
+      },
+    );
+  }
+}