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

package/src/runtime/replay.ts

@@ -0,0 +1,173 @@
+import { consoleText, redactSecretSearchParams, type ReplayBuffer } from "./replay-model.js";
+import { fieldIsSensitive, redactText } from "./redact.js";
+
+export * from "./replay-model.js";
+
+function requestPath(input: RequestInfo | URL) {
+  try {
+    const url = new URL(
+      typeof input === "string" ? input : input instanceof URL ? input.href : input.url,
+      location.href,
+    );
+    redactSecretSearchParams(url);
+    return redactText(`${url.pathname}${url.search}`).slice(0, 300);
+  } catch {
+    return "";
+  }
+}
+
+// Only what it reads: a workspace may type-check this source with the Workers types,
+// whose global `Element` conflicts with `HTMLSelectElement` (`remove(index)`), so a plain
+// `Element` parameter rejects form controls there.
+function controlLabel(element: Pick<Element, "closest" | "getAttribute" | "tagName">) {
+  const target = element.closest(
+    "button, a, input, textarea, select, [role='button'], [role='link'], label",
+  );
+  if (!target)
+    return redactText(element.getAttribute("aria-label") || element.tagName.toLowerCase()).slice(
+      0,
+      120,
+    );
+  const aria = target.getAttribute("aria-label");
+  const textContent = (target.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 120);
+  return redactText(
+    aria || textContent || target.getAttribute("placeholder") || target.tagName.toLowerCase(),
+  ).slice(0, 120);
+}
+
+/**
+ * Records clicks, field changes, navigations, and console errors on this page.
+ * Ignores the toolbar. Does not read network traffic. Call the return to stop and drop the buffer.
+ */
+export function watchActivity(
+  buffer: ReplayBuffer,
+  /** Requests that are the toolbar's own (the comment service): never part of what the person did. */
+  ignoreUrl: (url: string) => boolean = () => false,
+) {
+  const notePath = () => {
+    const url = new URL(location.href);
+    redactSecretSearchParams(url);
+    buffer.push({ type: "navigate", path: `${url.pathname}${url.search}`.slice(0, 300) });
+  };
+  notePath();
+  const onClick = (event: MouseEvent) => {
+    const target = event.target;
+    if (!(target instanceof Element) || target.closest("#cs-root")) return;
+    buffer.push({ type: "click", label: controlLabel(target) });
+  };
+  const onChange = (event: Event) => {
+    const target = event.target;
+    if (
+      !(
+        target instanceof HTMLInputElement ||
+        target instanceof HTMLTextAreaElement ||
+        target instanceof HTMLSelectElement
+      )
+    )
+      return;
+    if (target.closest("#cs-root")) return;
+    const label = controlLabel(target);
+    const sensitive = fieldIsSensitive({
+      type: target instanceof HTMLSelectElement ? "select" : target.type,
+      name: target.name,
+      id: target.id,
+      autocomplete: target.getAttribute("autocomplete") ?? "",
+      label,
+    });
+    const value = sensitive ? "" : redactText(target.value).slice(0, 80);
+    buffer.push({
+      type: "input",
+      label,
+      redacted: sensitive || !value,
+      ...(value && !sensitive ? { value } : {}),
+    });
+  };
+  // eslint-disable-next-line no-console -- the replay recorder captures page console errors and warnings, then restores them.
+  const original = { error: console.error, warn: console.warn, fetch: window.fetch };
+  // A patch someone installed after ours keeps ours in its chain after stop: from then on it only passes through.
+  let active = true;
+  const patchedError = (...args: unknown[]) => {
+    if (!active) return original.error.apply(console, args);
+    buffer.push({ type: "console", level: "error", message: consoleText(args) });
+    original.error.apply(console, args);
+  };
+  const patchedWarn = (...args: unknown[]) => {
+    if (!active) return original.warn.apply(console, args);
+    buffer.push({ type: "console", level: "warn", message: consoleText(args) });
+    original.warn.apply(console, args);
+  };
+  // eslint-disable-next-line no-console -- the replay recorder captures page console errors and warnings, then restores them.
+  console.error = patchedError;
+  // eslint-disable-next-line no-console -- the replay recorder captures page console errors and warnings, then restores them.
+  console.warn = patchedWarn;
+  // Errors nobody logged: an exception that escaped, a promise nobody caught.
+  const onError = (event: ErrorEvent) => {
+    const message = event.error instanceof Error ? event.error.message : event.message;
+    buffer.push({
+      type: "console",
+      level: "error",
+      message: redactText(`Uncaught: ${message || "error"}`),
+    });
+  };
+  const onRejection = (event: PromiseRejectionEvent) => {
+    const reason = event.reason;
+    const message =
+      reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "rejection";
+    buffer.push({ type: "console", level: "error", message: redactText(`Unhandled: ${message}`) });
+  };
+  window.addEventListener("error", onError);
+  window.addEventListener("unhandledrejection", onRejection);
+  // Requests that failed, by path only: no bodies, no headers, no query values that look secret.
+  // Assigned through `unknown`: the workspace type-checks this file with the Workers types, whose `fetch`
+  // signature differs from the browser's.
+  const page = window as unknown as { fetch: unknown };
+  let patchedFetch: unknown = null;
+  if (typeof original.fetch === "function") {
+    const patched = async (input: RequestInfo | URL, init?: RequestInit) => {
+      const method = (
+        init?.method ?? (input instanceof Request ? input.method : "GET")
+      ).toUpperCase();
+      const href =
+        typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      if (!active || ignoreUrl(href)) return original.fetch.call(window, input, init);
+      const path = requestPath(input);
+      try {
+        const response = await original.fetch.call(window, input, init);
+        if (path && response.status >= 400)
+          buffer.push({ type: "network", method, path, status: response.status });
+        return response;
+      } catch (caught) {
+        if (path) buffer.push({ type: "network", method, path, status: 0 });
+        throw caught;
+      }
+    };
+    page.fetch = patched;
+    patchedFetch = patched;
+  }
+  let href = location.href;
+  const onNavigate = () => {
+    if (location.href === href) return;
+    href = location.href;
+    notePath();
+  };
+  const timer = window.setInterval(onNavigate, 1000);
+  window.addEventListener("popstate", onNavigate);
+  document.addEventListener("click", onClick, true);
+  document.addEventListener("change", onChange, true);
+  return () => {
+    active = false;
+    document.removeEventListener("click", onClick, true);
+    document.removeEventListener("change", onChange, true);
+    window.removeEventListener("popstate", onNavigate);
+    window.removeEventListener("error", onError);
+    window.removeEventListener("unhandledrejection", onRejection);
+    window.clearInterval(timer);
+    // Put back only what is still ours: a patch installed after this one (debug context, Sentry) stays.
+    // eslint-disable-next-line no-console -- the replay recorder captures page console errors and warnings, then restores them.
+    if (console.error === patchedError) console.error = original.error;
+    // eslint-disable-next-line no-console -- the replay recorder captures page console errors and warnings, then restores them.
+    if (console.warn === patchedWarn) console.warn = original.warn;
+    if (patchedFetch !== null && page.fetch === patchedFetch) page.fetch = original.fetch;
+    buffer.clear();
+  };
+}

package/src/runtime/runtime-version.ts

@@ -0,0 +1,7 @@
+/**
+ * The contract between the loader in the npm package and the toolbar the Worker serves at
+ * `/v1/toolbar/<runtimeVersion>.js`. Bump it only when `mount` or `ToolbarProps` change incompatibly,
+ * and commit the last build of the old version under apps/worker/public/v1/toolbar/ first so apps
+ * still on it keep working.
+ */
+export const runtimeVersion = 1;

package/src/runtime/runtime.tsx

@@ -0,0 +1,51 @@
+import { createRoot } from "react-dom/client";
+import { ToolbarApp, type RuntimeProps } from "./toolbar.js";
+import { registerSwapper } from "./update.js";
+
+export { runtimeBuild } from "./build-id.js";
+export { runtimeVersion } from "./runtime-version.js";
+export type { RuntimeProps } from "./toolbar.js";
+
+export type ToolbarHandle = { update(props: RuntimeProps): void; unmount(): void };
+
+type RuntimeModule = {
+  mount?: (container: HTMLElement, props: RuntimeProps) => ToolbarHandle;
+  runtimeBuild?: string;
+};
+
+/**
+ * Mounts the toolbar. The handle stays valid across a live update: when the worker starts serving a newer build,
+ * the toolbar loads it, unmounts this one and mounts the new one in the same container with the same props, and
+ * the handle the host holds forwards to it.
+ */
+export function mount(container: HTMLElement, props: RuntimeProps): ToolbarHandle {
+  let current = props;
+  let next: ToolbarHandle | null = null;
+  const root = createRoot(container);
+  root.render(<ToolbarApp {...props} />);
+  registerSwapper(async (url, build) => {
+    const loaded = (await import(
+      /* @vite-ignore */ /* webpackIgnore: true */ url
+    )) as RuntimeModule;
+    if (typeof loaded.mount !== "function") throw new Error(`${url} has no mount export`);
+    // A stale edge answered with another bundle: this one keeps running (see `swapRuntime`).
+    if (loaded.runtimeBuild !== build) return false;
+    registerSwapper(null);
+    root.unmount();
+    // The new build registers its own swapper, so later updates go through it.
+    next = loaded.mount(container, current);
+    return true;
+  });
+  return {
+    update: (props) => {
+      current = props;
+      if (next) next.update(props);
+      else root.render(<ToolbarApp {...props} />);
+    },
+    unmount: () => {
+      registerSwapper(null);
+      if (next) next.unmount();
+      else root.unmount();
+    },
+  };
+}

package/src/runtime/screen.ts

@@ -0,0 +1,182 @@
+/**
+ * Which screen of the host app an address is, and so which threads' pins belong on the page. DOM-free.
+ *
+ * A thread stores the address it was left on (`url`: path, query and hash) next to its `route` (the path). Two
+ * addresses are one screen when they have the same path, the same hash route (a hash that starts with `#/` or
+ * `#!/`, as hash routers write them; any other hash is a place on the page and does not count), and the same
+ * values for every query parameter that names a screen.
+ *
+ * Without a rule from the host, every query parameter names a screen except the ones that never do: tracking
+ * (`utm_*`, `gclid`, …), paging, sorting, searching and filtering by their usual names, and the toolbar's own.
+ * A host whose screens differ by fewer parameters names them (`{ params: ["view"] }`), and one whose screens
+ * are not in the address that way names each screen itself with a function.
+ *
+ * A thread whose address is a bare path (no query, no hash route) was stored before addresses were kept, or was
+ * left where the path was all there was: it shows on every screen at that path, as every thread did before. A
+ * host function decides for those too.
+ */
+
+/** What the host says identifies a screen: the query parameters that do, or a function that names it. */
+export type ScreenRule = { readonly params: readonly string[] } | ((address: URL) => string);
+
+/** Query parameters that never select a screen when the host gave no rule. */
+const NOISE = new Set([
+  // Tracking and attribution.
+  "gclid",
+  "gbraid",
+  "wbraid",
+  "dclid",
+  "fbclid",
+  "msclkid",
+  "twclid",
+  "ttclid",
+  "li_fat_id",
+  "igshid",
+  "yclid",
+  "mc_cid",
+  "mc_eid",
+  "_ga",
+  "_gl",
+  "_hsenc",
+  "_hsmi",
+  "mkt_tok",
+  "ref",
+  "ref_src",
+  "srsltid",
+  // Paging and sorting.
+  "page",
+  "p",
+  "per_page",
+  "perpage",
+  "page_size",
+  "pagesize",
+  "limit",
+  "offset",
+  "cursor",
+  "after",
+  "before",
+  "sort",
+  "sort_by",
+  "sortby",
+  "order",
+  "order_by",
+  "orderby",
+  "dir",
+  "direction",
+  // Searching and filtering.
+  "q",
+  "query",
+  "search",
+  "filter",
+  "filters",
+]);
+
+function isNoise(name: string): boolean {
+  const lower = name.toLowerCase();
+  return (
+    NOISE.has(lower) ||
+    lower.startsWith("utm_") ||
+    lower.startsWith("hsa_") ||
+    lower.startsWith("cs-") ||
+    /^filters?[[._]/.test(lower)
+  );
+}
+
+const BASE = "https://screen.invalid";
+
+/** The part of a hash a hash router owns (`#/orders?tab=2` → `/orders?tab=2`), or null for an in-page hash. */
+function hashRoute(hash: string): URL | null {
+  const route = hash.startsWith("#!/")
+    ? hash.slice(2)
+    : hash.startsWith("#/")
+      ? hash.slice(1)
+      : null;
+  if (route === null) return null;
+  try {
+    return new URL(route, BASE);
+  } catch {
+    return null;
+  }
+}
+
+function paramsKey(search: URLSearchParams, rule: { readonly params: readonly string[] } | null) {
+  const kept = [...search].filter(([name]) => (rule ? rule.params.includes(name) : !isNoise(name)));
+  kept.sort(([a, x], [b, y]) => (a === b ? (x < y ? -1 : x > y ? 1 : 0) : a < b ? -1 : 1));
+  return new URLSearchParams(kept).toString();
+}
+
+/** `address` (a path with its query and hash, or a whole URL) as a URL, or null when it is not a web page. */
+function parse(address: string, origin: string): URL | null {
+  if (!address.startsWith("/") || address.startsWith("//")) {
+    try {
+      const url = new URL(address);
+      return url.protocol === "http:" || url.protocol === "https:" ? url : null;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return new URL(address, origin);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The screen `url` is, as a string two addresses of one screen share. A host function that throws names
+ * nothing, and the address is read by the parameters instead.
+ */
+export function screenKey(url: URL, rule: ScreenRule | null = null): string {
+  if (typeof rule === "function") {
+    try {
+      return `=${String(rule(new URL(url.href)))}`;
+    } catch {
+      return screenKey(url, null);
+    }
+  }
+  const route = hashRoute(url.hash);
+  const parts = [url.pathname, paramsKey(url.searchParams, rule)];
+  if (route) parts.push(route.pathname, paramsKey(route.searchParams, rule));
+  return parts.join("\u0000");
+}
+
+/** True for an address that is only a path: no query and no hash route. */
+export function isBarePath(address: string): boolean {
+  const url = parse(address, BASE);
+  return url !== null && url.search === "" && hashRoute(url.hash) === null;
+}
+
+/** The address a thread was left on, as the toolbar reads it: its `url`, else its `route`. */
+export type Placed = { readonly route: string; readonly url?: string | null };
+
+export type Here = {
+  /** The page's path, which anchors are captured and resolved against. */
+  readonly route: string;
+  /** The screen the page is on. */
+  readonly key: string;
+  /** Whether `thread` was left on this screen, so its pin belongs here. */
+  has(thread: Placed): boolean;
+};
+
+/**
+ * The screen at `href` (the page's whole address), and which threads belong on it. A thread is only ever on
+ * a screen at its own path, because its anchor is found among that path's elements. One whose `url` is not a
+ * page of this app (a native app's screen) belongs here by its `route` alone, as before.
+ */
+export function screenAt(href: string, rule: ScreenRule | null = null): Here {
+  const page = new URL(href);
+  const key = screenKey(page, rule);
+  const route = page.pathname;
+  return {
+    route,
+    key,
+    has(thread) {
+      if (thread.route !== route) return false;
+      const address = thread.url || thread.route;
+      const url = parse(address, page.origin);
+      if (!url) return true;
+      if (typeof rule !== "function" && isBarePath(address)) return true;
+      return screenKey(url, rule) === key;
+    },
+  };
+}

package/src/runtime/screenshot.ts

@@ -0,0 +1,260 @@
+import type { Sketch } from "../core/index.js";
+import { browserLabel } from "./browser-label.js";
+import type { Capture } from "./client.js";
+import { pageBackground } from "./page-background.js";
+import { renderSnapshot, snapshotPage, type PageSnapshot } from "./page-image.js";
+import { paintSketch, sketchBox } from "./sketch.js";
+
+const MAX_WIDTH = 1200;
+/** Widest page screenshot that is attached. */
+const PAGE_MAX_WIDTH = 1600;
+/** Room kept around the ring, in CSS pixels. */
+const RING_PAD = 6;
+/** The smallest crop `cropFor` cuts around an element, in CSS pixels. */
+const CROP_MIN = { width: 760, height: 420 };
+/** Room kept around the element (and its drawing) in a crop, in CSS pixels. */
+const CROP_PAD = 200;
+
+/** The page, viewport and browser a screenshot is being taken in. */
+export function describeCapture(url: string): Capture {
+  return {
+    url,
+    viewport: { width: document.documentElement.clientWidth, height: window.innerHeight },
+    browser: browserLabel(navigator.userAgent),
+  };
+}
+
+function roundedRect(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  r: number,
+) {
+  ctx.moveTo(x + r, y);
+  ctx.arcTo(x + w, y, x + w, y + h, r);
+  ctx.arcTo(x + w, y + h, x, y + h, r);
+  ctx.arcTo(x, y + h, x, y, r);
+  ctx.arcTo(x, y, x + w, y, r);
+  ctx.closePath();
+}
+
+function isToolbar(node: Element) {
+  return node.id === "cs-root";
+}
+
+/** Device pixels per CSS pixel for a page-wide screenshot: the display's ratio, capped by the output width. */
+function pageScale(width: number) {
+  return Math.min(window.devicePixelRatio || 1, 2, PAGE_MAX_WIDTH / width);
+}
+
+function currentViewport() {
+  return { width: document.documentElement.clientWidth, height: window.innerHeight };
+}
+
+/** A box in CSS pixels from the top-left of the viewport. */
+export type Frame = { left: number; top: number; width: number; height: number };
+export type Viewport = { width: number; height: number };
+
+/** `rect` as a frame, or null when none of it is inside the viewport. */
+export function frameOf(rect: DOMRect | Frame, viewport: Viewport): Frame | null {
+  const right = rect.left + rect.width;
+  const bottom = rect.top + rect.height;
+  if (
+    rect.width < 1 ||
+    bottom <= 0 ||
+    rect.top >= viewport.height ||
+    right <= 0 ||
+    rect.left >= viewport.width
+  )
+    return null;
+  return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+}
+
+/** The ring drawn around `frame`, in output pixels, when the picture is `scale` output pixels per CSS pixel. */
+export function ringFor(frame: Frame, scale: number, origin = { left: 0, top: 0 }) {
+  return {
+    x: (frame.left - origin.left - RING_PAD) * scale,
+    y: (frame.top - origin.top - RING_PAD) * scale,
+    w: (frame.width + RING_PAD * 2) * scale,
+    h: (frame.height + RING_PAD * 2) * scale,
+  };
+}
+
+/**
+ * The part of the viewport a crop around `frame` shows: the element and its drawing with room around them, at
+ * least `CROP_MIN`, never beyond the viewport, centred on the element as far as the viewport allows.
+ */
+export function cropFor(frame: Frame, viewport: Viewport, sketch?: Sketch): Frame {
+  const ink = sketch ? sketchBox(sketch) : null;
+  const left = ink ? Math.min(frame.left, frame.left + ink.left) : frame.left;
+  const top = ink ? Math.min(frame.top, frame.top + ink.top) : frame.top;
+  const right = ink
+    ? Math.max(frame.left + frame.width, frame.left + ink.right)
+    : frame.left + frame.width;
+  const bottom = ink
+    ? Math.max(frame.top + frame.height, frame.top + ink.bottom)
+    : frame.top + frame.height;
+  const width = Math.min(viewport.width, Math.max(right - left + CROP_PAD, CROP_MIN.width));
+  const height = Math.min(viewport.height, Math.max(bottom - top + CROP_PAD, CROP_MIN.height));
+  const x = Math.max(0, Math.min((left + right) / 2 - width / 2, viewport.width - width));
+  const y = Math.max(0, Math.min((top + bottom) / 2 - height / 2, viewport.height - height));
+  return { left: x, top: y, width, height };
+}
+
+/**
+ * The page as it was at one instant: a copy of its DOM and, if an element was being pointed at, that element's
+ * box in the viewport at the same instant. Drawing the copy happens later and takes a while; measuring the
+ * element then instead would put its ring wherever the element had moved to in the meantime.
+ */
+export type PageShot = {
+  /** The highlighted element's box when the page was copied; null when nothing was, or it was off screen. */
+  frame: Frame | null;
+  viewport: Viewport;
+  /** Device pixels per CSS pixel the drawing is made at. */
+  scale: number;
+  /** The drawing, made once on the first request and shared by every picture cut from this shot. */
+  render: () => Promise<HTMLCanvasElement>;
+};
+
+/**
+ * Draws the already-copied page. A failure stays a failure: painting the live document would include
+ * password and token fields the copy had blanked.
+ */
+async function drawSnapshot(snapshot: PageSnapshot, scale: number, timeout: number) {
+  return renderSnapshot(snapshot, scale, timeout);
+}
+
+/**
+ * Copies the visible page now, synchronously, with `highlight`'s box measured at the same moment. The toolbar is
+ * left out. Nothing is drawn until `render` is first called (see `shotPage`, `shotAround`).
+ */
+export function takeShot(highlight?: Element | null, timeout = 6000): PageShot {
+  const viewport = currentViewport();
+  const frame = highlight ? frameOf(highlight.getBoundingClientRect(), viewport) : null;
+  const snapshot = snapshotPage({
+    width: viewport.width,
+    height: viewport.height,
+    exclude: isToolbar,
+    backgroundColor: pageBackground(),
+  });
+  const scale = pageScale(viewport.width);
+  let drawn: Promise<HTMLCanvasElement> | null = null;
+  return {
+    frame,
+    viewport,
+    scale,
+    render: () => {
+      drawn ??= drawSnapshot(snapshot, scale, timeout);
+      return drawn;
+    },
+  };
+}
+
+/** The visible page as a canvas, toolbar left out, drawn from the page as it is now. `timeout` bounds a slow frame. */
+export function renderViewport(scale: number, timeout = 6000) {
+  const viewport = currentViewport();
+  const snapshot = snapshotPage({
+    width: viewport.width,
+    height: viewport.height,
+    exclude: isToolbar,
+    backgroundColor: pageBackground(),
+  });
+  return drawSnapshot(snapshot, scale, timeout);
+}
+
+function outline(
+  ctx: CanvasRenderingContext2D,
+  width: number,
+  height: number,
+  ring: { x: number; y: number; w: number; h: number },
+  scale: number,
+) {
+  const radius = Math.min(12 * scale, ring.w / 2, ring.h / 2);
+  ctx.beginPath();
+  ctx.rect(0, 0, width, height);
+  roundedRect(ctx, ring.x, ring.y, ring.w, ring.h, radius);
+  ctx.fillStyle = "rgba(15, 15, 20, 0.22)";
+  ctx.fill("evenodd");
+  ctx.beginPath();
+  roundedRect(ctx, ring.x, ring.y, ring.w, ring.h, radius);
+  ctx.lineWidth = 3 * scale;
+  ctx.strokeStyle = "#007aff";
+  ctx.stroke();
+}
+
+function toBlob(canvas: HTMLCanvasElement) {
+  return new Promise<Blob | null>((resolve) =>
+    canvas.toBlob((blob) => resolve(blob), "image/jpeg", 0.85),
+  );
+}
+
+/**
+ * The whole visible page as a JPEG, from `shot`. If the shot framed an element it's outlined, or `sketch`
+ * (drawn against it) is painted on instead.
+ */
+export async function shotPage(shot: PageShot, sketch?: Sketch): Promise<Blob | null> {
+  let page: HTMLCanvasElement;
+  try {
+    page = await shot.render();
+  } catch {
+    return null;
+  }
+  const { frame, scale } = shot;
+  if (!frame) return toBlob(page);
+  const out = document.createElement("canvas");
+  out.width = page.width;
+  out.height = page.height;
+  const ctx = out.getContext("2d");
+  if (!ctx) return null;
+  ctx.drawImage(page, 0, 0);
+  if (sketch) paintSketch(ctx, sketch, { x: frame.left, y: frame.top }, scale);
+  else outline(ctx, out.width, out.height, ringFor(frame, scale), scale);
+  return toBlob(out);
+}
+
+/**
+ * What the person saw around the framed element, cut from `shot`, with the rest dimmed and the element
+ * outlined, or with `sketch` painted on instead. A JPEG data URL, or null when nothing was framed or the
+ * page couldn't be drawn.
+ */
+export async function shotAround(shot: PageShot, sketch?: Sketch): Promise<string | null> {
+  const { frame, viewport, scale } = shot;
+  if (!frame) return null;
+  let page: HTMLCanvasElement;
+  try {
+    page = await shot.render();
+  } catch {
+    return null;
+  }
+  const crop = cropFor(frame, viewport, sketch);
+  const out = document.createElement("canvas");
+  const outScale = Math.min(scale, MAX_WIDTH / crop.width);
+  out.width = Math.round(crop.width * outScale);
+  out.height = Math.round(crop.height * outScale);
+  const ctx = out.getContext("2d");
+  if (!ctx) return null;
+  ctx.drawImage(
+    page,
+    crop.left * scale,
+    crop.top * scale,
+    crop.width * scale,
+    crop.height * scale,
+    0,
+    0,
+    out.width,
+    out.height,
+  );
+  if (sketch) {
+    paintSketch(ctx, sketch, { x: frame.left - crop.left, y: frame.top - crop.top }, outScale);
+    return out.toDataURL("image/jpeg", 0.82);
+  }
+  outline(ctx, out.width, out.height, ringFor(frame, outScale, crop), outScale);
+  return out.toDataURL("image/jpeg", 0.82);
+}
+
+/** `shotAround` for the page as it is now. */
+export function captureAround(element: Element, sketch?: Sketch): Promise<string | null> {
+  return shotAround(takeShot(element), sketch);
+}