@stigmer/react 3.2.2 → 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/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

@@ -346,9 +346,6 @@ export {
   toFileDiffEntry,
   FILE_CHANGE_DOCUMENT_ENTRY_ID,
   fileChangeTabPath,
-  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
-  agentExecutionTabPath,
-  parseAgentExecutionTabPath,
   EmptyChangeNotice,
   isTextArtifact,
   formatArtifactSize,
@@ -363,6 +360,7 @@ export type {
   SharedAgentExecutionFields,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
+  UseLiveAgentExecutionOptions,
   UseLiveAgentExecutionReturn,
   UseAgentExecutionActionsOptions,
   UseAgentExecutionActionsReturn,
@@ -1176,6 +1174,7 @@ export type {
   UseImportResourceReturn,
   ImportResourceDialogProps,
   VisibilitySelectorProps,
+  VisibilityBadgeProps,
   VisibilityLevelOption,
   BlueprintVisibilityLevelsContext,
   VisibilityResourceKind,
@@ -1485,7 +1484,7 @@ export {
   WorkflowChangesTab,
   WorkflowUsageTab,
   WorkflowArtifactDocument,
-  WorkflowAgentExecutionDocument,
+  WorkflowAgentCallTranscript,
   useWorkflowArtifactDownload,
   useWorkflowExecutionFileChanges,
   enumerateAgentCallChildren,
@@ -1627,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();
+  });
+});

package/src/internal/useInViewport.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * Pre-warm margin in pixels. The element is reported visible while it is
+ * within this distance of the viewport, so consumers that attach expensive
+ * resources on visibility (e.g. a live stream subscription) connect just
+ * BEFORE the element scrolls into view and linger just after it leaves —
+ * a fast scroll past a row never thrashes connect/disconnect.
+ */
+const PREWARM_MARGIN_PX = 200;
+
+export interface UseInViewportReturn {
+  /** Attach to the element whose viewport visibility is tracked. */
+  readonly ref: React.RefObject<HTMLDivElement | null>;
+  /** True while the element is within the pre-warmed viewport. */
+  readonly isVisible: boolean;
+}
+
+/**
+ * Headless viewport-visibility hook over `IntersectionObserver`.
+ *
+ * `root` is deliberately `null` (the top-level viewport): per the
+ * IntersectionObserver spec, an element clipped by any intervening
+ * scroll container (e.g. the workflow thread's own scroller) does not
+ * intersect the viewport either, so nested scroll contexts are handled
+ * without naming them. `display: none` subtrees report not-visible — a
+ * CSS-hidden center view correctly suspends its visibility-gated work.
+ *
+ * Starts `false` until the observer's first callback; consumers should
+ * treat visibility as an upgrade signal, not a render gate.
+ *
+ * @internal Not part of the public API (promote if a second consumer
+ * appears outside the workflow thread).
+ */
+export function useInViewport(): UseInViewportReturn {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const io = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[entries.length - 1];
+        if (!entry) return;
+        setIsVisible(entry.isIntersecting);
+      },
+      {
+        root: null,
+        rootMargin: `${PREWARM_MARGIN_PX}px 0px ${PREWARM_MARGIN_PX}px 0px`,
+        threshold: 0,
+      },
+    );
+
+    io.observe(el);
+    return () => io.disconnect();
+  }, []);
+
+  return { ref, isVisible };
+}

package/src/library/VisibilitySelector.tsx

@@ -409,28 +409,69 @@ function CaretIcon() {
   );
 }
 
+/** Props for {@link VisibilityBadge}. */
+export interface VisibilityBadgeProps {
+  /** The visibility level to display. */
+  readonly visibility: ApiResourceVisibility;
+  /** Additional CSS classes applied to the chip. */
+  readonly className?: string;
+  /**
+   * When provided, the badge renders as a button and invokes this on
+   * activation. Detail headers use it as a shortcut into the Manage access
+   * dialog, so the at-a-glance chip is also the entry point to editing —
+   * the chip stays navigation-only (the dialog remains the single writer
+   * for both access axes). Omit it for a plain, non-interactive badge.
+   */
+  readonly onClick?: () => void;
+}
+
 /**
- * Read-only visibility indicator with a matching icon, covering all four
- * levels (Private / Organization / Platform / Public).
+ * Visibility indicator with a matching icon, covering all four levels
+ * (Private / Organization / Platform / Public).
  *
  * Rendered wherever the interactive {@link VisibilitySelector} is not
  * available — for viewers who lack `can_edit`, and while a permission check
  * is in flight — so a resource's visibility is always legible rather than
  * silently blank. Shares the chip styling with the selector trigger so the
  * read-only and editable states are visually consistent.
+ *
+ * With {@link VisibilityBadgeProps.onClick} the chip becomes an accessible
+ * button (hover + focus affordances, "Manage access" label) that hosts wire
+ * to their access-management surface; the badge itself never edits.
  */
 export function VisibilityBadge({
   visibility,
   className,
-}: {
-  readonly visibility: ApiResourceVisibility;
-  readonly className?: string;
-}) {
+  onClick,
+}: VisibilityBadgeProps) {
   const option = visibilityOption(visibility);
-  return (
-    <span className={cn(VISIBILITY_CHIP_CLASS, className)}>
+  const content = (
+    <>
       <VisibilityIcon tone={option.tone} className="size-2.5" />
       {option.label}
-    </span>
+    </>
+  );
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        onClick={onClick}
+        title="Manage access"
+        aria-label={`${option.label} visibility — manage access`}
+        className={cn(
+          VISIBILITY_CHIP_CLASS,
+          "transition-colors hover:bg-accent-hover hover:text-foreground",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          className,
+        )}
+      >
+        {content}
+      </button>
+    );
+  }
+
+  return (
+    <span className={cn(VISIBILITY_CHIP_CLASS, className)}>{content}</span>
   );
 }