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

package/src/runtime/boot.ts

@@ -0,0 +1,95 @@
+/**
+ * How a host page brings the toolbar up: wait for an idle moment, ask the session route, import the runtime
+ * from the service the session names, mount it at the end of `<body>`. `<CommentToolbar>` (`./loader.tsx`, the
+ * npm package) and the script-tag loader the service serves (`../embed`, `/v1/toolbar/embed.js`) both run this
+ * and nothing else, so the two cannot drift.
+ *
+ * No React and no toolbar code is imported here (types only): the script-tag loader is this file and a few
+ * small ones, a few kilobytes in all.
+ */
+import { whenIdle } from "./idle.js";
+import type { RuntimeProps, ToolbarHandle } from "./runtime.js";
+import { runtimeVersion } from "./runtime-version.js";
+import type { Session } from "./session-source.js";
+
+export type Runtime = { mount(container: HTMLElement, props: RuntimeProps): ToolbarHandle };
+
+/** The session request waits for the page to go idle, but no longer than this after the loader starts. */
+export const IDLE_TIMEOUT_MS = 3000;
+
+/** Runs `task` later and returns a function that cancels it. */
+export type Wait = (task: () => void) => () => void;
+
+const untilIdle: Wait = (task) => whenIdle(task, IDLE_TIMEOUT_MS);
+
+const importModule = (url: string): Promise<unknown> =>
+  import(/* @vite-ignore */ /* webpackIgnore: true */ url);
+
+/**
+ * The toolbar always comes from the App comments worker, never from the host's own bundle: every deploy of the
+ * service serves the new build, open toolbars swap to it on their own, and a host never needs an update for it.
+ */
+export async function loadRuntime(apiUrl: string, load = importModule): Promise<Runtime> {
+  const url = `${apiUrl.replace(/\/+$/, "")}/v1/toolbar/${runtimeVersion}.js`;
+  const remote = (await load(url)) as Partial<Runtime>;
+  if (typeof remote.mount === "function") return remote as Runtime;
+  throw new Error(`${url} has no mount export`);
+}
+
+export type Boot = {
+  /** Asks the session route, or reuses its kept answer. Null, or a rejection, means no toolbar. */
+  getSession: () => Promise<Session | null>;
+  /** Read when the toolbar mounts, so it starts with the host's latest props. */
+  props: () => RuntimeProps;
+  /** Called once the toolbar is mounted, with its handle and the element it is mounted in. */
+  onMount?: (handle: ToolbarHandle, container: HTMLElement) => void;
+  /** Called when this attempt is over: the toolbar is mounted, or it will not be. */
+  onSettled?: () => void;
+  /** When to start. Default: when the page is idle, or after IDLE_TIMEOUT_MS at the latest. */
+  wait?: Wait;
+  /** Where the runtime comes from. Default: `loadRuntime`. */
+  load?: (apiUrl: string) => Promise<Runtime>;
+};
+
+/**
+ * One attempt to bring the toolbar up. Does nothing until `wait` runs it; then asks for the session once, and
+ * only when comments are on loads the runtime and mounts it in a new `<div data-cs-runtime="latest">` at the
+ * end of `<body>`.
+ *
+ * Returns `stop`: before the mount it calls the attempt off, after it it unmounts the toolbar and removes the
+ * element.
+ */
+export function bootToolbar(boot: Boot): () => void {
+  let cancelled = false;
+  let mounted: ToolbarHandle | null = null;
+  let container: HTMLElement | null = null;
+  const start = async () => {
+    const session = await boot.getSession().catch(() => null);
+    if (!session || cancelled) return;
+    const runtime = await (boot.load ?? loadRuntime)(session.apiUrl);
+    if (cancelled) return;
+    container = document.createElement("div");
+    container.setAttribute("data-cs-runtime", "latest");
+    container.style.display = "contents";
+    // appendChild, not append: the Workers types (a workspace may type-check this source with
+    // them) replace `Element.append` with HTMLRewriter's string/stream signature.
+    document.body.appendChild(container);
+    mounted = runtime.mount(container, boot.props());
+    boot.onMount?.(mounted, container);
+  };
+  const cancelWait = (boot.wait ?? untilIdle)(() => {
+    start()
+      .catch((error) => console.warn("[comment-service] The toolbar could not start.", error))
+      .finally(() => boot.onSettled?.());
+  });
+  return () => {
+    cancelled = true;
+    cancelWait();
+    // In a microtask: a host that stops the toolbar from inside its own React commit (an effect cleanup) must
+    // not unmount the toolbar's root while React is still rendering.
+    queueMicrotask(() => {
+      mounted?.unmount();
+      container?.remove();
+    });
+  };
+}

package/src/runtime/browser-label.ts

@@ -0,0 +1,31 @@
+const BROWSERS: Array<[string, RegExp]> = [
+  ["Edge", /Edg\/(\d+)/],
+  ["Firefox", /Firefox\/(\d+)/],
+  ["Chrome", /Chrome\/(\d+)/],
+  ["Safari", /Version\/(\d+)[\d.]* .*Safari/],
+];
+const SYSTEMS: Array<[string, RegExp]> = [
+  ["iOS", /iPhone|iPad/],
+  ["Android", /Android/],
+  ["macOS", /Mac OS X/],
+  ["Windows", /Windows/],
+  ["Linux", /Linux/],
+];
+
+/** "Chrome 142" from a user agent, or undefined. Only the name and major version: never the full string. */
+export function browserName(agent: string): string | undefined {
+  for (const [name, pattern] of BROWSERS) {
+    const version = agent.match(pattern)?.[1];
+    if (version) return `${name} ${version}`;
+  }
+  return undefined;
+}
+
+export function systemName(agent: string): string | undefined {
+  return SYSTEMS.find(([, pattern]) => pattern.test(agent))?.[0];
+}
+
+/** "Chrome 142 · macOS", or undefined when neither is known. */
+export function browserLabel(agent: string): string | undefined {
+  return [browserName(agent), systemName(agent)].filter(Boolean).join(" · ") || undefined;
+}

package/src/runtime/build-id.ts

@@ -0,0 +1,10 @@
+declare const __CS_BUILD__: string | undefined;
+
+/**
+ * Identifies this build of the runtime. `scripts/app-comments/build-toolbar.mjs` defines it from a hash of the
+ * runtime's source and writes the same value to `/v1/toolbar/build.json` next to the bundle, so a running toolbar
+ * can tell when the worker started serving a newer build. "dev" when the bundle was built without it (tests).
+ * Any change under src/runtime or src/core changes the id, so every deploy that touches the toolbar is announced.
+ */
+export const runtimeBuild: string =
+  typeof __CS_BUILD__ === "string" && __CS_BUILD__ ? __CS_BUILD__ : "dev";

package/src/runtime/capture-ui.tsx

@@ -0,0 +1,306 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { Capture } from "./client.js";
+import { describeCapture } from "./screenshot.js";
+import { redactSecretSearchParams } from "./replay.js";
+import {
+  formatClock,
+  RECORD_MAX_MS,
+  startTabRecording,
+  toggleMicrophone,
+  type TabTake,
+} from "./record.js";
+import * as Icon from "./icons.js";
+
+const MAX_BYTES = 10 * 1024 * 1024;
+
+type AddFiles = (files: Array<{ blob: Blob; name: string; capture?: Capture }>) => void;
+
+/** What a take tells the world while it runs, and what goes with the file when it is kept. */
+export type RecordingExtras = {
+  /** Every chunk as it lands (see `RecordOptions.onChunk`). */
+  onChunk?: (chunk: Blob, index: number, mime: string) => void;
+  /** Files to attach beside the recording, named after the same stamp (a replay of what happened in it). */
+  companions?: (info: {
+    stamp: string;
+    startedAt: number;
+    durationMs: number;
+    name: string;
+  }) => Array<{ blob: Blob; name: string }>;
+};
+
+function pageUrl() {
+  const url = new URL(window.location.href);
+  url.searchParams.delete("cs-thread");
+  url.searchParams.delete("cs-invite");
+  redactSecretSearchParams(url);
+  return `${url.origin}${url.pathname}${url.search}`;
+}
+
+function stamp() {
+  return new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-");
+}
+
+/** The clock turns into a warning this close to the limit. */
+const ENDING_MS = 10_000;
+
+/**
+ * The recording's sound: `on` and `muted` while the mic is in the take, `off` when the person chose no sound,
+ * `refused` when they wanted it but the mic wasn't given.
+ */
+export type RecordingSound = "on" | "muted" | "off" | "refused";
+
+/**
+ * Records the current tab and attaches the file to the draft as soon as it stops. Nothing is uploaded here. `sound` is the
+ * person's saved choice to record the mic; `onSoundChange` saves a new one.
+ */
+export function useTabRecording(
+  onError: (message: string) => void,
+  sound: boolean,
+  onSoundChange: (sound: boolean) => void,
+) {
+  const [phase, setPhase] = useState<"idle" | "recording">("idle");
+  const [soundState, setSoundState] = useState<RecordingSound>("off");
+  const [startedAt, setStartedAt] = useState(0);
+  const [now, setNow] = useState(0);
+  const take = useRef<TabTake | null>(null);
+  const addFiles = useRef<AddFiles | null>(null);
+  const extras = useRef<RecordingExtras | null>(null);
+  const capture = useRef<Capture | null>(null);
+  const alive = useRef(true);
+  const generation = useRef(0);
+  const phaseRef = useRef(phase);
+  useEffect(() => {
+    phaseRef.current = phase;
+  }, [phase]);
+
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+      generation.current += 1;
+      take.current?.cancel();
+    };
+  }, []);
+
+  useEffect(() => {
+    if (phase !== "recording") return;
+    const id = window.setInterval(() => setNow(Date.now()), 250);
+    return () => window.clearInterval(id);
+  }, [phase]);
+
+  /** Attaches a finished take, with its companions, to whatever the recording was started for. */
+  const attach = useCallback((blob: Blob, startedAt: number, stoppedAt: number) => {
+    const extension = blob.type === "video/mp4" ? "mp4" : "webm";
+    const when = stamp();
+    const name = `recording-${when}.${extension}`;
+    const companions =
+      extras.current?.companions?.({
+        stamp: when,
+        startedAt,
+        durationMs: Math.max(1000, stoppedAt - startedAt),
+        name,
+      }) ?? [];
+    addFiles.current?.([{ blob, name, capture: capture.current ?? undefined }, ...companions]);
+  }, []);
+
+  const begin = useCallback(
+    async (add: AddFiles, more?: RecordingExtras) => {
+      if (take.current || phaseRef.current === "recording") return;
+      addFiles.current = add;
+      extras.current = more ?? null;
+      const gen = ++generation.current;
+      phaseRef.current = "recording";
+      try {
+        const onChunk = more?.onChunk;
+        const next = await startTabRecording({ sound, onChunk }, (ready) => {
+          if (!alive.current || generation.current !== gen) {
+            ready.cancel();
+            return;
+          }
+          take.current = ready;
+        });
+        if (!alive.current || generation.current !== gen) {
+          next.cancel();
+          return;
+        }
+        take.current = next;
+        setSoundState(next.microphone ? "on" : sound ? "refused" : "off");
+        capture.current = describeCapture(pageUrl());
+        const started = Date.now();
+        setStartedAt(started);
+        setNow(started);
+        setPhase("recording");
+        void next.finished.then((blob) => {
+          take.current = null;
+          const stopped = Date.now();
+          if (!alive.current || generation.current !== gen) return;
+          phaseRef.current = "idle";
+          setPhase("idle");
+          if (!blob) return;
+          if (blob.size > MAX_BYTES) {
+            onError("That recording is over 10 MB. Record a shorter one.");
+            return;
+          }
+          attach(blob, started, stopped);
+        });
+      } catch (caught) {
+        if (generation.current === gen) phaseRef.current = "idle";
+        if (alive.current && generation.current === gen)
+          onError(caught instanceof Error ? caught.message : "Couldn’t start a recording.");
+      }
+    },
+    [attach, onError, sound],
+  );
+
+  const stop = useCallback(() => take.current?.stop(), []);
+
+  /** Mutes or unmutes the mic in this take, and remembers the choice for the next one. */
+  const toggleSound = useCallback(() => {
+    const microphone = take.current?.microphone;
+    if (microphone) {
+      const enabled = toggleMicrophone(microphone);
+      setSoundState(enabled ? "on" : "muted");
+      onSoundChange(enabled);
+      return;
+    }
+    // No mic in this take: the choice applies from the next recording.
+    onSoundChange(!sound);
+  }, [onSoundChange, sound]);
+
+  const cancel = useCallback(() => {
+    generation.current += 1;
+    take.current?.cancel();
+    take.current = null;
+    phaseRef.current = "idle";
+    setPhase("idle");
+  }, []);
+
+  return {
+    phase,
+    elapsed: phase === "recording" ? Math.max(0, now - startedAt) : 0,
+    sound: soundState,
+    /** What the next recording will do about sound. */
+    soundNext: sound,
+    toggleSound,
+    begin,
+    stop,
+    cancel,
+  };
+}
+
+/** Dictation into the comment the recording belongs to, driven from the record bar. */
+export type RecordDictation = {
+  listening: boolean;
+  /** Pieces still being written. */
+  queued: number;
+  toggle: () => void;
+};
+
+function soundLabel(sound: RecordingSound, soundNext: boolean) {
+  if (sound === "on")
+    return {
+      text: "Mic on",
+      tip: "Your voice is in the recording. Click to mute.",
+    };
+  if (sound === "muted") return { text: "Mic muted", tip: "Click to put your voice back in." };
+  if (sound === "refused")
+    return {
+      text: "No mic",
+      tip: "The microphone wasn’t allowed, so this recording has no sound.",
+    };
+  return soundNext
+    ? {
+        text: "Mic next time",
+        tip: "This recording has no sound. The next one will.",
+      }
+    : {
+        text: "Mic off",
+        tip: "This recording has no sound. Click to record your voice next time.",
+      };
+}
+
+export function RecordChrome({
+  elapsed,
+  sound,
+  soundNext,
+  dictation,
+  onToggleSound,
+  onStop,
+  onCancel,
+}: {
+  elapsed: number;
+  sound: RecordingSound;
+  soundNext: boolean;
+  /** Absent when there is no comment box to type into. */
+  dictation?: RecordDictation;
+  onToggleSound: () => void;
+  onStop: () => void;
+  onCancel: () => void;
+}) {
+  const left = RECORD_MAX_MS - elapsed;
+  const ending = left <= ENDING_MS;
+  const mic = soundLabel(sound, soundNext);
+  const talking = sound === "on" || dictation?.listening;
+  return (
+    <div className="cs-record cs-hit" data-cs-ui="record" role="status">
+      <span className="cs-record-dot" />
+      <span
+        className={`cs-record-time${ending ? " is-ending" : ""}`}
+        title={`Recordings stop by themselves at ${formatClock(RECORD_MAX_MS)}`}
+      >
+        {ending
+          ? `Stops in ${formatClock(left)}`
+          : `${formatClock(elapsed)} / ${formatClock(RECORD_MAX_MS)}`}
+      </span>
+      <button
+        className={`cs-button cs-record-toggle${sound === "on" ? " is-on" : ""}`}
+        data-cs-ui="record-sound"
+        data-cs-sound={sound}
+        type="button"
+        aria-pressed={sound === "on"}
+        title={mic.tip}
+        disabled={sound === "refused"}
+        onClick={onToggleSound}
+      >
+        <Icon.Mic />
+        {mic.text}
+      </button>
+      {dictation ? (
+        <button
+          className={`cs-button cs-record-toggle${dictation.listening ? " is-on" : ""}`}
+          data-cs-ui="record-dictate"
+          type="button"
+          aria-pressed={dictation.listening}
+          title={
+            dictation.listening
+              ? "Stop typing what you say"
+              : "Also type what you say into your comment"
+          }
+          onClick={dictation.toggle}
+        >
+          {dictation.listening
+            ? "Typing what you say…"
+            : dictation.queued > 0
+              ? "Writing…"
+              : "Type what I say"}
+        </button>
+      ) : null}
+      <span className="cs-record-note">
+        {talking
+          ? "Show and explain what went wrong, then stop."
+          : "Show what went wrong, then stop."}
+      </span>
+      <button
+        className="cs-button is-danger"
+        data-cs-ui="record-stop"
+        type="button"
+        onClick={onStop}
+      >
+        Stop
+      </button>
+      <button className="cs-button" data-cs-ui="record-cancel" type="button" onClick={onCancel}>
+        Cancel
+      </button>
+    </div>
+  );
+}