@hypit/hypit 0.0.1 → 0.1.1

package/packages/studio/src/ui/code.ts

@@ -0,0 +1,450 @@
+import type { Range, StudioSnapshot, StudioSourceView } from "../shared.js";
+import { icon, setIcon } from "./icons.js";
+import { intentTones } from "./markers.js";
+import { tokenizeSvml } from "./syntax.js";
+import type { Token } from "./syntax.js";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+export type Highlight = {
+  readonly range: Range;
+  /**
+   * `element` outlines the authored tag, `binding` the author's intent, and
+   * `onscreen` a tag that is merely drawn at this frame rather than chosen.
+   */
+  readonly tone: "element" | "binding" | "onscreen";
+  /** Nesting depth, so an inner pair is drawn distinctly from the one enclosing it. */
+  readonly depth?: number;
+};
+
+export type CodePane = {
+  readonly toolbar: HTMLElement;
+  readonly element: HTMLElement;
+  /** Returns false only while an unsaved file is being saved before a switch. */
+  show(snapshot: StudioSnapshot, source?: StudioSourceView): boolean;
+  activePath(): string | undefined;
+  highlight(values: readonly Highlight[], scrollIntoView: boolean): void;
+  /** Mark the word being spoken at the playhead, or nothing outside speech. */
+  speak(range: Range | undefined): void;
+  /** Absolute source offset under a pointer event, or undefined outside the text. */
+  offsetAt(event: MouseEvent): number | undefined;
+};
+
+/** One text node and the absolute source span it covers. */
+type Piece = { readonly node: Text; readonly start: number; readonly end: number };
+
+type Line = {
+  readonly element: HTMLElement;
+  readonly code: HTMLElement;
+  readonly start: number;
+  readonly end: number;
+  readonly pieces: readonly Piece[];
+};
+
+/** A point on the rendered glyph grid, in scroll-container coordinates. */
+type Caret = { readonly x: number; readonly y: number; readonly height: number };
+
+/**
+ * One rounded outline through an arbitrary polygon. Ported from the Hypit
+ * demo so a highlight here reads the same as a highlight on the site.
+ */
+function roundedRangePath(points: readonly { x: number; y: number }[], radius = 6): string {
+  return `${points.map((point, index) => {
+    const previous = points[(index - 1 + points.length) % points.length]!;
+    const next = points[(index + 1) % points.length]!;
+    const previousLength = Math.hypot(previous.x - point.x, previous.y - point.y) || 1;
+    const nextLength = Math.hypot(next.x - point.x, next.y - point.y) || 1;
+    const corner = Math.min(radius, previousLength / 2, nextLength / 2);
+    const before = {
+      x: point.x + (previous.x - point.x) * corner / previousLength,
+      y: point.y + (previous.y - point.y) * corner / previousLength,
+    };
+    const after = {
+      x: point.x + (next.x - point.x) * corner / nextLength,
+      y: point.y + (next.y - point.y) * corner / nextLength,
+    };
+    return `${index === 0 ? "M" : "L"} ${before.x} ${before.y} Q ${point.x} ${point.y} ${after.x} ${after.y}`;
+  }).join(" ")} Z`;
+}
+
+/** Keep source-range outlines clear of the line-number column. */
+const RANGE_LEFT = 41;
+
+export function createCodePane(): CodePane {
+  const toolbar = document.createElement("div");
+  toolbar.className = "code-toolbar";
+  toolbar.innerHTML = `
+    <strong class="code-location" data-path></strong>
+    <div class="code-actions">
+      <span class="code-save-state" data-save-state></span>
+      <button type="button" class="icon-button code-wrap" data-wrap aria-label="Wrap lines" aria-pressed="false" title="Wrap lines">
+        ${icon("wrap")}
+      </button>
+      <button type="button" class="icon-button code-mode" data-mode aria-label="Edit source" title="Edit source">
+        <span data-mode-icon>${icon("edit")}</span>
+      </button>
+    </div>`;
+  const element = document.createElement("section");
+  element.className = "code";
+  element.innerHTML = `
+    <div class="code-scroll"><svg class="range-canvas" aria-hidden="true"></svg></div>
+    <textarea class="code-editor" data-editor spellcheck="false" aria-label="SVML source"></textarea>`;
+  const path = toolbar.querySelector<HTMLElement>("[data-path]")!;
+  const scroll = element.querySelector<HTMLElement>(".code-scroll")!;
+  const canvas = element.querySelector<SVGSVGElement>(".range-canvas")!;
+  const editor = element.querySelector<HTMLTextAreaElement>("[data-editor]")!;
+  const wrap = toolbar.querySelector<HTMLButtonElement>("[data-wrap]")!;
+  const mode = toolbar.querySelector<HTMLButtonElement>("[data-mode]")!;
+  const modeIcon = mode.querySelector<HTMLElement>("[data-mode-icon]")!;
+  const saveState = toolbar.querySelector<HTMLElement>("[data-save-state]")!;
+
+  let lines: Line[] = [];
+  let current: readonly Highlight[] = [];
+  let spoken: HTMLElement | undefined;
+  let snapshotRevision = 0;
+  let editingRevision = 0;
+  let sourceText = "";
+  let activeSource: StudioSourceView | undefined;
+  let authorPath = "";
+  let editing = false;
+  let dirty = false;
+  let saveInFlight = false;
+  let saveTimer: number | undefined;
+  let wrapped = false;
+
+  const setWrapped = (value: boolean): void => {
+    wrapped = value;
+    element.classList.toggle("is-wrapped", wrapped);
+    wrap.setAttribute("aria-pressed", String(wrapped));
+    wrap.setAttribute("aria-label", wrapped ? "Keep lines unwrapped" : "Wrap lines");
+    wrap.title = wrapped ? "Keep lines unwrapped" : "Wrap lines";
+    window.requestAnimationFrame(draw);
+  };
+
+  const setEditing = (value: boolean): void => {
+    editing = value;
+    element.classList.toggle("is-editing", editing);
+    setIcon(modeIcon, editing ? "eye" : "edit");
+    mode.setAttribute("aria-label", editing ? "Read source" : "Edit source");
+    mode.title = editing ? "Read source" : "Edit source";
+    if (editing) {
+      editor.value = sourceText;
+      editingRevision = snapshotRevision;
+      editor.focus({ preventScroll: true });
+    }
+  };
+
+  const save = async (): Promise<void> => {
+    if (!editing || !dirty || saveInFlight) return;
+    const savingPath = activeSource?.path;
+    const savingText = editor.value;
+    const savingRevision = editingRevision;
+    if (savingPath === undefined) return;
+    saveInFlight = true;
+    let accepted = false;
+    let acceptedRevision = savingRevision;
+    saveState.textContent = "Saving";
+    saveState.className = "code-save-state saving";
+    try {
+      const response = await fetch("/__studio/source", {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: savingPath, text: savingText, revision: savingRevision }),
+      });
+      if (!response.ok) {
+        const reason = await response.text();
+        throw new Error(reason || `Save failed (${response.status})`);
+      }
+      const result = await response.json() as { readonly revision?: unknown };
+      if (typeof result.revision === "number") acceptedRevision = result.revision;
+      accepted = true;
+      if (activeSource?.path === savingPath) editingRevision = acceptedRevision;
+      if (activeSource?.path === savingPath && editor.value === savingText) {
+        sourceText = savingText;
+        dirty = false;
+      }
+      saveState.textContent = "Saved";
+      saveState.className = "code-save-state saved";
+      window.setTimeout(() => {
+        if (!dirty) saveState.textContent = "";
+      }, 1200);
+    } catch (error) {
+      saveState.textContent = error instanceof Error && error.message.includes("changed")
+        ? "Changed outside Studio"
+        : "Save failed";
+      saveState.className = "code-save-state error";
+    } finally {
+      saveInFlight = false;
+      if (accepted && dirty && activeSource?.path === savingPath) {
+        if (saveTimer !== undefined) window.clearTimeout(saveTimer);
+        saveTimer = window.setTimeout(() => void save(), 240);
+      }
+    }
+  };
+
+  mode.addEventListener("click", () => {
+    if (editing && dirty) void save();
+    setEditing(!editing);
+  });
+  wrap.addEventListener("click", () => setWrapped(!wrapped));
+  editor.addEventListener("input", () => {
+    dirty = true;
+    saveState.textContent = "Unsaved";
+    saveState.className = "code-save-state dirty";
+    if (saveTimer !== undefined) window.clearTimeout(saveTimer);
+    saveTimer = window.setTimeout(() => void save(), 480);
+  });
+  editor.addEventListener("keydown", (event) => {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "s") {
+      event.preventDefault();
+      if (saveTimer !== undefined) window.clearTimeout(saveTimer);
+      void save();
+    }
+  });
+
+  const lineAt = (offset: number): Line | undefined =>
+    lines.find((line) => offset >= line.start && offset <= line.end);
+
+  /**
+   * Measure one absolute offset from a real source character. Using a character
+   * rectangle also keeps punctuation and token boundaries exact.
+   */
+  const caret = (offset: number, edge: "start" | "end"): Caret | undefined => {
+    const line = lineAt(offset);
+    if (line === undefined) return undefined;
+    const box = scroll.getBoundingClientRect();
+    const toLocal = (rect: DOMRect, x: number): Caret => ({
+      x: x - box.left + scroll.scrollLeft,
+      y: (rect.top + rect.bottom) / 2 - box.top + scroll.scrollTop,
+      height: rect.height,
+    });
+
+    const piece = edge === "start"
+      ? line.pieces.find((item) => offset >= item.start && offset < item.end)
+        ?? line.pieces.find((item) => offset <= item.start)
+      : line.pieces.find((item) => offset > item.start && offset <= item.end)
+        ?? line.pieces.findLast((item) => offset >= item.end);
+
+    const range = document.createRange();
+    if (piece !== undefined) {
+      const within = Math.max(0, Math.min(offset - piece.start, piece.node.length));
+      if (within < piece.node.length) {
+        range.setStart(piece.node, within);
+        range.setEnd(piece.node, within + 1);
+        const rect = range.getClientRects()[0];
+        if (rect !== undefined) return toLocal(rect, rect.left);
+      }
+      if (within > 0) {
+        range.setStart(piece.node, within - 1);
+        range.setEnd(piece.node, within);
+        const rect = range.getClientRects()[0];
+        if (rect !== undefined) return toLocal(rect, rect.right);
+      }
+    }
+    const rect = line.code.getBoundingClientRect();
+    return toLocal(rect, edge === "start" ? rect.left : rect.right);
+  };
+
+  const draw = (): void => {
+    // In wrapped mode the viewport is the content width. Reusing scrollWidth
+    // here would let the previous wide SVG keep itself wide forever after a
+    // mode switch, because that absolute canvas also contributes to scrollWidth.
+    const width = wrapped ? scroll.clientWidth : Math.max(scroll.clientWidth, scroll.scrollWidth);
+    const last = lines.at(-1)?.element;
+    const height = Math.max(scroll.clientHeight, last === undefined ? 0 : last.offsetTop + last.offsetHeight);
+    canvas.setAttribute("width", String(width));
+    canvas.setAttribute("height", String(height));
+    canvas.setAttribute("viewBox", `0 0 ${width} ${height}`);
+    canvas.replaceChildren();
+    if (width === 0) return;
+
+    for (const item of current) {
+      const start = caret(item.range.start, "start");
+      const end = caret(item.range.end, "end");
+      if (start === undefined || end === undefined) continue;
+      const lineHeight = start.height || Number.parseFloat(getComputedStyle(scroll).lineHeight) || 20;
+      // The outline starts at the code column rather than over the line number.
+      const left = RANGE_LEFT;
+      const rightInset = Number.parseFloat(getComputedStyle(element).getPropertyValue("--code-inline-end")) || 12;
+      const right = width - rightInset;
+      const startX = Math.max(left, start.x - 3);
+      const endX = Math.max(left, end.x + 3);
+      const top = start.y - lineHeight / 2;
+      const bottom = end.y + lineHeight / 2;
+      // Compare measured baselines so multi-line source ranges use one outline.
+      const sameRow = Math.abs(start.y - end.y) < lineHeight / 2;
+      // A multi-row range becomes one flag rather than a stack of boxes, so the
+      // whole region reads as a single selection.
+      const points = sameRow
+        ? [{ x: startX, y: top }, { x: endX, y: top }, { x: endX, y: bottom }, { x: startX, y: bottom }]
+        : [
+          { x: startX, y: top }, { x: right, y: top },
+          { x: right, y: end.y - lineHeight / 2 }, { x: endX, y: end.y - lineHeight / 2 },
+          { x: endX, y: bottom }, { x: left, y: bottom },
+          { x: left, y: start.y + lineHeight / 2 }, { x: startX, y: start.y + lineHeight / 2 },
+        ];
+      const node = document.createElementNS(SVG_NS, "path");
+      node.setAttribute("d", roundedRangePath(points));
+      node.setAttribute("class",
+        `range range-${item.tone}${item.depth === undefined ? "" : ` tone-${item.depth}`}`);
+      canvas.append(node);
+    }
+  };
+
+  scroll.addEventListener("scroll", draw);
+  new ResizeObserver(draw).observe(scroll);
+
+  return {
+    toolbar,
+    element,
+    show(snapshot, selected) {
+      const sourceFile = selected
+        ?? snapshot.source.files.find((file) => file.path === snapshot.source.path)
+        ?? {
+          path: snapshot.source.path,
+          text: snapshot.source.text,
+          language: "svml" as const,
+          role: "author" as const,
+          imports: [],
+        };
+      if (activeSource !== undefined && activeSource.path !== sourceFile.path && dirty) {
+        saveState.textContent = "Saving before switch";
+        saveState.className = "code-save-state saving";
+        void save();
+        return false;
+      }
+      if (activeSource !== undefined && activeSource.path !== sourceFile.path && editing) setEditing(false);
+      activeSource = sourceFile;
+      authorPath = snapshot.source.path;
+      path.textContent = sourceFile.path.split(/[\\/]/u).filter(Boolean).at(-1) ?? sourceFile.path;
+      path.title = sourceFile.path;
+      const source = sourceFile.text;
+      snapshotRevision = snapshot.revision;
+      sourceText = source;
+      if (!editing || !dirty) {
+        editor.value = source;
+        editingRevision = snapshot.revision;
+      }
+      const tokens: readonly Token[] = tokenizeSvml(source);
+      const tones = intentTones(snapshot);
+      lines = [];
+      const fragment = document.createDocumentFragment();
+      let offset = 0;
+      let index = 0;
+
+      for (const [number, value] of source.split("\n").entries()) {
+        const lineStart = offset;
+        const lineEnd = offset + value.length;
+        const row = document.createElement("div");
+        row.className = "code-line";
+        row.dataset.offset = String(lineStart);
+        const gutter = document.createElement("span");
+        gutter.className = "line-number";
+        gutter.textContent = String(number + 1);
+        const code = document.createElement("code");
+        const pieces: Piece[] = [];
+
+        // Emit one text node per token and per gap between tokens, clipped to
+        // this line, so the concatenation stays byte-identical to the source.
+        const emit = (from: number, to: number, token?: Token): void => {
+          if (to <= from) return;
+          const node = document.createTextNode(source.slice(from, to));
+          if (token === undefined) code.append(node);
+          else {
+            const span = document.createElement("span");
+            // A marker pair shares a tone with the clip it binds, so the two
+            // ends of `@claim … @/claim` read as one thing.
+            const tone = token.id === undefined ? undefined : tones.get(token.id);
+            span.className = `tok tok-${token.kind}${tone === undefined ? "" : ` tone-${tone}`}`;
+            if (token.id !== undefined) span.dataset.marker = token.id;
+            span.append(node);
+            code.append(span);
+          }
+          pieces.push({ node, start: from, end: to });
+        };
+
+        while (index < tokens.length && tokens[index]!.end <= lineStart) index += 1;
+        let cursor = lineStart;
+        for (let scan = index; scan < tokens.length && tokens[scan]!.start < lineEnd; scan += 1) {
+          const token = tokens[scan]!;
+          const from = Math.max(token.start, lineStart);
+          const to = Math.min(token.end, lineEnd);
+          if (to <= cursor) continue;
+          emit(cursor, from);
+          emit(from, to, token);
+          cursor = to;
+        }
+        emit(cursor, lineEnd);
+        // An empty line still needs a box to measure and click.
+        if (pieces.length === 0) code.append(document.createTextNode(" "));
+
+        row.append(gutter, code);
+        fragment.append(row);
+        lines.push({ element: row, code, start: lineStart, end: lineEnd, pieces });
+        offset = lineEnd + 1;
+      }
+
+      scroll.replaceChildren(canvas, fragment);
+      draw();
+      return true;
+    },
+    activePath() { return activeSource?.path; },
+    speak(range) {
+      spoken?.remove();
+      spoken = undefined;
+      if (range === undefined || activeSource?.path !== authorPath) return;
+      const line = lineAt(range.start);
+      const piece = line?.pieces.find((item) => range.start >= item.start && range.start < item.end);
+      // A word is highlighted by drawing over it rather than by rewriting the
+      // text: the offsets every other measurement depends on stay put.
+      const start = caret(range.start, "start");
+      const end = caret(range.end, "end");
+      if (line === undefined || piece === undefined || start === undefined || end === undefined) return;
+      if (Math.abs(start.y - end.y) > (start.height || 20) / 2) return;
+      const mark = document.createElement("div");
+      mark.className = "spoken";
+      mark.style.left = `${start.x - 2}px`;
+      mark.style.top = `${start.y - (start.height || 20) / 2}px`;
+      mark.style.width = `${Math.max(2, end.x - start.x + 4)}px`;
+      mark.style.height = `${start.height || 20}px`;
+      scroll.append(mark);
+      spoken = mark;
+    },
+    highlight(values, scrollIntoView) {
+      current = activeSource?.path === authorPath ? values : [];
+      draw();
+      const first = current[0];
+      if (!scrollIntoView || first === undefined) return;
+      lineAt(first.range.start)?.element.scrollIntoView({ behavior: "smooth", block: "center" });
+    },
+    offsetAt(event) {
+      const row = (event.target as HTMLElement | null)?.closest<HTMLElement>(".code-line");
+      const line = row === null || row === undefined
+        ? undefined
+        : lines.find((item) => item.element === row);
+      if (line === undefined) return undefined;
+      // Pick the character whose rendered box is nearest to the pointer.
+      const range = document.createRange();
+      let best = line.start;
+      let bestDistance = Number.POSITIVE_INFINITY;
+      for (const piece of line.pieces) {
+        for (let within = 0; within < piece.node.length; within += 1) {
+          range.setStart(piece.node, within);
+          range.setEnd(piece.node, within + 1);
+          const rect = range.getClientRects()[0];
+          if (rect === undefined) continue;
+          const dy = event.clientY < rect.top ? rect.top - event.clientY
+            : event.clientY > rect.bottom ? event.clientY - rect.bottom : 0;
+          const dx = event.clientX < rect.left ? rect.left - event.clientX
+            : event.clientX > rect.right ? event.clientX - rect.right : 0;
+          const distance = dy * 1000 + dx;
+          if (distance < bestDistance) {
+            bestDistance = distance;
+            best = piece.start + within;
+          }
+        }
+      }
+      return best;
+    },
+  };
+}

package/packages/studio/src/ui/icons.ts

@@ -0,0 +1,51 @@
+const paths: Readonly<Record<string, string>> = {
+  brand: '<g transform="translate(0 1.282) scale(.091603) translate(-50 -180)"><path fill="currentColor" stroke="none" d="M303.78,277.82c-5.98-8.63-15.83-13.77-26.32-13.77h-93.41c-12.28,0-24.92,7.44-29.6,18.8l-28.26,75.82c-4.6,11.25-4.54,24.05,2.22,34.16,6.79,10.15,19.36,16.15,31.57,16.15h85.98c14.12,0,26.9-8.88,31.84-22.1l29.69-79.57c3.67-9.84,2.29-20.86-3.69-29.48v-.02h-.02ZM252.02,377.25c-.94,2.52-3.39,4.22-6.08,4.22h-83.45c-4.34,0-6.68-2.8-7.49-3.99s-2.5-4.43-.84-8.44l23.85-66.24c2.29-6.35,8.08-10.87,14.82-11.22.33-.02.67-.02,1.02-.02h75.41s12.51,1.42,9.29,14.61l-26.53,71.09h0ZM106.85,361.73s-22.36-11.59-17.66-32.66l29.67-82.23c4.78-13.25,17.36-22.09,31.45-22.09h95.02c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-112.97c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h0ZM73.3,323.27s-22.37-11.59-17.66-32.66l29.67-82.23c4.79-13.25,17.37-22.09,31.45-22.09h89.91c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-107.84c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h-.02Z"/></g>',
+  code: '<path d="M9 7 4 12l5 5M15 7l5 5-5 5M13 4l-2 16"/>',
+  edit: '<path d="m4 16-.8 4 4-.8L18.5 8.9 15.1 5.5 4 16Z"/><path d="m13.8 6.8 3.4 3.4"/>',
+  eye: '<path d="M2.5 12s3.5-6 9.5-6 9.5 6 9.5 6-3.5 6-9.5 6-9.5-6-9.5-6Z"/><circle cx="12" cy="12" r="2.5"/>',
+  preview: '<rect x="3" y="4" width="18" height="14" rx="2"/><path d="m10 8 5 3.5-5 3.5V8ZM8 21h8"/>',
+  tune: '<path d="M4 7h10M18 7h2M4 17h2M10 17h10"/><circle cx="16" cy="7" r="2"/><circle cx="8" cy="17" r="2"/>',
+  where: '<rect x="6" y="6" width="12" height="12" rx="1"/><path d="M12 2v7M12 15v7M2 12h7M15 12h7"/>',
+  how: '<path d="M6 3v18M12 3v18M18 3v18"/><rect x="4" y="7" width="4" height="5" rx="1"/><rect x="10" y="13" width="4" height="5" rx="1"/><rect x="16" y="5" width="4" height="5" rx="1"/>',
+  when: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3.5 2M4.5 4.5 2.5 7M19.5 4.5 21.5 7"/>',
+  chevron: '<path d="m7 9 5 5 5-5"/>',
+  select: '<path d="M5 3v15l4-4 3 6 3-1.5-3-6h6L5 3Z"/>',
+  tasks: '<path d="M10 6h10M10 12h10M10 18h10"/><path d="m3.5 6 1.5 1.5L7.5 4.5M3.5 12 5 13.5l2.5-3M3.5 18 5 19.5l2.5-3"/>',
+  results: '<path d="M4 8v12h16V8M3 4h18v4H3zM9 12h6"/>',
+  run: '<circle cx="12" cy="12" r="9"/><path d="m10 8 6 4-6 4V8Z"/>',
+  image: '<rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="8.5" cy="9" r="2"/><path d="m4 18 5-5 3 3 3-4 5 6"/>',
+  sidebarCollapse: '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M8 4v16m7-11-3 3 3 3"/>',
+  wrap: '<path d="M4 6h16M4 10h12a4 4 0 0 1 0 8h-5m3-3-3 3 3 3M4 14h5M4 18h4"/>',
+  timeline: '<path d="M3 6h18M3 12h18M3 18h18"/><path d="M8 4v4M16 10v4M11 16v4"/>',
+  minus: '<path d="M5 12h14"/>',
+  plus: '<path d="M12 5v14M5 12h14"/>',
+  fit: '<path d="M8 4H4v4M16 4h4v4M8 20H4v-4M16 20h4v-4"/>',
+  previous: '<path d="M7 5v14M18 6l-8 6 8 6V6Z"/>',
+  next: '<path d="M17 5v14M6 6l8 6-8 6V6Z"/>',
+  play: '<path d="m8 5 11 7-11 7V5Z"/>',
+  pause: '<path d="M8 5v14M16 5v14"/>',
+  volume: '<path d="M4 10v4h4l5 4V6l-5 4H4Z"/><path d="M16 9c1.5 1.7 1.5 4.3 0 6M19 6.5c3 3 3 8 0 11"/>',
+  muted: '<path d="M4 10v4h4l5 4V6l-5 4H4ZM17 10l4 4M21 10l-4 4"/>',
+  // The speech bubble's geometric path is left-heavy because of its tail.
+  // Shift it two view-box units so its optical centre shares the same column
+  // as the symmetric video, waveform, text and caption glyphs.
+  speech: '<g transform="translate(2 0)"><path d="M7 17H5a3 3 0 0 1-3-3V7a3 3 0 0 1 3-3h10a3 3 0 0 1 3 3v7a3 3 0 0 1-3 3h-4l-4 3v-3Z"/><path d="M7 9h6M7 12h4"/></g>',
+  waveform: '<path d="M3 12h2l1.5-6 3 12 3-14 3 16 2-8H21"/>',
+  video: '<rect x="3" y="5" width="14" height="14" rx="2"/><path d="m17 10 4-2v8l-4-2v-4Z"/>',
+  text: '<path d="M5 5h14M12 5v14M8 19h8"/>',
+  captions: '<rect x="3" y="5" width="18" height="14" rx="2"/><path d="M7 11h4M13 11h4M7 15h3M12 15h5"/>',
+  link: '<path d="m9 15 6-6"/><path d="M7.5 17.5h-1a4 4 0 0 1 0-8h3"/><path d="M16.5 6.5h1a4 4 0 0 1 0 8h-3"/>',
+  moment: '<path d="m12 3 3 9-3 9-3-9 3-9Z"/>',
+  component: '<rect x="4" y="4" width="6" height="6" rx="1"/><rect x="14" y="4" width="6" height="6" rx="1"/><rect x="4" y="14" width="6" height="6" rx="1"/><rect x="14" y="14" width="6" height="6" rx="1"/>',
+  layers: '<path d="m12 3 9 5-9 5-9-5 9-5Z"/><path d="m3 12 9 5 9-5M3 16l9 5 9-5"/>',
+  ranking: '<path d="M5 19V9h4v10M10 19V5h4v14M15 19v-7h4v7M3 19h18"/>',
+  refresh: '<path d="M20 7v5h-5M4 17v-5h5"/><path d="M18.5 9a7 7 0 0 0-11.8-2.3L4 9M5.5 15a7 7 0 0 0 11.8 2.3L20 15"/>',
+};
+
+export function icon(name: string, className = "icon"): string {
+  return `<svg class="${className}" viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">${paths[name] ?? paths.layers}</svg>`;
+}
+
+export function setIcon(target: Element, name: string): void {
+  target.innerHTML = icon(name);
+}