@grackle-ai/web-components 0.107.2

package/src/utils/eventContent.ts

@@ -0,0 +1,209 @@
+/**
+ * Utilities for classifying session events and formatting them for clipboard copy.
+ *
+ * Pure functions with no React or DOM dependencies.
+ *
+ * @module
+ */
+
+import type { SessionEvent } from "../hooks/types.js";
+import type { DisplayEvent } from "./sessionEvents.js";
+
+/** Event types that carry meaningful, copyable content. */
+const CONTENT_BEARING_TYPES: ReadonlySet<string> = new Set([
+  "text",
+  "output",
+  "user_input",
+  "tool_use",
+  "tool_result",
+  "error",
+]);
+
+/**
+ * Returns true when an event's type represents copyable content.
+ *
+ * Content-bearing: text, output, user_input, tool_use, tool_result, error.
+ * Non-content: status, signal, usage, system, and anything else.
+ */
+export function isContentBearingEvent(event: SessionEvent): boolean {
+  return CONTENT_BEARING_TYPES.has(event.eventType);
+}
+
+/**
+ * Extracts the raw text that should be placed on the clipboard when a single
+ * event is copied via the hover action row.
+ *
+ * This returns the plain content without labels or timestamps — it mirrors
+ * what the old per-event CopyButton provided.
+ */
+export function getEventCopyText(event: DisplayEvent): string {
+  switch (event.eventType) {
+    case "tool_result": {
+      // Prefer detailedResult when available (e.g. Copilot unified diffs)
+      if (event.toolUseCtx?.detailedResult) {
+        return event.toolUseCtx.detailedResult;
+      }
+      // When paired, the result content may be JSON-wrapped. Extract the
+      // displayable content the same way EventRenderer does.
+      let resultContent = event.content;
+      if (event.content.trimStart().startsWith("{")) {
+        try {
+          const parsed = JSON.parse(event.content) as Record<string, unknown>;
+          if (typeof parsed.content === "string") {
+            resultContent = parsed.content;
+          }
+        } catch { /* use as-is */ }
+      }
+      return resultContent;
+    }
+    case "tool_use": {
+      // Show the tool name and args in a readable form
+      try {
+        const parsed = JSON.parse(event.content) as { tool?: string; args?: unknown };
+        const tool = parsed.tool ?? "tool";
+        const args = parsed.args !== undefined ? JSON.stringify(parsed.args, undefined, 2) : "";
+        return `${tool}\n${args}`;
+      } catch {
+        return event.content;
+      }
+    }
+    default:
+      return event.content;
+  }
+}
+
+/** Extracts a one-line args summary for tool events (e.g. file path, command). */
+function toolArgsSummary(args: unknown): string {
+  if (args === null || args === undefined) {
+    return "";
+  }
+  if (typeof args !== "object") {
+    return String(args);
+  }
+  const obj = args as Record<string, unknown>;
+  // Common arg patterns across tool cards
+  if (typeof obj.command === "string") {
+    return `\`${obj.command}\``;
+  }
+  if (typeof obj.file_path === "string" || typeof obj.filePath === "string") {
+    return `\`${(obj.file_path ?? obj.filePath) as string}\``;
+  }
+  if (typeof obj.path === "string") {
+    return `\`${obj.path}\``;
+  }
+  if (typeof obj.query === "string") {
+    return `\`${obj.query}\``;
+  }
+  if (typeof obj.pattern === "string") {
+    return `\`${obj.pattern}\``;
+  }
+  return "";
+}
+
+/**
+ * Formats a list of events as well-structured markdown for clipboard copy.
+ *
+ * Each event gets a label and timestamp header, followed by its content.
+ * Events are separated by blank lines. Non-content-bearing events are skipped.
+ */
+export function formatEventsAsMarkdown(events: DisplayEvent[]): string {
+  const parts: string[] = [];
+
+  for (const event of events) {
+    if (!isContentBearingEvent(event)) {
+      continue;
+    }
+
+    const time = new Date(event.timestamp).toLocaleTimeString();
+
+    switch (event.eventType) {
+      case "text":
+      case "output": {
+        parts.push(`**Assistant** (${time}):\n${event.content}`);
+        break;
+      }
+      case "user_input": {
+        parts.push(`**User** (${time}):\n${event.content}`);
+        break;
+      }
+      case "tool_result": {
+        // Prefer detailedResult (e.g. Copilot unified diffs)
+        let resultContent = event.toolUseCtx?.detailedResult ?? undefined;
+        if (!resultContent) {
+          // Extract displayable content from JSON-wrapped results
+          resultContent = event.content;
+          if (event.content.trimStart().startsWith("{")) {
+            try {
+              const parsed = JSON.parse(event.content) as Record<string, unknown>;
+              if (typeof parsed.content === "string") {
+                resultContent = parsed.content;
+              }
+            } catch { /* use as-is */ }
+          }
+        }
+
+        if (event.toolUseCtx) {
+          const summary = toolArgsSummary(event.toolUseCtx.args);
+          const label = summary
+            ? `**Tool: ${event.toolUseCtx.tool}** ${summary}`
+            : `**Tool: ${event.toolUseCtx.tool}**`;
+          parts.push(`${label} (${time}):\n${resultContent}`);
+        } else {
+          parts.push(`**Tool output** (${time}):\n${resultContent}`);
+        }
+        break;
+      }
+      case "tool_use": {
+        let tool = "tool";
+        let args: unknown;
+        try {
+          const parsed = JSON.parse(event.content) as { tool?: string; args?: unknown };
+          tool = parsed.tool ?? "tool";
+          args = parsed.args;
+        } catch { /* use defaults */ }
+        const summary = toolArgsSummary(args);
+        const label = summary ? `**Tool: ${tool}** ${summary}` : `**Tool: ${tool}**`;
+        if (args !== undefined) {
+          parts.push(`${label} (${time}):\n\`\`\`json\n${JSON.stringify(args, undefined, 2)}\n\`\`\``);
+        } else {
+          parts.push(`${label} (${time}):`);
+        }
+        break;
+      }
+      case "error": {
+        parts.push(`**Error** (${time}):\n${event.content}`);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  return parts.join("\n\n");
+}
+
+/**
+ * Wraps formatted event markdown in a forwarding envelope.
+ *
+ * The envelope identifies the source session and delimits the forwarded
+ * content so the receiving agent can distinguish it from new input.
+ *
+ * @param sourceLabel - A human-readable label for the source (e.g. environment name).
+ * @param events - The events to format and enclose.
+ * @returns The complete envelope string ready to pass to `sendInput`.
+ */
+export function formatForwardEnvelope(sourceLabel: string, events: DisplayEvent[]): string {
+  const safeLabel = sanitizeSourceLabel(sourceLabel);
+  const body = formatEventsAsMarkdown(events);
+  return `--- Forwarded from ${safeLabel} ---\n\n${body}\n\n--- End forwarded ---`;
+}
+
+/**
+ * Ensures a source label is a single line and cannot break envelope delimiters.
+ *
+ * Strips newlines and replaces `---` sequences with an em-dash so the label
+ * cannot be confused with the envelope's own `---` markers.
+ */
+function sanitizeSourceLabel(label: string): string {
+  return label.replace(/[\r\n]+/g, " ").trim().replace(/---/g, "\u2014");
+}

package/src/utils/findingCategory.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared category-to-color mapping for findings.
+ *
+ * Centralized here so FindingsPanel, FindingsNav, and consuming pages
+ * all use the same palette and stay in sync.
+ *
+ * @module
+ */
+
+/** Color pair for a finding category. */
+export interface CategoryColor {
+  /** Foreground / text color (CSS custom property). */
+  text: string;
+  /** Background / badge color (CSS custom property). */
+  bg: string;
+}
+
+/** Category color mapping using CSS custom property values. */
+export const CATEGORY_COLORS: Record<string, CategoryColor> = {
+  architecture: { text: "var(--accent-blue)", bg: "var(--accent-blue-dim)" },
+  api: { text: "var(--accent-green)", bg: "var(--accent-green-dim)" },
+  bug: { text: "var(--accent-red)", bg: "var(--accent-red-dim)" },
+  decision: { text: "var(--accent-yellow)", bg: "var(--accent-yellow-dim)" },
+  dependency: { text: "var(--accent-purple)", bg: "var(--accent-purple-dim)" },
+  pattern: { text: "var(--accent-cyan)", bg: "var(--accent-cyan-dim)" },
+  general: { text: "var(--text-secondary)", bg: "var(--bg-elevated)" },
+};
+
+/** Look up the color pair for a category, falling back to `general`. */
+export function getCategoryColor(category: string): CategoryColor {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- category may not be in the map
+  return CATEGORY_COLORS[category] || CATEGORY_COLORS.general;
+}

package/src/utils/format.ts

@@ -0,0 +1,27 @@
+/** Format a token count in compact notation (e.g. 1952 → "2.0k", 1234567 → "1.2M"). */
+export function formatTokens(n: number): string {
+  if (n >= 1_000_000) {
+    return `${(n / 1_000_000).toFixed(1)}M`;
+  }
+  if (n >= 1_000) {
+    const kValue = Number((n / 1_000).toFixed(1));
+    if (kValue >= 1_000) {
+      return `${(n / 1_000_000).toFixed(1)}M`;
+    }
+    return `${kValue.toFixed(1)}k`;
+  }
+  return String(n);
+}
+
+/** Format an integer millicent cost for display (e.g. 500 → "$0.0050", 123000 → "$1.23"). */
+export function formatCost(millicents: number): string {
+  if (millicents === 0) {
+    return "-";
+  }
+  const usd = millicents / 100_000;
+  if (usd < 0.01) {
+    const decimals = millicents < 5 ? 5 : 4;
+    return `$${usd.toFixed(decimals)}`;
+  }
+  return `$${usd.toFixed(2)}`;
+}

package/src/utils/iconSize.ts

@@ -0,0 +1,18 @@
+/**
+ * Standardized icon sizes for lucide-react SVG icons.
+ *
+ * Use these constants instead of magic numbers so that icon sizing
+ * stays consistent across the UI.
+ */
+
+/** Extra-small icon size (8px) — connection dots, status indicators. */
+export const ICON_XS: number = 8;
+
+/** Small icon size (12px) — inline status dots, small indicators, expand chevrons. */
+export const ICON_SM: number = 12;
+
+/** Medium icon size (14px) — tool card icons, close buttons, copy buttons. */
+export const ICON_MD: number = 14;
+
+/** Large icon size (16px) — navigation icons, notification icons. */
+export const ICON_LG: number = 16;

package/src/utils/navigation.ts

@@ -0,0 +1,205 @@
+/**
+ * Centralized URL builder functions and navigation helpers for all application routes.
+ *
+ * Every component that needs to navigate should import from here
+ * instead of hardcoding URL strings.
+ */
+
+import { useCallback } from "react";
+import { useNavigate, type NavigateOptions, type To } from "react-router";
+
+/**
+ * Wrapper around react-router's `useNavigate` that returns a fire-and-forget
+ * navigate function. This avoids lint conflicts between `no-floating-promises`
+ * (which wants the returned `Promise<void> | void` handled) and `no-void`
+ * (which forbids the `void` operator).
+ */
+export function useAppNavigate(): (to: To | number, options?: NavigateOptions) => void {
+  const nav = useNavigate();
+  return useCallback(
+    (to: To | number, options?: NavigateOptions) => {
+      if (typeof to === "number") {
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        nav(to);
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        nav(to, options);
+      }
+    },
+    [nav],
+  );
+}
+
+/** Build URL for a session detail page. */
+export function sessionUrl(sessionId: string): string {
+  return `/sessions/${encodeURIComponent(sessionId)}`;
+}
+
+/** Build URL for a workspace overview page, nested under its environment when available. */
+export function workspaceUrl(workspaceId: string, environmentId?: string): string {
+  if (environmentId) {
+    return `/environments/${encodeURIComponent(environmentId)}/workspaces/${encodeURIComponent(workspaceId)}`;
+  }
+  // Fallback to legacy route so WorkspaceRedirect can resolve the environment.
+  return `/workspaces/${encodeURIComponent(workspaceId)}`;
+}
+
+/** Build URL for a task detail page, optionally targeting a specific tab and workspace/environment scope. */
+export function taskUrl(taskId: string, tab?: "stream" | "findings", workspaceId?: string, environmentId?: string): string {
+  const encodedTaskId = encodeURIComponent(taskId);
+  let base: string;
+  if (workspaceId && environmentId) {
+    base = `/environments/${encodeURIComponent(environmentId)}/workspaces/${encodeURIComponent(workspaceId)}/tasks/${encodedTaskId}`;
+  } else if (workspaceId) {
+    // Fallback to legacy route so WorkspaceRedirect can resolve the environment.
+    base = `/workspaces/${encodeURIComponent(workspaceId)}/tasks/${encodedTaskId}`;
+  } else {
+    base = `/tasks/${encodedTaskId}`;
+  }
+  if (tab) {
+    return `${base}/${tab}`;
+  }
+  return base;
+}
+
+/** Build URL for the task edit page. */
+export function taskEditUrl(taskId: string, workspaceId?: string, environmentId?: string): string {
+  if (workspaceId && environmentId) {
+    return `/environments/${encodeURIComponent(environmentId)}/workspaces/${encodeURIComponent(workspaceId)}/tasks/${encodeURIComponent(taskId)}/edit`;
+  }
+  if (workspaceId) {
+    // Fallback to legacy route so WorkspaceRedirect can resolve the environment.
+    return `/workspaces/${encodeURIComponent(workspaceId)}/tasks/${encodeURIComponent(taskId)}/edit`;
+  }
+  return `/tasks/${encodeURIComponent(taskId)}/edit`;
+}
+
+/** Build URL for the new task form. */
+export function newTaskUrl(workspaceId?: string, parentTaskId?: string, environmentId?: string): string {
+  const params = new URLSearchParams();
+  if (workspaceId) {
+    params.set("workspace", workspaceId);
+  }
+  if (parentTaskId) {
+    params.set("parent", parentTaskId);
+  }
+  const qs = params.toString();
+  if (workspaceId && environmentId) {
+    const base = `/environments/${encodeURIComponent(environmentId)}/workspaces/${encodeURIComponent(workspaceId)}/tasks/new`;
+    return parentTaskId ? `${base}?parent=${encodeURIComponent(parentTaskId)}` : base;
+  }
+  return qs ? `/tasks/new?${qs}` : "/tasks/new";
+}
+
+/** Build URL for the new chat form. */
+export function newChatUrl(environmentId: string): string {
+  const params = new URLSearchParams({ env: environmentId });
+  return `/sessions/new?${params.toString()}`;
+}
+
+/** URL for the environments landing page. */
+export const ENVIRONMENTS_URL: string = "/environments";
+
+/** URL for the new environment form. */
+export const NEW_ENVIRONMENT_URL: string = "/environments/new";
+
+/** Build URL for an environment detail page. */
+export function environmentUrl(environmentId: string): string {
+  return `/environments/${encodeURIComponent(environmentId)}`;
+}
+
+/** Build URL for the environment edit page. */
+export function environmentEditUrl(environmentId: string): string {
+  return `/environments/${encodeURIComponent(environmentId)}/edit`;
+}
+
+/** URL for the settings page. */
+export const SETTINGS_URL: string = "/settings";
+
+/** URL for the settings environments tab. */
+export const SETTINGS_ENVIRONMENTS_URL: string = "/settings/environments";
+
+/** URL for the settings credentials tab. */
+export const SETTINGS_CREDENTIALS_URL: string = "/settings/credentials";
+
+/** URL for the persona management tab. */
+export const PERSONAS_URL: string = "/settings/personas";
+
+/** URL for the new persona form. */
+export const NEW_PERSONA_URL: string = "/settings/personas/new";
+
+/** Build URL for a persona detail page. */
+export function personaUrl(personaId: string): string {
+  return `/settings/personas/${encodeURIComponent(personaId)}`;
+}
+
+/** URL for the schedule management tab. */
+export const SCHEDULES_URL: string = "/settings/schedules";
+
+/** URL for the new schedule form. */
+export const NEW_SCHEDULE_URL: string = "/settings/schedules/new";
+
+/** Build URL for a schedule detail page. */
+export function scheduleUrl(scheduleId: string): string {
+  return `/settings/schedules/${encodeURIComponent(scheduleId)}`;
+}
+
+/** URL for the settings appearance tab. */
+export const SETTINGS_APPEARANCE_URL: string = "/settings/appearance";
+
+/** URL for the settings about tab. */
+export const SETTINGS_ABOUT_URL: string = "/settings/about";
+
+/** URL for the keyboard shortcuts reference tab. */
+export const SETTINGS_SHORTCUTS_URL: string = "/settings/shortcuts";
+
+/** URL for the device pairing page. */
+export const PAIR_PATH: string = "/pair";
+
+/** URL for the root-task chat page. */
+export const CHAT_URL: string = "/chat";
+
+/** Build URL for a specific IPC stream's chat page. */
+export function chatStreamUrl(streamId: string): string {
+  return `/chat/${encodeURIComponent(streamId)}`;
+}
+
+/** URL for the home dashboard page. */
+export const HOME_URL: string = "/";
+
+/** URL for the tasks landing page. */
+export const TASKS_URL: string = "/tasks";
+
+/** URL for the workspaces landing page. */
+export const WORKSPACES_URL: string = "/workspaces";
+
+/** URL for the new workspace form. */
+export const NEW_WORKSPACE_URL: string = "/workspaces/new";
+
+/** URL for the knowledge graph explorer page. */
+export const KNOWLEDGE_URL: string = "/knowledge";
+
+/** URL for the findings landing page. */
+export const FINDINGS_URL: string = "/findings";
+
+/** Build URL for the findings list page, optionally scoped to a workspace. */
+export function findingsUrl(workspaceId?: string, environmentId?: string): string {
+  if (workspaceId && environmentId) {
+    return `/environments/${encodeURIComponent(environmentId)}/workspaces/${encodeURIComponent(workspaceId)}/findings`;
+  }
+  return FINDINGS_URL;
+}
+
+/** Build URL for a finding detail page, optionally scoped to a workspace. */
+export function findingUrl(findingId: string, workspaceId?: string, environmentId?: string): string {
+  const encodedFindingId = encodeURIComponent(findingId);
+  if (workspaceId && environmentId) {
+    return `/environments/${encodeURIComponent(environmentId)}/workspaces/${encodeURIComponent(workspaceId)}/findings/${encodedFindingId}`;
+  }
+  return `/findings/${encodedFindingId}`;
+}
+
+/** Build URL for the root-task chat page. */
+export function chatUrl(): string {
+  return CHAT_URL;
+}

package/src/utils/route-config.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import {
+  sessionUrl,
+  workspaceUrl,
+  taskUrl,
+  taskEditUrl,
+  newTaskUrl,
+  newChatUrl,
+  personaUrl,
+  findingUrl,
+  findingsUrl,
+  HOME_URL,
+  SETTINGS_URL,
+  PERSONAS_URL,
+  NEW_PERSONA_URL,
+  NEW_ENVIRONMENT_URL,
+  NEW_WORKSPACE_URL,
+  FINDINGS_URL,
+} from "./navigation.js";
+
+describe("URL builder functions", () => {
+  it("sessionUrl encodes sessionId", () => {
+    expect(sessionUrl("abc-123")).toBe("/sessions/abc-123");
+    expect(sessionUrl("has space")).toBe("/sessions/has%20space");
+    expect(sessionUrl("special/chars")).toBe("/sessions/special%2Fchars");
+  });
+
+  it("workspaceUrl encodes workspaceId under environments", () => {
+    expect(workspaceUrl("proj-1", "env-1")).toBe("/environments/env-1/workspaces/proj-1");
+    expect(workspaceUrl("proj with space", "env-1")).toBe("/environments/env-1/workspaces/proj%20with%20space");
+  });
+
+  it("taskUrl without tab produces base path", () => {
+    expect(taskUrl("task-1")).toBe("/tasks/task-1");
+  });
+
+  it("taskUrl with stream tab produces correct path", () => {
+    expect(taskUrl("task-1", "stream")).toBe("/tasks/task-1/stream");
+  });
+
+  it("taskUrl with findings tab produces correct path", () => {
+    expect(taskUrl("task-1", "findings")).toBe("/tasks/task-1/findings");
+  });
+
+  it("taskUrl encodes taskId", () => {
+    expect(taskUrl("has space")).toBe("/tasks/has%20space");
+    expect(taskUrl("has space", "stream")).toBe("/tasks/has%20space/stream");
+  });
+
+  it("taskUrl with workspace and environment produces environment-scoped path", () => {
+    expect(taskUrl("task-1", undefined, "ws-1", "env-1")).toBe("/environments/env-1/workspaces/ws-1/tasks/task-1");
+    expect(taskUrl("task-1", "stream", "ws-1", "env-1")).toBe("/environments/env-1/workspaces/ws-1/tasks/task-1/stream");
+    expect(taskUrl("task-1", "findings", "ws-1", "env-1")).toBe("/environments/env-1/workspaces/ws-1/tasks/task-1/findings");
+  });
+
+  it("taskUrl with only workspaceId (no environmentId) falls back to legacy workspace path", () => {
+    expect(taskUrl("task-1", undefined, "ws-1")).toBe("/workspaces/ws-1/tasks/task-1");
+  });
+
+  it("taskEditUrl produces correct path", () => {
+    expect(taskEditUrl("task-1")).toBe("/tasks/task-1/edit");
+  });
+
+  it("taskEditUrl with workspace and environment produces scoped path", () => {
+    expect(taskEditUrl("task-1", "ws-1", "env-1")).toBe("/environments/env-1/workspaces/ws-1/tasks/task-1/edit");
+  });
+
+  it("newTaskUrl with no params produces base path", () => {
+    expect(newTaskUrl()).toBe("/tasks/new");
+  });
+
+  it("newTaskUrl includes workspace param", () => {
+    expect(newTaskUrl("proj-1")).toBe("/tasks/new?workspace=proj-1");
+  });
+
+  it("newTaskUrl includes workspace and parent params", () => {
+    const url = newTaskUrl("proj-1", "parent-task");
+    expect(url).toBe("/tasks/new?workspace=proj-1&parent=parent-task");
+  });
+
+  it("newTaskUrl with environment produces scoped path", () => {
+    expect(newTaskUrl("ws-1", undefined, "env-1")).toBe("/environments/env-1/workspaces/ws-1/tasks/new");
+    expect(newTaskUrl("ws-1", "parent-1", "env-1")).toBe("/environments/env-1/workspaces/ws-1/tasks/new?parent=parent-1");
+  });
+
+  it("newChatUrl includes env param", () => {
+    const url = newChatUrl("env-1");
+    expect(url).toBe("/sessions/new?env=env-1");
+  });
+
+  it("constant URLs are correct", () => {
+    expect(SETTINGS_URL).toBe("/settings");
+    expect(HOME_URL).toBe("/");
+    expect(PERSONAS_URL).toBe("/settings/personas");
+    expect(NEW_PERSONA_URL).toBe("/settings/personas/new");
+    expect(NEW_ENVIRONMENT_URL).toBe("/environments/new");
+    expect(NEW_WORKSPACE_URL).toBe("/workspaces/new");
+  });
+
+  it("personaUrl encodes personaId", () => {
+    expect(personaUrl("p-1")).toBe("/settings/personas/p-1");
+    expect(personaUrl("has space")).toBe("/settings/personas/has%20space");
+  });
+
+  it("FINDINGS_URL constant is correct", () => {
+    expect(FINDINGS_URL).toBe("/findings");
+  });
+
+  it("findingUrl produces base path without scope", () => {
+    expect(findingUrl("f1")).toBe("/findings/f1");
+  });
+
+  it("findingUrl with workspace and environment produces scoped path", () => {
+    expect(findingUrl("f1", "ws1", "env1")).toBe("/environments/env1/workspaces/ws1/findings/f1");
+  });
+
+  it("findingUrl encodes special characters", () => {
+    expect(findingUrl("has space")).toBe("/findings/has%20space");
+  });
+
+  it("findingsUrl without scope returns base findings path", () => {
+    expect(findingsUrl()).toBe("/findings");
+  });
+
+  it("findingsUrl with workspace and environment produces scoped path", () => {
+    expect(findingsUrl("ws1", "env1")).toBe("/environments/env1/workspaces/ws1/findings");
+  });
+});

package/src/utils/scrollUtils.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import {
+  isNearAnchor,
+  computeScrollCompensation,
+  SCROLL_ANCHOR_THRESHOLD_PX,
+} from "./scrollUtils.js";
+
+describe("isNearAnchor", () => {
+  // Default mode — anchor at bottom
+  it("returns true when near the bottom in default mode", () => {
+    // scrollHeight=1000, clientHeight=400, scrollTop=570 → distance = 1000-570-400 = 30 < 50
+    expect(isNearAnchor(570, 1000, 400, false)).toBe(true);
+  });
+
+  it("returns false when scrolled well above the bottom in default mode", () => {
+    // distance = 1000 - 200 - 400 = 400 > 50
+    expect(isNearAnchor(200, 1000, 400, false)).toBe(false);
+  });
+
+  it("returns true when fully scrolled to bottom in default mode", () => {
+    // distance = 1000 - 600 - 400 = 0 < 50
+    expect(isNearAnchor(600, 1000, 400, false)).toBe(true);
+  });
+
+  // Reverse mode — anchor at top
+  it("returns true when near the top in reverse mode", () => {
+    // scrollTop = 20 < 50
+    expect(isNearAnchor(20, 1000, 400, true)).toBe(true);
+  });
+
+  it("returns false when scrolled well below the top in reverse mode", () => {
+    // scrollTop = 300 > 50
+    expect(isNearAnchor(300, 1000, 400, true)).toBe(false);
+  });
+
+  it("returns true at exact top in reverse mode", () => {
+    expect(isNearAnchor(0, 1000, 400, true)).toBe(true);
+  });
+
+  // Custom threshold
+  it("respects a custom threshold parameter", () => {
+    // distance = 1000 - 880 - 100 = 20, threshold=10 → 20 >= 10 → false
+    expect(isNearAnchor(880, 1000, 100, false, 10)).toBe(false);
+    // distance = 1000 - 895 - 100 = 5, threshold=10 → 5 < 10 → true
+    expect(isNearAnchor(895, 1000, 100, false, 10)).toBe(true);
+  });
+
+  it("uses default threshold of SCROLL_ANCHOR_THRESHOLD_PX", () => {
+    expect(SCROLL_ANCHOR_THRESHOLD_PX).toBe(50);
+  });
+});
+
+describe("computeScrollCompensation", () => {
+  it("returns positive delta when content was prepended", () => {
+    expect(computeScrollCompensation(1000, 1200)).toBe(200);
+  });
+
+  it("returns 0 when no change occurred", () => {
+    expect(computeScrollCompensation(1000, 1000)).toBe(0);
+  });
+
+  it("returns 0 when scrollHeight decreased", () => {
+    expect(computeScrollCompensation(1000, 800)).toBe(0);
+  });
+});