@stigmer/react 3.1.3 → 3.1.5

package/src/session/SessionViewer.tsx

@@ -17,14 +17,14 @@ import {
   WorkspaceSurface,
   type SurfaceVirtualDocument,
 } from "../workspace/WorkspaceSurface.js";
-import type { InteractionModeOption, SessionComposerHandle } from "../composer/index.js";
+import type { InteractionModeOption, SessionComposerHandle, SessionComposerSubmitContext } from "../composer/index.js";
 import type { ApplyResourceResult } from "../library/useApplyResource.js";
 import { ResizableSplit } from "../internal/ResizableSplit.js";
 import { SelectionStore } from "../internal/store/selection-store.js";
 import { useWorkspaceEditors, isVirtualEntryId } from "../internal/store/index.js";
 import { ThreadSelectionContext } from "../execution/ThreadSelectionContext.js";
 import { useSelectedThreadItem } from "../execution/useThreadSelection.js";
-import { MessageThread } from "../execution/MessageThread.js";
+import { MessageThread, type MessageThreadSlots } from "../execution/MessageThread.js";
 import { FileChangeProgressBar } from "../execution/FileChangeProgressBar.js";
 import { FileReviewDock } from "../execution/FileReviewDock.js";
 import {
@@ -47,11 +47,18 @@ import { usePlanDraft, planDraftKey, type PlanDraftController } from "./usePlanD
 import { PlanEditor } from "./PlanEditor.js";
 import { PlanStreamingDocument } from "./PlanStreamingDocument.js";
 import { PLAN_DOCUMENT_ENTRY_ID, PLAN_DOCUMENT_PATH } from "./plan-document.js";
+import { ARTIFACT_DOCUMENT_ENTRY_ID } from "./artifact-document.js";
+import { ArtifactDocument } from "../execution/ArtifactDocument.js";
 import { useSessionRailViews } from "./useSessionRailViews.js";
 import { useSessionPanel, type SessionPanelController } from "./useSessionPanel.js";
 import { SessionPanelChip } from "./SessionPanelChip.js";
 import { useSessionWriteBacks } from "./useSessionWriteBacks.js";
-import { useSessionArtifacts } from "./useSessionArtifacts.js";
+import { useWorkspaceReadRefs } from "./useWorkspaceReadRefs.js";
+import {
+  useSessionArtifacts,
+  artifactKey,
+  type SessionArtifactEntry,
+} from "./useSessionArtifacts.js";
 import type { SetupTabProps } from "./facets/SetupTab.js";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { RuntimeEnvProvider } from "./runtime-env.js";
@@ -222,6 +229,15 @@ export interface SessionViewerProps {
   readonly accessSlot?: ReactNode;
   /** Called after a resource is applied from the Artifacts tab. */
   readonly onApplied?: (result: ApplyResourceResult) => void;
+  /**
+   * Component overrides for the conversation thread's chrome (message
+   * bubbles, approval card, to-dos card, plan cards, thinking indicator) —
+   * forwarded to the inner {@link MessageThread}. See
+   * {@link MessageThreadSlots}. Define the object and its components at
+   * module level (or memoize) so thread rows keep their streaming
+   * re-render guarantees.
+   */
+  readonly threadSlots?: MessageThreadSlots;
   /** Additional CSS classes for the root container. */
   readonly className?: string;
 }
@@ -283,6 +299,7 @@ export function SessionViewer({
   headerActions,
   accessSlot,
   onApplied,
+  threadSlots,
   className,
 }: SessionViewerProps) {
   const flow = useSessionPageFlow({ sessionId, org, getRuntimeEnv });
@@ -455,6 +472,28 @@ export function SessionViewer({
     [sessionPlan, panel.openPlanDocument],
   );
 
+  // "Open artifact" (an Artifacts-facet row) → an editor-pane document tab.
+  // Writing the editors store re-renders only the panel subtree (which
+  // subscribes), never this streaming column. Plan artifacts are routed to the
+  // plan tab upstream (in ArtifactsTab), so they never reach here.
+  const handleOpenArtifact = useCallback(
+    (entry: SessionArtifactEntry) => {
+      panel.openArtifact(entry.artifact);
+    },
+    [panel.openArtifact],
+  );
+
+  // Double-click an artifact row → pin its tab (the leading single click already
+  // opened the preview via `handleOpenArtifact`). Mirrors the file tree's
+  // preview/pin split; plan artifacts are routed to the plan tab upstream (in
+  // ArtifactsTab) and never reach here.
+  const handleActivateArtifact = useCallback(
+    (entry: SessionArtifactEntry) => {
+      panel.pinArtifact(entry.artifact);
+    },
+    [panel.pinArtifact],
+  );
+
   // Open a transcript tool-call file path in the panel's read-only editor.
   // Resolves the (possibly absolute / subdir-prefixed) path to a
   // repo/root-relative selection the editor can fetch; on a definite hit it
@@ -544,6 +583,7 @@ export function SessionViewer({
               onDismissPlanAttachFailed={() => setPlanAttachFailed(false)}
               onFilePathClick={handleTranscriptFilePathClick}
               isEndUser={isEndUser}
+              threadSlots={threadSlots}
             />
           }
           secondary={
@@ -561,6 +601,8 @@ export function SessionViewer({
                 planDraft={planDraft}
                 openPlanExecutionId={openPlanExecutionId}
                 onOpenPlan={handleOpenPlan}
+                onOpenArtifact={handleOpenArtifact}
+                onActivateArtifact={handleActivateArtifact}
                 enableLocal={enableLocal}
                 onBrowseLocalFolder={onBrowseLocalFolder}
                 workspaceFileLister={workspaceFileLister}
@@ -607,6 +649,7 @@ interface ConversationColumnProps {
    */
   readonly onFilePathClick: (path: string) => boolean;
   readonly isEndUser: boolean;
+  readonly threadSlots?: MessageThreadSlots;
 }
 
 const ConversationColumn = memo(function ConversationColumn({
@@ -628,6 +671,7 @@ const ConversationColumn = memo(function ConversationColumn({
   onDismissPlanAttachFailed,
   onFilePathClick,
   isEndUser,
+  threadSlots,
 }: ConversationColumnProps) {
   const { conv } = flow;
   // Approval failures are NOT folded into this banner: they now surface in-card,
@@ -652,18 +696,55 @@ const ConversationColumn = memo(function ConversationColumn({
     void conv.stop();
   }, [conv.stop]);
 
-  // Edit-and-resubmit: stop the in-flight turn and pre-fill the composer with
-  // the original text. The append-only execution log can't be rewritten, so
-  // the user reviews the prefilled message and resubmits it as a NEW execution
-  // through the normal Send pipeline. The cancelled turn stays in history with
-  // its phase badge — an honest record rather than a silent edit.
+  // Edit-and-resubmit: stop the in-flight turn, pre-fill the composer with
+  // the original text, and remember which execution is being edited. The
+  // append-only execution log is never rewritten — submitting while editing
+  // creates a NEW execution that carries `supersedesExecutionId`, and the
+  // conversation read model hides the superseded turn so the edited message
+  // replaces the original in place (Cursor-style, stigmer/stigmer#181).
+  //
+  // The editing state is explicit (banner + cancel in the composer) so the
+  // supersede link only attaches when the user actually resubmits the edit.
+  // Cancelling drops the link — a subsequent unrelated message appends
+  // normally without hiding any history.
+  const [editingExecutionId, setEditingExecutionId] = useState<string | null>(
+    null,
+  );
+  const activeExecutionId = conv.activeStreamExecution?.metadata?.id ?? null;
+
   const handleEditMessage = useCallback(
     (text: string) => {
       void conv.stop();
+      setEditingExecutionId(activeExecutionId);
       composerRef.current?.setMessage(text);
       composerRef.current?.focus();
     },
-    [conv.stop, composerRef],
+    [conv.stop, activeExecutionId, composerRef],
+  );
+
+  const handleCancelEdit = useCallback(() => {
+    setEditingExecutionId(null);
+    composerRef.current?.setMessage("");
+  }, [composerRef]);
+
+  // Submit wrapper that attaches the supersede link while editing, then
+  // exits editing mode. Ordinary (non-editing) submits pass through as-is.
+  const handleComposerSubmit = useCallback(
+    (
+      message: string,
+      modelName?: string,
+      context?: SessionComposerSubmitContext,
+    ) => {
+      void flow.handleSubmit(
+        message,
+        modelName,
+        editingExecutionId
+          ? { ...context, supersedesExecutionId: editingExecutionId }
+          : context,
+      );
+      setEditingExecutionId(null);
+    },
+    [flow.handleSubmit, editingExecutionId],
   );
 
   // The composer-docked FileReviewDock sits OUTSIDE MessageThread, so the
@@ -703,6 +784,7 @@ const ConversationColumn = memo(function ConversationColumn({
         planActionsDisabled={!conv.canSendFollowUp || isBuildingFromPlan}
         planBuildPending={isBuildingFromPlan}
         contentColumn="center"
+        slots={threadSlots}
         className="flex-1"
       />
       <div className={CONVERSATION_COLUMN_CLASS}>
@@ -743,11 +825,13 @@ const ConversationColumn = memo(function ConversationColumn({
         </FilePathContext.Provider>
         <SessionComposer
           ref={composerRef}
-          onSubmit={flow.handleSubmit}
+          onSubmit={handleComposerSubmit}
           isSubmitting={conv.isSending}
           disabled={!conv.canSendFollowUp}
           onStop={conv.isStoppable ? handleStop : undefined}
           isStopping={conv.isStopping}
+          isEditing={editingExecutionId != null}
+          onCancelEdit={handleCancelEdit}
           org={org}
           harness={flow.harness}
           defaultModelId={modelId}
@@ -815,6 +899,10 @@ interface SessionPanelRegionProps {
   readonly openPlanExecutionId: string | null;
   /** Opens a plan in the plan tab (routed to the Artifacts facet's plan.md). */
   readonly onOpenPlan: (executionId: string) => void;
+  /** Opens an artifact as an editor-pane document (routed to the Artifacts facet). */
+  readonly onOpenArtifact: (entry: SessionArtifactEntry) => void;
+  /** Pins an artifact's document tab — the double-click half of the open/pin split. */
+  readonly onActivateArtifact: (entry: SessionArtifactEntry) => void;
   readonly enableLocal: boolean;
   readonly onBrowseLocalFolder?: () => Promise<string | null>;
   readonly workspaceFileLister?: WorkspaceFileLister;
@@ -836,6 +924,8 @@ function SessionPanelRegion({
   planDraft,
   openPlanExecutionId,
   onOpenPlan,
+  onOpenArtifact,
+  onActivateArtifact,
   enableLocal,
   onBrowseLocalFolder,
   workspaceFileLister,
@@ -847,6 +937,9 @@ function SessionPanelRegion({
   const { editors, activeKey, activeFile, reveal } = useWorkspaceEditors(
     panel.editorsStore,
   );
+  // Session artifacts, deduped by identity — the source both the Artifacts
+  // rail-view badge and the open artifact document tabs resolve against.
+  const { artifacts: sessionArtifacts } = useSessionArtifacts(flow.allExecutions);
 
   // Honor a pending jump-to-line reveal only while it targets the active editor
   // (an EditorReveal is structurally a RevealTarget). Switching tabs changes
@@ -902,30 +995,28 @@ function SessionPanelRegion({
   // tab and its turn then ended without publishing, with no earlier plan to
   // fall back to.
   const openPlanIsLatest = openPlan?.executionId === sessionPlan?.executionId;
-  const virtualDocuments = useMemo<readonly SurfaceVirtualDocument[]>(() => {
-    return [
-      {
-        entryId: PLAN_DOCUMENT_ENTRY_ID,
-        path: PLAN_DOCUMENT_PATH,
-        content: streamingPlan ? (
-          <PlanStreamingDocument
-            key={`streaming-${streamingPlan.executionId}`}
-            displayText={streamingPlan.displayText}
-          />
-        ) : openPlan ? (
-          <PlanEditor
-            key={planDraftKey(openPlan)}
-            plan={openPlan}
-            draft={openPlanIsLatest ? planDraft : undefined}
-            onBuildFromPlan={openPlanIsLatest ? onImplementPlan : undefined}
-            buildDisabled={implementPlanDisabled}
-            readOnly={!openPlanIsLatest}
-          />
-        ) : (
-          <PlanUnavailableNotice />
-        ),
-      },
-    ];
+  const planVirtualDocument = useMemo<SurfaceVirtualDocument>(() => {
+    return {
+      entryId: PLAN_DOCUMENT_ENTRY_ID,
+      path: PLAN_DOCUMENT_PATH,
+      content: streamingPlan ? (
+        <PlanStreamingDocument
+          key={`streaming-${streamingPlan.executionId}`}
+          displayText={streamingPlan.displayText}
+        />
+      ) : openPlan ? (
+        <PlanEditor
+          key={planDraftKey(openPlan)}
+          plan={openPlan}
+          draft={openPlanIsLatest ? planDraft : undefined}
+          onBuildFromPlan={openPlanIsLatest ? onImplementPlan : undefined}
+          buildDisabled={implementPlanDisabled}
+          readOnly={!openPlanIsLatest}
+        />
+      ) : (
+        <PlanUnavailableNotice />
+      ),
+    };
   }, [
     streamingPlan,
     openPlan,
@@ -935,6 +1026,50 @@ function SessionPanelRegion({
     implementPlanDisabled,
   ]);
 
+  // The open artifact document tabs (the artifact virtual-document FAMILY).
+  // Built in a SEPARATE memo from the plan doc so artifact-tab churn never
+  // recreates the plan doc (and vice versa). Bounded to what is actually open:
+  // one document per editor whose entry id is the artifact family's, resolved
+  // back to its `SessionArtifactEntry` by the same `artifactKey` used to open
+  // it (single source of truth for artifact identity). Only the ACTIVE doc's
+  // `content` is mounted by the surface, so building these elements is cheap;
+  // keying on `contentHash` remounts a tab whose artifact was overwritten by a
+  // later execution. A tab whose artifact no longer exists degrades to an
+  // honest notice rather than vanishing.
+  const artifactByKey = useMemo(
+    () =>
+      new Map(sessionArtifacts.map((entry) => [artifactKey(entry.artifact), entry])),
+    [sessionArtifacts],
+  );
+  const artifactVirtualDocuments = useMemo<readonly SurfaceVirtualDocument[]>(() => {
+    return editors
+      .filter((editor) => editor.entryId === ARTIFACT_DOCUMENT_ENTRY_ID)
+      .map((editor) => {
+        const entry = artifactByKey.get(editor.path);
+        return {
+          entryId: ARTIFACT_DOCUMENT_ENTRY_ID,
+          path: editor.path,
+          content: entry ? (
+            <ArtifactDocument
+              key={entry.artifact.contentHash || editor.path}
+              artifact={entry.artifact}
+              executionId={entry.executionId}
+              org={org}
+              isTerminal={entry.isTerminal}
+              onApplied={onApplied}
+            />
+          ) : (
+            <ArtifactUnavailableNotice />
+          ),
+        };
+      });
+  }, [editors, artifactByKey, org, onApplied]);
+
+  const virtualDocuments = useMemo<readonly SurfaceVirtualDocument[]>(
+    () => [planVirtualDocument, ...artifactVirtualDocuments],
+    [planVirtualDocument, artifactVirtualDocuments],
+  );
+
   const handleRemoveAgent = useCallback(() => {
     flow.setAgentRef(null);
     flow.setResolution(null);
@@ -1001,6 +1136,8 @@ function SessionPanelRegion({
     onApplied,
     onImplementPlan,
     onOpenPlan,
+    onOpenArtifact,
+    onActivateArtifact,
   });
 
   // Explorer-footer folder attach (desktop only — needs the native picker).
@@ -1011,9 +1148,19 @@ function SessionPanelRegion({
     if (path) flow.workspace.addLocalPath(path);
   }, [onBrowseLocalFolder, flow.workspace.addLocalPath]);
 
+  // Entries decorated with per-entry read refs (the latest write-back commit
+  // SHA), so the surface's read-side capabilities — file viewer, tree listing,
+  // name search — resolve at the ref the agent's changes actually live on. A
+  // read-side projection only: `flow.workspace.entries` stays undecorated for
+  // setup and session input.
+  const surfaceEntries = useWorkspaceReadRefs(
+    flow.allExecutions,
+    flow.workspace.entries,
+  );
+
   return (
     <WorkspaceSurface
-      entries={flow.workspace.entries}
+      entries={surfaceEntries}
       lister={workspaceFileLister}
       reader={workspaceFileReader}
       searcher={workspaceContentSearcher}
@@ -1125,6 +1272,28 @@ function PlanUnavailableNotice() {
   );
 }
 
+/**
+ * Shown in an artifact document tab whose artifact is no longer among the
+ * session's outputs (an edge only reachable if the executions backing the tab
+ * changed underneath it). The tab stays closable; the content is honest rather
+ * than blank.
+ */
+function ArtifactUnavailableNotice() {
+  return (
+    <div
+      role="status"
+      className="mx-auto flex w-full max-w-3xl flex-col items-center gap-1 px-4 py-8 text-center"
+    >
+      <p className="text-xs font-medium text-foreground">
+        This artifact is no longer available.
+      </p>
+      <p className="text-xs text-muted-foreground">
+        It may have been replaced by a newer version of this session.
+      </p>
+    </div>
+  );
+}
+
 /**
  * Non-blocking notice for a build that fell back to message-only implement
  * (the approved plan.md could not be uploaded/attached). The build itself

package/src/session/__tests__/SessionViewer-artifactTabs.test.tsx

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, act, fireEvent } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import {
+  ExecutionArtifactKind,
+  ExecutionPhase,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ARTIFACT_DOCUMENT_ENTRY_ID } from "../artifact-document";
+import { artifactKey, type SessionArtifactEntry } from "../useSessionArtifacts";
+
+// ---------------------------------------------------------------------------
+// Wiring-contract test for the Artifacts facet's open/pin gestures. The
+// `onOpenArtifact` (single-click preview) and `onActivateArtifact` (double-click
+// pin) callbacks must thread from SessionViewer, through the intermediate
+// SessionPanelRegion, into useSessionRailViews' <ArtifactsTab>, and — when
+// invoked — land as an artifact virtual-document tab on the editors store.
+// WorkspaceSurface renders as a prop-capturing probe; the store + panel-region
+// wire between them is the subject under test. Tab MECHANICS (preview-slot
+// reuse, pin promotion) live in workspace-editors-store.test.ts and are not
+// re-tested here.
+// ---------------------------------------------------------------------------
+
+type CapturedProps = Record<string, unknown>;
+
+const threadProps: CapturedProps[] = [];
+vi.mock("../../execution/MessageThread", () => ({
+  MessageThread: (props: CapturedProps) => {
+    threadProps.push(props);
+    return <div data-testid="thread-probe" />;
+  },
+}));
+
+const surfaceProps: CapturedProps[] = [];
+vi.mock("../../workspace/WorkspaceSurface", () => ({
+  WorkspaceSurface: (props: CapturedProps) => {
+    surfaceProps.push(props);
+    return <div data-testid="surface-probe" />;
+  },
+}));
+
+vi.mock("../../composer", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../composer")>();
+  return {
+    ...actual,
+    SessionComposer: () => <div data-testid="composer-probe" />,
+  };
+});
+
+const artifact = create(ExecutionArtifactSchema, {
+  name: "agent.yaml",
+  kind: ExecutionArtifactKind.FILE,
+  sizeBytes: 512n,
+  sandboxPath: ".stigmer/agent.yaml",
+  storageKey: "artifacts/aex_1/agent.yaml",
+});
+
+const artifactExecution = create(AgentExecutionSchema, {
+  metadata: { id: "aex_1" },
+  status: {
+    phase: ExecutionPhase.EXECUTION_COMPLETED,
+    artifacts: [artifact],
+  },
+});
+
+const entry: SessionArtifactEntry = {
+  artifact,
+  executionId: "aex_1",
+  isTerminal: true,
+  hasNameCollision: false,
+};
+
+const stubWorkspace = {
+  entries: [],
+  hasEntries: false,
+  toInput: vi.fn().mockReturnValue([]),
+  addGitRepo: vi.fn(),
+  addLocalPath: vi.fn(),
+  remove: vi.fn(),
+  clear: vi.fn(),
+  clearLocal: vi.fn(),
+};
+
+const stubConv = {
+  session: { spec: {} },
+  isLoading: false,
+  loadError: null,
+  completedExecutions: [artifactExecution],
+  activeStreamExecution: null,
+  pendingUserMessage: null,
+  workspaceEntries: [],
+  fileChangeSets: [],
+  submitFileDecision: vi.fn(),
+  submittingFileDecisionKeys: new Set<string>(),
+  fileDecisionErrors: new Map<string, Error>(),
+  sendError: null,
+  stopError: null,
+  streamError: null,
+  reconnectStream: vi.fn(),
+  submittingApprovalIds: new Set<string>(),
+  approvalErrors: new Map<string, Error>(),
+  isStoppable: false,
+  isStopping: false,
+  isSending: false,
+  canSendFollowUp: true,
+  isReconnecting: false,
+  connectTimedOut: false,
+  isSlow: false,
+  stop: vi.fn(),
+  retryLastSend: vi.fn(),
+};
+
+const stubSessionPageFlow = {
+  conv: stubConv,
+  harness: "native" as const,
+  executionTarget: undefined,
+  model: [undefined, vi.fn()] as const,
+  interactionMode: ["agent" as const, vi.fn()] as const,
+  agentRef: { org: "acme", slug: "support-bot" },
+  setAgentRef: vi.fn(),
+  resolution: null,
+  setResolution: vi.fn(),
+  isDefaultAgent: false,
+  mcpServerUsages: [],
+  setMcpServerUsages: vi.fn(),
+  skillRefs: [],
+  setSkillRefs: vi.fn(),
+  workspace: stubWorkspace,
+  sessionVariables: { entries: [], isEmpty: true, clear: vi.fn() },
+  autoApproveAll: false,
+  setAutoApproveAll: vi.fn(),
+  handleSubmit: vi.fn(),
+  submitError: null as Error | null,
+  displayExecution: artifactExecution,
+  allExecutions: [artifactExecution],
+  sandboxWorkspaceRoot: "/home/daytona/workspace",
+};
+vi.mock("../useSessionPageFlow", () => ({
+  useSessionPageFlow: () => stubSessionPageFlow,
+}));
+
+vi.mock("../../hooks", () => ({
+  useStigmer: () => ({
+    agentExecution: {
+      uploadAttachment: vi.fn(),
+      getArtifactContent: vi.fn(),
+    },
+  }),
+}));
+
+import { SessionViewer } from "../SessionViewer";
+
+/** The latest editors array the (mocked) WorkspaceSurface received. */
+function latestEditors(): ReadonlyArray<{
+  entryId: string;
+  path: string;
+  preview: boolean;
+}> {
+  return (surfaceProps.at(-1)?.editors ?? []) as never;
+}
+
+/** Read a callback off the rail-view <ArtifactsTab> element the surface received. */
+function artifactsTabCallback(
+  name: "onOpenArtifact" | "onActivateArtifact",
+): (entry: SessionArtifactEntry) => void {
+  const views = surfaceProps.at(-1)?.extraViews as
+    | ReadonlyArray<{ id: string; content: { props: CapturedProps } }>
+    | undefined;
+  const artifactsView = views?.find((v) => v.id === "artifacts");
+  if (!artifactsView) throw new Error("Artifacts rail view not present");
+  return artifactsView.content.props[name] as (e: SessionArtifactEntry) => void;
+}
+
+beforeEach(() => {
+  threadProps.length = 0;
+  surfaceProps.length = 0;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("SessionViewer — Artifacts facet open/pin wiring", () => {
+  it("threads onOpenArtifact + onActivateArtifact into the Artifacts rail view", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+    fireEvent.click(screen.getByRole("button", { name: "Show panel" }));
+
+    expect(typeof artifactsTabCallback("onOpenArtifact")).toBe("function");
+    expect(typeof artifactsTabCallback("onActivateArtifact")).toBe("function");
+  });
+
+  it("opening an artifact lands a PREVIEW tab; activating it pins the tab", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+    fireEvent.click(screen.getByRole("button", { name: "Show panel" }));
+
+    // Single-click preview → one preview tab keyed by the artifact identity.
+    act(() => artifactsTabCallback("onOpenArtifact")(entry));
+    expect(latestEditors()).toEqual([
+      { entryId: ARTIFACT_DOCUMENT_ENTRY_ID, path: artifactKey(artifact), preview: true },
+    ]);
+
+    // Double-click pin → the same tab, now persistent.
+    act(() => artifactsTabCallback("onActivateArtifact")(entry));
+    expect(latestEditors()).toEqual([
+      { entryId: ARTIFACT_DOCUMENT_ENTRY_ID, path: artifactKey(artifact), preview: false },
+    ]);
+  });
+});