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

package/src/runtime/icons.tsx

@@ -0,0 +1,295 @@
+import { useId, type ReactNode } from "react";
+
+function Icon({ children, size = 12 }: { children: ReactNode; size?: number }) {
+  return (
+    <svg
+      className="cs-icon"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      {children}
+    </svg>
+  );
+}
+
+export const AddComment = () => (
+  <Icon size={13}>
+    <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+    <path d="M12 7v6M9 10h6" />
+  </Icon>
+);
+export const Inbox = () => (
+  <Icon size={13}>
+    <polyline points="22 12 16 12 14 15 10 15 8 12 2 12" />
+    <path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
+  </Icon>
+);
+export const Eye = () => (
+  <Icon size={13}>
+    <path d="M2 12s3-7 10-7 10 7 10 7-3 7-10 7-10-7-10-7Z" />
+    <circle cx="12" cy="12" r="3" />
+  </Icon>
+);
+export const EyeOff = () => (
+  <Icon size={13}>
+    <path d="M9.88 9.88a3 3 0 1 0 4.24 4.24" />
+    <path d="M10.73 5.08A10.43 10.43 0 0 1 12 5c7 0 10 7 10 7a13.16 13.16 0 0 1-1.67 2.68" />
+    <path d="M6.61 6.61A13.53 13.53 0 0 0 2 12s3 7 10 7a9.74 9.74 0 0 0 5.39-1.61" />
+    <path d="M2 2l20 20" />
+  </Icon>
+);
+export const Lock = ({ size = 15 }: { size?: number }) => (
+  <Icon size={size}>
+    <rect width="16" height="10" x="4" y="11" rx="2" />
+    <path d="M8 11V7a4 4 0 0 1 8 0v4" />
+  </Icon>
+);
+export const Close = () => (
+  <Icon size={11}>
+    <path d="M18 6 6 18M6 6l12 12" />
+  </Icon>
+);
+export const Send = () => (
+  <Icon size={11}>
+    <path d="m5 12 7-7 7 7M12 19V5" />
+  </Icon>
+);
+export const Check = () => (
+  <Icon size={11}>
+    <polyline points="20 6 9 17 4 12" />
+  </Icon>
+);
+export const Target = () => (
+  <Icon size={11}>
+    <circle cx="12" cy="12" r="8" />
+    <circle cx="12" cy="12" r="2.5" />
+  </Icon>
+);
+export const Relink = () => (
+  <Icon size={11}>
+    <path d="M9 17H7A5 5 0 0 1 7 7h2M15 7h2a5 5 0 1 1 0 10h-2M8 12h8" />
+  </Icon>
+);
+export const Undo = () => (
+  <Icon size={11}>
+    <path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" />
+    <path d="M3 3v5h5" />
+  </Icon>
+);
+export const Pencil = ({ size = 10 }: { size?: number }) => (
+  <Icon size={size}>
+    <path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z" />
+  </Icon>
+);
+export const Scribble = () => (
+  <Icon size={13}>
+    <path d="M4 17c2-6 5-11 7-11 3 0-4 12-1 12 2 0 4-5 6-5 1.5 0 0 4 1.5 4 1 0 2-1 2.5-2" />
+  </Icon>
+);
+export const Cursor = () => (
+  <Icon size={11}>
+    <path d="m4 4 7.07 17 2.51-7.39L21 11.07z" />
+  </Icon>
+);
+export const Paperclip = () => (
+  <Icon size={11}>
+    <path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57A4 4 0 1 1 18 8.84l-8.59 8.57a2 2 0 0 1-2.83-2.83l8.49-8.48" />
+  </Icon>
+);
+export const Record = () => (
+  <Icon size={11}>
+    <circle cx="12" cy="12" r="7" />
+    <circle cx="12" cy="12" r="3" fill="currentColor" stroke="none" />
+  </Icon>
+);
+export const Mic = () => (
+  <Icon size={11}>
+    <rect x="9" y="3" width="6" height="11" rx="3" />
+    <path d="M5 11a7 7 0 0 0 14 0M12 18v3" />
+  </Icon>
+);
+export const Camera = ({ size = 11 }: { size?: number }) => (
+  <Icon size={size}>
+    <path d="M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z" />
+    <circle cx="12" cy="13" r="3" />
+  </Icon>
+);
+export const FileIcon = () => (
+  <Icon size={11}>
+    <path d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z" />
+    <polyline points="14 2 14 8 20 8" />
+  </Icon>
+);
+export const Back = () => (
+  <Icon>
+    <path d="m15 18-6-6 6-6" />
+  </Icon>
+);
+export const Ellipsis = () => (
+  <Icon size={11}>
+    <circle cx="6" cy="12" r="1.25" fill="currentColor" stroke="none" />
+    <circle cx="12" cy="12" r="1.25" fill="currentColor" stroke="none" />
+    <circle cx="18" cy="12" r="1.25" fill="currentColor" stroke="none" />
+  </Icon>
+);
+export const ChevronLeft = () => (
+  <Icon size={14}>
+    <path d="m15 18-6-6 6-6" />
+  </Icon>
+);
+export const ChevronRight = () => (
+  <Icon size={14}>
+    <path d="m9 18 6-6-6-6" />
+  </Icon>
+);
+export const Play = () => (
+  <Icon size={11}>
+    <polygon points="8 5 19 12 8 19" fill="currentColor" stroke="none" />
+  </Icon>
+);
+export const Plane = () => (
+  <Icon size={13}>
+    <path d="m22 2-7 20-4-9-9-4Z" />
+    <path d="M22 2 11 13" />
+  </Icon>
+);
+export const Bubble = () => (
+  <Icon size={14}>
+    <path d="M12 18.2a6.6 6.6 0 1 0-5.7-3.2L4.2 18.4l3.1-1.3A6.6 6.6 0 0 0 12 18.2z" />
+    <circle cx="9.1" cy="11.4" r="0.75" fill="currentColor" stroke="none" />
+    <circle cx="12" cy="11.4" r="0.75" fill="currentColor" stroke="none" />
+    <circle cx="14.9" cy="11.4" r="0.75" fill="currentColor" stroke="none" />
+  </Icon>
+);
+/** A pin that a slash draws through when `hidden`; the slash also cuts a gap in the pin behind it. */
+export function Pins({ hidden }: { hidden: boolean }) {
+  const mask = `cs-pins-${useId().replace(/[^\w-]/g, "")}`;
+  const slash = hidden ? "cs-slash is-on" : "cs-slash";
+  return (
+    <Icon size={13}>
+      <mask id={mask} maskUnits="userSpaceOnUse" x="0" y="0" width="24" height="24">
+        <rect width="24" height="24" fill="#fff" />
+        <path className={slash} d="M3 3l18 18" stroke="#000" strokeWidth={5} />
+      </mask>
+      <g mask={`url(#${mask})`}>
+        <path d="M12 21s-6.5-5.6-6.5-11a6.5 6.5 0 0 1 13 0c0 5.4-6.5 11-6.5 11z" />
+        <circle cx="12" cy="10" r="2.4" />
+      </g>
+      <path className={slash} d="M3 3l18 18" />
+    </Icon>
+  );
+}
+export const User = () => (
+  <Icon size={12}>
+    <circle cx="12" cy="8" r="3.75" />
+    <path d="M4.5 20a7.5 7.5 0 0 1 15 0" />
+  </Icon>
+);
+export const Gear = () => (
+  <Icon size={12}>
+    <circle cx="12" cy="12" r="3" />
+    <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" />
+  </Icon>
+);
+export const Copy = () => (
+  <Icon size={11}>
+    <rect x="9" y="9" width="11" height="11" rx="2" />
+    <path d="M5 15V6a2 2 0 0 1 2-2h9" />
+  </Icon>
+);
+export const Clock = () => (
+  <Icon size={12}>
+    <circle cx="12" cy="12" r="8" />
+    <path d="M12 8v4.5l3 2" />
+  </Icon>
+);
+export const Board = () => (
+  <Icon size={12}>
+    <rect x="3" y="3" width="7.5" height="7.5" rx="1.5" />
+    <rect x="13.5" y="3" width="7.5" height="4.5" rx="1.5" />
+    <rect x="13.5" y="10.5" width="7.5" height="10.5" rx="1.5" />
+    <rect x="3" y="13.5" width="7.5" height="7.5" rx="1.5" />
+  </Icon>
+);
+export const ChevronDown = () => (
+  <Icon size={11}>
+    <path d="m6 9 6 6 6-6" />
+  </Icon>
+);
+export const Search = () => (
+  <Icon size={11}>
+    <circle cx="11" cy="11" r="6" />
+    <path d="m20 20-3.2-3.2" />
+  </Icon>
+);
+export const ZoomOut = () => (
+  <Icon size={11}>
+    <circle cx="11" cy="11" r="6.5" />
+    <path d="m16 16 4.5 4.5M8.5 11h5" />
+  </Icon>
+);
+export const ZoomIn = () => (
+  <Icon size={11}>
+    <circle cx="11" cy="11" r="6.5" />
+    <path d="m16 16 4.5 4.5M11 8.5v5M8.5 11h5" />
+  </Icon>
+);
+export const Reply = () => (
+  <Icon size={11}>
+    <path d="M9 13 4 8.5 9 4" />
+    <path d="M4 8.5h8.5a4.5 4.5 0 0 1 0 9H12" />
+  </Icon>
+);
+export const Markup = () => (
+  <Icon size={12}>
+    <path d="M15.5 3.5a2.1 2.1 0 0 1 3 3l-8.6 8.6-4 1 1-4Z" />
+    <path d="M3 21c1.7-2.6 3.4-3.4 5.1-2.8 1.5.6 2.8.4 4-1.2" />
+  </Icon>
+);
+export const Highlighter = () => (
+  <Icon size={12}>
+    <path d="M9 14 4.5 9.5a1.5 1.5 0 0 1 0-2.1l5-5a1.5 1.5 0 0 1 2.1 0L16 6.8z" />
+    <path d="m9 14 3.5 3.5M3 21h7" />
+    <path d="m15.5 8 3.6 3.6-6.4 6.4H8.4z" />
+  </Icon>
+);
+export const ArrowTool = () => (
+  <Icon size={12}>
+    <path d="M4 20 20 4" />
+    <path d="M20 4h-6.5M20 4v6.5" />
+  </Icon>
+);
+export const Square = () => (
+  <Icon size={12}>
+    <rect x="3.5" y="3.5" width="17" height="17" rx="2.5" />
+  </Icon>
+);
+export const Circle = () => (
+  <Icon size={12}>
+    <circle cx="12" cy="12" r="8.5" />
+  </Icon>
+);
+export const TextTool = () => (
+  <Icon size={12}>
+    <path d="M5 5h14M12 5v14M8.5 19h7" />
+  </Icon>
+);
+export const Redo = () => (
+  <Icon size={11}>
+    <path d="M21 12a9 9 0 1 1-9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" />
+    <path d="M21 3v5h-5" />
+  </Icon>
+);
+export const Trash = () => (
+  <Icon size={11}>
+    <path d="M4 7h16M10 4h4M6 7l1 13h10l1-13" />
+    <path d="M10 11v6M14 11v6" />
+  </Icon>
+);

package/src/runtime/idle.ts

@@ -0,0 +1,20 @@
+export type IdleDeadline = { didTimeout: boolean; timeRemaining(): number };
+
+/** How long a fallback idle slice may run where the browser has no requestIdleCallback (Safari). */
+const FALLBACK_SLICE_MS = 8;
+
+/** Runs `task` when the browser is next idle, or after `timeout` ms at the latest. Returns a cancel function. */
+export function whenIdle(task: (deadline: IdleDeadline) => void, timeout: number): () => void {
+  if (typeof requestIdleCallback === "function") {
+    const id = requestIdleCallback(task, { timeout });
+    return () => cancelIdleCallback(id);
+  }
+  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);
+}

package/src/runtime/index.ts

@@ -0,0 +1,11 @@
+"use client";
+
+export { CommentToolbar } from "./loader.js";
+export type { ToolbarPosition, ToolbarProps, ToolbarTheme } from "./toolbar.js";
+export { queryCacheSummary, reportToolbarError } from "./debug-context-host.js";
+export type {
+  DebugContextConfig,
+  DebugContextOptions,
+  DebugSignal,
+  HostContext,
+} from "./debug-context-model.js";

package/src/runtime/ink.ts

@@ -0,0 +1,6 @@
+/** A point in px, and the toolbar's ink colours. DOM-free; shared by sketches and markup. */
+export type Point = { x: number; y: number };
+
+/** Ink colour, and the halo under it that keeps a stroke readable on dark and busy pages. */
+export const INK = "#ff3b30";
+export const INK_HALO = "rgba(255, 255, 255, 0.85)";

package/src/runtime/kind-model.ts

@@ -0,0 +1,20 @@
+/**
+ * What kind of report a new comment is, when the person says: `POST /v1/threads` takes it as `kind`. Left
+ * unsaid, nothing is sent and the service decides with the title. DOM-free.
+ *
+ * The kinds mirror `ClarityKind` in `packages/contract/src/clarity.ts`; the toolbar bundle does not import the
+ * contract package. `tests/kind-composer.spec.tsx` holds the two in step.
+ */
+
+export type ReportKind = "bug" | "feedback" | "discussion";
+
+export const REPORT_KINDS: readonly { readonly kind: ReportKind; readonly label: string }[] = [
+  { kind: "bug", label: "Bug" },
+  { kind: "feedback", label: "Feedback" },
+  { kind: "discussion", label: "Discussion" },
+];
+
+/** `value` as a kind, or null: a stored draft holds whatever an older or newer build wrote. */
+export function readReportKind(value: unknown): ReportKind | null {
+  return REPORT_KINDS.some((item) => item.kind === value) ? (value as ReportKind) : null;
+}

package/src/runtime/live-model.ts

@@ -0,0 +1,32 @@
+/**
+ * The live socket's protocol and timing, shared by the web toolbar's `useThreadsSync` (`./sync.ts`) and native
+ * clients: what a message means, the keepalive, the push batch, and the reconnect backoff. DOM-free.
+ */
+export type LiveMessage = { type: "changed" } | { type: "build"; build: string } | { type: "pong" };
+
+/**
+ * What the worker sent over the live socket: "changed" (threads moved; also anything unrecognised, so an older
+ * worker's pushes still refresh), a build announcement, or the keepalive answer.
+ */
+export function parseLiveMessage(data: unknown): LiveMessage {
+  if (data === "pong") return { type: "pong" };
+  if (typeof data === "string" && data.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(data) as { type?: unknown; build?: unknown };
+      if (parsed.type === "build" && typeof parsed.build === "string" && parsed.build)
+        return { type: "build", build: parsed.build };
+    } catch {
+      // Not JSON after all: treated as a change below.
+    }
+  }
+  return { type: "changed" };
+}
+
+/** If the live socket hasn't opened by then, fetch anyway instead of waiting on a slow handshake. */
+export const OPEN_WAIT_MS = 2_000;
+/** After this many handshakes in a row that never opened (a CSP block, say), retry only every RETRY_LATER_MS. */
+export const MAX_QUICK_RETRIES = 4;
+export const RETRY_LATER_MS = 5 * 60_000;
+export const KEEPALIVE_MS = 25_000;
+/** Pushes that arrive together cause one refetch. */
+export const PUSH_BATCH_MS = 120;

package/src/runtime/loader.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useRef } from "react";
+import { bootToolbar } from "./boot.js";
+import { captureHandoff } from "./handoff.js";
+import { watchHost } from "./host-watch.js";
+import type { RuntimeProps, ToolbarHandle } from "./runtime.js";
+import { sessionFor } from "./session.js";
+import type { DebugContextConfig, HostBuild } from "./debug-context-model.js";
+import type { ToolbarProps } from "./toolbar.js";
+
+/** The build the Vite plugin stamped into this bundle (`commentService()`), when it did. */
+declare const __COMMENT_TOOL_HOST_BUILD__: HostBuild | undefined;
+const stampedBuild: HostBuild | undefined =
+  typeof __COMMENT_TOOL_HOST_BUILD__ === "object" ? __COMMENT_TOOL_HOST_BUILD__ : undefined;
+
+/** The host's debug context with the stamped build as its `build`, unless the host gave one. */
+function withStampedBuild(config: DebugContextConfig | undefined): DebugContextConfig | undefined {
+  if (!config || !stampedBuild) return config;
+  const options = config === true ? {} : config;
+  return options.build ? config : { ...options, build: stampedBuild };
+}
+
+captureHandoff();
+
+const now = (task: () => void) => {
+  task();
+  return () => {};
+};
+
+/**
+ * Renders nothing and does nothing during render. Once the page is idle it asks the session route whether
+ * comments are on, and only then loads and mounts the toolbar (`./boot.ts`, which the script-tag loader runs
+ * too). While the toolbar is not on the page the route is asked again when a sign-in may have happened
+ * (`./host-watch.ts`); once it is, the toolbar follows the host's sign-in itself.
+ */
+export function CommentToolbar({
+  sessionPath = "/api/comment-service/session",
+  pollMs,
+  position,
+  theme,
+  navigate,
+  screen,
+  debugContext,
+}: ToolbarProps) {
+  const handle = useRef<ToolbarHandle | null>(null);
+  const navigateRef = useRef(navigate);
+  const propsRef = useRef<RuntimeProps>({});
+
+  useEffect(() => {
+    navigateRef.current = navigate;
+    propsRef.current = {
+      sessionPath,
+      pollMs,
+      position,
+      theme,
+      navigate: navigate ? (href) => navigateRef.current?.(href) : undefined,
+      screen,
+      debugContext: withStampedBuild(debugContext),
+      getSession: sessionFor(sessionPath),
+    };
+    handle.current?.update(propsRef.current);
+  }, [debugContext, navigate, pollMs, position, screen, sessionPath, theme]);
+
+  useEffect(() => {
+    const boot = (refresh: boolean, wait?: typeof now) =>
+      bootToolbar({
+        getSession: () => sessionFor(sessionPath)({ refresh }),
+        props: () => propsRef.current,
+        onMount: (mounted) => {
+          handle.current = mounted;
+        },
+        ...(wait ? { wait } : {}),
+      });
+    let stop = boot(false);
+    const watch = watchHost(() => {
+      if (handle.current) return;
+      stop();
+      stop = boot(true, now);
+    });
+    return () => {
+      watch.stop();
+      handle.current = null;
+      stop();
+    };
+  }, [sessionPath]);
+
+  return null;
+}