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

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

@@ -0,0 +1,37 @@
+/**
+ * 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 declare const CHECK_EVERY_MS = 60000;
+type BuildListener = (build: string) => void;
+/** Called with the build the worker says it serves (a live-socket message). */
+export declare function announceBuild(build: string): void;
+/** Hears every announced build until the returned function is called. */
+export declare function onBuildAnnounced(listener: BuildListener): () => void;
+/**
+ * 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>;
+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.
+ * A page imports a module URL once and keeps it, so each retry (`attempt` > 0) gets a URL of its own.
+ */
+export declare function runtimeUrl(apiUrl: string, build: string, attempt?: number): 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 `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 declare function swapRuntime(apiUrl: string, build: string): Promise<boolean>;
+export {};

package/dist/types/runtime/use-debug-context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { type MutableRefObject } from "react";
+import { type DebugCapture, type DebugSnapshotInput } from "./debug-context.js";
+import { 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 declare function useDebugContext(config: DebugContextConfig | undefined): DebugContextControl;
+/**
+ * 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 declare function uploadDebugContext(capture: DebugCapture | null, input: DebugSnapshotInput, upload: (blob: Blob, name: string) => Promise<{
+    id: string;
+}>): Promise<string | null>;

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

@@ -11,4 +11,26 @@ export type CommentServiceConfig = {
     linked?: string[];
 };
 export declare function readCommentServiceConfig(env?: Record<string, string | undefined>): CommentServiceConfig | null;
+/**
+ * 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 declare function requestedOrigin(request: Request): string;
 export declare function handleSessionRequest(request: Request, config?: CommentServiceConfig | null): Promise<Response>;

package/dist/types/server/support.d.ts

@@ -0,0 +1,20 @@
+export type SupportRequestConfig = {
+    /** Comment Tool: `https://comment-tool.example.com`. */
+    serviceUrl: string;
+    /** The host's connection token. Server only: it never reaches the browser. */
+    connectionToken: string;
+    /** The connection's own id for the project its support requests are filed in. */
+    project: string;
+    /** Who is asking, from the host's own sign-in. `userId` is the host's id for them. */
+    reporter: {
+        userId: string;
+        name: string;
+    };
+    /** The reporter's account in the host (a customer, a workspace), shown beside them in the console. */
+    account?: {
+        id: string;
+        name: string;
+    };
+    fetch?: typeof fetch;
+};
+export declare function handleSupportRequest(request: Request, config: SupportRequestConfig): Promise<Response>;

package/dist/types/server.d.ts

@@ -1,2 +1,4 @@
 export { handleSessionRequest, readCommentServiceConfig } from "./server/index.js";
 export type { CommentServiceConfig } from "./server/index.js";
+export { handleSupportRequest } from "./server/support.js";
+export type { SupportRequestConfig } from "./server/support.js";

package/dist/types/vite/plugin.d.ts

@@ -1,3 +1,11 @@
+import type { HostBuild } from "../runtime/debug-context-model.js";
+/** The constant `<CommentToolbar>` reads for the debug context's `build`, when nothing else gave one. */
+export declare const HOST_BUILD_CONSTANT = "__COMMENT_TOOL_HOST_BUILD__";
+/**
+ * The build this bundle is: the commit from the CI's variable or from `git`, the version from
+ * `COMMENT_SERVICE_BUILD_VERSION` or the package being built, and the mode. Only short, public facts.
+ */
+export declare function hostBuildOf(mode: string, root: string, env?: Record<string, string | undefined>, git?: () => string): HostBuild;
 type ResolvedConfig = {
     command: "build" | "serve";
     mode: string;
@@ -11,6 +19,13 @@ export declare function commentService(options?: {
 }): {
     name: string;
     enforce: "pre";
+    config(_config: unknown, environment: {
+        mode: string;
+    }): {
+        define: {
+            __COMMENT_TOOL_HOST_BUILD__: string;
+        };
+    };
     configResolved(config: ResolvedConfig): void;
     transform(code: string, id: string): {
         code: string;

package/dist/vite.js

@@ -1,15 +1,16 @@
+// src/vite/plugin.ts
+import { execFileSync } from "node:child_process";
+
 // src/compiler/annotate.ts
 import generateModule from "@babel/generator";
 import { parse } from "@babel/parser";
-import traverseModule from "@babel/traverse";
 import * as t from "@babel/types";
 function generate() {
   const mod = generateModule;
   return mod.default ?? mod;
 }
-function traverse() {
-  const mod = traverseModule;
-  return mod.default ?? mod;
+function isWalkNode(value) {
+  return value !== null && typeof value === "object" && typeof value.type === "string";
 }
 function toProjectPath(filename, root) {
   const clean = filename.split("?")[0].replaceAll("\\", "/");
@@ -18,45 +19,73 @@ function toProjectPath(filename, root) {
   if (relative.startsWith("/")) relative = relative.slice(1);
   return relative;
 }
-function componentName(path2, fallback) {
-  let current = path2;
-  while (current) {
-    if (current.isFunctionDeclaration() && current.node.id) return current.node.id.name;
-    if (current.isClassDeclaration() && current.node.id) return current.node.id.name;
-    if (current.isFunctionExpression() || current.isArrowFunctionExpression()) {
-      const parent = current.parentPath;
-      if (parent?.isVariableDeclarator() && parent.node.id.type === "Identifier")
-        return parent.node.id.name;
-      if ((parent?.isObjectProperty() || parent?.isClassProperty()) && parent.node.key.type === "Identifier") {
-        return parent.node.key.name;
+function componentName(ancestors, fallback) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const current = ancestors[i];
+    if ((current.type === "FunctionDeclaration" || current.type === "ClassDeclaration") && current.id) {
+      return current.id.name;
+    }
+    if (current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") {
+      const parent = i > 0 ? ancestors[i - 1] : null;
+      if (parent?.type === "VariableDeclarator" && parent.id.type === "Identifier")
+        return parent.id.name;
+      if ((parent?.type === "ObjectProperty" || parent?.type === "ClassProperty") && parent.key.type === "Identifier") {
+        return parent.key.name;
       }
     }
-    current = current.parentPath;
   }
   return fallback;
 }
-function isRootJsx(path2) {
-  const fn = path2.getFunctionParent();
-  if (!fn) return false;
-  let current = path2.parentPath;
-  while (current && current !== fn) {
-    if (current.isJSXElement()) return false;
-    current = current.parentPath;
+function isRootJsx(ancestors) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const current = ancestors[i];
+    if (t.isFunction(current)) return true;
+    if (current.type === "JSXElement") return false;
   }
-  return true;
+  return false;
 }
-function hasAttr(path2, name) {
-  return path2.node.openingElement.attributes.some(
+function hasAttr(node, name) {
+  return node.openingElement.attributes.some(
     (attr) => attr.type === "JSXAttribute" && attr.name?.type === "JSXIdentifier" && attr.name.name === name
   );
 }
-function setAttr(path2, name, value) {
-  if (hasAttr(path2, name)) return;
-  path2.node.openingElement.attributes.push(
+function setAttr(node, name, value) {
+  if (hasAttr(node, name)) return;
+  node.openingElement.attributes.push(
     t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value))
   );
 }
-var unstampable = /^(?:React\.)?(?:Fragment|Suspense|StrictMode|Profiler|Activity|ViewTransition)$|\.(?:Provider|Consumer)$/;
+var REACT_BUILTINS = /* @__PURE__ */ new Set([
+  "Fragment",
+  "Suspense",
+  "StrictMode",
+  "Profiler",
+  "Activity",
+  "ViewTransition"
+]);
+var contextComponent = /\.(?:Provider|Consumer)$/;
+function reactBuiltinTags(program) {
+  const tags = /* @__PURE__ */ new Set();
+  const namespaces = /* @__PURE__ */ new Set(["React"]);
+  for (const statement of program.body ?? []) {
+    if (statement.type !== "ImportDeclaration" || statement.source?.value !== "react") continue;
+    for (const specifier of statement.specifiers ?? []) {
+      const local = specifier.local?.name;
+      if (typeof local !== "string") continue;
+      if (specifier.type === "ImportNamespaceSpecifier" || specifier.type === "ImportDefaultSpecifier") {
+        namespaces.add(local);
+      } else if (specifier.type === "ImportSpecifier") {
+        const imported = specifier.imported?.name ?? specifier.imported?.value;
+        if (REACT_BUILTINS.has(imported)) tags.add(local);
+      }
+    }
+  }
+  for (const builtin of REACT_BUILTINS) {
+    tags.add(builtin);
+    for (const namespace of namespaces) tags.add(`${namespace}.${builtin}`);
+  }
+  return tags;
+}
 function jsxName(name) {
   if (t.isJSXIdentifier(name)) return name.name;
   if (t.isJSXMemberExpression(name)) {
@@ -80,18 +109,32 @@ function annotateSource(code, filename, root) {
   const file = toProjectPath(filename, root);
   const fallback = file.split("/").pop()?.replace(/\.[jt]sx$/, "") || "component";
   let changed = false;
-  traverse()(ast, {
-    JSXElement(path2) {
-      const tag = jsxName(path2.node.openingElement.name);
-      if (!tag || unstampable.test(tag)) return;
-      if (!isRootJsx(path2)) return;
-      const name = componentName(path2, fallback);
-      const before = path2.node.openingElement.attributes.length;
-      setAttr(path2, "data-cs-cmp", name);
-      setAttr(path2, "data-cs-file", file);
-      if (path2.node.openingElement.attributes.length !== before) changed = true;
+  const ancestors = [];
+  const builtins = reactBuiltinTags(ast.program);
+  const stamp = (node) => {
+    const tag = jsxName(node.openingElement.name);
+    if (!tag || builtins.has(tag) || contextComponent.test(tag)) return;
+    if (!isRootJsx(ancestors)) return;
+    const name = componentName(ancestors, fallback);
+    const before = node.openingElement.attributes.length;
+    setAttr(node, "data-cs-cmp", name);
+    setAttr(node, "data-cs-file", file);
+    if (node.openingElement.attributes.length !== before) changed = true;
+  };
+  const visit = (node) => {
+    if (node.type === "JSXElement") stamp(node);
+    ancestors.push(node);
+    for (const key of t.VISITOR_KEYS[node.type] ?? []) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) if (isWalkNode(item)) visit(item);
+      } else if (isWalkNode(child)) {
+        visit(child);
+      }
     }
-  });
+    ancestors.pop();
+  };
+  visit(ast);
   if (!changed) return code;
   const printed = generate()(ast, { retainLines: true, comments: true }, code);
   return printed.code;
@@ -132,6 +175,37 @@ function buildConfigured(root, mode, env = process.env) {
 }
 
 // src/vite/plugin.ts
+var HOST_BUILD_CONSTANT = "__COMMENT_TOOL_HOST_BUILD__";
+var COMMIT_VARIABLES = [
+  "COMMENT_SERVICE_BUILD_COMMIT",
+  "GITHUB_SHA",
+  "CF_PAGES_COMMIT_SHA",
+  "WORKERS_CI_COMMIT_SHA",
+  "VERCEL_GIT_COMMIT_SHA",
+  "CI_COMMIT_SHA"
+];
+function hostBuildOf(mode, root, env = process.env, git = () => execFileSync("git", ["rev-parse", "--short=12", "HEAD"], {
+  cwd: root,
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "ignore"]
+})) {
+  let commit = COMMIT_VARIABLES.map((name) => env[name]?.trim()).find(Boolean);
+  if (!commit) {
+    try {
+      commit = git().trim();
+    } catch {
+      commit = void 0;
+    }
+  }
+  const short = commit && /^[0-9a-f]{7,40}$/i.test(commit) ? commit.slice(0, 12) : void 0;
+  const version = (env.COMMENT_SERVICE_BUILD_VERSION ?? env.npm_package_version)?.trim().slice(0, 64);
+  return {
+    ...short ? { commit: short } : {},
+    ...version ? { version } : {},
+    env: mode.slice(0, 40),
+    builtAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
 function commentService(options) {
   const root = (options?.root ?? process.cwd()).replace(/\/$/, "");
   let enabled = options?.enabled ?? process.env.COMMENT_SERVICE_ENABLED !== "0";
@@ -139,6 +213,12 @@ function commentService(options) {
   return {
     name: "devaccel-comment-service",
     enforce: "pre",
+    // The build's commit and version, for the debug context of each comment (`<CommentToolbar debugContext>`).
+    config(_config, environment) {
+      return {
+        define: { [HOST_BUILD_CONSTANT]: JSON.stringify(hostBuildOf(environment.mode, root)) }
+      };
+    },
     configResolved(config) {
       enabled = stampingEnabled({
         option: options?.enabled,

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@devaccel-labs/app-comments-toolbar",
-  "version": "1.0.0",
-  "description": "In-app comment toolbar for host apps on MyStatusFlow App comments: Vite plugin, <CommentToolbar>, and the same-origin session route.",
+  "version": "1.3.0",
+  "description": "In-app comment toolbar for host apps: Vite plugin, <CommentToolbar>, and the same-origin session route.",
   "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DevAccel-Labs/comment_tool.git",
+    "directory": "packages/toolbar"
+  },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "type": "module",
@@ -21,6 +27,12 @@
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
     },
+    "./dictation": "./src/dictation.ts",
+    "./replay": "./src/replay.ts",
+    "./debug-context": "./src/debug-context.ts",
+    "./debug-context-host": "./src/runtime/debug-context-host.ts",
+    "./native-wire": "./src/native-wire.ts",
+    "./native": "./src/native.ts",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -29,26 +41,27 @@
   },
   "scripts": {
     "build": "bun build.mjs",
-    "build:runtime": "bun ../../scripts/app-comments/build-toolbar.mjs",
-    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile tsconfig.tsbuildinfo",
-    "lint": "bun ../../scripts/lint-package.mjs",
-    "lint:type-aware": "bun ../../scripts/lint-package.mjs --type-aware",
-    "format:check": "oxfmt --ignore-path=../../.oxfmtignore --check package.json tsconfig.json src",
-    "lint:fix": "bun ../../scripts/lint-package.mjs --fix",
-    "format": "oxfmt --ignore-path=../../.oxfmtignore package.json tsconfig.json src"
+    "build:runtime": "bun ../../scripts/build-toolbar.mjs",
+    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile tsconfig.tsbuildinfo && tsc --noEmit -p tests"
   },
   "dependencies": {
     "@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": {
-    "esbuild": "0.28.1"
+    "@fontsource-variable/inter": "^5.3.0",
+    "esbuild": "0.28.1",
+    "modern-screenshot": "4.7.0",
+    "radix-ui": "1.4.3"
   },
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
   }
 }

package/src/capture/api.ts

@@ -0,0 +1,128 @@
+/**
+ * `window.CommentToolCapture`: the toolbar's capture tools for a host page that has its own place to put what
+ * they produce (a support form, say). There is no session here and nothing is sent anywhere: this folder
+ * imports none of the toolbar's sign-in, storage or `/v1` code (the build checks that), and each call resolves
+ * with files for the host to keep or drop.
+ *
+ * One capture at a time. A call made while another is open closes that one, which resolves null.
+ */
+import { createElement } from "react";
+import { captureAnchor } from "../runtime/capture.js";
+import { targetName } from "../runtime/format.js";
+import { Editor } from "./editor.js";
+import { Capturing, Picker } from "./picker.js";
+import { pictureOf, shootPage, type CapturedImage } from "./picture.js";
+import { openSurface, type CaptureTheme } from "./surface.js";
+
+export type { CapturedImage } from "./picture.js";
+export type { CaptureTheme } from "./surface.js";
+
+export type CaptureOptions = {
+  /** The look of the capture UI. `auto` (the default) follows the system's light or dark setting. */
+  theme?: CaptureTheme;
+};
+
+export type CapturedTarget = {
+  /** What a person would call it: the toolbar's own name for an anchor ("button › Save"). */
+  label: string;
+  /** The page's path. */
+  route: string;
+  /** The visible page with the element outlined, or null when the page could not be drawn. */
+  image: CapturedImage | null;
+};
+
+export type CommentToolCaptureApi = {
+  /**
+   * Takes a picture of the page as it is now and opens the toolbar's drawing editor over it. Resolves with
+   * the picture, drawn on or not, when the person presses Done; null when they close it. Rejects when the
+   * page could not be drawn.
+   */
+  screenshot(options?: CaptureOptions): Promise<CapturedImage | null>;
+  /**
+   * Lets the person point at one thing on the page, as the toolbar's "comment on this" does. Resolves with
+   * what they pointed at and a picture of the page with it outlined; null on Escape.
+   */
+  pick(options?: CaptureOptions): Promise<CapturedTarget | null>;
+};
+
+const THEMES: readonly CaptureTheme[] = ["light", "dark", "auto"];
+
+function themeOf(options: CaptureOptions | undefined): CaptureTheme {
+  const theme = options?.theme ?? "auto";
+  if (!THEMES.includes(theme)) {
+    throw new TypeError(
+      `CommentToolCapture: theme must be "light", "dark" or "auto", not ${JSON.stringify(theme)}.`,
+    );
+  }
+  return theme;
+}
+
+export function createCapture(): CommentToolCaptureApi {
+  /** Closes the capture that is open, resolving its promise with null. */
+  let closeOpen: (() => void) | null = null;
+
+  /**
+   * Runs one capture: `start` gets the surface to draw in and `settle`, which closes the surface and settles
+   * the call. Anything after the first `settle` is ignored.
+   */
+  function capture<T>(
+    theme: CaptureTheme,
+    start: (
+      surface: ReturnType<typeof openSurface>,
+      settle: (outcome: { value: T | null } | { error: Error }) => void,
+    ) => void,
+  ): Promise<T | null> {
+    closeOpen?.();
+    return new Promise<T | null>((resolve, reject) => {
+      let settled = false;
+      const settle = (outcome: { value: T | null } | { error: Error }) => {
+        if (settled) return;
+        settled = true;
+        if (closeOpen === cancel) closeOpen = null;
+        surface.close();
+        if ("error" in outcome) reject(outcome.error);
+        else resolve(outcome.value);
+      };
+      const cancel = () => settle({ value: null });
+      const surface = openSurface(theme, cancel);
+      closeOpen = cancel;
+      start(surface, settle);
+    });
+  }
+
+  return {
+    async screenshot(options) {
+      const theme = themeOf(options);
+      // Copied before anything of this script is on the page, in the same task as the call.
+      const shot = shootPage(null);
+      return capture<CapturedImage>(theme, (surface, settle) => {
+        const cancel = () => settle({ value: null });
+        const done = (image: CapturedImage) => settle({ value: image });
+        surface.show(createElement(Editor, { picture: null, onDone: done, onCancel: cancel }));
+        void pictureOf(shot).then((picture) => {
+          if (!picture) {
+            settle({ error: new Error("CommentToolCapture: the page could not be captured.") });
+            return;
+          }
+          surface.show(createElement(Editor, { picture, onDone: done, onCancel: cancel }));
+        });
+      });
+    },
+
+    async pick(options) {
+      const theme = themeOf(options);
+      return capture<CapturedTarget>(theme, (surface, settle) => {
+        const onPick = (element: Element) => {
+          const anchor = captureAnchor(element, window.location.pathname);
+          // Copied in the click itself, so the picture is the page the person was looking at.
+          const shot = shootPage(element);
+          surface.show(createElement(Capturing));
+          void pictureOf(shot).then((image) =>
+            settle({ value: { label: targetName(anchor), route: anchor.route, image } }),
+          );
+        };
+        surface.show(createElement(Picker, { onPick, onCancel: () => settle({ value: null }) }));
+      });
+    },
+  };
+}