@stigmer/react 3.2.1 → 3.2.3

package/src/access/__tests__/useManageAccess.test.tsx

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { useManageAccess } from "../useManageAccess";
+import { VisibilityBadge } from "../../library/VisibilitySelector";
+import type { AccessResource } from "../types";
+
+// Drive the gate through the permission hook (owned by useManageAccess) and
+// stand in a lightweight dialog so the open-state wiring is observable
+// without exercising the real modal (covered by its own test).
+const checkPermission = vi.fn<() => { allowed: boolean; isLoading: boolean; error: null }>(
+  () => ({ allowed: true, isLoading: false, error: null }),
+);
+vi.mock("../../iam-policy/useCheckPermission", () => ({
+  useCheckPermission: () => checkPermission(),
+}));
+
+vi.mock("../ManageAccessDialog", () => ({
+  ManageAccessDialog: ({ open }: { open: boolean }) => (
+    <div data-testid="dialog" data-open={String(open)} />
+  ),
+}));
+
+afterEach(() => {
+  cleanup();
+  checkPermission.mockReset();
+  checkPermission.mockReturnValue({ allowed: true, isLoading: false, error: null });
+});
+
+const RESOURCE: AccessResource = {
+  kind: ApiResourceKind.agent,
+  kindString: "agent",
+  id: "agt_123",
+  org: "acme",
+  name: "Release Bot",
+};
+
+/**
+ * Mirrors how the blueprint detail views (agent/skill/mcp_server/workflow)
+ * wire the header visibility chip: clickable into the Manage access dialog
+ * only when the user can view access, a static badge otherwise.
+ */
+function DetailHeaderHarness({ resource }: { resource: AccessResource | null }) {
+  const access = useManageAccess({ resource });
+  return (
+    <>
+      <VisibilityBadge
+        visibility={ApiResourceVisibility.visibility_org}
+        onClick={access.action ? access.open : undefined}
+      />
+      {access.dialog}
+    </>
+  );
+}
+
+describe("useManageAccess — header visibility chip wiring", () => {
+  it("renders the chip as a Manage-access button and opens the dialog on click", () => {
+    render(<DetailHeaderHarness resource={RESOURCE} />);
+
+    const chip = screen.getByRole("button", {
+      name: /Organization visibility — manage access/i,
+    });
+    expect(screen.getByTestId("dialog").getAttribute("data-open")).toBe("false");
+
+    fireEvent.click(chip);
+    expect(screen.getByTestId("dialog").getAttribute("data-open")).toBe("true");
+  });
+
+  it("keeps the chip a static badge when the user cannot view access", () => {
+    checkPermission.mockReturnValue({ allowed: false, isLoading: false, error: null });
+    render(<DetailHeaderHarness resource={RESOURCE} />);
+
+    // Visibility stays legible, but there is nothing to click.
+    expect(screen.getByText("Organization")).toBeTruthy();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("keeps the chip static and mounts no dialog while the resource is loading", () => {
+    render(<DetailHeaderHarness resource={null} />);
+
+    expect(screen.getByText("Organization")).toBeTruthy();
+    expect(screen.queryByRole("button")).toBeNull();
+    expect(screen.queryByTestId("dialog")).toBeNull();
+  });
+});
+
+describe("useManageAccess — action gating", () => {
+  function ActionProbe({ resource }: { resource: AccessResource | null }) {
+    const access = useManageAccess({ resource });
+    return <div data-testid="action" data-present={String(access.action !== null)} />;
+  }
+
+  it("returns a sharing-group action when permitted", () => {
+    render(<ActionProbe resource={RESOURCE} />);
+    expect(screen.getByTestId("action").getAttribute("data-present")).toBe("true");
+  });
+
+  it("returns null without can_view_access", () => {
+    checkPermission.mockReturnValue({ allowed: false, isLoading: false, error: null });
+    render(<ActionProbe resource={RESOURCE} />);
+    expect(screen.getByTestId("action").getAttribute("data-present")).toBe("false");
+  });
+});

package/src/activity/__tests__/format-relative-time.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { formatRelativeTime } from "../format-relative-time";
+
+// The recents rows' "why is this here" stamp: compact single-unit ages,
+// then short dates. See format-relative-time.ts for the design rationale.
+
+describe("formatRelativeTime", () => {
+  const now = new Date("2026-07-18T12:00:00Z");
+
+  it("renders sub-minute ages as 'now'", () => {
+    expect(formatRelativeTime(new Date("2026-07-18T11:59:30Z"), now)).toBe("now");
+  });
+
+  it("clamps future stamps (writer clock skew) to 'now'", () => {
+    expect(formatRelativeTime(new Date("2026-07-18T12:00:45Z"), now)).toBe("now");
+  });
+
+  it("renders minutes under an hour", () => {
+    expect(formatRelativeTime(new Date("2026-07-18T11:15:00Z"), now)).toBe("45m");
+  });
+
+  it("renders hours under a day", () => {
+    expect(formatRelativeTime(new Date("2026-07-18T04:30:00Z"), now)).toBe("7h");
+  });
+
+  it("renders days under a week", () => {
+    expect(formatRelativeTime(new Date("2026-07-15T12:00:00Z"), now)).toBe("3d");
+  });
+
+  it("renders a short date beyond a week, same year", () => {
+    const result = formatRelativeTime(new Date("2026-06-01T12:00:00Z"), now);
+    expect(result).toMatch(/Jun/);
+    expect(result).not.toMatch(/2026/);
+  });
+
+  it("includes the year for prior-year dates", () => {
+    const result = formatRelativeTime(new Date("2025-06-01T12:00:00Z"), now);
+    expect(result).toMatch(/2025/);
+  });
+});

package/src/activity/entry-status-badge.ts

@@ -0,0 +1,39 @@
+import type { RecentActivityEntry } from "./types.js";
+
+/**
+ * A tiny status annotation for a recents row, or `null` when the row
+ * should stay clean.
+ *
+ * Only NOTEWORTHY execution states earn a badge: a completed run is the
+ * expected outcome (annotating every row would be noise), and sessions
+ * carry no phase at all. Paired with the relative-time stamp, the badge
+ * explains why an old-named execution sits high in a last-activity-sorted
+ * list ("failed · 2h" — it just failed, that's the activity).
+ */
+export interface RecentActivityStatusBadge {
+  /** Lowercase phase word, rendered verbatim (e.g. "failed"). */
+  readonly label: string;
+  /** Rendering tone: `"destructive"` for terminal failures, else `"muted"`. */
+  readonly tone: "destructive" | "muted";
+}
+
+const BADGED_STATUSES: ReadonlyMap<string, RecentActivityStatusBadge["tone"]> =
+  new Map([
+    ["failed", "destructive"],
+    ["terminated", "destructive"],
+    ["cancelled", "muted"],
+    ["running", "muted"],
+    ["pending", "muted"],
+  ]);
+
+/**
+ * Resolves the status badge for a recent-activity entry. Returns `null`
+ * for sessions, completed executions, and unknown phases.
+ */
+export function recentActivityStatusBadge(
+  entry: RecentActivityEntry,
+): RecentActivityStatusBadge | null {
+  if (entry.type !== "workflow_execution" || !entry.status) return null;
+  const tone = BADGED_STATUSES.get(entry.status);
+  return tone ? { label: entry.status, tone } : null;
+}

package/src/activity/format-relative-time.ts

@@ -0,0 +1,38 @@
+/**
+ * Compact relative-time formatter for recent-activity rows.
+ *
+ * The recents list sorts by LAST ACTIVITY (`statusAudit.updatedAt`), while
+ * execution names embed their CREATION time — so an old run legitimately
+ * re-bumped by a status change (a cancel, a late failure) sorts above
+ * newer-named items and reads as "wrong order" unless the row says why it
+ * is there. This stamp is that explanation: it renders the sort key the
+ * user cannot otherwise see.
+ *
+ * Compact single-unit output — a sidebar row suffix, not prose:
+ * `now`, `5m`, `3h`, `6d`, then a short date (`Jul 12`, `Jul 12, 2025`)
+ * once "days ago" stops being how people think about it.
+ */
+export function formatRelativeTime(date: Date, now?: Date): string {
+  const ref = now ?? new Date();
+  const deltaMs = ref.getTime() - date.getTime();
+
+  // Clock skew between writers can put a stamp slightly in the future;
+  // render it as "now" rather than a nonsense negative age.
+  if (deltaMs < 60_000) return "now";
+
+  const minutes = Math.floor(deltaMs / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d`;
+
+  const sameYear = date.getFullYear() === ref.getFullYear();
+  return date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    ...(sameYear ? {} : { year: "numeric" }),
+  });
+}

package/src/activity/index.ts

@@ -12,3 +12,10 @@ export {
 } from "./useRecentActivity.js";
 
 export { groupRecentActivityByTime } from "./group-activity.js";
+
+export { formatRelativeTime } from "./format-relative-time.js";
+
+export {
+  recentActivityStatusBadge,
+  type RecentActivityStatusBadge,
+} from "./entry-status-badge.js";

package/src/agent/AgentDetailView.tsx

@@ -360,10 +360,16 @@ export function AgentDetailView({
     updatedAt: specAudit?.updatedAt ? timestampDate(specAudit.updatedAt) : null,
   };
 
-  // Inline visibility is read-only (at-a-glance); editing lives in the
-  // Manage access dialog, the single writer for both access axes.
+  // Inline visibility is at-a-glance AND a shortcut into the Manage access
+  // dialog — the single writer for both access axes. The chip is navigation
+  // only (never edits in place); it stays a static badge for users who
+  // cannot view access. An inert chip reads as "not editable" (2026-07-18
+  // dogfood friction), so the shortcut is the discoverability affordance.
   const visibilityControl = meta ? (
-    <VisibilityBadge visibility={meta.visibility} />
+    <VisibilityBadge
+      visibility={meta.visibility}
+      onClick={access.action ? access.open : undefined}
+    />
   ) : undefined;
 
   // Share — the sibling consent to Manage access: visibility governs who

package/src/execution/__tests__/useLiveAgentExecution.test.tsx

@@ -200,3 +200,128 @@ describe("useLiveAgentExecution", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// The { live } visibility gate (T07)
+// ---------------------------------------------------------------------------
+
+describe("useLiveAgentExecution { live }", () => {
+  it("live: false fetches the snapshot but never subscribes", async () => {
+    const running = executionFixture("aex_p1", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => running);
+
+    const { result } = renderHook(() =>
+      useLiveAgentExecution("aex_p1", { live: false }),
+    );
+    await waitFor(() => expect(result.current.execution).toBe(running));
+
+    // Non-terminal + fetched, yet the gate stays closed on every render.
+    for (const call of mockUseExecutionStream.mock.calls) {
+      expect(call[0]).toBeNull();
+    }
+  });
+
+  it("live: true (and omitted) behave identically for a non-terminal execution", async () => {
+    const running = executionFixture("aex_p2", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => running);
+
+    const { result } = renderHook(() =>
+      useLiveAgentExecution("aex_p2", { live: true }),
+    );
+    await waitFor(() => expect(result.current.execution).not.toBeNull());
+
+    const lastCall =
+      mockUseExecutionStream.mock.calls[mockUseExecutionStream.mock.calls.length - 1];
+    expect(lastCall[0]).toBe("aex_p2");
+  });
+
+  it("a terminal execution never streams regardless of live", async () => {
+    const terminal = executionFixture("aex_p3", ExecutionPhase.EXECUTION_COMPLETED);
+    mockGet(async () => terminal);
+
+    const { result } = renderHook(() =>
+      useLiveAgentExecution("aex_p3", { live: true }),
+    );
+    await waitFor(() => expect(result.current.execution).toBe(terminal));
+
+    for (const call of mockUseExecutionStream.mock.calls) {
+      expect(call[0]).toBeNull();
+    }
+  });
+
+  it("false → true attaches the stream in place", async () => {
+    const running = executionFixture("aex_p4", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => running);
+
+    const { result, rerender } = renderHook(
+      ({ live }: { live: boolean }) =>
+        useLiveAgentExecution("aex_p4", { live }),
+      { initialProps: { live: false } },
+    );
+    await waitFor(() => expect(result.current.execution).toBe(running));
+
+    let lastCall =
+      mockUseExecutionStream.mock.calls[mockUseExecutionStream.mock.calls.length - 1];
+    expect(lastCall[0]).toBeNull();
+
+    rerender({ live: true });
+
+    lastCall =
+      mockUseExecutionStream.mock.calls[mockUseExecutionStream.mock.calls.length - 1];
+    expect(lastCall[0]).toBe("aex_p4");
+  });
+
+  it("never rewinds: a stream pause keeps the last-streamed snapshot, not the mount fetch", async () => {
+    const fetched = executionFixture("aex_p5", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const streamed = executionFixture("aex_p5", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => fetched);
+    mockUseExecutionStream.mockReturnValue({
+      ...idleStream(),
+      execution: streamed,
+      isStreaming: true,
+    });
+
+    const { result, rerender } = renderHook(
+      ({ live }: { live: boolean }) =>
+        useLiveAgentExecution("aex_p5", { live }),
+      { initialProps: { live: true } },
+    );
+    await waitFor(() => expect(result.current.execution).toBe(streamed));
+
+    // Pause: the stream hook resets to its idle shape (execution: null) —
+    // the exact behavior of an unsubscribed useExecutionStream.
+    mockUseExecutionStream.mockReturnValue(idleStream());
+    rerender({ live: false });
+
+    // The freshest streamed snapshot stays visible; the view never rolls
+    // back to the mount-time fetch.
+    expect(result.current.execution).toBe(streamed);
+  });
+
+  it("does not leak the previous execution's snapshot across an id switch", async () => {
+    const first = executionFixture("aex_p6a", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const streamedFirst = executionFixture("aex_p6a", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const second = executionFixture("aex_p6b", ExecutionPhase.EXECUTION_COMPLETED);
+    mockGet(async (id) => (id === "aex_p6a" ? first : second));
+    mockUseExecutionStream.mockReturnValue({
+      ...idleStream(),
+      execution: streamedFirst,
+      isStreaming: true,
+    });
+
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useLiveAgentExecution(id, { live: true }),
+      { initialProps: { id: "aex_p6a" } },
+    );
+    await waitFor(() => expect(result.current.execution).toBe(streamedFirst));
+
+    // Switch executions; the stream resets while the new fetch is in flight.
+    mockUseExecutionStream.mockReturnValue(idleStream());
+    rerender({ id: "aex_p6b" });
+
+    // The retained snapshot is keyed by id — it must NOT bleed into the
+    // new execution's view.
+    expect(result.current.execution).not.toBe(streamedFirst);
+    await waitFor(() => expect(result.current.execution).toBe(second));
+  });
+});

package/src/execution/index.ts

@@ -13,7 +13,10 @@ export { useExecutionStream } from "./useExecutionStream.js";
 export type { UseExecutionStreamReturn } from "./useExecutionStream.js";
 
 export { useLiveAgentExecution } from "./useLiveAgentExecution.js";
-export type { UseLiveAgentExecutionReturn } from "./useLiveAgentExecution.js";
+export type {
+  UseLiveAgentExecutionOptions,
+  UseLiveAgentExecutionReturn,
+} from "./useLiveAgentExecution.js";
 
 export { useAgentExecutionActions } from "./useAgentExecutionActions.js";
 export type {
@@ -291,12 +294,6 @@ export {
   fileChangeTabPath,
 } from "./file-change-document.js";
 
-export {
-  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
-  agentExecutionTabPath,
-  parseAgentExecutionTabPath,
-} from "./agent-execution-document.js";
-
 export { ArtifactContentRenderer } from "./ArtifactContentRenderer.js";
 export type { ArtifactContentRendererProps } from "./ArtifactContentRenderer.js";
 

package/src/execution/useLiveAgentExecution.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useRef } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { isNotFound } from "@stigmer/sdk";
@@ -9,6 +9,23 @@ import { useFetch } from "../internal/useFetch.js";
 import { isTerminalPhase } from "./execution-phases.js";
 import { useExecutionStream } from "./useExecutionStream.js";
 
+/** Options for {@link useLiveAgentExecution}. */
+export interface UseLiveAgentExecutionOptions {
+  /**
+   * Whether the live stream may be open. Defaults to `true`.
+   *
+   * When `false`, the snapshot fetch still runs (so consumers always have
+   * something to render) but no subscription is opened — the
+   * visibility-gating seam for surfaces that mount many executions at once
+   * (e.g. inline agent-call transcripts in the workflow task thread, where
+   * only on-screen cards stream). A `false → true` transition attaches the
+   * stream in place; a `true → false` transition pauses it while the
+   * last-streamed snapshot stays visible (the view never rewinds to the
+   * mount-time snapshot).
+   */
+  readonly live?: boolean;
+}
+
 /** Return value of {@link useLiveAgentExecution}. */
 export interface UseLiveAgentExecutionReturn {
   /**
@@ -67,8 +84,10 @@ export interface UseLiveAgentExecutionReturn {
  */
 export function useLiveAgentExecution(
   executionId: string | null,
+  options?: UseLiveAgentExecutionOptions,
 ): UseLiveAgentExecutionReturn {
   const stigmer = useStigmer();
+  const live = options?.live ?? true;
 
   const fetchFn = executionId
     ? async () => {
@@ -94,12 +113,31 @@ export function useLiveAgentExecution(
   // snapshot never advances, so a run that terminates mid-stream does not
   // flip this gate and unmount-thrash the subscription — useExecutionStream
   // ends itself on the terminal snapshot (completion is phase-driven).
+  // `live` is the consumer's visibility gate layered on top (an off-screen
+  // surface pauses its subscription without losing the fetch).
   const fetchedPhase =
     fetched?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
-  const shouldStream = fetched !== null && !isTerminalPhase(fetchedPhase);
+  const shouldStream =
+    live && fetched !== null && !isTerminalPhase(fetchedPhase);
   const stream = useExecutionStream(shouldStream ? executionId : null);
 
-  const execution = stream.execution ?? fetched;
+  // Retain the freshest snapshot ever shown for THIS execution across a
+  // stream pause (`live: true → false`): useExecutionStream resets its
+  // store when unsubscribed, so without this a paused surface would rewind
+  // to the mount-time fetch — visibly rolling the view backwards. Keyed by
+  // id so an execution switch never leaks the previous one's snapshot.
+  const lastStreamedRef = useRef<{
+    id: string;
+    execution: AgentExecution;
+  } | null>(null);
+  if (executionId && stream.execution) {
+    lastStreamedRef.current = { id: executionId, execution: stream.execution };
+  } else if (lastStreamedRef.current?.id !== executionId) {
+    lastStreamedRef.current = null;
+  }
+
+  const execution =
+    stream.execution ?? lastStreamedRef.current?.execution ?? fetched;
   const phase =
     execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
 

package/src/index.ts

@@ -217,11 +217,14 @@ export type {
 export {
   useRecentActivity,
   groupRecentActivityByTime,
+  formatRelativeTime,
+  recentActivityStatusBadge,
 } from "./activity/index.js";
 export type {
   RecentActivityType,
   RecentActivityEntry,
   RecentActivityGroup,
+  RecentActivityStatusBadge,
   UseRecentActivityOptions,
   UseRecentActivityReturn,
 } from "./activity/index.js";
@@ -343,9 +346,6 @@ export {
   toFileDiffEntry,
   FILE_CHANGE_DOCUMENT_ENTRY_ID,
   fileChangeTabPath,
-  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
-  agentExecutionTabPath,
-  parseAgentExecutionTabPath,
   EmptyChangeNotice,
   isTextArtifact,
   formatArtifactSize,
@@ -360,6 +360,7 @@ export type {
   SharedAgentExecutionFields,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
+  UseLiveAgentExecutionOptions,
   UseLiveAgentExecutionReturn,
   UseAgentExecutionActionsOptions,
   UseAgentExecutionActionsReturn,
@@ -1173,6 +1174,7 @@ export type {
   UseImportResourceReturn,
   ImportResourceDialogProps,
   VisibilitySelectorProps,
+  VisibilityBadgeProps,
   VisibilityLevelOption,
   BlueprintVisibilityLevelsContext,
   VisibilityResourceKind,
@@ -1482,7 +1484,7 @@ export {
   WorkflowChangesTab,
   WorkflowUsageTab,
   WorkflowArtifactDocument,
-  WorkflowAgentExecutionDocument,
+  WorkflowAgentCallTranscript,
   useWorkflowArtifactDownload,
   useWorkflowExecutionFileChanges,
   enumerateAgentCallChildren,
@@ -1624,7 +1626,7 @@ export type {
   UseWorkflowExecutionFileChangesOptions,
   UseWorkflowExecutionFileChangesReturn,
   WorkflowArtifactDocumentProps,
-  WorkflowAgentExecutionDocumentProps,
+  WorkflowAgentCallTranscriptProps,
   WorkflowAgentExecutionHitl,
   UseWorkflowArtifactDownloadReturn,
   WorkflowArtifactEntry,

package/src/internal/__tests__/useInViewport.test.tsx

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act, screen, cleanup } from "@testing-library/react";
+import React from "react";
+import { useInViewport, type UseInViewportReturn } from "../useInViewport";
+
+// ---------------------------------------------------------------------------
+// Test harness — renders a real element so the ref gets populated
+// ---------------------------------------------------------------------------
+
+let latestResult: UseInViewportReturn;
+
+function Harness() {
+  const result = useInViewport();
+  latestResult = result;
+  return <div ref={result.ref} data-testid="target" />;
+}
+
+// ---------------------------------------------------------------------------
+// Observer mock (the useAutoScroll.test pattern)
+// ---------------------------------------------------------------------------
+
+type IOCallback = IntersectionObserverCallback;
+
+let ioCallback: IOCallback;
+let ioDisconnect: ReturnType<typeof vi.fn>;
+let ioObserve: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  ioDisconnect = vi.fn();
+  ioObserve = vi.fn();
+
+  vi.stubGlobal(
+    "IntersectionObserver",
+    vi.fn((cb: IOCallback) => {
+      ioCallback = cb;
+      return {
+        observe: ioObserve,
+        unobserve: vi.fn(),
+        disconnect: ioDisconnect,
+        takeRecords: vi.fn(() => []),
+        root: null,
+        rootMargin: "",
+        thresholds: [0],
+      };
+    }),
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function fireIO(isIntersecting: boolean) {
+  act(() => {
+    ioCallback(
+      [{ isIntersecting } as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useInViewport", () => {
+  it("starts not-visible until the observer's first callback", () => {
+    render(<Harness />);
+    expect(latestResult.isVisible).toBe(false);
+  });
+
+  it("observes the target element on mount", () => {
+    render(<Harness />);
+    expect(ioObserve).toHaveBeenCalledWith(screen.getByTestId("target"));
+  });
+
+  it("uses the top-level viewport as root with the pre-warm margin", () => {
+    render(<Harness />);
+    const IOConstructor = vi.mocked(IntersectionObserver);
+    const options = IOConstructor.mock.calls[0]?.[1];
+    expect(options?.root).toBeNull();
+    expect(options?.rootMargin).toBe("200px 0px 200px 0px");
+  });
+
+  it("flips visible on enter and back on leave", () => {
+    render(<Harness />);
+
+    fireIO(true);
+    expect(latestResult.isVisible).toBe(true);
+
+    fireIO(false);
+    expect(latestResult.isVisible).toBe(false);
+  });
+
+  it("reads the LATEST entry when a batch carries several", () => {
+    render(<Harness />);
+    act(() => {
+      ioCallback(
+        [
+          { isIntersecting: true } as IntersectionObserverEntry,
+          { isIntersecting: false } as IntersectionObserverEntry,
+        ],
+        {} as IntersectionObserver,
+      );
+    });
+    expect(latestResult.isVisible).toBe(false);
+  });
+
+  it("disconnects the observer on unmount", () => {
+    const { unmount } = render(<Harness />);
+    unmount();
+    expect(ioDisconnect).toHaveBeenCalled();
+  });
+});