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

package/src/help/pill-styles.ts

@@ -0,0 +1,75 @@
+/**
+ * The pill's CSS, and the ground the panel's CSS stands on (`./panel-styles.ts`): the reset and the colours.
+ *
+ * The pill lives in the page's own document, not in a shadow tree: a toolbar on the same page reads keys
+ * from `window` and tells "the person is typing" by the event's target, which a shadow tree would hide from
+ * it. So every element here is first cleared of whatever the host's stylesheet gives its kind (`all: unset`)
+ * and then styled by a rule under `.cth`, which outranks a host rule written for a bare element.
+ */
+
+/** Above the page, below the comment toolbar (2147483000) and its capture UI. */
+export const HELP_Z_INDEX = 2147482000;
+
+const DARK = `
+  --cth-card: #1c1c20; --cth-ink: #f5f5f7; --cth-muted: #a8a8ad; --cth-line: rgba(255, 255, 255, 0.14);
+  --cth-ring: rgba(255, 255, 255, 0.1); --cth-fill: rgba(255, 255, 255, 0.08); --cth-fill-2: rgba(255, 255, 255, 0.13);
+  --cth-track: rgba(0, 0, 0, 0.34); --cth-raised: #3a3a41; --cth-field: #131316; --cth-link: #8ab4ff;
+  --cth-danger: #ff8a80; --cth-ok: #1f7a3d; --cth-received-bg: rgba(255, 255, 255, 0.1); --cth-received-ink: #d7d7dc;
+  --cth-progress-bg: rgba(255, 190, 60, 0.18); --cth-progress-ink: #ffd27a; --cth-resolved-bg: rgba(70, 200, 110, 0.18);
+  --cth-resolved-ink: #8fe0a8; --cth-shadow: 0 2px 6px rgba(0, 0, 0, 0.4), 0 16px 48px rgba(0, 0, 0, 0.5);
+  --cth-pill-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 8px 24px rgba(0, 0, 0, 0.45);
+`;
+
+export const HELP_BASE_CSS = `
+.cth {
+  all: initial; display: contents;
+  --cth-card: #ffffff; --cth-ink: #141416; --cth-muted: #62625e; --cth-line: #e2e2dd; --cth-ring: rgba(20, 20, 30, 0.08);
+  --cth-fill: #f3f3f0; --cth-fill-2: #e9e9e4; --cth-track: #e9e9e4; --cth-raised: #ffffff; --cth-field: #ffffff;
+  --cth-accent: #2563eb; --cth-accent-ink: #ffffff; --cth-link: #1d4ed8; --cth-danger: #b42318; --cth-ok: #1f7a3d;
+  --cth-received-bg: #eeeeea; --cth-received-ink: #4a4a47; --cth-progress-bg: #fff1cc; --cth-progress-ink: #7a4f00;
+  --cth-resolved-bg: #e0f4e6; --cth-resolved-ink: #17612f;
+  --cth-shadow: 0 2px 6px rgba(20, 20, 30, 0.08), 0 16px 48px rgba(20, 20, 30, 0.18);
+  --cth-pill-shadow: 0 1px 2px rgba(20, 20, 30, 0.08), 0 8px 24px rgba(20, 20, 30, 0.14);
+  --cth-edge: 20px;
+  color: var(--cth-ink);
+  font: 400 13px/1.4 -apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", Inter, system-ui, sans-serif;
+  letter-spacing: -0.005em; -webkit-font-smoothing: antialiased; text-align: left; direction: ltr;
+}
+.cth[data-theme="dark"] {${DARK}}
+@media (prefers-color-scheme: dark) { .cth[data-theme="auto"] {${DARK}} }
+.cth :is(a, button, div, form, h2, header, img, label, li, p, section, span, svg, textarea, time, ul) {
+  all: unset; box-sizing: border-box;
+}
+.cth :focus-visible { outline: 2px solid var(--cth-accent); outline-offset: 2px; }
+.cth .cth-pill {
+  position: fixed; z-index: ${HELP_Z_INDEX};
+  bottom: calc(var(--cth-edge) + env(safe-area-inset-bottom, 0px) + var(--cth-lift, 0px));
+  display: inline-flex; align-items: center; gap: 8px; height: 40px; max-width: calc(100vw - 2 * var(--cth-edge));
+  padding: 0 16px 0 9px; border-radius: 999px; background: var(--cth-card); color: var(--cth-ink);
+  box-shadow: 0 0 0 1px var(--cth-ring), var(--cth-pill-shadow);
+  font-size: 13px; font-weight: 600; white-space: nowrap; cursor: pointer;
+  -webkit-user-select: none; user-select: none; -webkit-tap-highlight-color: transparent;
+}
+.cth[data-position="bottom-right"] .cth-pill { right: calc(var(--cth-edge) + env(safe-area-inset-right, 0px)); }
+.cth[data-position="bottom-left"] .cth-pill { left: calc(var(--cth-edge) + env(safe-area-inset-left, 0px)); }
+.cth .cth-pill:hover { background: var(--cth-raised); box-shadow: 0 0 0 1px var(--cth-ring), var(--cth-shadow); }
+.cth .cth-mark {
+  display: inline-flex; flex: none; align-items: center; justify-content: center; width: 22px; height: 22px;
+  border-radius: 50%; background: var(--cth-accent); color: var(--cth-accent-ink); font-size: 13px; font-weight: 700;
+}
+.cth .cth-label { display: block; overflow: hidden; text-overflow: ellipsis; }
+.cth .cth-note {
+  position: fixed; z-index: ${HELP_Z_INDEX};
+  bottom: calc(var(--cth-edge) + 50px + env(safe-area-inset-bottom, 0px) + var(--cth-lift, 0px));
+  display: block; max-width: 240px; padding: 8px 12px; border-radius: 10px; background: var(--cth-ink);
+  color: var(--cth-card); font-size: 12px;
+}
+.cth[data-position="bottom-right"] .cth-note { right: var(--cth-edge); }
+.cth[data-position="bottom-left"] .cth-note { left: var(--cth-edge); }
+@media (prefers-reduced-motion: no-preference) {
+  .cth .cth-pill { transition: box-shadow 0.2s ease, transform 0.2s ease, bottom 0.2s ease; }
+  .cth .cth-pill:active { transform: scale(0.97); }
+  .cth .cth-pill[aria-busy="true"] .cth-mark { animation: cth-wait 0.9s ease-in-out infinite alternate; }
+  @keyframes cth-wait { to { opacity: 0.45; } }
+}
+`;

package/src/help/pill.ts

@@ -0,0 +1,338 @@
+/**
+ * The pill: all that `help.js` puts on a page before anyone asks for help. A labelled button fixed to a
+ * bottom corner, a few kilobytes with its CSS, no React.
+ *
+ * The panel it opens (`./panel.ts`, served as `help-panel.js`) and the capture script (`../capture`, served
+ * as `capture.js`) are fetched the first time the pointer rests on the pill, it takes focus, or it is opened.
+ *
+ * There is one pill per page. `mount` called again changes its options and keeps the pill, an open panel and
+ * a draft; every handle `mount` has returned speaks for that one pill.
+ */
+import type { CommentToolCaptureApi } from "../capture/api.js";
+import { HELP_BASE_CSS } from "./pill-styles.js";
+import { supportRequestsAt } from "./requests.js";
+import {
+  HelpError,
+  type CommentToolHelpApi,
+  type HelpHandle,
+  type HelpOptions,
+  type HelpPosition,
+  type HelpTheme,
+} from "./types.js";
+
+/** What the panel is given: where to draw, what the host said, and the capture tools. */
+export type PanelHost = {
+  /** The pill's root. The panel is appended to it, after the pill. */
+  root: HTMLElement;
+  pill: HTMLButtonElement;
+  /** The host's options as they are now. */
+  options(): HelpOptions;
+  /** The capture script's API, fetched when it is not on the page yet. Rejects when it cannot be. */
+  capture(): Promise<CommentToolCaptureApi>;
+  /** Hides the pill and the panel while a capture is open, and brings them back. */
+  hide(hidden: boolean): void;
+};
+
+/** The panel, as the pill drives it. Additive only: a page may hold a `help.js` older than its panel. */
+export type PanelView = {
+  readonly isOpen: boolean;
+  open(): void;
+  close(): void;
+  /** The host's options changed. */
+  update(): void;
+  destroy(): void;
+};
+
+export type HelpPanelApi = { create(host: PanelHost): PanelView };
+
+export type HelpEnvironment = {
+  /** Where this script's siblings are served: `<service>/v1/toolbar/`. */
+  base: string;
+  /** Adds a classic script to the page. Default: a `<script async>` in `<head>`. */
+  loadScript?: (url: string) => Promise<void>;
+};
+
+const STYLE_ID = "cth-style";
+const DEFAULT_LABEL = "Need help?";
+const POSITIONS: readonly HelpPosition[] = ["bottom-right", "bottom-left"];
+const THEMES: readonly HelpTheme[] = ["light", "dark", "auto"];
+/** The gap kept between the pill and a comment toolbar's bar. */
+const CLEARANCE = 8;
+/** A bar this close to the bottom of the window is in a sheet's way. */
+const SHEET_ZONE = 120;
+
+function addScript(url: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tag = document.createElement("script");
+    tag.src = url;
+    tag.async = true;
+    tag.onload = () => resolve();
+    tag.onerror = () => {
+      tag.remove();
+      reject(new Error(`${url} did not load.`));
+    };
+    document.head.appendChild(tag);
+  });
+}
+
+/** Runs `load` once; a failure is forgotten, so the next call tries again. */
+function once<T>(load: () => Promise<T>): () => Promise<T> {
+  let kept: Promise<T> | null = null;
+  return () => {
+    kept ??= load().catch((error: unknown) => {
+      kept = null;
+      throw error;
+    });
+    return kept;
+  };
+}
+
+export function ensureHelpStyles(id: string, css: string): void {
+  if (document.getElementById(id)) return;
+  const style = document.createElement("style");
+  style.id = id;
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
+type Page = {
+  CommentToolHelpPanel?: Partial<HelpPanelApi>;
+  CommentToolCapture?: Partial<CommentToolCaptureApi>;
+};
+
+export function createHelp(environment: HelpEnvironment): CommentToolHelpApi {
+  const load = environment.loadScript ?? addScript;
+  const page = window as unknown as Page;
+
+  const panelApi = once(async (): Promise<HelpPanelApi> => {
+    if (typeof page.CommentToolHelpPanel?.create !== "function") {
+      await load(`${environment.base}help-panel.js`);
+    }
+    const api = page.CommentToolHelpPanel;
+    if (typeof api?.create !== "function") throw new Error("help-panel.js defined no panel.");
+    return api as HelpPanelApi;
+  });
+  const captureApi = once(async (): Promise<CommentToolCaptureApi> => {
+    if (typeof page.CommentToolCapture?.screenshot !== "function") {
+      await load(`${environment.base}capture.js`);
+    }
+    const api = page.CommentToolCapture;
+    if (typeof api?.screenshot !== "function") throw new Error("capture.js defined no capture.");
+    return api as CommentToolCaptureApi;
+  });
+
+  let options: HelpOptions | null = null;
+  let root: HTMLDivElement | null = null;
+  let pill: HTMLButtonElement | null = null;
+  let label: HTMLSpanElement | null = null;
+  let note: HTMLDivElement | null = null;
+  let view: PanelView | null = null;
+  let wantOpen = false;
+  let lift = 0;
+  let stopWatching: (() => void) | null = null;
+
+  const capturesOn = () => {
+    const captures = options?.captures;
+    try {
+      return typeof captures === "function" ? captures() !== false : captures !== false;
+    } catch {
+      return false;
+    }
+  };
+
+  /** Fetches what the first open needs, ahead of it. */
+  function warm() {
+    void panelApi().catch(() => {});
+    if (capturesOn()) void captureApi().catch(() => {});
+  }
+
+  function say(message: string | null) {
+    note?.remove();
+    note = null;
+    if (!message || !root) return;
+    note = document.createElement("div");
+    note.className = "cth-note";
+    note.setAttribute("role", "status");
+    note.textContent = message;
+    root.appendChild(note);
+  }
+
+  async function panel(): Promise<PanelView | null> {
+    if (view) return view;
+    const mountedRoot = root;
+    const api = await panelApi();
+    // Unmounted, or mounted afresh, while the panel was on its way.
+    if (!root || !pill || root !== mountedRoot) return null;
+    view ??= api.create({
+      root,
+      pill,
+      options: () => options as HelpOptions,
+      capture: captureApi,
+      hide: (hidden) => {
+        if (root) root.style.display = hidden ? "none" : "";
+      },
+    });
+    return view;
+  }
+
+  function open() {
+    if (!pill) return;
+    wantOpen = true;
+    say(null);
+    if (view) {
+      view.open();
+      return;
+    }
+    pill.setAttribute("aria-busy", "true");
+    warm();
+    panel()
+      .then((ready) => {
+        if (ready && wantOpen) ready.open();
+      })
+      .catch(() => say("Help could not open. Try again."))
+      .finally(() => pill?.removeAttribute("aria-busy"));
+  }
+
+  function close() {
+    wantOpen = false;
+    view?.close();
+  }
+
+  /**
+   * Keeps the pill off a comment toolbar's bar. The bar's default place is the bottom centre and a person can
+   * drag it to either corner, so the pill is lifted above it whenever the two would touch. A sheet (the
+   * panel on a narrow screen) spans the window, so it is lifted above any bar near the bottom.
+   */
+  function clearToolbar() {
+    if (!root || !pill) return;
+    const bar = document.querySelector('#cs-root:not([data-cs-capture]) [data-cs-ui="bar"]');
+    let next = 0;
+    let sheet = 0;
+    if (bar) {
+      const box = bar.getBoundingClientRect();
+      const own = pill.getBoundingClientRect();
+      // Where the pill sits when nothing lifts it.
+      const top = own.top + lift;
+      const bottom = own.bottom + lift;
+      const touching =
+        box.width > 0 &&
+        own.width > 0 &&
+        box.left < own.right + CLEARANCE &&
+        box.right > own.left - CLEARANCE &&
+        box.top < bottom + CLEARANCE &&
+        box.bottom > top - CLEARANCE;
+      if (touching) next = Math.max(0, Math.ceil(bottom - box.top + CLEARANCE));
+      if (box.width > 0 && window.innerHeight - box.bottom < SHEET_ZONE) {
+        sheet = Math.max(0, Math.ceil(window.innerHeight - box.top + CLEARANCE));
+      }
+    }
+    if (next !== lift) {
+      lift = next;
+      root.style.setProperty("--cth-lift", `${lift}px`);
+    }
+    root.style.setProperty("--cth-sheet-lift", `${sheet}px`);
+  }
+
+  /** Looks again when a toolbar may have arrived, moved or changed size. Nothing runs on a timer. */
+  function watchToolbar(): () => void {
+    let frame = 0;
+    let settle: ReturnType<typeof setTimeout> | undefined;
+    const soon = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(clearToolbar);
+      // Once more when the bar has finished arriving or sliding to a corner.
+      clearTimeout(settle);
+      settle = setTimeout(clearToolbar, 450);
+    };
+    const arrivals = typeof MutationObserver === "function" ? new MutationObserver(soon) : null;
+    arrivals?.observe(document.body, { childList: true });
+    window.addEventListener("resize", soon);
+    window.addEventListener("pointerup", soon, true);
+    soon();
+    return () => {
+      cancelAnimationFrame(frame);
+      clearTimeout(settle);
+      arrivals?.disconnect();
+      window.removeEventListener("resize", soon);
+      window.removeEventListener("pointerup", soon, true);
+    };
+  }
+
+  function build() {
+    ensureHelpStyles(STYLE_ID, HELP_BASE_CSS);
+    root = document.createElement("div");
+    root.className = "cth";
+    root.setAttribute("data-cs-help", "");
+    // The capture script leaves this out of every picture and never offers it to point at.
+    root.setAttribute("data-cs-capture-ignore", "");
+    pill = document.createElement("button");
+    pill.type = "button";
+    pill.className = "cth-pill";
+    pill.setAttribute("data-cs-help-ui", "pill");
+    pill.setAttribute("aria-haspopup", "dialog");
+    pill.setAttribute("aria-expanded", "false");
+    const mark = document.createElement("span");
+    mark.className = "cth-mark";
+    mark.setAttribute("aria-hidden", "true");
+    mark.textContent = "?";
+    label = document.createElement("span");
+    label.className = "cth-label";
+    pill.append(mark, label);
+    pill.addEventListener("click", () => {
+      if (view?.isOpen) close();
+      else open();
+    });
+    pill.addEventListener("pointerenter", warm, { once: true });
+    pill.addEventListener("focus", warm, { once: true });
+    root.appendChild(pill);
+    document.body.appendChild(root);
+    stopWatching = watchToolbar();
+  }
+
+  function apply() {
+    if (!root || !label || !options) return;
+    const text = typeof options.label === "string" ? options.label.trim() : "";
+    label.textContent = text || DEFAULT_LABEL;
+    root.setAttribute(
+      "data-position",
+      POSITIONS.includes(options.position as HelpPosition)
+        ? (options.position as HelpPosition)
+        : "bottom-right",
+    );
+    root.setAttribute(
+      "data-theme",
+      THEMES.includes(options.theme as HelpTheme) ? (options.theme as HelpTheme) : "auto",
+    );
+  }
+
+  function unmount() {
+    wantOpen = false;
+    stopWatching?.();
+    stopWatching = null;
+    view?.destroy();
+    view = null;
+    root?.remove();
+    root = null;
+    pill = null;
+    label = null;
+    note = null;
+    lift = 0;
+    options = null;
+  }
+
+  return {
+    mount(given: HelpOptions): HelpHandle {
+      if (typeof given?.submit !== "function") {
+        throw new TypeError("CommentToolHelp.mount: submit must be a function.");
+      }
+      options = given;
+      if (!root) build();
+      apply();
+      view?.update();
+      clearToolbar();
+      return { open, close, unmount };
+    },
+    supportRequestsAt,
+    HelpError,
+  };
+}

package/src/help/react.tsx

@@ -0,0 +1,143 @@
+/**
+ * `<HelpPill>`: the "Need help?" pill for a host that installs the package. Renders nothing itself: once the
+ * page is idle it adds `<service>/v1/toolbar/help.js` and mounts the pill that script defines, so the pill a
+ * React host shows is the one a script-tag host shows, and both follow the service's deploys.
+ *
+ * It mounts with the component and leaves with it. What a person has written goes with it too, so put it
+ * where it stays for as long as the person is signed in, not inside a page that is swapped on navigation.
+ */
+import { useEffect, useRef } from "react";
+import { IDLE_TIMEOUT_MS } from "../runtime/boot.js";
+import { whenIdle } from "../runtime/idle.js";
+import { sessionFor } from "../runtime/session.js";
+import type { CommentToolHelpApi, HelpHandle, HelpOptions } from "./types.js";
+
+export type HelpPillProps = HelpOptions & {
+  /**
+   * Comment Tool's address: `https://comment-tool.example.com`. Left out, it is the one the session route
+   * names, which is how `<CommentToolbar>` learns it. That route says so only to people the comment toolbar
+   * is on for, so a host that shows the pill to everyone gives the address here.
+   */
+  serviceUrl?: string;
+  /** The session route asked when `serviceUrl` is left out. Default `/api/comment-service/session`. */
+  sessionPath?: string;
+};
+
+type Page = { CommentToolHelp?: Partial<CommentToolHelpApi> };
+
+const loading = new Map<string, Promise<CommentToolHelpApi>>();
+
+/** Adds `help.js` to the page once, or takes the one a script tag already put there. */
+function loadHelp(serviceUrl: string): Promise<CommentToolHelpApi> {
+  const page = window as unknown as Page;
+  const there = () =>
+    typeof page.CommentToolHelp?.mount === "function"
+      ? (page.CommentToolHelp as CommentToolHelpApi)
+      : null;
+  const ready = there();
+  if (ready) return Promise.resolve(ready);
+  const url = `${serviceUrl.replace(/\/+$/, "")}/v1/toolbar/help.js`;
+  let kept = loading.get(url);
+  if (!kept) {
+    kept = new Promise<CommentToolHelpApi>((resolve, reject) => {
+      const tag = document.createElement("script");
+      tag.src = url;
+      tag.async = true;
+      tag.onload = () => {
+        const api = there();
+        if (api) resolve(api);
+        else reject(new Error(`${url} defined no CommentToolHelp.`));
+      };
+      tag.onerror = () => {
+        tag.remove();
+        reject(new Error(`${url} did not load.`));
+      };
+      document.head.appendChild(tag);
+    });
+    // A failed load is not kept: the next mount tries again.
+    kept.catch(() => loading.delete(url));
+    loading.set(url, kept);
+  }
+  return kept;
+}
+
+export function HelpPill(props: HelpPillProps) {
+  const {
+    serviceUrl,
+    sessionPath = "/api/comment-service/session",
+    label,
+    position,
+    theme,
+  } = props;
+  const hasList = typeof props.list === "function";
+  const hasMore = typeof props.moreOptions === "function";
+  const latest = useRef(props);
+  const mounted = useRef<{ api: CommentToolHelpApi; handle: HelpHandle } | null>(null);
+
+  /** The options as the pill gets them: the hooks always call the host's latest functions. */
+  const options = useRef((): HelpOptions => {
+    const now = latest.current;
+    return {
+      submit: (request) => latest.current.submit(request),
+      ...(typeof now.list === "function"
+        ? {
+            list: () => {
+              const list = latest.current.list;
+              return list ? list() : Promise.resolve([]);
+            },
+          }
+        : {}),
+      label: now.label,
+      position: now.position,
+      theme: now.theme,
+      captures: () => {
+        const captures = latest.current.captures;
+        return typeof captures === "function" ? captures() : captures !== false;
+      },
+      ...(typeof now.moreOptions === "function"
+        ? { moreOptions: (draft) => latest.current.moreOptions?.(draft) }
+        : {}),
+    };
+  });
+
+  useEffect(() => {
+    latest.current = props;
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    const start = async () => {
+      const address =
+        serviceUrl ?? (await sessionFor(sessionPath)().catch(() => null))?.apiUrl ?? null;
+      if (cancelled) return;
+      if (!address) {
+        console.info(
+          `[comment-service] <HelpPill> is not shown: ${sessionPath} names no service for this person. Pass serviceUrl to show it to everyone.`,
+        );
+        return;
+      }
+      const api = await loadHelp(address);
+      if (cancelled) return;
+      mounted.current = { api, handle: api.mount(options.current()) };
+    };
+    const cancelWait = whenIdle(() => {
+      start().catch((error: unknown) =>
+        console.warn("[comment-service] The help pill could not start.", error),
+      );
+    }, IDLE_TIMEOUT_MS);
+    return () => {
+      cancelled = true;
+      cancelWait();
+      mounted.current?.handle.unmount();
+      mounted.current = null;
+    };
+  }, [serviceUrl, sessionPath]);
+
+  // What the pill draws from changed: the same pill takes the new options, and a draft stays.
+  useEffect(() => {
+    const now = mounted.current;
+    if (now) now.handle = now.api.mount(options.current());
+  }, [label, position, theme, hasList, hasMore]);
+
+  return null;
+}

package/src/help/requests.ts

@@ -0,0 +1,111 @@
+/**
+ * The pill's two hooks for a host whose server route is `handleSupportRequest` (`../server/support.ts`):
+ *
+ *   CommentToolHelp.mount(CommentToolHelp.supportRequestsAt("/api/support"));
+ *
+ * `submit` posts the request as JSON with its pictures as base64; `list` reads the person's own requests.
+ * Both go to the host's own origin with its own cookies. A refusal's sentence, written by the route for the
+ * person, is passed on as a `HelpError`.
+ */
+import {
+  HELP_LIMITS,
+  type HelpFailureWire,
+  type HelpImageWire,
+  type HelpReceiptWire,
+  type HelpRequestWire,
+} from "./wire.js";
+import {
+  HelpError,
+  type HelpImage,
+  type HelpReceipt,
+  type HelpRequest,
+  type SubmittedRequest,
+  type SupportRequests,
+} from "./types.js";
+
+const NOT_SENT = "That did not send. Check your connection and try again.";
+const NOT_READ = "Your requests could not be loaded.";
+
+async function base64Of(blob: Blob): Promise<string> {
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  let binary = "";
+  const chunk = 0x8000;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+  }
+  return btoa(binary);
+}
+
+async function imageWire(image: HelpImage): Promise<HelpImageWire> {
+  if (image.blob.size > HELP_LIMITS.imageBytes) {
+    throw new HelpError("A picture is too large to send. Remove it and try again.");
+  }
+  return {
+    name: image.name,
+    contentType: image.blob.type,
+    width: image.width,
+    height: image.height,
+    markedUp: image.markedUp,
+    data: await base64Of(image.blob),
+  };
+}
+
+/** The route's own sentence, when it answered with one. */
+async function sentenceOf(response: Response): Promise<string | null> {
+  const payload = (await response.json().catch(() => null)) as Partial<HelpFailureWire> | null;
+  return typeof payload?.error === "string" && payload.error.trim() ? payload.error : null;
+}
+
+export function supportRequestsAt(url: string): SupportRequests {
+  return {
+    async submit(request: HelpRequest): Promise<HelpReceipt> {
+      const body: HelpRequestWire = {
+        id: request.id,
+        message: request.message,
+        pageUrl: request.pageUrl,
+        route: request.route,
+        pointed: request.pointed,
+        images: await Promise.all(request.images.map(imageWire)),
+        client: request.client,
+      };
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          method: "POST",
+          headers: { accept: "application/json", "content-type": "application/json" },
+          credentials: "same-origin",
+          cache: "no-store",
+          body: JSON.stringify(body),
+        });
+      } catch {
+        throw new HelpError(NOT_SENT);
+      }
+      if (!response.ok) throw new HelpError((await sentenceOf(response)) ?? NOT_SENT);
+      const receipt = (await response.json().catch(() => null)) as HelpReceiptWire | null;
+      return {
+        ...(typeof receipt?.reference === "string" ? { reference: receipt.reference } : {}),
+        ...(typeof receipt?.url === "string" ? { url: receipt.url } : {}),
+        ...(typeof receipt?.note === "string" ? { note: receipt.note } : {}),
+      };
+    },
+
+    async list(): Promise<readonly SubmittedRequest[]> {
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          headers: { accept: "application/json" },
+          credentials: "same-origin",
+          cache: "no-store",
+        });
+      } catch {
+        throw new HelpError(NOT_READ);
+      }
+      if (!response.ok) throw new HelpError((await sentenceOf(response)) ?? NOT_READ);
+      const payload = (await response.json().catch(() => null)) as {
+        requests?: unknown;
+      } | null;
+      if (!Array.isArray(payload?.requests)) throw new HelpError(NOT_READ);
+      return payload.requests as SubmittedRequest[];
+    },
+  };
+}