blume 1.7.3 → 2.0.1

package/src/components/content/Prompt.astro

@@ -1,7 +1,10 @@
 ---
 import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
+import data from "blume:data";
 
+import { contentStrings } from "./content-strings.ts";
 import { escapeRawHtml, unwrapParagraph } from "./inline-markdown.ts";
+import { promptMarkdown } from "./prompt-markdown.ts";
 
 interface Props {
   actions?: boolean | string | string[];
@@ -26,6 +29,15 @@ const renderedDescription = await markdownProcessor.render(
   escapeRawHtml(description)
 );
 const descriptionHtml = unwrapParagraph(renderedDescription.code);
+// The prompt as Markdown, for the copy button and the Cursor link: the rendered
+// body's text alone would drop its links, list markers, and code fences.
+const promptSource = Astro.slots.has("default")
+  ? promptMarkdown(await Astro.slots.render("default"))
+  : "";
+const { actions: actionStrings, content: strings } = contentStrings(
+  data,
+  Astro.currentLocale
+);
 
 const primaryButton =
   "inline-flex h-8 cursor-pointer items-center rounded-lg bg-accent px-3.5 font-medium text-accent-foreground text-xs transition hover:bg-accent/90";
@@ -35,6 +47,7 @@ const secondaryButton =
 
 <blume-prompt
   class="not-prose my-6 block rounded-blume border border-border bg-muted/30"
+  data-blume-prompt-markdown={promptSource}
 >
   <div class="flex items-center justify-between gap-3 px-4 py-3">
     <p
@@ -47,39 +60,35 @@ const secondaryButton =
         <div class="flex shrink-0 items-center gap-2">
           {enabledActions.has("copy") && (
             <button
-              aria-label="Copy prompt"
               class={primaryButton}
               data-blume-prompt-copy
+              data-copied={actionStrings.copied}
               type="button"
             >
               {/* Both labels share one grid cell so the button is always sized
-                  to the wider ("Copy prompt") — swapping to "Copied" on copy
-                  can't resize it and shift the description beside it. */}
+                  to the wider one — swapping to the copied label on copy can't
+                  resize it and shift the description beside it. */}
               <span class="grid *:col-start-1 *:row-start-1 *:text-center">
-                <span data-blume-prompt-copy-idle>Copy prompt</span>
+                <span data-blume-prompt-copy-idle>{strings.copyPrompt}</span>
                 <span aria-hidden="true" class="invisible" data-blume-prompt-copy-done>
-                  Copied
+                  {actionStrings.copied}
                 </span>
               </span>
             </button>
           )}
           {enabledActions.has("cursor") && (
             <a
-              aria-label="Open prompt in Cursor"
               class={secondaryButton}
               data-blume-prompt-cursor
-              href="cursor://anysphere.cursor-deeplink/prompt"
+              href={`cursor://anysphere.cursor-deeplink/prompt?text=${encodeURIComponent(promptSource)}`}
             >
-              Open in Cursor
+              {actionStrings.openIn.replace("{name}", "Cursor")}
             </a>
           )}
         </div>
       )
     }
   </div>
-  <div data-blume-prompt-content hidden>
-    <slot />
-  </div>
 </blume-prompt>
 
 <script>
@@ -87,17 +96,9 @@ const secondaryButton =
 
   class BlumePrompt extends HTMLElement {
     connectedCallback() {
-      const content = this.querySelector<HTMLElement>(
-        "[data-blume-prompt-content]"
-      );
-      const promptText = () => content?.textContent?.trim() ?? "";
-
-      const cursor = this.querySelector<HTMLAnchorElement>(
-        "[data-blume-prompt-cursor]"
-      );
-      if (cursor) {
-        cursor.href = `cursor://anysphere.cursor-deeplink/prompt?text=${encodeURIComponent(promptText())}`;
-      }
+      // Serialized to Markdown at build time; the Cursor link already carries
+      // it in its href.
+      const promptText = this.dataset.blumePromptMarkdown ?? "";
 
       const copy = this.querySelector<HTMLButtonElement>(
         "[data-blume-prompt-copy]"
@@ -113,10 +114,9 @@ const secondaryButton =
       const flash = createCopyFlash((copied) => {
         idle?.classList.toggle("invisible", copied);
         done?.classList.toggle("invisible", !copied);
-      }, "Copied");
+      }, copy?.dataset.copied ?? "Copied!");
       copy?.addEventListener("click", async () => {
-        const text = promptText();
-        if (text && (await copyText(text))) {
+        if (promptText && (await copyText(promptText))) {
           flash();
         }
       });

package/src/components/content/Tabs.astro

@@ -272,7 +272,9 @@ const useDropdown = dropdown && !inline;
           url.searchParams.set(param, id);
           history.replaceState(history.state, "", url);
         } else if (this.#hashEnabled()) {
-          history.replaceState(null, "", `#${encodeURIComponent(id)}`);
+          // Keep the entry's state here too: the client router ignores a
+          // popstate whose state is null, so Back would change only the URL.
+          history.replaceState(history.state, "", `#${encodeURIComponent(id)}`);
         }
       }
       if (sync && this.#syncEnabled()) {

package/src/components/content/Tile.astro

@@ -1,10 +1,10 @@
 ---
+import { newTabAttrs } from "../../core/new-tab.ts";
 import Icon from "../Icon.astro";
 import { contentHref } from "./base-href.ts";
 
 const { description, href, title } = Astro.props;
 const Tag = href ? "a" : "div";
-const external = href?.startsWith("http");
 const previewPattern =
   "background-image:radial-gradient(circle at 1px 1px,color-mix(in oklab,currentColor 18%,transparent) 1px,transparent 0);background-size:18px 18px;";
 ---
@@ -13,8 +13,7 @@ const previewPattern =
   class="not-prose block overflow-hidden rounded-blume border border-border bg-background text-inherit no-underline! transition-colors hover:no-underline! hover:[&[href]]:border-accent"
   data-blume-tile
   href={href === undefined ? undefined : contentHref(href)}
-  rel={external ? "noreferrer" : undefined}
-  target={external ? "_blank" : undefined}
+  {...newTabAttrs(href)}
 >
   <div
     class="flex aspect-[16/9] min-h-32 items-center justify-center bg-muted/40 p-4 text-muted-foreground [&_img]:max-h-full [&_img]:max-w-full [&_svg]:max-h-full [&_svg]:max-w-full"

package/src/components/content/Tooltip.astro

@@ -1,8 +1,8 @@
 ---
-import { randomUUID } from "node:crypto";
-
+import { newTabAttrs } from "../../core/new-tab.ts";
 import { contentHref } from "./base-href.ts";
 import { unwrapParagraph } from "./inline-markdown.ts";
+import { tooltipId as tooltipIdFor } from "./tooltip-id.ts";
 
 interface Props {
   cta?: string;
@@ -12,15 +12,24 @@ interface Props {
 }
 
 const { cta, headline, href, tip } = Astro.props;
-const tooltipId = `blume-tooltip-${randomUUID()}`;
-const external = href?.startsWith("http");
 
 const labelHtml = Astro.slots.has("default")
   ? unwrapParagraph(await Astro.slots.render("default"))
   : "";
+// Derived from the content, so an unchanged page rebuilds byte-identical.
+const tooltipId = tooltipIdFor(Astro.locals, [
+  labelHtml,
+  headline,
+  tip,
+  cta,
+  href,
+]);
 ---
 
-<span class="not-prose group relative inline-flex cursor-help items-baseline">
+<span
+  class="not-prose relative inline-flex cursor-help items-baseline"
+  data-blume-tooltip
+>
   <span
     aria-describedby={tooltipId}
     class="underline decoration-dotted underline-offset-4"
@@ -41,8 +50,7 @@ const labelHtml = Astro.slots.has("default")
         <a
           class="mt-2 inline-flex font-medium text-accent text-xs hover:underline"
           href={contentHref(href)}
-          rel={external ? "noreferrer" : undefined}
-          target={external ? "_blank" : undefined}
+          {...newTabAttrs(href)}
         >
           {cta}
         </a>
@@ -57,9 +65,49 @@ const labelHtml = Astro.slots.has("default")
     visibility: hidden;
   }
 
-  [data-blume-tooltip-trigger]:focus + [data-blume-tooltip-panel],
-  .group:hover [data-blume-tooltip-panel] {
+  /* Focus anywhere inside keeps it open, so a keyboard reader can Tab from
+     the trigger to the call-to-action link without the panel vanishing. */
+  [data-blume-tooltip]:hover [data-blume-tooltip-panel],
+  [data-blume-tooltip]:focus-within [data-blume-tooltip-panel] {
     pointer-events: auto;
     visibility: visible;
   }
+
+  /* Escape hides it until the pointer or focus leaves (WCAG 1.4.13). */
+  [data-blume-tooltip][data-dismissed] [data-blume-tooltip-panel] {
+    pointer-events: none;
+    visibility: hidden;
+  }
 </style>
+
+<script>
+  // Delegated from the document, so tooltips a client-router swap brings in
+  // are covered without re-binding; the module runs once per real load.
+  const TOOLTIP = "[data-blume-tooltip]";
+
+  document.addEventListener("keydown", (event) => {
+    if (event.key !== "Escape") {
+      return;
+    }
+    for (const tooltip of document.querySelectorAll(TOOLTIP)) {
+      if (tooltip.matches(":hover, :focus-within")) {
+        tooltip.setAttribute("data-dismissed", "");
+      }
+    }
+  });
+
+  // Leaving the tooltip re-arms it for the next hover or focus.
+  const rearm = (event: FocusEvent | PointerEvent) => {
+    const tooltip =
+      event.target instanceof Element ? event.target.closest(TOOLTIP) : null;
+    const { relatedTarget } = event;
+    if (
+      tooltip &&
+      !(relatedTarget instanceof Node && tooltip.contains(relatedTarget))
+    ) {
+      tooltip.removeAttribute("data-dismissed");
+    }
+  };
+  document.addEventListener("focusout", rearm);
+  document.addEventListener("pointerout", rearm);
+</script>

package/src/components/content/content-strings.ts

@@ -0,0 +1,34 @@
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+
+/** The `blume:data` fields a content component resolves its labels from. */
+export interface ContentStringsData {
+  config: { i18n: object | null };
+  ui: UIStrings;
+  uiByLocale: Record<string, UIStrings>;
+}
+
+/** The UI string groups a content component's chrome reads. */
+export type ContentStrings = Pick<UIStrings, "actions" | "content">;
+
+/**
+ * Labels for a component rendered inside page content (MDX), which gets no
+ * strings prop from the layout the way chrome components do: the dictionary of
+ * the locale Astro resolved for the URL (`Astro.currentLocale`, the page's own
+ * locale — a fallback page included, matching its chrome), else the site
+ * default. Merged over the English baseline per group, so a key a translation
+ * lacks still renders instead of coming out blank.
+ */
+export const contentStrings = (
+  data: ContentStringsData,
+  currentLocale?: string
+): ContentStrings => {
+  const dictionary =
+    data.config.i18n && currentLocale
+      ? (data.uiByLocale[currentLocale] ?? data.ui)
+      : data.ui;
+  return {
+    actions: { ...EN_UI.actions, ...dictionary.actions },
+    content: { ...EN_UI.content, ...dictionary.content },
+  };
+};

package/src/components/content/diff.ts

@@ -36,7 +36,7 @@ export interface DiffOptions {
   /** Path to a `.patch`/`.diff` file, resolved relative to {@link DiffOptions.root}. */
   src?: string;
   /**
-   * Light/dark Shiki themes (`markdown.codeBlocks.theme`). Defaults to the same
+   * Light/dark Shiki themes (`markdown.code.theme`). Defaults to the same
    * github pair Blume's code blocks use, keeping diffs in lockstep.
    */
   theme?: CodeThemes;

package/src/components/content/mermaid-element.ts

@@ -23,7 +23,10 @@ const prefersDark = () => document.documentElement.dataset.theme === "dark";
 
 let counter = 0;
 
-class BlumeMermaid extends HTMLElement {
+// Exported so this file is a module, not a script: `blume:features` lazy-loads
+// it with `import()`, and `astro check` rejects a dynamic import of a file with
+// no import or export of its own (ts(2306)) on every site with a diagram.
+export class BlumeMermaid extends HTMLElement {
   #observer: MutationObserver | null = null;
   #renderToken = 0;
 
@@ -84,8 +87,16 @@ class BlumeMermaid extends HTMLElement {
     // Re-render on color-theme changes so the diagram tracks light and dark.
     // One observer per connection, disconnected on removal — otherwise every
     // DOM move stacks another observer that renders into detached DOM forever.
+    // The theme script rewrites `data-theme` after every client-router swap,
+    // usually to the value it already had, so only a real flip re-renders.
+    let dark = prefersDark();
     this.#observer?.disconnect();
-    this.#observer = new MutationObserver(() => render());
+    this.#observer = new MutationObserver(() => {
+      if (prefersDark() !== dark) {
+        dark = prefersDark();
+        render();
+      }
+    });
     this.#observer.observe(document.documentElement, {
       attributeFilter: ["data-theme"],
     });

package/src/components/content/prompt-markdown.ts

@@ -0,0 +1,292 @@
+import { NodeType, parse } from "node-html-parser";
+import type { HTMLElement, Node } from "node-html-parser";
+
+/**
+ * A `<Prompt>`'s body as Markdown, for its copy button and "Open in Cursor"
+ * link. The component only ever sees its slot as rendered HTML, so this turns
+ * that HTML back into the Markdown a reader pastes into an AI tool — keeping
+ * link URLs, list markers, emphasis, and code fences that the element's plain
+ * `textContent` would drop.
+ */
+
+/** Elements that carry no prompt text: chrome, media, and hidden content. */
+const SKIPPED = new Set(["BUTTON", "SCRIPT", "STYLE", "SVG", "TEMPLATE"]);
+
+const HEADING = /^H(?<level>[1-6])$/u;
+
+/** Elements that start a block of their own rather than flowing inline. */
+const BLOCKS = new Set([
+  "BLOCKQUOTE",
+  "DETAILS",
+  "DIV",
+  "FIGURE",
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+  "HR",
+  "OL",
+  "P",
+  "PRE",
+  "SECTION",
+  "TABLE",
+  "UL",
+]);
+
+const isElement = (node: Node): node is HTMLElement =>
+  node.nodeType === NodeType.ELEMENT_NODE;
+
+const isSkipped = (element: HTMLElement): boolean =>
+  SKIPPED.has(element.tagName) ||
+  element.hasAttribute("hidden") ||
+  element.getAttribute("aria-hidden") === "true";
+
+/** A backtick run one longer than any inside `text`, so it can't close early. */
+const fenceFor = (text: string, minimum: number): string => {
+  const longest = Math.max(
+    0,
+    ...(text.match(/`+/gu) ?? []).map((run) => run.length)
+  );
+  return "`".repeat(Math.max(minimum, longest + 1));
+};
+
+/** Wrap `inner` in `marker`, keeping edge spaces outside the markers. */
+const wrap = (marker: string, inner: string): string => {
+  const trimmed = inner.trim();
+  if (!trimmed) {
+    return inner;
+  }
+  const lead = inner.startsWith(" ") ? " " : "";
+  const trail = inner.endsWith(" ") ? " " : "";
+  return `${lead}${marker}${trimmed}${marker}${trail}`;
+};
+
+const inlineCode = (text: string): string => {
+  const fence = fenceFor(text, 1);
+  const pad = text.startsWith("`") || text.endsWith("`") ? " " : "";
+  return `${fence}${pad}${text}${pad}${fence}`;
+};
+
+/**
+ * Finish an inline run: HTML collapses whitespace across element edges too, so
+ * the space a text node and an emphasis marker each kept becomes one.
+ */
+const collapse = (text: string): string =>
+  text.replaceAll(/ {2,}/gu, " ").trim();
+
+const inline = (node: Node): string => {
+  if (!isElement(node)) {
+    // HTML collapses runs of whitespace (source newlines included) to one space.
+    return node.text.replaceAll(/\s+/gu, " ");
+  }
+  if (isSkipped(node)) {
+    return "";
+  }
+  const children = () => node.childNodes.map(inline).join("");
+  switch (node.tagName) {
+    case "A": {
+      const href = node.getAttribute("href");
+      const label = children().trim();
+      if (!href) {
+        return label;
+      }
+      return label && label !== href ? `[${label}](${href})` : href;
+    }
+    case "B":
+    case "STRONG": {
+      return wrap("**", children());
+    }
+    case "BR": {
+      return "\n";
+    }
+    case "CODE": {
+      return inlineCode(node.text);
+    }
+    case "DEL":
+    case "S": {
+      return wrap("~~", children());
+    }
+    case "EM":
+    case "I": {
+      return wrap("_", children());
+    }
+    case "IMG": {
+      const src = node.getAttribute("src");
+      return src ? `![${node.getAttribute("alt") ?? ""}](${src})` : "";
+    }
+    default: {
+      return children();
+    }
+  }
+};
+
+/** A line-by-line indent, leaving blank lines blank. */
+const indent = (text: string, prefix: string): string =>
+  text
+    .split("\n")
+    .map((line) => (line ? `${prefix}${line}` : line))
+    .join("\n");
+
+const codeBlock = (pre: HTMLElement): string => {
+  const code = pre.querySelector("code");
+  const language =
+    pre.attributes["data-language"] ??
+    /\blanguage-(?<lang>\S+)/u.exec(code?.getAttribute("class") ?? "")?.groups
+      ?.lang ??
+    "";
+  const text = (code ?? pre).text.replace(/\n$/u, "");
+  const fence = fenceFor(text, 3);
+  return `${fence}${language}\n${text}\n${fence}`;
+};
+
+const listBlock = (list: HTMLElement): string => {
+  const ordered = list.tagName === "OL";
+  let number = Number(list.getAttribute("start") ?? "1") || 1;
+  const items: string[] = [];
+  for (const item of list.childNodes) {
+    if (!isElement(item) || item.tagName !== "LI") {
+      continue;
+    }
+    const marker = ordered ? `${number}.` : "-";
+    number += 1;
+    // A tight item (no paragraphs of its own) keeps its nested list on the
+    // next line; a loose one separates its blocks with a blank line.
+    const loose = item.childNodes.some(
+      (child) => isElement(child) && child.tagName === "P"
+    );
+    // oxlint-disable-next-line no-use-before-define -- mutual recursion: an item holds blocks, including nested lists
+    const body = blocks(item).join(loose ? "\n\n" : "\n");
+    const [first = "", ...rest] = body.split("\n");
+    const continuation = indent(rest.join("\n"), " ".repeat(marker.length + 1));
+    items.push(
+      continuation
+        ? `${marker} ${first}\n${continuation}`
+        : `${marker} ${first}`
+    );
+  }
+  return items.join("\n");
+};
+
+/** A GFM delimiter cell per column alignment; unaligned columns get `---`. */
+const DELIMITERS = new Map([
+  ["center", ":---:"],
+  ["left", ":---"],
+  ["right", "---:"],
+]);
+
+const TEXT_ALIGN = /text-align:\s*(?<align>center|left|right)/u;
+
+/** A cell's alignment, from the `align` attribute or an inline style. */
+const cellAlign = (cell: HTMLElement | undefined): string =>
+  cell?.getAttribute("align") ??
+  TEXT_ALIGN.exec(cell?.getAttribute("style") ?? "")?.groups?.align ??
+  "";
+
+/** A cell's inline Markdown on one line, its pipes escaped. */
+const tableCell = (cell: HTMLElement | undefined): string =>
+  cell
+    ? collapse(inline(cell).replaceAll("\n", " ")).replaceAll(
+        "|",
+        String.raw`\|`
+      )
+    : "";
+
+const isCell = (node: Node): node is HTMLElement =>
+  isElement(node) && (node.tagName === "TD" || node.tagName === "TH");
+
+/**
+ * A table as a GFM table: its first row as the header (GFM requires one), a
+ * delimiter row carrying each column's alignment, then the body rows, padded
+ * to the widest row.
+ */
+const tableBlock = (table: HTMLElement): string => {
+  const rows = table
+    .querySelectorAll("tr")
+    .filter((row) => !isSkipped(row))
+    .map((row) => row.childNodes.filter(isCell));
+  const [head, ...body] = rows;
+  if (!head) {
+    return "";
+  }
+  const width = Math.max(...rows.map((row) => row.length));
+  const columns = Array.from({ length: width }, (_, index) => index);
+  const row = (cells: HTMLElement[]): string =>
+    `| ${columns.map((index) => tableCell(cells[index])).join(" | ")} |`;
+  const delimiter = `| ${columns
+    .map((index) => DELIMITERS.get(cellAlign(head[index])) ?? "---")
+    .join(" | ")} |`;
+  return [row(head), delimiter, ...body.map(row)].join("\n");
+};
+
+const block = (element: HTMLElement): string[] => {
+  const heading = HEADING.exec(element.tagName)?.groups?.level;
+  if (heading) {
+    return [`${"#".repeat(Number(heading))} ${collapse(inline(element))}`];
+  }
+  switch (element.tagName) {
+    case "BLOCKQUOTE": {
+      // Every line is quoted, blank ones included, so the paragraphs stay in
+      // one quote.
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion: a quote holds blocks
+      const quoted = blocks(element)
+        .join("\n\n")
+        .split("\n")
+        .map((line) => (line ? `> ${line}` : ">"));
+      return [quoted.join("\n")];
+    }
+    case "HR": {
+      return ["---"];
+    }
+    case "OL":
+    case "UL": {
+      return [listBlock(element)];
+    }
+    case "P": {
+      return [collapse(inline(element))];
+    }
+    case "PRE": {
+      return [codeBlock(element)];
+    }
+    case "TABLE": {
+      return [tableBlock(element)];
+    }
+    default: {
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion: a container holds blocks
+      return blocks(element);
+    }
+  }
+};
+
+/** A container's children as Markdown blocks, inline runs grouped into one. */
+const blocks = (container: HTMLElement): string[] => {
+  const out: string[] = [];
+  let run = "";
+  const flush = () => {
+    const text = collapse(run);
+    if (text) {
+      out.push(text);
+    }
+    run = "";
+  };
+  for (const child of container.childNodes) {
+    if (isElement(child) && BLOCKS.has(child.tagName)) {
+      flush();
+      if (!isSkipped(child)) {
+        out.push(...block(child).filter(Boolean));
+      }
+    } else {
+      run += inline(child);
+    }
+  }
+  flush();
+  return out;
+};
+
+export const promptMarkdown = (html: string): string =>
+  // `pre` is parsed as elements (not raw text) so a code block's `<code>` and
+  // its language attribute are reachable.
+  blocks(parse(html, { blockTextElements: { script: true, style: true } }))
+    .join("\n\n")
+    .trim();

package/src/components/content/tooltip-id.ts

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Per-render bookkeeping for stable element ids, kept on the request's
+ * `Astro.locals` so every component in one page render — layout and MDX
+ * content alike — shares it, and concurrent page renders never see each
+ * other's.
+ */
+export interface StableIdLocals {
+  /** Prefix + content digest → how many elements on this page carried it. */
+  blumeStableIds?: Map<string, number>;
+}
+
+/**
+ * An element id derived from what the element renders, not drawn at random,
+ * so rebuilding an unchanged page produces the same HTML. A second identical
+ * element on the same page gets a numbered suffix to keep ids unique;
+ * identical elements render identical markup, so which copy is numbered never
+ * changes the page's bytes.
+ */
+export const stableId = (
+  locals: StableIdLocals,
+  prefix: string,
+  content: readonly (string | undefined)[]
+): string => {
+  const digest = createHash("sha256")
+    .update(JSON.stringify(content))
+    .digest("hex")
+    .slice(0, 12);
+  const base = `${prefix}-${digest}`;
+  locals.blumeStableIds ??= new Map();
+  const count = (locals.blumeStableIds.get(base) ?? 0) + 1;
+  locals.blumeStableIds.set(base, count);
+  return count === 1 ? base : `${base}-${count}`;
+};
+
+/** The element id a tooltip's panel and trigger pair on. */
+export const tooltipId = (
+  locals: StableIdLocals,
+  content: readonly (string | undefined)[]
+): string => stableId(locals, "blume-tooltip", content);

package/src/components/copy-feedback.ts

@@ -1,6 +1,6 @@
 /**
  * Shared clipboard + "Copied" feedback used by every copy affordance (code
- * blocks, page actions, color swatches, prompts, API panels, Ask AI). One
+ * blocks, page actions, color swatches, prompts, API panels, the assistant). One
  * implementation owns the invariants each site used to hand-roll:
  *
  * - the clipboard write is guarded and a confirmation must never lie: a