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

package/README.md

@@ -2,19 +2,35 @@
 
 The in-app comment toolbar that host apps (Officers Assist, JebelAI) load at runtime from the App comments
 worker as `/v1/toolbar/1.js`. Ported from the comment-service repo (`packages/core` and `packages/react`) on
-2026-10-12; this is now the source of record for the runtime.
+2026-10-12; this is the source of record for the runtime.
 
 - `src/core`: anchor model and resolution (`resolveAnchor`), DOM-free.
 - `src/runtime`: the React runtime (`runtime.tsx` is the bundle entry), element capture and placement, sync,
-  attachments, screenshots, styles. `loader.tsx` is the host-side `<CommentToolbar>`.
+  attachments, page screenshots (`page-image.ts`), styles, and the live update (`update.ts`, `build-id.ts`).
+  `loader.tsx` is the host-side `<CommentToolbar>`.
 - `src/compiler`, `src/vite`, `src/server`: the Vite plugin that stamps components with `data-cs-cmp` /
   `data-cs-file`, and the same-origin session route. Entry points `src/react.ts`, `src/vite.ts`, `src/server.ts`.
-- Worker bundle: `bun scripts/app-comments/build-toolbar.mjs` writes `workers/app-comments/toolbar-dist/v1/toolbar/`
-  (checked in; see `docs/policies/generated-files-policy.md`). `bun scripts/dev/dev-app-comments.mjs` builds it too.
-- npm package: `bun run build` here writes `dist/` (vite, react with the runtime bundled as fallback, server, and
-  declarations); publish with `npm publish` from this directory. Host apps install it and use
-  `@devaccel-labs/app-comments-toolbar/vite`, `/react` and `/server`; the `COMMENT_SERVICE_*` env names are unchanged.
 - Tests: `tests/unit/app-comments-toolbar-*.spec.ts`.
 
-The bundle has no version negotiation with host apps: `/v1` responses and the runtime's storage keys must stay
-compatible with whatever package version the hosts have installed.
+## How the toolbar ships
+
+The toolbar is released by deploying MyStatusFlow, nothing else (ADR-APPC-008):
+
+- `bun scripts/app-comments/build-toolbar.mjs` writes `workers/app-comments/toolbar-dist/v1/toolbar/` (checked in;
+  see `docs/policies/generated-files-policy.md`) with a build id hashed from the runtime's source, stamped into
+  the bundle and written to `build.json`. `bun scripts/dev/dev-app-comments.mjs` builds it too.
+- `bun run deploy:staging` (and the CI deploy) rebuilds it as its own phase and deploys the worker; a worker's
+  served assets count toward the deploy's change detection.
+- A toolbar that is open reads `/v1/toolbar/build.json` when its live socket reconnects (a deploy restarts it),
+  when its tab becomes visible, and every five minutes. A different id makes it import the new bundle and remount
+  itself in place, once nobody is mid-draft, mid-reply, recording or editing.
+
+## The npm package
+
+Hosts install the package for the three things that are host-side by nature: the Vite plugin (build time), the
+session route (server side) and the `<CommentToolbar>` loader. The package holds no runtime (since 1.1.0), so it
+only changes when the loader contract (`runtimeVersion`) does. `bun run build` here writes `dist/`; publish with
+`npm publish` from this directory. The `COMMENT_SERVICE_*` env names in hosts are unchanged.
+
+`/v1` responses and the runtime's storage keys must stay compatible with whatever package version the hosts have
+installed; the runtime itself is always the worker's current build.

package/dist/react.js

@@ -1,36 +1,139 @@
-import {
-  captureHandoff,
-  runtimeVersion,
-  sessionFor,
-  whenIdle
-} from "./chunks/chunk-CSKXLF33.js";
-
 // src/runtime/loader.tsx
 import { useEffect, useRef } from "react";
+
+// src/runtime/handoff.ts
+var key = "devaccel.comment.handoff";
+var ttl = 30 * 60 * 1e3;
+function readHandoff() {
+  try {
+    const value = JSON.parse(sessionStorage.getItem(key) ?? "null");
+    return value && Date.now() - value.at < ttl ? value : null;
+  } catch {
+    return null;
+  }
+}
+function write(value) {
+  try {
+    if (value.invite || value.thread) sessionStorage.setItem(key, JSON.stringify(value));
+    else sessionStorage.removeItem(key);
+  } catch {
+  }
+}
+function linkParams() {
+  const url = new URL(window.location.href);
+  const hash = new URLSearchParams(url.hash.slice(1));
+  return {
+    url,
+    hash,
+    invite: url.searchParams.get("cs-invite") ?? hash.get("cs-invite"),
+    thread: url.searchParams.get("cs-thread") ?? hash.get("cs-thread")
+  };
+}
+function captureHandoff() {
+  if (typeof window === "undefined") return;
+  const { invite, thread } = linkParams();
+  if (!invite && !thread) return;
+  write({
+    ...readHandoff(),
+    ...invite ? { invite } : {},
+    ...thread ? { thread } : {},
+    at: Date.now()
+  });
+}
+
+// src/runtime/idle.ts
+var FALLBACK_SLICE_MS = 8;
+function whenIdle(task, timeout) {
+  if (typeof requestIdleCallback === "function") {
+    const id2 = requestIdleCallback(task, { timeout });
+    return () => cancelIdleCallback(id2);
+  }
+  const id = setTimeout(
+    () => {
+      const end = performance.now() + FALLBACK_SLICE_MS;
+      task({ didTimeout: false, timeRemaining: () => Math.max(0, end - performance.now()) });
+    },
+    Math.min(timeout, 200)
+  );
+  return () => clearTimeout(id);
+}
+
+// src/runtime/runtime-version.ts
+var runtimeVersion = 1;
+
+// src/runtime/session.ts
+var EXPIRY_MARGIN_MS = 6e4;
+var UNKNOWN_EXPIRY_MS = 5 * 6e4;
+function readJwt(token) {
+  try {
+    const part = token.split(".")[1];
+    if (!part) return null;
+    const pad = part.length % 4 === 0 ? "" : "=".repeat(4 - part.length % 4);
+    return JSON.parse(atob(part.replaceAll("-", "+").replaceAll("_", "/") + pad));
+  } catch {
+    return null;
+  }
+}
+function sessionFrom(payload) {
+  const value = payload;
+  if (!value?.enabled || !value.apiUrl || !value.project || !value.environment || !value.hostToken)
+    return null;
+  return {
+    apiUrl: value.apiUrl,
+    project: value.project,
+    environment: value.environment,
+    hostToken: value.hostToken
+  };
+}
+async function fetchSession(path) {
+  const response = await fetch(path, {
+    headers: { accept: "application/json", "x-comment-service-origin": window.location.origin },
+    cache: "no-store"
+  });
+  return response.json();
+}
+function sessionSource(path, load = fetchSession, now = Date.now) {
+  let kept = null;
+  let pending = null;
+  return ({ refresh = false } = {}) => {
+    if (!refresh && kept && now() < kept.until) return Promise.resolve(kept.session);
+    if (pending) return pending;
+    pending = load(path).then((payload) => {
+      const session = sessionFrom(payload);
+      const expires = session ? readJwt(session.hostToken)?.exp : void 0;
+      const until = !session ? Infinity : expires ? expires * 1e3 - EXPIRY_MARGIN_MS : now() + UNKNOWN_EXPIRY_MS;
+      kept = { session, until };
+      return session;
+    }).finally(() => {
+      pending = null;
+    });
+    return pending;
+  };
+}
+var sources = /* @__PURE__ */ new Map();
+function sessionFor(path) {
+  let source = sources.get(path);
+  if (!source) {
+    source = sessionSource(path);
+    sources.set(path, source);
+  }
+  return source;
+}
+
+// src/runtime/loader.tsx
 var IDLE_TIMEOUT_MS = 3e3;
 captureHandoff();
-var bundled = () => import("./chunks/runtime-JX75TKER.js");
-async function loadRuntime(apiUrl, source) {
-  if (source === "bundled") return bundled();
+async function loadRuntime(apiUrl) {
   const url = `${apiUrl.replace(/\/+$/, "")}/v1/toolbar/${runtimeVersion}.js`;
-  try {
-    const remote = await import(
-      /* @vite-ignore */
-      /* webpackIgnore: true */
-      url
-    );
-    if (typeof remote.mount === "function") return remote;
-    throw new Error(`${url} has no mount export`);
-  } catch (error) {
-    console.warn(
-      "[comment-service] Could not load the latest toolbar, using the copy bundled with the package.",
-      error
-    );
-    return bundled();
-  }
+  const remote = await import(
+    /* @vite-ignore */
+    /* webpackIgnore: true */
+    url
+  );
+  if (typeof remote.mount === "function") return remote;
+  throw new Error(`${url} has no mount export`);
 }
 function CommentToolbar({
-  source = "latest",
   sessionPath = "/api/comment-service/session",
   pollMs,
   position,
@@ -39,17 +142,19 @@ function CommentToolbar({
 }) {
   const handle = useRef(null);
   const navigateRef = useRef(navigate);
-  navigateRef.current = navigate;
-  const hasNavigate = Boolean(navigate);
-  const props = useRef({});
-  props.current = {
-    sessionPath,
-    pollMs,
-    position,
-    theme,
-    navigate: hasNavigate ? (href) => navigateRef.current?.(href) : void 0,
-    getSession: sessionFor(sessionPath)
-  };
+  const propsRef = useRef({});
+  useEffect(() => {
+    navigateRef.current = navigate;
+    propsRef.current = {
+      sessionPath,
+      pollMs,
+      position,
+      theme,
+      navigate: navigate ? (href) => navigateRef.current?.(href) : void 0,
+      getSession: sessionFor(sessionPath)
+    };
+    handle.current?.update(propsRef.current);
+  }, [navigate, pollMs, position, sessionPath, theme]);
   useEffect(() => {
     let cancelled = false;
     let mounted = null;
@@ -57,13 +162,13 @@ function CommentToolbar({
     const start = async () => {
       const session = await sessionFor(sessionPath)().catch(() => null);
       if (!session || cancelled) return;
-      const runtime = await loadRuntime(session.apiUrl, source);
+      const runtime = await loadRuntime(session.apiUrl);
       if (cancelled) return;
       container = document.createElement("div");
-      container.setAttribute("data-cs-runtime", source);
+      container.setAttribute("data-cs-runtime", "latest");
       container.style.display = "contents";
       document.body.append(container);
-      mounted = runtime.mount(container, props.current);
+      mounted = runtime.mount(container, propsRef.current);
       handle.current = mounted;
     };
     const cancelIdle = whenIdle(() => {
@@ -80,10 +185,7 @@ function CommentToolbar({
         container?.remove();
       });
     };
-  }, [sessionPath, source]);
-  useEffect(() => {
-    handle.current?.update(props.current);
-  }, [pollMs, position, theme, hasNavigate]);
+  }, [sessionPath]);
   return null;
 }
 export {

package/dist/types/react.d.ts

@@ -1,2 +1,2 @@
-export { CommentToolbar, type ToolbarSource } from "./runtime/loader.js";
+export { CommentToolbar } from "./runtime/loader.js";
 export type { ToolbarPosition, ToolbarProps, ToolbarTheme } from "./runtime/toolbar.js";

package/dist/types/runtime/build-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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).
+ */
+export declare const runtimeBuild: string;

package/dist/types/runtime/index.d.ts

@@ -1,2 +1,2 @@
-export { CommentToolbar, type ToolbarSource } from "./loader.js";
+export { CommentToolbar } from "./loader.js";
 export type { ToolbarPosition, ToolbarProps, ToolbarTheme } from "./toolbar.js";

package/dist/types/runtime/loader.d.ts

@@ -1,14 +1,6 @@
 import type { ToolbarProps } from "./toolbar.js";
-export type ToolbarSource = "latest" | "bundled";
 /**
  * Renders nothing and does nothing during render. Once the page is idle it asks the session route, once per page
  * load, whether comments are on, and only then loads and mounts the toolbar.
  */
-export declare function CommentToolbar({ source, sessionPath, pollMs, position, theme, navigate, }: ToolbarProps & {
-    /**
-     * "latest" (default) loads the newest compatible toolbar from the comment service, so fixes ship
-     * without a dependency upgrade, and falls back to the copy in this package if that fails.
-     * "bundled" always uses the copy in this package.
-     */
-    source?: ToolbarSource;
-}): null;
+export declare function CommentToolbar({ sessionPath, pollMs, position, theme, navigate, }: ToolbarProps): null;

package/dist/types/runtime/page-image.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Draws the visible page onto a canvas without reading a computed style per element.
+ *
+ * The page is cloned natively (`cloneNode(true)`, a few milliseconds for thousands of nodes), the page's own
+ * stylesheets are inlined once (cached per page, with fonts and `url()` assets embedded as data URLs), and the
+ * result is rasterized through an SVG `<foreignObject>`. The previous renderer (modern-screenshot) copied the
+ * diff of ~400 computed properties for every element and its pseudo-elements, which cost about a second of
+ * main-thread time per capture on an ordinary page and grew with the page. This one spends the main thread on
+ * the clone walk and on the browser's own SVG layout, and nothing on the network once warmed.
+ *
+ * What is not carried over: cross-origin iframes (drawn blank), `<video>` frames (blank), styles that depend on
+ * `:hover`/`:focus` (dropped, which is what a screenshot should show anyway).
+ */
+export type PageImageOptions = {
+    /** Device pixels per CSS pixel in the output. */
+    scale: number;
+    /** Upper bound on the whole capture. */
+    timeout?: number;
+    /** Subtrees to leave out (the toolbar). */
+    exclude?: (element: Element) => boolean;
+    /** Painted behind the page. */
+    backgroundColor?: string;
+    /** CSS width/height of the captured area; defaults to the viewport. */
+    width?: number;
+    height?: number;
+    /** Window scroll offsets the page is shifted by. */
+    scrollX?: number;
+    scrollY?: number;
+};
+type Viewport = {
+    width: number;
+    height: number;
+};
+/** A data URL for `url`, or null when it can't be fetched in time. Never rejects. */
+export declare function assetDataUrl(url: string, timeout?: number): Promise<string | null>;
+/** Replaces every `url()` in `cssText` with a data URL. Unfetchable ones are left as they are. */
+export declare function inlineCssUrls(cssText: string, baseHref: string): Promise<string>;
+type StyleSource = {
+    key: string;
+    ownHref: string;
+    text: string | null;
+    href: string | null;
+};
+/** The sheets that style the page, read in document order. */
+export declare function collectStyleSources(doc: Document): StyleSource[];
+/** Every page style as one block of CSS with assets embedded. Cached; refreshed when a sheet is added or grows. */
+export declare function pageStyleText(doc?: Document): Promise<string>;
+/** Fetches fonts and CSS assets now, so the first capture pays nothing on the network. */
+export declare function prewarmPageImage(doc?: Document): void;
+/**
+ * The elements that paint inside the viewport, plus every ancestor of one (so the tree above them survives).
+ * Elements without a box (`display: none`, `<option>`, SVG `<defs>`, `display: contents` wrappers) are not
+ * listed: they neither show nor hide anything by themselves, so the clone keeps them under a kept parent.
+ */
+export declare function visibleSet(root: Element, viewport: Viewport): Set<Element>;
+export type ClonedPage = {
+    root: Element;
+    waits: Promise<unknown>[];
+    elements: number;
+};
+/**
+ * A copy of `root` ready to serialize: offscreen and non-painting subtrees removed, live form values, scroll
+ * offsets, canvases and images carried over. `waits` resolve when every image has its pixels.
+ */
+export declare function clonePage(root: Element, viewport: Viewport, exclude: (element: Element) => boolean, view?: Window): ClonedPage;
+/** The SVG document that draws `clone` with `css` applied, `width`×`height` CSS pixels. */
+export declare function pageSvg(clone: Element, css: string, width: number, height: number): string;
+/** The visible page as a canvas. Throws when the page can't be drawn in time. */
+export declare function drawPage(options: PageImageOptions): Promise<HTMLCanvasElement>;
+export {};

package/dist/types/runtime/runtime.d.ts

@@ -1,8 +1,14 @@
 import { type RuntimeProps } from "./toolbar.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;
 };
+/**
+ * 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 declare function mount(container: HTMLElement, props: RuntimeProps): ToolbarHandle;

package/dist/types/runtime/screenshot.d.ts

@@ -3,6 +3,8 @@ import type { Capture } from "./client.js";
 export declare function describeCapture(url: string): Capture;
 /** The visible page as a canvas, toolbar left out. `timeout` bounds a slow frame. */
 export declare function renderViewport(scale: number, timeout?: number): Promise<HTMLCanvasElement>;
+/** Drops the reused render, for example after the page changed in a way the view key can't see. */
+export declare function forgetDrawnPage(): void;
 /** The whole visible page as a JPEG, toolbar left out. If `highlight` is on screen it's outlined. */
 export declare function capturePage(highlight?: Element | null): Promise<Blob | null>;
 /**

package/dist/types/runtime/update.d.ts

@@ -0,0 +1,13 @@
+/** Between checks of the served build while the page stays open. Reconnects and tab switches also check. */
+export declare const CHECK_EVERY_MS: number;
+/** Loads a newer runtime at `url` and remounts the toolbar from it. Registered by the running runtime's `mount`. */
+export type Swapper = (url: string) => Promise<void>;
+export declare function registerSwapper(next: Swapper | null): void;
+/** The bundle URL for `build`. The query defeats the module cache; the chunks it imports carry their own hashes. */
+export declare function runtimeUrl(apiUrl: string, build: string): string;
+/** The build the worker serves now, or null when it can't be read. Never throws. */
+export declare function servedBuild(apiUrl: string, fetchFn?: typeof fetch): Promise<string | null>;
+/** True when the worker serves a different build than the one running here. A "dev" build never swaps. */
+export declare function needsSwap(served: string | null, current?: string): boolean;
+/** Swaps to the build at `url` once. Resolves false when no runtime registered or a swap is under way. */
+export declare function swapRuntime(url: string): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devaccel-labs/app-comments-toolbar",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "In-app comment toolbar for host apps on MyStatusFlow App comments: Vite plugin, <CommentToolbar>, and the same-origin session route.",
   "license": "UNLICENSED",
   "files": [
@@ -41,10 +41,10 @@
     "@babel/generator": "^7.28.5",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
-    "@babel/types": "^7.28.5",
-    "modern-screenshot": "4.7.0"
+    "@babel/types": "^7.28.5"
   },
   "devDependencies": {
+    "modern-screenshot": "4.7.0",
     "esbuild": "0.28.1"
   },
   "peerDependencies": {

package/dist/chunks/chunk-CSKXLF33.js

@@ -1,153 +0,0 @@
-// src/runtime/runtime-version.ts
-var runtimeVersion = 1;
-
-// src/runtime/handoff.ts
-var key = "devaccel.comment.handoff";
-var ttl = 30 * 60 * 1e3;
-function readHandoff() {
-  try {
-    const value = JSON.parse(sessionStorage.getItem(key) ?? "null");
-    return value && Date.now() - value.at < ttl ? value : null;
-  } catch {
-    return null;
-  }
-}
-function write(value) {
-  try {
-    if (value.invite || value.thread) sessionStorage.setItem(key, JSON.stringify(value));
-    else sessionStorage.removeItem(key);
-  } catch {
-  }
-}
-function linkParams() {
-  const url = new URL(window.location.href);
-  const hash = new URLSearchParams(url.hash.slice(1));
-  return {
-    url,
-    hash,
-    invite: url.searchParams.get("cs-invite") ?? hash.get("cs-invite"),
-    thread: url.searchParams.get("cs-thread") ?? hash.get("cs-thread")
-  };
-}
-function captureHandoff() {
-  if (typeof window === "undefined") return;
-  const { invite, thread } = linkParams();
-  if (!invite && !thread) return;
-  write({
-    ...readHandoff(),
-    ...invite ? { invite } : {},
-    ...thread ? { thread } : {},
-    at: Date.now()
-  });
-}
-function dropHandoff(part) {
-  const current = readHandoff();
-  if (!current) return;
-  const { [part]: _dropped, ...rest } = current;
-  write(rest);
-}
-function stripHandoffFromUrl() {
-  const { url, hash } = linkParams();
-  const inQuery = url.searchParams.has("cs-invite") || url.searchParams.has("cs-thread");
-  const inHash = hash.has("cs-invite") || hash.has("cs-thread");
-  if (!inQuery && !inHash) return;
-  url.searchParams.delete("cs-invite");
-  url.searchParams.delete("cs-thread");
-  if (inHash) url.hash = "";
-  history.replaceState(history.state, "", url);
-}
-function linkWith(href, name, value) {
-  const url = new URL(href, window.location.origin);
-  url.searchParams.delete("cs-invite");
-  url.searchParams.delete("cs-thread");
-  url.hash = `${name}=${encodeURIComponent(value)}`;
-  return url.toString();
-}
-
-// src/runtime/idle.ts
-var FALLBACK_SLICE_MS = 8;
-function whenIdle(task, timeout) {
-  if (typeof requestIdleCallback === "function") {
-    const id2 = requestIdleCallback(task, { timeout });
-    return () => cancelIdleCallback(id2);
-  }
-  const id = setTimeout(
-    () => {
-      const end = performance.now() + FALLBACK_SLICE_MS;
-      task({ didTimeout: false, timeRemaining: () => Math.max(0, end - performance.now()) });
-    },
-    Math.min(timeout, 200)
-  );
-  return () => clearTimeout(id);
-}
-
-// src/runtime/session.ts
-var EXPIRY_MARGIN_MS = 6e4;
-var UNKNOWN_EXPIRY_MS = 5 * 6e4;
-function readJwt(token) {
-  try {
-    const part = token.split(".")[1];
-    if (!part) return null;
-    const pad = part.length % 4 === 0 ? "" : "=".repeat(4 - part.length % 4);
-    return JSON.parse(atob(part.replaceAll("-", "+").replaceAll("_", "/") + pad));
-  } catch {
-    return null;
-  }
-}
-function sessionFrom(payload) {
-  const value = payload;
-  if (!value?.enabled || !value.apiUrl || !value.project || !value.environment || !value.hostToken)
-    return null;
-  return {
-    apiUrl: value.apiUrl,
-    project: value.project,
-    environment: value.environment,
-    hostToken: value.hostToken
-  };
-}
-async function fetchSession(path) {
-  const response = await fetch(path, {
-    headers: { accept: "application/json", "x-comment-service-origin": window.location.origin },
-    cache: "no-store"
-  });
-  return response.json();
-}
-function sessionSource(path, load = fetchSession, now = Date.now) {
-  let kept = null;
-  let pending = null;
-  return ({ refresh = false } = {}) => {
-    if (!refresh && kept && now() < kept.until) return Promise.resolve(kept.session);
-    if (pending) return pending;
-    pending = load(path).then((payload) => {
-      const session = sessionFrom(payload);
-      const expires = session ? readJwt(session.hostToken)?.exp : void 0;
-      const until = !session ? Infinity : expires ? expires * 1e3 - EXPIRY_MARGIN_MS : now() + UNKNOWN_EXPIRY_MS;
-      kept = { session, until };
-      return session;
-    }).finally(() => {
-      pending = null;
-    });
-    return pending;
-  };
-}
-var sources = /* @__PURE__ */ new Map();
-function sessionFor(path) {
-  let source = sources.get(path);
-  if (!source) {
-    source = sessionSource(path);
-    sources.set(path, source);
-  }
-  return source;
-}
-
-export {
-  readHandoff,
-  captureHandoff,
-  dropHandoff,
-  stripHandoffFromUrl,
-  linkWith,
-  whenIdle,
-  runtimeVersion,
-  readJwt,
-  sessionFor
-};