@devaccel-labs/app-comments-toolbar 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @devaccel-labs/app-comments-toolbar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 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, 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`.
+- Tests: `tests/unit/app-comments-toolbar-*.spec.ts`.
+
+## 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.d.ts

@@ -0,0 +1 @@
+export * from "./types/react.js";

package/dist/react.js

@@ -0,0 +1,193 @@
+// 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();
+async function loadRuntime(apiUrl) {
+  const url = `${apiUrl.replace(/\/+$/, "")}/v1/toolbar/${runtimeVersion}.js`;
+  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({
+  sessionPath = "/api/comment-service/session",
+  pollMs,
+  position,
+  theme,
+  navigate
+}) {
+  const handle = useRef(null);
+  const navigateRef = useRef(navigate);
+  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;
+    let container = null;
+    const start = async () => {
+      const session = await sessionFor(sessionPath)().catch(() => null);
+      if (!session || cancelled) return;
+      const runtime = await loadRuntime(session.apiUrl);
+      if (cancelled) return;
+      container = document.createElement("div");
+      container.setAttribute("data-cs-runtime", "latest");
+      container.style.display = "contents";
+      document.body.append(container);
+      mounted = runtime.mount(container, propsRef.current);
+      handle.current = mounted;
+    };
+    const cancelIdle = whenIdle(() => {
+      start().catch(
+        (error) => console.warn("[comment-service] The toolbar could not start.", error)
+      );
+    }, IDLE_TIMEOUT_MS);
+    return () => {
+      cancelled = true;
+      cancelIdle();
+      handle.current = null;
+      queueMicrotask(() => {
+        mounted?.unmount();
+        container?.remove();
+      });
+    };
+  }, [sessionPath]);
+  return null;
+}
+export {
+  CommentToolbar
+};

package/dist/server.d.ts

@@ -0,0 +1 @@
+export * from "./types/server.js";

package/dist/server.js

@@ -0,0 +1,87 @@
+// src/server/index.ts
+function readCommentServiceConfig(env = process.env) {
+  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 };
+}
+function declaredOrigin(request) {
+  const value = request.headers.get("origin") ?? request.headers.get("x-comment-service-origin");
+  if (!value) return null;
+  try {
+    const origin = new URL(value).origin;
+    return origin === "null" ? null : origin;
+  } catch {
+    return null;
+  }
+}
+function requestOrigin(request) {
+  const declared = declaredOrigin(request);
+  if (declared) return declared;
+  const url = new URL(request.url);
+  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("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}`;
+}
+async function handleSessionRequest(request, config = readCommentServiceConfig()) {
+  const headers = { "cache-control": "no-store" };
+  if (!config) return Response.json({ enabled: false }, { headers });
+  const origin = requestOrigin(request);
+  let 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 payload2 = await response.json().catch(() => null);
+    return Response.json(
+      {
+        enabled: false,
+        error: payload2?.error?.message ?? "Comment service rejected this environment.",
+        origin,
+        status: response.status
+      },
+      { status: 502, headers }
+    );
+  }
+  const payload = await response.json();
+  if (payload.unknownLinked?.length) {
+    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 }
+  );
+}
+export {
+  handleSessionRequest,
+  readCommentServiceConfig
+};

package/dist/types/compiler/annotate.d.ts

@@ -0,0 +1,10 @@
+export declare function toProjectPath(filename: string, root: string): string;
+/**
+ * Stamp the root node of each component of each component with a stable file + component name.
+ * Line numbers are intentionally not included: moving the component in the file
+ * or on the page must not change the stamp. A root that is itself a component
+ * (`<DropdownMenu>`, `<Menu.Root>`) gets the stamp as a prop: it reaches the DOM when
+ * the component spreads its props, and the toolbar reads it from React's tree when
+ * the component renders into a portal.
+ */
+export declare function annotateSource(code: string, filename: string, root: string): string;

package/dist/types/compiler/enabled.d.ts

@@ -0,0 +1,14 @@
+/** A host app that serves the toolbar sets this, in its env files, its Wrangler `vars`, or the build's environment. */
+export declare const CONFIG_KEY = "COMMENT_SERVICE_URL";
+/**
+ * Whether to stamp components. An explicit option or COMMENT_SERVICE_ENABLED wins; otherwise the dev server always
+ * stamps, and a build stamps only when it can see comment-service configuration.
+ */
+export declare function stampingEnabled({ option, flag, command, configured, }: {
+    option: boolean | undefined;
+    flag: string | undefined;
+    command: "build" | "serve";
+    configured: () => boolean;
+}): boolean;
+/** Comment-service configuration a build can see: its environment, Vite env files for the mode, or Wrangler config. */
+export declare function buildConfigured(root: string, mode: string, env?: Record<string, string | undefined>): boolean;

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

@@ -0,0 +1,2 @@
+export { annotateSource, toProjectPath } from "./annotate.js";
+export { CONFIG_KEY, buildConfigured, stampingEnabled } from "./enabled.js";

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

@@ -0,0 +1,2 @@
+export { describeAnchor, dropAncestors, resolveAnchor, validateAnchor } from "./resolve.js";
+export type { Anchor, Candidate, Resolution, ResolutionStatus } from "./types.js";

package/dist/types/core/resolve.d.ts

@@ -0,0 +1,29 @@
+import type { Anchor, Candidate, Resolution } from "./types.js";
+/**
+ * Drop elements that contain another match, so a wrapping div doesn't steal the button.
+ *
+ * Sorted by path, an element's descendants ("0/1/…") come directly after it: "/" sorts before every digit, so
+ * nothing else can sit between "0/1" and "0/1/4". One pass over the sorted list finds every ancestor, instead of
+ * comparing every pair; a page section with thousands of elements used to take seconds here.
+ */
+export declare function dropAncestors(candidates: Candidate[]): Candidate[];
+/**
+ * Resolve a stored anchor against the elements currently on the route.
+ *
+ * Order is deliberate:
+ * 1. An explicit id (`data-cs-anchor`, `data-testid`, stable `id`) wins.
+ * 2. Otherwise the match is component file + component name + role + label.
+ * 3. Sibling index and pixel position are ignored, so inserting, reordering,
+ *    or moving the element (including out of a sheet) does not retarget the comment.
+ * 4. A tie is ambiguous. We do not fall back to "the first one" or the old index.
+ * 5. A unique component whose label changed is "drifted": still shown, marked uncertain.
+ * 6. A match that exists but is inside a closed dialog is "hidden", not deleted.
+ * 7. No match is "unavailable". The thread stays in the inbox.
+ *
+ * `candidates` may be a targeted subset of the page, as long as it holds every element with one of the anchor's
+ * explicit ids and every element owned by a component of the anchor's name. The drift check looks at everything
+ * inside the component's root, so such callers pass `inside` to supply those candidates on demand.
+ */
+export declare function resolveAnchor(anchor: Anchor, candidates: Candidate[], inside?: (root: Candidate) => Candidate[]): Resolution;
+export declare function describeAnchor(anchor: Anchor): string;
+export declare function validateAnchor(input: unknown): Anchor | null;

package/dist/types/core/types.d.ts

@@ -0,0 +1,65 @@
+/** Stable identity for a commented element. Pixel and DOM-index position are not part of the match. */
+export type Anchor = {
+    v: 1;
+    /** Pathname only, no query or hash. */
+    route: string;
+    /**
+     * Dialog or sheet the element lived in when the comment was written.
+     * Used to explain a hidden thread. Not required to match after the element moves out of the overlay.
+     */
+    overlay: {
+        role: string;
+        name: string;
+    } | null;
+    /** Opt-in stable ids: data-cs-anchor, data-testid, or a human id. Highest priority. */
+    explicit: Array<{
+        attr: string;
+        value: string;
+    }>;
+    /** React component that owns the element. File path is relative and has no line number. */
+    component: {
+        name: string;
+        file: string | null;
+    } | null;
+    /** Component names from the tree, outer to inner. Diagnostic. */
+    stack: string[];
+    role: string | null;
+    accName: string | null;
+    text: string | null;
+    tag: string;
+    /** Sibling path inside the component. Stored for agents, never used to choose a match. */
+    intra: string | null;
+};
+export type Candidate = {
+    key: string;
+    route: string;
+    visible: boolean;
+    /** Index path from the document body. Used only to tell ancestors from descendants. */
+    path: string;
+    componentRoot: boolean;
+    overlay: {
+        role: string;
+        name: string;
+    } | null;
+    explicit: Array<{
+        attr: string;
+        value: string;
+    }>;
+    component: {
+        name: string;
+        file: string | null;
+    } | null;
+    stack: string[];
+    role: string | null;
+    accName: string | null;
+    text: string | null;
+    tag: string;
+    intra: string | null;
+};
+export type ResolutionStatus = "pinned" | "drifted" | "hidden" | "ambiguous" | "unavailable";
+export type Resolution = {
+    status: ResolutionStatus;
+    key: string | null;
+    score: number;
+    reason: string;
+};

package/dist/types/react.d.ts

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

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

@@ -0,0 +1,73 @@
+import { type ClipboardEvent } from "react";
+import { type Attachment, type Capture } from "./client.js";
+import type { Session } from "./session.js";
+export type Pending = {
+    key: string;
+    name: string;
+    size: number;
+    contentType: string;
+    preview: string | null;
+    status: "uploading" | "ready" | "failed";
+    id?: string;
+    error?: string;
+    capture?: Capture;
+};
+export declare function formatSize(bytes: number): string;
+/** Files attached to one draft. Each upload starts immediately so posting doesn't wait on the network. */
+export declare function useAttachments(session: Session | null, memberToken: string | null, onError: (message: string) => void, environment?: string): {
+    items: Pending[];
+    add: (files: Array<{
+        blob: Blob;
+        name: string;
+        capture?: Capture;
+    }>) => void;
+    remove: (key: string) => void;
+    reset: () => void;
+    ids: string[];
+    uploading: boolean;
+};
+export declare function filesFromClipboard(event: ClipboardEvent): {
+    blob: Blob;
+    name: string;
+}[];
+export type PreviewFile = {
+    id: string;
+    name: string;
+    contentType: string;
+    url: string;
+    capture?: Capture;
+};
+/** Images, videos, and replays waiting in a draft, in tray order, for the preview beside the composer. */
+export declare function pendingPreviews(items: Pending[]): PreviewFile[];
+export declare function AttachmentTray({ items, activeKey, onPreview, onRemove, }: {
+    items: Pending[];
+    activeKey?: string | null;
+    onPreview?: (item: Pending) => void;
+    onRemove: (key: string) => void;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function AttachButtons({ onFiles, onSnapshot, onRecord, onReplay, capturing, }: {
+    onFiles: (files: Array<{
+        blob: Blob;
+        name: string;
+    }>) => void;
+    onSnapshot: () => void;
+    onRecord: () => void;
+    onReplay: (() => void) | null;
+    capturing: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+/** Images, videos, and replays in the order a thread shows them, so preview arrows follow the thread. */
+export declare function visualAttachments(messages: Array<{
+    attachments?: Attachment[];
+}> | undefined): Attachment[];
+export declare function MessageAttachments({ attachments, activeId, onPreview, }: {
+    attachments?: Attachment[];
+    activeId?: string | null;
+    onPreview: (file: Attachment) => void;
+}): import("react/jsx-runtime").JSX.Element | null;
+/** The image, video, or replay open beside a thread. Arrows walk the thread's other previewable files. */
+export declare function MediaPane({ files, fileId, onSelect, onClose, }: {
+    files: PreviewFile[];
+    fileId: string;
+    onSelect: (fileId: string) => void;
+    onClose: () => void;
+}): import("react/jsx-runtime").JSX.Element | null;

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/capture-ui.d.ts

@@ -0,0 +1,35 @@
+import type { Capture } from "./client.js";
+type AddFiles = (files: Array<{
+    blob: Blob;
+    name: string;
+    capture?: Capture;
+}>) => void;
+/** Records the current tab, then asks before the file is attached. Nothing is uploaded here. */
+export declare function useTabRecording(onError: (message: string) => void): {
+    phase: "idle" | "recording" | "review";
+    elapsed: number;
+    review: {
+        url: string;
+        blob: Blob;
+    } | null;
+    tooBig: boolean;
+    begin: (add: AddFiles) => Promise<void>;
+    stop: () => void | undefined;
+    cancel: () => void;
+    keep: () => void;
+    again: () => void;
+};
+export declare function RecordChrome({ phase, elapsed, review, tooBig, onStop, onCancel, onKeep, onAgain, }: {
+    phase: "recording" | "review";
+    elapsed: number;
+    review: {
+        url: string;
+        blob: Blob;
+    } | null;
+    tooBig: boolean;
+    onStop: () => void;
+    onCancel: () => void;
+    onKeep: () => void;
+    onAgain: () => void;
+}): import("react/jsx-runtime").JSX.Element | null;
+export {};

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

@@ -0,0 +1,30 @@
+import type { Anchor, Candidate, Resolution } from "../core/index.js";
+type Owned = {
+    component: {
+        name: string;
+        file: string | null;
+    } | null;
+    stack: string[];
+    componentRoot: boolean;
+    owner: Element | null;
+};
+/** Each field is computed when first read, so a resolve only pays for what the match looks at. */
+export declare function candidateFromElement(element: Element, route: string, key: string, owned?: Owned, pathOf?: (element: Element) => string): Candidate;
+export declare function captureAnchor(element: Element, route?: string): Anchor;
+export type Resolved = {
+    resolution: Resolution;
+    element: Element | null;
+};
+/**
+ * Resolves anchors against the page as it is now, building candidates only for the elements that can decide the
+ * result: those carrying one of the anchor's explicit ids, those owned by a component of the anchor's name, and,
+ * when the label changed, those inside that component's root. Never walks the whole page for a stamped anchor.
+ * Reuse one resolver for anchors resolved together; make a new one once the page may have changed.
+ */
+export declare function createResolver(route?: string): {
+    resolve(anchor: Anchor): Resolved;
+};
+export declare function resolveInDocument(anchor: Anchor, route?: string): Resolved;
+export declare function elementAt(x: number, y: number): Element | null;
+export declare function describeElement(element: Element): string;
+export {};