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

package/README.md

@@ -1,20 +1,154 @@
 # @devaccel-labs/app-comments-toolbar
 
-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.
-
-- `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>`.
-- `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.
+The in-app review toolbar of Comment Tool. A reviewer uses it inside a host app to comment on an element, take a
+page snapshot and draw on it, record the screen, dictate, keep drafts and read the threads of the page.
+
+One source tree produces five things:
+
+- **The runtime**: the browser bundle that does all of the above. Host apps never bundle it. They load it from the
+  API worker as `/v1/toolbar/1.js`.
+- **The script-tag loader**: `/v1/toolbar/embed.js`, also served by the API worker. One `<script>` tag in a host's
+  HTML loads the runtime with it, and the host installs nothing.
+- **The capture script**: `/v1/toolbar/capture.js`, also served by the API worker. A host page that has its own
+  place for a screenshot (a support form) adds it when a person asks to capture, and calls
+  `window.CommentToolCapture.screenshot()` or `.pick()`. No session, nothing sent
+  (`docs/handoff/lane-capture-api.md`).
+- **The help pill**: `/v1/toolbar/help.js`, and the panel it opens, `/v1/toolbar/help-panel.js`, also served by
+  the API worker. A host shows it to every signed-in person with `window.CommentToolHelp.mount({ submit, list })`;
+  what a person writes goes to the host's own hooks. No session (`docs/handoff/lane-help-pill.md`).
+- **The npm package**: the same loader as a React component, the session route as a function, a Vite plugin, the
+  pill as a React component and its server route as a function.
+
+## Source
+
+- `src/core`: the anchor model and how an anchor finds its element again (`resolveAnchor`). No DOM.
+- `src/runtime`: the toolbar. `runtime.tsx` is the bundle's entry and exports `mount`. `boot.ts` is how a host page
+  brings the toolbar up (idle wait, session route, import, mount); `loader.tsx`, the host-side `<CommentToolbar>`,
+  and the script-tag loader both run it. `update.ts` and `build-id.ts` are how an open toolbar moves to a new build.
+- `src/embed`: the script-tag loader. `index.ts` is its entry: it reads its own tag and installs
+  `window.CommentTool`. `options.ts` checks the tag's `data-` attributes, `controller.ts` is `refresh`, `unmount`
+  and `configure`, and the rule about which service the toolbar may come from.
+- `src/capture`: the capture script. `index.ts` is its entry and installs `window.CommentToolCapture`; `api.ts` is
+  `screenshot` and `pick`; `editor.tsx` and `picker.tsx` put the toolbar's own drawing editor and element outline
+  in a root of the toolbar's kind (`surface.tsx`); `ignore.ts` is what a picture leaves out. It imports from
+  `src/runtime` and changes nothing there.
+- `src/help`: the help pill. `index.ts` is the entry of `help.js` and installs `window.CommentToolHelp`; `pill.ts`
+  is the pill and what it loads when; `panel.ts` (entry `panel-index.ts`, served as `help-panel.js`) is the panel,
+  in plain DOM; `requests.ts` is `supportRequestsAt`; `react.tsx` is `<HelpPill>`; `wire.ts` is the request as it
+  travels to the host's route. `help.js` imports nothing outside this folder.
+- `src/compiler`, `src/vite`: the Vite plugin that stamps components with `data-cs-cmp` and `data-cs-file`.
+- `src/server`: the same-origin session route (`index.ts`) and the help pill's route (`support.ts`).
+- `src/native-wire.ts`, `src/native.ts`, `src/dictation.ts`, `src/replay.ts`: DOM-free code shared with native
+  clients and with the API worker. These four ship as TypeScript source and are not built into `dist`.
+- `tests`: the unit specs.
+
+## How the runtime ships
+
+`bun run build:toolbar`, from the repository root, runs `scripts/build-toolbar.mjs`. It writes seven things to
+`apps/api/toolbar-dist/v1/toolbar/`: the bundle `1.js`, the `chunks/` it loads on demand, `build.json`, the
+loader `embed.js`, the capture script `capture.js`, and the help pill's `help.js` and `help-panel.js`. That
+directory is build output and is not checked in.
+`--outdir <dir>` writes somewhere else.
+
+`embed.js` is one classic script of about 6 KB with no dependencies; the build fails if an import ever pulls one
+in. It carries no build id. The worker serves every file here with `cache-control: no-cache`, so a page asks for
+the loader again on each load and gets the new one after a deploy. `src/embed` is not part of the runtime's build
+id, so a change to the loader alone does not make open toolbars remount.
+
+`capture.js` is one classic script too, of about 368 KB (103 KB gzipped): it carries React and the drawing editor,
+so a host loads it on demand and never on every page. The build fails if it ever bundles the toolbar itself or its
+session, storage or service code. `src/capture` is not part of the runtime's build id either.
+
+`help.js` is one classic script of about 10 KB (4 KB gzipped): the pill and nothing else, because every signed-in
+person of a host loads it on every page. The build fails if it bundles anything outside `src/help`. It fetches
+`help-panel.js` (about 25 KB, 8 KB gzipped, plain DOM with no React) and `capture.js` from beside itself the first
+time the pill is hovered, focused or opened. `src/help` is not part of the runtime's build id, and neither the
+loader nor the runtime names these files.
+
+The API worker serves that directory as static files under `/v1/toolbar/*`.
+
+Every build has a build id: sixteen hex characters hashed from the esbuild version and from every file in
+`src/runtime` and `src/core`. The build writes the id into the bundle and into `build.json`. The same source gives
+the same id on every machine. A change to either directory gives a new one.
+
+An open toolbar moves to a new build by itself. It reads `/v1/toolbar/build.json` when it mounts, when its live
+socket connects or reconnects, when its tab becomes visible, and once a minute. The service can also announce a
+build over the live socket. When the id it reads is not its own, the toolbar imports the new bundle and remounts in
+place. It waits until that cannot lose a draft, a reply, a recording or an edit. A reviewer does not reload the
+page and a host app does not release anything.
+
+The `1` in `1.js` is `runtimeVersion` (`src/runtime/runtime-version.ts`). It is the contract between the loader in
+the npm package and the bundle: the loader asks for `/v1/toolbar/<runtimeVersion>.js` and calls its `mount`. Raise
+it only when `mount` or its props change incompatibly, and keep serving the old file, because installed host
+packages still ask for it.
+
+## The npm package
+
+A host app installs the package for three entry points:
+
+- `@devaccel-labs/app-comments-toolbar/vite`: `commentService()`, a Vite plugin. It stamps each JSX component with
+  its name and file so a comment can find its component again. It runs in the dev server, and in a build that has
+  `COMMENT_SERVICE_URL` configured or `COMMENT_SERVICE_ENABLED=1`.
+- `@devaccel-labs/app-comments-toolbar/server`: `handleSessionRequest(request)`, the route the host serves on its
+  own origin (by default `/api/comment-service/session`). It reads `COMMENT_SERVICE_URL`, `COMMENT_SERVICE_PROJECT`,
+  `COMMENT_SERVICE_ENVIRONMENT`, `COMMENT_SERVICE_SECRET` and the optional `COMMENT_SERVICE_LINKED`, and exchanges
+  the secret for a short-lived host token. The secret stays on the host's server.
+- `@devaccel-labs/app-comments-toolbar/react`: `<CommentToolbar>`. It renders nothing. Once the page is idle it
+  asks the session route whether comments are on, then imports the runtime from the API worker and mounts it.
+  Its `debugContext` prop turns on the debug context file each new comment carries; `reportToolbarError` and
+  `queryCacheSummary` feed it (`docs/integration/debug-context.md`). The Vite plugin stamps the build's commit
+  and version for it.
+
+`./debug-context` (source only, like `./replay`) reads a context file back safely (`sanitizeDebugContext`) and
+renders the agent brief (`debugContextBrief`), for the service, the console and destinations.
+
+Two of those entry points also carry the help pill (`docs/handoff/lane-help-pill.md`):
+
+- `/react`: `<HelpPill submit={…} list={…} serviceUrl={…} />`, which adds `help.js` once the page is idle and
+  mounts the pill it defines, and `supportRequestsAt(url)`, the two hooks for a host whose route is the helper
+  below.
+- `/server`: `handleSupportRequest(request, { serviceUrl, connectionToken, project, reporter, account })`, for a
+  host with no tracker of its own. The host calls it after its own sign-in check. `POST` files the request in
+  Comment Tool with the integration API's `fileReport`; `GET` answers the person's own requests from `reportsBy`.
+  A request the team merged into one it already had is answered as `consolidated`, with that one's status, and
+  the pill tells the person so.
+
+A host does not need the package for the first two of these: `embed.js` is the loader, and the integration guide
+gives the session route as code to copy (`docs/integration/session-route.md`). `tests/no-package-session.spec.ts`
+keeps that code answering exactly what `handleSessionRequest` answers. Only the Vite plugin has no other form.
+
+The package contains no runtime, so it changes only when `runtimeVersion` or one of these three pieces changes.
+`/v1` responses and the runtime's storage keys have to stay compatible with every package version a host has
+installed.
+
+The session route binds a host token to an origin it works out itself. For a browser that is the origin the host is
+served on (`x-forwarded-host` and `x-forwarded-proto`, then `Host`, then the request URL). The `Origin` header a
+caller sends is not used. A native app sends no `Origin` and declares `<scheme>://app` in
+`x-comment-service-origin`; only a value of that shape is read from that header.
+
+`bun run build` in this directory writes `dist/`: `react.js`, `vite.js`, `server.js`, a `.d.ts` file for each, and
+`dist/types/`. The published package is `dist`, `src` and this file. It is published by hand with `npm publish`
+from this directory.
+
+## Commands
+
+From the repository root:
+
+| Command                                    | What it does                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `bun run --cwd packages/toolbar typecheck` | Type-checks `src` under `tsconfig.json`, then the specs under `tests/tsconfig.json`. |
+| `bun run test --project toolbar`           | Runs the unit specs in `tests/` with Vitest.                                         |
+| `bun run build:toolbar`                    | Builds the runtime into `apps/api/toolbar-dist/v1/toolbar/`.                         |
+| `bun run --cwd packages/toolbar build`     | Builds the npm package into `packages/toolbar/dist/`.                                |
+
+`tsconfig.json` keeps three compiler checks off that `tsconfig.base.json` turns on. The runtime was written
+without them, and turning them on is separate work.
+
+A spec runs in Node unless its first line asks for jsdom. Three specs also import the API worker's half of a shared
+format from `apps/api/src/v1`: `sketch.spec.ts`, `dictation.spec.ts` and `native-wire.spec.ts`. `dist.spec.ts`
+runs a real runtime build into a temporary directory. `no-package-session.spec.ts` imports the guide's copy-paste
+session route from `docs/integration/examples` and runs its Python version in `python3`, which must be on the
+PATH.
+
+The help pill's specs are `help-*.spec.ts(x)`. `fake-comment-tool.ts` is a stand-in for the integration API's
+`fileReport` and `reportsBy`; it imports no test runner, because the browser suite's host server uses it too.