@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/capture/editor.tsx

@@ -0,0 +1,178 @@
+/**
+ * The toolbar's drawing editor over a picture of the page, with nothing beside it: no comment box, no draft,
+ * nothing sent. It is the toolbar's `MarkupEditor`, in the frame the toolbar's own screenshot surface gives it
+ * (`../runtime/shot.tsx`), with Cancel and Done where that surface has its draft controls.
+ */
+import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from "react";
+import { ATTACHMENT_MAX_BYTES } from "../runtime/attachment-model.js";
+import * as Icon from "../runtime/icons.js";
+import {
+  MarkupEditor,
+  type MarkupEditorHandle,
+  type MarkupResult,
+} from "../runtime/markup-editor.js";
+import { sizeOf, type CapturedImage } from "./picture.js";
+import { Announce } from "./surface.js";
+
+const TAB_STOPS =
+  'button:not(:disabled), input:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Keeps the keyboard in `node`. Tab goes round its controls: past the last comes the first, and the other way
+ * round. Escape is this dialog's to answer and never the browser's or the page's: left alone, it would also
+ * close a modal `<dialog>` of the host that this one is open in.
+ */
+function holdKeys(node: HTMLElement) {
+  const onKey = (event: KeyboardEvent) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      return;
+    }
+    if (event.key !== "Tab") return;
+    const stops = [...node.querySelectorAll<HTMLElement>(TAB_STOPS)];
+    const first = stops[0];
+    const last = stops[stops.length - 1];
+    if (!first || !last) {
+      event.preventDefault();
+      return;
+    }
+    const active = document.activeElement;
+    const leaving = event.shiftKey
+      ? active === first || active === node
+      : active === last || !node.contains(active);
+    if (!leaving) return;
+    event.preventDefault();
+    (event.shiftKey ? last : first).focus({ preventScroll: true });
+  };
+  // In the capture phase: the editor stops its own keys before they bubble this far.
+  node.addEventListener("keydown", onKey, true);
+  return () => node.removeEventListener("keydown", onKey, true);
+}
+
+export type EditorProps = {
+  /** The picture to draw on, or null while the page is still being drawn. */
+  picture: CapturedImage | null;
+  /** Done: the picture as it now is. */
+  onDone: (image: CapturedImage) => void;
+  /** Cancel, or Escape with nothing drawn. */
+  onCancel: () => void;
+};
+
+export function Editor({ picture, onDone, onCancel }: EditorProps) {
+  const section = useRef<HTMLElement>(null);
+  const editor = useRef<MarkupEditorHandle>(null);
+  const [drawn, setDrawn] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!picture) return;
+    const made = URL.createObjectURL(picture.blob);
+    setUrl(made);
+    return () => URL.revokeObjectURL(made);
+  }, [picture]);
+
+  useEffect(() => {
+    const node = section.current;
+    if (!node) return;
+    // Until the editor is there to take the focus itself, the dialog holds it.
+    node.focus({ preventScroll: true });
+    return holdKeys(node);
+  }, []);
+
+  /** Hands back what a save produced: the flattened picture, or the original when nothing is drawn on it. */
+  const finish = async (result: MarkupResult | null) => {
+    if (!picture) return;
+    if (!result?.blob) {
+      onDone(picture);
+      return;
+    }
+    const size = await sizeOf(result.blob, picture);
+    onDone({ blob: result.blob, name: result.name, ...size, markedUp: true });
+  };
+
+  const done = () => {
+    const handle = editor.current;
+    if (!handle || saving) return;
+    setSaving(true);
+    handle
+      .save()
+      .then(finish)
+      // The editor shows why it could not save, and stays open.
+      .catch(() => setSaving(false));
+  };
+
+  // Keys from the header's buttons, and from the dialog itself while the page is drawn. The editor handles
+  // its own, by the same rule: Escape leaves only while there is no drawing to lose.
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLElement>) => {
+    if (event.key !== "Escape" || drawn || saving) return;
+    onCancel();
+  };
+
+  return (
+    <>
+      <div className="cs-shot-scrim cs-hit" data-cs-ui="capture-scrim" />
+      <section
+        ref={section}
+        className="cs-card cs-shot cs-hit"
+        data-cs-ui="capture-editor"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Screenshot of this page. Draw on it, then press Done."
+        tabIndex={-1}
+        // The toolbar's surface leaves room for its bar under it; here there is none.
+        style={{ bottom: "calc(12 * var(--cs-u))", outline: "none" }}
+        onKeyDown={onKeyDown}
+      >
+        <header className="cs-shot-head">
+          <span className="cs-shot-title">
+            <Icon.Camera size={12} />
+            <strong>Screenshot</strong>
+            <span className="cs-shot-count">Draw on it to show what you mean</span>
+          </span>
+          <span className="cs-shot-spacer" />
+          <button
+            type="button"
+            className="cs-markup-cancel"
+            data-cs-ui="capture-cancel"
+            onClick={onCancel}
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            className="cs-markup-done"
+            data-cs-ui="capture-done"
+            disabled={!url || saving}
+            onClick={done}
+          >
+            {saving ? "Saving…" : "Done"}
+          </button>
+        </header>
+        <div className="cs-shot-body">
+          <div className="cs-shot-stage cs-media">
+            {picture && url ? (
+              <MarkupEditor
+                mode="inline"
+                handle={editor}
+                src={url}
+                name={picture.name}
+                shapes={[]}
+                maxBytes={ATTACHMENT_MAX_BYTES}
+                onChange={(shapes) => setDrawn(shapes.length > 0)}
+                onCancel={onCancel}
+                onSave={() => {}}
+                onSubmit={(result) => void finish(result)}
+              />
+            ) : (
+              <p className="cs-markup-status" data-cs-ui="capture-wait">
+                Capturing the page…
+              </p>
+            )}
+          </div>
+        </div>
+      </section>
+      <Announce text="Screenshot taken. Draw on it to show what you mean, then press Done. Escape closes it." />
+    </>
+  );
+}

package/src/capture/ignore.ts

@@ -0,0 +1,38 @@
+/**
+ * What is not the page, to a capture: Comment Tool's own UI and the host's floating UI.
+ *
+ * The toolbar's root is `#cs-root`, and the toolbar leaves that id out of its pictures, keeps its presses and
+ * its focus from the page, and never offers it to point at. The capture script's root carries the same id on
+ * purpose (`./surface.tsx`), so every toolbar build treats it as its own, and this script treats the toolbar the
+ * same way: neither is in the other's pictures.
+ *
+ * A host marks its own floating UI (a help button, the panel that asked for the capture) with
+ * `data-cs-capture-ignore`. Only this script reads the attribute: the toolbar still pictures a marked element,
+ * because to a reviewer it is part of the app.
+ */
+export const IGNORE_ATTRIBUTE = "data-cs-capture-ignore";
+
+const ROOT_ID = "cs-root";
+const NOT_THE_PAGE = `#${ROOT_ID}, [${IGNORE_ATTRIBUTE}]`;
+
+/** True for the root of a subtree a picture leaves out. */
+export function leftOut(element: Element): boolean {
+  return element.id === ROOT_ID || element.hasAttribute(IGNORE_ATTRIBUTE);
+}
+
+/** True when `target` is Comment Tool's UI or the host's marked UI, or inside either. */
+export function notThePage(target: EventTarget | null): boolean {
+  return target instanceof Element && target.closest(NOT_THE_PAGE) !== null;
+}
+
+/** The page's own element at a point of the viewport, as the toolbar's `elementAt` finds it. */
+export function pageElementAt(x: number, y: number): Element | null {
+  for (const element of document.elementsFromPoint(x, y)) {
+    if (element === document.body || element === document.documentElement) continue;
+    if (notThePage(element)) continue;
+    const tag = element.tagName;
+    if (tag === "SCRIPT" || tag === "STYLE") continue;
+    return element;
+  }
+  return null;
+}

package/src/capture/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `/v1/toolbar/capture.js`: the toolbar's capture tools, for a host page to call.
+ *
+ *   <script src="https://<service>/v1/toolbar/capture.js" async></script>
+ *
+ * A host adds the tag when a person asks to capture something, not on every page: this file carries the
+ * drawing editor and React, and is far larger than `embed.js`. It asks no session route, reads no stored
+ * sign-in and sends nothing; a toolbar on the same page is neither needed nor disturbed.
+ * `scripts/build-toolbar.mjs` builds it next to the runtime and the loader, so the service serves all three.
+ *
+ * A classic script, like `embed.js`: it defines `window.CommentToolCapture` and has no chunks to fetch.
+ */
+import { createCapture, type CommentToolCaptureApi } from "./api.js";
+
+const GLOBAL = "CommentToolCapture";
+/** Dispatched on `document` once `window.CommentToolCapture` exists, for code that does not wait on the tag. */
+const READY_EVENT = "comment-tool-capture:ready";
+
+function install(): void {
+  const page = window as unknown as Record<string, Partial<CommentToolCaptureApi> | undefined>;
+  // A second tag: the first one's object stays, with whatever capture it has open.
+  if (typeof page[GLOBAL]?.screenshot === "function") return;
+  page[GLOBAL] = createCapture();
+  document.dispatchEvent(new Event(READY_EVENT));
+}
+
+install();

package/src/capture/picker.tsx

@@ -0,0 +1,171 @@
+/**
+ * Pointing at one thing on the page, as the toolbar's "comment on this" does: a crosshair, the element under
+ * the pointer outlined and named, one click to choose it. The outline and the hint are the toolbar's own
+ * (`.cs-outline`, `.cs-banner`), and the listeners follow its picking mode in `../runtime/toolbar.tsx`: the
+ * page never sees the click that chooses, or the presses around it.
+ */
+import { useEffect, useRef, useState } from "react";
+import { describeElement } from "../runtime/capture.js";
+import * as Icon from "../runtime/icons.js";
+import { notThePage, pageElementAt } from "./ignore.js";
+import { Announce } from "./surface.js";
+
+type Highlight = { top: number; left: number; width: number; height: number; label: string };
+
+const PRESSES = ["pointerdown", "mousedown", "pointerup", "mouseup", "touchstart", "touchend"];
+
+export type PickerProps = {
+  /** The element the person clicked. */
+  onPick: (element: Element) => void;
+  /** Escape, or the hint's Cancel. */
+  onCancel: () => void;
+};
+
+export function Picker({ onPick, onCancel }: PickerProps) {
+  const [highlight, setHighlight] = useState<Highlight | null>(null);
+  const cancel = useRef<HTMLButtonElement>(null);
+  const handlers = useRef({ onPick, onCancel });
+  useEffect(() => {
+    handlers.current = { onPick, onCancel };
+  });
+
+  useEffect(() => {
+    cancel.current?.focus({ preventScroll: true });
+  }, []);
+
+  useEffect(() => {
+    const page = document.documentElement;
+    const cursor = page.style.cursor;
+    page.style.cursor = "crosshair";
+    // One hit-test per frame, however many moves arrive; the name is worked out only for a new element.
+    let frame = 0;
+    let pending: MouseEvent | null = null;
+    let under: Element | null = null;
+    let label = "";
+    const show = () => {
+      frame = 0;
+      const event = pending;
+      pending = null;
+      if (!event) return;
+      const element = notThePage(event.target) ? null : pageElementAt(event.clientX, event.clientY);
+      const rect = element?.getBoundingClientRect();
+      if (!element || !rect || (rect.width < 1 && rect.height < 1)) {
+        under = null;
+        setHighlight(null);
+        return;
+      }
+      if (element !== under) {
+        under = element;
+        label = describeElement(element);
+      }
+      const next = {
+        top: rect.top,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height,
+        label,
+      };
+      setHighlight((current) =>
+        current &&
+        current.top === next.top &&
+        current.left === next.left &&
+        current.width === next.width &&
+        current.height === next.height &&
+        current.label === next.label
+          ? current
+          : next,
+      );
+    };
+    const onMove = (event: MouseEvent) => {
+      pending = event;
+      if (!frame) frame = requestAnimationFrame(show);
+    };
+    const onClick = (event: MouseEvent) => {
+      // The hint's Cancel, a toolbar on the page, and the host's own marked UI keep their clicks.
+      if (notThePage(event.target)) return;
+      const element = pageElementAt(event.clientX, event.clientY);
+      if (!element) return;
+      event.preventDefault();
+      event.stopPropagation();
+      handlers.current.onPick(element);
+    };
+    const swallow = (event: Event) => {
+      if (notThePage(event.target)) return;
+      if (!event.type.startsWith("touch")) event.preventDefault();
+      event.stopPropagation();
+    };
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      // Before the page: an open menu or dialog there would close on the same key.
+      event.preventDefault();
+      event.stopPropagation();
+      handlers.current.onCancel();
+    };
+    document.addEventListener("mousemove", onMove, true);
+    window.addEventListener("click", onClick, true);
+    window.addEventListener("keydown", onKey, true);
+    for (const type of PRESSES) window.addEventListener(type, swallow, true);
+    return () => {
+      cancelAnimationFrame(frame);
+      page.style.cursor = cursor;
+      document.removeEventListener("mousemove", onMove, true);
+      window.removeEventListener("click", onClick, true);
+      window.removeEventListener("keydown", onKey, true);
+      for (const type of PRESSES) window.removeEventListener(type, swallow, true);
+    };
+  }, []);
+
+  return (
+    <>
+      {highlight ? (
+        <>
+          <div
+            className="cs-outline is-hover"
+            data-cs-ui="capture-outline"
+            style={{
+              transform: `translate(${highlight.left}px, ${highlight.top}px)`,
+              width: highlight.width,
+              height: highlight.height,
+            }}
+          />
+          <div
+            className="cs-outline-label is-hover"
+            data-cs-ui="capture-outline-label"
+            style={{
+              transform: `translate(${highlight.left}px, ${Math.max(3, highlight.top - 20)}px)`,
+            }}
+          >
+            {highlight.label}
+          </div>
+        </>
+      ) : null}
+      <div
+        className="cs-banner cs-hit"
+        data-cs-ui="capture-pick"
+        role="group"
+        aria-label="Point at something on the page"
+      >
+        <Icon.Cursor />
+        <span>Click the thing you mean</span>
+        <button
+          ref={cancel}
+          type="button"
+          data-cs-ui="capture-pick-cancel"
+          onClick={() => handlers.current.onCancel()}
+        >
+          Cancel
+        </button>
+      </div>
+      <Announce text="Click the thing you mean on the page. Escape cancels." />
+    </>
+  );
+}
+
+/** What stays on screen while the picture of a chosen element is drawn. */
+export function Capturing() {
+  return (
+    <div className="cs-toast" data-cs-ui="capture-wait" role="status">
+      Capturing…
+    </div>
+  );
+}

package/src/capture/picture.ts

@@ -0,0 +1,90 @@
+/**
+ * The pictures the capture script hands back. They are the toolbar's: the page is copied by the toolbar's
+ * `snapshotPage`, drawn by its `renderSnapshot`, and outlined and encoded by its `shotPage`. The one thing that
+ * differs from the toolbar's `takeShot` is what is left out (`./ignore.ts`).
+ */
+import { loadImage } from "../runtime/markup.js";
+import { pageBackground } from "../runtime/page-background.js";
+import { renderSnapshot, snapshotPage } from "../runtime/page-image.js";
+import { frameOf, shotPage, type PageShot } from "../runtime/screenshot.js";
+import { leftOut } from "./ignore.js";
+
+/** Widest picture, in device pixels: the toolbar's limit for a page screenshot (`screenshot.ts`). */
+const PAGE_MAX_WIDTH = 1600;
+
+/** What a host gets back for a picture. */
+export type CapturedImage = {
+  blob: Blob;
+  name: string;
+  /** The picture's own size, in its pixels. */
+  width: number;
+  height: number;
+  /** True when the person drew on it. */
+  markedUp: boolean;
+};
+
+function stamp() {
+  return new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-");
+}
+
+/**
+ * Copies the visible page now, synchronously, as the toolbar's `takeShot` does, with `highlight`'s box measured
+ * at the same moment. Comment Tool's UI and the host's marked UI are left out.
+ */
+export function shootPage(highlight?: Element | null, timeout = 6000): PageShot {
+  const viewport = { width: document.documentElement.clientWidth, height: window.innerHeight };
+  const frame = highlight ? frameOf(highlight.getBoundingClientRect(), viewport) : null;
+  const snapshot = snapshotPage({
+    width: viewport.width,
+    height: viewport.height,
+    exclude: leftOut,
+    backgroundColor: pageBackground(),
+  });
+  const scale = Math.min(window.devicePixelRatio || 1, 2, PAGE_MAX_WIDTH / viewport.width);
+  let drawn: Promise<HTMLCanvasElement> | null = null;
+  return {
+    frame,
+    viewport,
+    scale,
+    render: () => {
+      drawn ??= renderSnapshot(snapshot, scale, timeout);
+      return drawn;
+    },
+  };
+}
+
+/**
+ * Draws `shot` into a file: the whole visible page as a JPEG, the framed element outlined when there is one.
+ * Null when the page could not be drawn.
+ */
+export async function pictureOf(shot: PageShot): Promise<CapturedImage | null> {
+  const blob = await shotPage(shot).catch(() => null);
+  if (!blob) return null;
+  // `shotPage` drew from this same canvas, at its size.
+  const page = await shot.render();
+  return {
+    blob,
+    name: `screenshot-${stamp()}.jpg`,
+    width: page.width,
+    height: page.height,
+    markedUp: false,
+  };
+}
+
+/** The size of an encoded picture, or `fallback` where the browser cannot decode it. */
+export async function sizeOf(
+  blob: Blob,
+  fallback: { width: number; height: number },
+): Promise<{ width: number; height: number }> {
+  const url = URL.createObjectURL(blob);
+  try {
+    const image = await loadImage(url);
+    return image.naturalWidth > 0 && image.naturalHeight > 0
+      ? { width: image.naturalWidth, height: image.naturalHeight }
+      : fallback;
+  } catch {
+    return fallback;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}

package/src/capture/surface.tsx

@@ -0,0 +1,185 @@
+/**
+ * Where the capture script draws its own UI: a root of the toolbar's kind, mounted for one capture and removed
+ * when it ends.
+ *
+ * The root is `<div id="cs-root">`, the toolbar's id, on purpose. The toolbar's stylesheet is written against
+ * that id, so the editor and the picker look as they do in the toolbar with no second copy of the CSS. And
+ * every toolbar build already treats that id as Comment Tool's own UI: it leaves it out of pictures and
+ * recordings drawn from the page, keeps its presses from the page, and does not read keys typed in it as page
+ * shortcuts. So a toolbar on the same page needs no change to live beside this script.
+ *
+ * While both are on the page there are two elements with that id. The toolbar's is in `<body>` and this one
+ * sits after `<body>`, so `document.getElementById("cs-root")` still finds the toolbar's, whichever came
+ * first.
+ *
+ * The one exception is a page with a modal `<dialog>` open. The browser draws that above everything else and
+ * makes everything outside it inert, so the root goes inside the dialog, as the toolbar's own does
+ * (`../runtime/placement.ts`). It is still fixed to the window, unless the dialog's own CSS makes it the
+ * containing block of fixed-position content (a transform, a filter), in which case it fills the dialog.
+ */
+import { useEffect, useState, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { shieldFromPage } from "../runtime/shield.js";
+import { injectStyles, type StylePart } from "../runtime/styles.js";
+import { useScreenTier } from "../runtime/ui-scale.js";
+
+export type CaptureTheme = "light" | "dark" | "auto";
+
+const STYLE_PARTS: StylePart[] = ["bar", "panel", "overlay"];
+const DARK_SCHEME = "(prefers-color-scheme: dark)";
+
+/**
+ * The toolbar's stylesheet, added once. A sheet that is already there is the toolbar's own (or an earlier
+ * capture's) and is left as it is: `injectStyles` would rewrite it with this build's text, and a toolbar of
+ * another build on the page must keep the CSS it was built with.
+ */
+function ensureStyles() {
+  for (const part of STYLE_PARTS) {
+    if (!document.getElementById(`cs-style-${part}`)) injectStyles(part);
+  }
+}
+
+function inCapture(target: EventTarget | null) {
+  return target instanceof Element && target.closest("[data-cs-capture]") !== null;
+}
+
+/**
+ * Hides focus moving into the capture UI from the page's focus traps. The toolbar's shield does this with
+ * listeners on `document` that it registers when the page loads, ahead of any dialog's. This script loads
+ * later, often from inside the host's own open panel, so its listeners sit on `<html>`: an event passes there
+ * before it reaches `document`, whenever the trap's listeners were added.
+ */
+function shieldFocus() {
+  const guard = (event: Event) => {
+    const into = event.type === "focusin" ? event.target : (event as FocusEvent).relatedTarget;
+    if (inCapture(into)) event.stopPropagation();
+  };
+  const root = document.documentElement;
+  root.addEventListener("focusin", guard);
+  root.addEventListener("focusout", guard);
+  return () => {
+    root.removeEventListener("focusin", guard);
+    root.removeEventListener("focusout", guard);
+  };
+}
+
+/**
+ * The modal `<dialog>` the page has open, if it has one: the last in the document, as the toolbar picks its
+ * own. A dialog shown without `showModal()` is ordinary content and needs nothing.
+ */
+function modalDialog(): HTMLDialogElement | null {
+  let open: HTMLDialogElement[];
+  try {
+    open = [...document.querySelectorAll<HTMLDialogElement>("dialog:modal")];
+  } catch {
+    // A browser without `:modal` has no top layer to be under.
+    return null;
+  }
+  return open.filter((dialog) => !dialog.closest("#cs-root")).at(-1) ?? null;
+}
+
+function prefersDark() {
+  return typeof window.matchMedia === "function" && window.matchMedia(DARK_SCHEME).matches;
+}
+
+function useDark(theme: CaptureTheme) {
+  const [system, setSystem] = useState(prefersDark);
+  useEffect(() => {
+    if (theme !== "auto" || typeof window.matchMedia !== "function") return;
+    const query = window.matchMedia(DARK_SCHEME);
+    const sync = () => setSystem(query.matches);
+    sync();
+    query.addEventListener("change", sync);
+    return () => query.removeEventListener("change", sync);
+  }, [theme]);
+  return theme === "dark" || (theme === "auto" && system);
+}
+
+function Root({ theme, children }: { theme: CaptureTheme; children: ReactNode }) {
+  const dark = useDark(theme);
+  const screen = useScreenTier();
+  return (
+    <div
+      id="cs-root"
+      data-cs-capture=""
+      data-react-grab-ignore=""
+      className={dark ? "cs-fixed cs-dark" : "cs-fixed"}
+      data-cs-screen={screen === "desktop" ? undefined : screen}
+      // Nothing typed in the capture UI belongs to the page, or to a toolbar's shortcuts.
+      onKeyDown={(event) => event.stopPropagation()}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Tells a screen reader what opened. The region is on the page first and gets its text a moment later: a live
+ * region that arrives already filled is not read by every screen reader.
+ */
+export function Announce({ text }: { text: string }) {
+  const [said, setSaid] = useState("");
+  useEffect(() => {
+    const id = window.setTimeout(() => setSaid(text), 50);
+    return () => window.clearTimeout(id);
+  }, [text]);
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      data-cs-ui="capture-announce"
+      style={{
+        position: "absolute",
+        width: 1,
+        height: 1,
+        overflow: "hidden",
+        clipPath: "inset(50%)",
+        whiteSpace: "nowrap",
+      }}
+    >
+      {said}
+    </div>
+  );
+}
+
+export type Surface = {
+  /** Draws `node` in the root, in place of what was there. */
+  show(node: ReactNode): void;
+  /** Removes the root and gives the focus back to what had it. Safe to call twice. */
+  close(): void;
+};
+
+/**
+ * Mounts an empty root for one capture. `onLost` is called when the page takes the root away while it is
+ * open: the modal dialog it was mounted in has closed.
+ */
+export function openSurface(theme: CaptureTheme, onLost: () => void): Surface {
+  const focused = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  ensureStyles();
+  const unshieldPresses = shieldFromPage();
+  const unshieldFocus = shieldFocus();
+  const container = document.createElement("div");
+  container.setAttribute("data-cs-capture-runtime", "");
+  container.style.display = "contents";
+  // After <body>, not in it, or in the open modal dialog: see the note at the top of this file.
+  const dialog = modalDialog();
+  (dialog ?? document.documentElement).appendChild(container);
+  dialog?.addEventListener("close", onLost);
+  const root = createRoot(container);
+  let open = true;
+  return {
+    show(node) {
+      if (open) root.render(<Root theme={theme}>{node}</Root>);
+    },
+    close() {
+      if (!open) return;
+      open = false;
+      dialog?.removeEventListener("close", onLost);
+      root.unmount();
+      container.remove();
+      unshieldPresses();
+      unshieldFocus();
+      if (focused?.isConnected) focused.focus({ preventScroll: true });
+    },
+  };
+}