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

package/src/runtime/ui-scale.ts

@@ -0,0 +1,75 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * The toolbar's size follows the screen it is on, not the window: a laptop's display gets a smaller step and a
+ * large monitor a larger one, so the bar, cards and type take about the same room to the eye everywhere. Every
+ * length in the stylesheet is `calc(N * var(--cs-u))`; the step sets `--cs-u` on `#cs-root`. Browser zoom keeps
+ * working because `window.screen` is in CSS pixels at the display's own scale and page zoom never changes it.
+ */
+export type ScreenTier = "compact" | "laptop" | "desktop" | "wide";
+
+/** Pixels per design pixel for each tier; `desktop` is the drawn size. */
+export const TIER_UNIT: Record<ScreenTier, number> = {
+  compact: 0.8125,
+  laptop: 0.875,
+  desktop: 1,
+  wide: 1.125,
+};
+
+/** A screen is ranked by its long side and its short side separately and gets the smaller tier of the two. */
+const LONG_SIDE: Array<[ScreenTier, number]> = [
+  ["wide", 2400],
+  ["desktop", 1800],
+  ["laptop", 1440],
+];
+const SHORT_SIDE: Array<[ScreenTier, number]> = [
+  ["wide", 1350],
+  ["desktop", 1050],
+  ["laptop", 940],
+];
+const ORDER: ScreenTier[] = ["compact", "laptop", "desktop", "wide"];
+/** Below this long side (tablets, phones) nothing is scaled: tap targets stay as drawn. */
+const MIN_LONG_SIDE = 1024;
+
+function rank(size: number, steps: Array<[ScreenTier, number]>): ScreenTier {
+  for (const [tier, min] of steps) if (size >= min) return tier;
+  return "compact";
+}
+
+export function screenTier(screen: { width: number; height: number }, coarse = false): ScreenTier {
+  const long = Math.max(screen.width, screen.height);
+  const short = Math.min(screen.width, screen.height);
+  if (coarse || !Number.isFinite(long) || long < MIN_LONG_SIDE) return "desktop";
+  const byLong = rank(long, LONG_SIDE);
+  const byShort = rank(short, SHORT_SIDE);
+  return ORDER[Math.min(ORDER.indexOf(byLong), ORDER.indexOf(byShort))]!;
+}
+
+function currentTier(): ScreenTier {
+  if (typeof window === "undefined" || !window.screen) return "desktop";
+  const coarse =
+    typeof window.matchMedia === "function" && window.matchMedia("(pointer: coarse)").matches;
+  return screenTier(window.screen, coarse);
+}
+
+function subscribe(onChange: () => void) {
+  window.addEventListener("resize", onChange);
+  const screen = window.screen as Screen & Partial<EventTarget>;
+  screen.addEventListener?.("change", onChange);
+  return () => {
+    window.removeEventListener("resize", onChange);
+    screen.removeEventListener?.("change", onChange);
+  };
+}
+
+/** The tier of the screen the toolbar is on now; follows the window to another monitor. */
+export function useScreenTier(): ScreenTier {
+  return useSyncExternalStore(subscribe, currentTier, () => "desktop");
+}
+
+/** The toolbar's pixels per design pixel right now, for lengths computed in script. */
+export function uiUnit(root: Element | null = document.getElementById("cs-root")): number {
+  if (!root) return 1;
+  const value = parseFloat(getComputedStyle(root).getPropertyValue("--cs-u"));
+  return Number.isFinite(value) && value > 0 ? value : 1;
+}

package/src/runtime/update.ts

@@ -0,0 +1,98 @@
+import { runtimeBuild } from "./build-id.js";
+import { runtimeVersion } from "./runtime-version.js";
+
+/**
+ * Between checks of the served build while the page stays open. The worker also announces its build over the
+ * live socket when its project object starts, and reconnects and tab switches check too; this is the backstop
+ * for a toolbar whose project object stayed asleep through a deploy.
+ */
+export const CHECK_EVERY_MS = 60_000;
+
+type BuildListener = (build: string) => void;
+const listeners = new Set<BuildListener>();
+
+/** Called with the build the worker says it serves (a live-socket message). */
+export function announceBuild(build: string) {
+  for (const listener of listeners) listener(build);
+}
+
+/** Hears every announced build until the returned function is called. */
+export function onBuildAnnounced(listener: BuildListener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * Loads the runtime at `url` and remounts the toolbar from it when it is `build`; resolves false (nothing remounted)
+ * when the bundle that came back is some other build. `runtime.tsx#mount` registers it.
+ */
+export type Swapper = (url: string, build: string) => Promise<boolean>;
+let swapper: Swapper | null = null;
+let swapping = false;
+/** Tries per build before this page gives up on it until a reload. */
+const MAX_SWAP_ATTEMPTS = 3;
+const attempts = new Map<string, number>();
+
+export function registerSwapper(next: Swapper | null) {
+  swapper = next;
+}
+
+function base(apiUrl: string) {
+  return apiUrl.replace(/\/+$/, "");
+}
+
+/**
+ * The bundle URL for `build`. The query defeats the module cache; the chunks it imports carry their own hashes.
+ * A page imports a module URL once and keeps it, so each retry (`attempt` > 0) gets a URL of its own.
+ */
+export function runtimeUrl(apiUrl: string, build: string, attempt = 0) {
+  const url = `${base(apiUrl)}/v1/toolbar/${runtimeVersion}.js?b=${encodeURIComponent(build)}`;
+  return attempt > 0 ? `${url}&n=${attempt}` : url;
+}
+
+/** The build the worker serves now, or null when it can't be read. Never throws. */
+export async function servedBuild(
+  apiUrl: string,
+  fetchFn: typeof fetch = fetch,
+): Promise<string | null> {
+  try {
+    const response = await fetchFn(`${base(apiUrl)}/v1/toolbar/build.json`, {
+      cache: "no-store",
+      mode: "cors",
+    });
+    if (!response.ok) return null;
+    const body = (await response.json()) as { build?: unknown };
+    return typeof body.build === "string" && body.build ? body.build : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when the worker serves a different build than the one running here. A "dev" build never swaps. */
+export function needsSwap(served: string | null, current: string = runtimeBuild) {
+  return Boolean(served) && current !== "dev" && served !== current;
+}
+
+/**
+ * Swaps to `build`. Resolves false when no runtime registered, a swap is under way, the bundle that loaded is not
+ * `build`, or this page already tried `build` too often.
+ *
+ * Right after a deploy an edge can still answer `1.js?b=<new>` with the previous bundle. Mounting it would loop:
+ * it sees the newer build served, imports the same URL, gets itself back from the module cache and swaps again,
+ * remounting the toolbar (and dropping its socket) as fast as it can. The swapper refuses such a bundle instead,
+ * and the next try uses a URL this page hasn't imported.
+ */
+export async function swapRuntime(apiUrl: string, build: string): Promise<boolean> {
+  if (!swapper || swapping) return false;
+  const attempt = attempts.get(build) ?? 0;
+  if (attempt >= MAX_SWAP_ATTEMPTS) return false;
+  attempts.set(build, attempt + 1);
+  swapping = true;
+  try {
+    return await swapper(runtimeUrl(apiUrl, build, attempt), build);
+  } finally {
+    swapping = false;
+  }
+}

package/src/runtime/use-debug-context.ts

@@ -0,0 +1,81 @@
+/**
+ * The toolbar's debug context: running while someone is signed in to the toolbar and the host turned it on
+ * in code, stopped otherwise (the toolbar's effect calls `start`). The host's functions are read through a ref, so a new options object on every
+ * render does not restart the capture and lose what it has seen; only a change of what is captured does.
+ */
+import { useCallback, useEffect, useRef, type MutableRefObject } from "react";
+import { startDebugContext, type DebugCapture, type DebugSnapshotInput } from "./debug-context.js";
+import { DEBUG_ERROR_EVENT, type DebugErrorDetail } from "./debug-context-host.js";
+import {
+  debugContextKey,
+  debugContextName,
+  liveDebugOptions,
+  resolveDebugContext,
+  type DebugContextConfig,
+} from "./debug-context-model.js";
+
+export type DebugContextControl = {
+  /** The running capture, or null. */
+  capture: MutableRefObject<DebugCapture | null>;
+  /** Changes when what is captured changes: the effect that calls `start` depends on it. */
+  key: string;
+  /**
+   * Starts the capture and returns its stop. The caller starts it after the activity trail and stops it
+   * first, so each puts back exactly the patches it made.
+   */
+  start: (apiUrl: string) => () => void;
+};
+
+export function useDebugContext(config: DebugContextConfig | undefined): DebugContextControl {
+  const capture = useRef<DebugCapture | null>(null);
+  const configRef = useRef(config);
+  // Declared before the caller's effect that starts the capture, so it runs first and the capture reads this
+  // render's config.
+  useEffect(() => {
+    configRef.current = config;
+  });
+  const key = debugContextKey(config);
+  const start = useCallback((apiUrl: string) => {
+    const resolved = resolveDebugContext(
+      configRef.current === true ? true : liveDebugOptions(() => configRef.current),
+    );
+    if (!resolved) return () => {};
+    const own = apiUrl.replace(/\/+$/, "");
+    const running = startDebugContext(resolved, { ignoreUrl: (url) => url.startsWith(own) });
+    capture.current = running;
+    const onError = (event: Event) => {
+      const detail = (event as CustomEvent<DebugErrorDetail>).detail;
+      if (detail) running.reportError(detail.error, detail.componentStack);
+    };
+    window.addEventListener(DEBUG_ERROR_EVENT, onError);
+    return () => {
+      window.removeEventListener(DEBUG_ERROR_EVENT, onError);
+      running.stop();
+      if (capture.current === running) capture.current = null;
+    };
+  }, []);
+  return { capture, key, start };
+}
+
+/**
+ * Builds the context file and uploads it as `context-<stamp>.json`. Resolves with the attachment id, or null
+ * when there is none to send or it could not be sent: a report is never held back by its context.
+ */
+export async function uploadDebugContext(
+  capture: DebugCapture | null,
+  input: DebugSnapshotInput,
+  upload: (blob: Blob, name: string) => Promise<{ id: string }>,
+): Promise<string | null> {
+  if (!capture) return null;
+  try {
+    const started = performance.now();
+    const file = await capture.snapshot(input);
+    // Where a host can read what a report cost: `performance.getEntriesByName("comment-tool:debug-context")`.
+    performance.measure("comment-tool:debug-context", { start: started, end: performance.now() });
+    if (!file) return null;
+    const blob = new Blob([JSON.stringify(file)], { type: "application/json" });
+    return (await upload(blob, debugContextName(new Date(file.capturedAt)))).id;
+  } catch {
+    return null;
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,133 @@
+import { APP_ORIGIN_HEADER, appOriginScheme } from "../native-wire.js";
+
+export type CommentServiceConfig = {
+  url: string;
+  project: string;
+  environment: string;
+  secret: string;
+  /**
+   * Other environments of the project whose comments this one shows, live, alongside its own.
+   * Replies are allowed; resolving stays in the comment's own environment. Sent on every session, so this list is the
+   * whole truth: removing a name unlinks it.
+   */
+  linked?: string[];
+};
+
+export function readCommentServiceConfig(
+  env: Record<string, string | undefined> = process.env,
+): CommentServiceConfig | null {
+  const url = env.COMMENT_SERVICE_URL?.replace(/\/$/, "");
+  const project = env.COMMENT_SERVICE_PROJECT;
+  const environment = env.COMMENT_SERVICE_ENVIRONMENT;
+  const secret = env.COMMENT_SERVICE_SECRET;
+  if (!url || !project || !environment || !secret) return null;
+  const linked = (env.COMMENT_SERVICE_LINKED ?? "").split(/[\s,]+/).filter(Boolean);
+  return { url, project, environment, secret, linked };
+}
+
+/**
+ * Same-origin session route used by Next.js and TanStack Start.
+ * The integration secret stays on the server. The browser only receives a short-lived host token,
+ * which still cannot read or write comments until someone signs in to the toolbar.
+ *
+ * ## The origin is derived, never taken from a caller-chosen header
+ *
+ * The worker binds a host token to an origin, and it allow-lists every origin registered for the project —
+ * which includes linked environments. When this function forwarded the caller's header, any caller could
+ * name a *different* registered origin and receive a token bound to it. The header is a request field, so it
+ * was never a statement about which site made the request.
+ *
+ * Two clients legitimately need different answers, and they are distinguishable here:
+ *
+ * - **A native app** has no browser origin. It declares `<scheme>://app` in `x-comment-service-origin`, and
+ *   only that *shape* is accepted — never a web origin, which the worker would otherwise honour. Its host
+ *   proves it is the app by requiring a bearer session before it calls this at all.
+ * - **A browser** is bound to the origin the deployment is served from. A page cannot change that by sending a
+ *   header, so the caller-chosen `origin` is not consulted for a web request at all.
+ */
+
+/** The session this deployment may bind a token to: the origin it is served from, or one native app scheme. */
+export function requestedOrigin(request: Request): string {
+  const declared = request.headers.get(APP_ORIGIN_HEADER);
+  // A native app sends no `Origin`. Only a scheme of the documented shape is accepted from the header, so a web
+  // page cannot use this path to name a registered web origin of another environment.
+  if (
+    request.headers.get("origin") === null &&
+    declared !== null &&
+    appOriginScheme(declared) !== null
+  ) {
+    return declared;
+  }
+  // The origin the platform accepted the request on. `x-forwarded-host`/`x-forwarded-proto` are written by the
+  // host's edge from the actual connection, not by the page; the page cannot choose them. This is the whole fix:
+  // the header a caller controls is no longer consulted for a web request.
+  const url = new URL(request.url);
+  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host") ?? url.host;
+  if (!host || host.includes("/")) return url.origin;
+  const proto = (request.headers.get("x-forwarded-proto") ?? url.protocol.replace(":", ""))
+    .split(",")[0]
+    .trim();
+  return `${proto}://${host}`;
+}
+
+export async function handleSessionRequest(
+  request: Request,
+  config: CommentServiceConfig | null = readCommentServiceConfig(),
+): Promise<Response> {
+  const headers = { "cache-control": "no-store" };
+  if (!config) return Response.json({ enabled: false }, { headers });
+  const origin = requestedOrigin(request);
+  let response: Response;
+  try {
+    response = await fetch(`${config.url}/v1/host/session`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${config.secret}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        project: config.project,
+        environment: config.environment,
+        origin,
+        linked: config.linked ?? [],
+      }),
+    });
+  } catch {
+    return Response.json(
+      { enabled: false, error: "Comment service is unreachable." },
+      { status: 502, headers },
+    );
+  }
+  if (!response.ok) {
+    const payload = (await response.json().catch(() => null)) as {
+      error?: { message?: string };
+    } | null;
+    return Response.json(
+      {
+        enabled: false,
+        error: payload?.error?.message ?? "Comment service rejected this environment.",
+        origin,
+        status: response.status,
+      },
+      { status: 502, headers },
+    );
+  }
+  const payload = (await response.json()) as { token: string; unknownLinked?: string[] };
+  if (payload.unknownLinked?.length) {
+    // Server-side, in the host app: its logs are the only place this misconfiguration shows.
+    // oxlint-disable-next-line no-console
+    console.warn(
+      `[comment-service] COMMENT_SERVICE_LINKED: no environment named ${payload.unknownLinked.join(", ")} in project ${config.project}.`,
+    );
+  }
+  return Response.json(
+    {
+      enabled: true,
+      apiUrl: config.url,
+      project: config.project,
+      environment: config.environment,
+      hostToken: payload.token,
+    },
+    { headers },
+  );
+}