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

package/dist/chunks/screenshot-66ARTBGR.js

@@ -0,0 +1,12 @@
+import {
+  captureAround,
+  capturePage,
+  describeCapture,
+  renderViewport
+} from "./chunk-HUM5FQII.js";
+export {
+  captureAround,
+  capturePage,
+  describeCapture,
+  renderViewport
+};

package/dist/react.d.ts

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

package/dist/react.js

@@ -0,0 +1,91 @@
+import {
+  captureHandoff,
+  runtimeVersion,
+  sessionFor,
+  whenIdle
+} from "./chunks/chunk-CSKXLF33.js";
+
+// src/runtime/loader.tsx
+import { useEffect, useRef } from "react";
+var IDLE_TIMEOUT_MS = 3e3;
+captureHandoff();
+var bundled = () => import("./chunks/runtime-JX75TKER.js");
+async function loadRuntime(apiUrl, source) {
+  if (source === "bundled") return bundled();
+  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();
+  }
+}
+function CommentToolbar({
+  source = "latest",
+  sessionPath = "/api/comment-service/session",
+  pollMs,
+  position,
+  theme,
+  navigate
+}) {
+  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)
+  };
+  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, source);
+      if (cancelled) return;
+      container = document.createElement("div");
+      container.setAttribute("data-cs-runtime", source);
+      container.style.display = "contents";
+      document.body.append(container);
+      mounted = runtime.mount(container, props.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, source]);
+  useEffect(() => {
+    handle.current?.update(props.current);
+  }, [pollMs, position, theme, hasNavigate]);
+  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, type ToolbarSource } 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/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 {};