feat: artifactAutoOpen — auto-open artifact detail panels (default on)

packages/react-headless/src/index.ts

@@ -19,6 +19,7 @@ export {
 } from "./store/ArtifactRenderersContext";
 export { defineArtifactRenderer } from "./store/artifactRendererTypes";
 export { useArtifactStorage } from "./store/ArtifactStorageContext";
+export { artifactViewId, parseArtifactViewId } from "./store/artifactViewId";
 export { ChatProvider } from "./store/ChatProvider";
 export { DetailedViewContext, useDetailedViewStore } from "./store/DetailedViewContext";
 export { ThreadContextContext, useThreadContextStore } from "./store/ThreadContextContext";

packages/react-headless/src/store/ChatProvider.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState, type FC } from "react";
 import { createDefaultInMemoryStorage } from "../adapters/_defaultStorage";
+import { useArtifactAutoOpenWatcher } from "./artifactAutoOpenWatcher";
 import { ArtifactCategoriesContext } from "./ArtifactCategoriesContext";
 import {
   ArtifactRenderersContext,
@@ -22,6 +23,7 @@ export const ChatProvider: FC<ChatProviderProps> = ({
   llm,
   artifactRenderers,
   artifactCategories,
+  artifactAutoOpen,
 }) => {
   const [resolvedStorage] = useState(() => storage ?? createDefaultInMemoryStorage());
   const [chatStore] = useState(() => createChatStore({ storage: resolvedStorage, llm }));
@@ -64,6 +66,13 @@ export const ChatProvider: FC<ChatProviderProps> = ({
     return unsubscribe;
   }, [chatStore, detailedViewStore, threadContextStore]);
 
+  useArtifactAutoOpenWatcher(
+    artifactAutoOpen ?? true,
+    chatStore,
+    threadContextStore,
+    detailedViewStore,
+  );
+
   return (
     <ChatContext.Provider value={chatStore}>
       <DetailedViewContext.Provider value={detailedViewStore}>

packages/react-headless/src/store/__tests__/artifactAutoOpenWatcher.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import { evaluateRegisteredArtifacts } from "../artifactAutoOpenWatcher";
+import { createDetailedViewStore } from "../createDetailedViewStore";
+import type { ArtifactEntry } from "../threadContextTypes";
+
+const entry = (id: string, version = 1): ArtifactEntry => ({
+  id,
+  version,
+  heading: `${id} v${version}`,
+  type: "test_artifact",
+});
+
+const registry = (...entries: ArtifactEntry[]): Record<string, ArtifactEntry[]> => {
+  const out: Record<string, ArtifactEntry[]> = {};
+  for (const e of entries) (out[e.id] ??= []).push(e);
+  return out;
+};
+
+describe("evaluateRegisteredArtifacts", () => {
+  it("opens a newly registered artifact while the stream runs", () => {
+    const store = createDetailedViewStore();
+    const claimed = new Set<string>();
+    const opened = evaluateRegisteredArtifacts(registry(entry("art")), true, claimed, store);
+    expect(opened).toBe(true);
+    expect(store.getState().activeDetailedViewId).toBe("art:1");
+    expect(claimed.has("art:1")).toBe(true);
+  });
+
+  it("a user close sticks across re-registrations", () => {
+    const store = createDetailedViewStore();
+    const claimed = new Set<string>();
+    const arts = registry(entry("art"));
+    evaluateRegisteredArtifacts(arts, true, claimed, store);
+    store.getState().setActiveDetailedView(null);
+    const opened = evaluateRegisteredArtifacts(arts, true, claimed, store);
+    expect(opened).toBe(false);
+    expect(store.getState().activeDetailedViewId).toBeNull();
+  });
+
+  it("an edit re-opens: a new version gets a fresh chance, even after a close", () => {
+    const store = createDetailedViewStore();
+    const claimed = new Set<string>();
+    evaluateRegisteredArtifacts(registry(entry("art", 1)), true, claimed, store);
+    store.getState().setActiveDetailedView(null);
+    const opened = evaluateRegisteredArtifacts(
+      registry(entry("art", 1), entry("art", 2)),
+      true,
+      claimed,
+      store,
+    );
+    expect(opened).toBe(true);
+    expect(store.getState().activeDetailedViewId).toBe("art:2");
+  });
+
+  it("the same version never re-opens after a close", () => {
+    const store = createDetailedViewStore();
+    const claimed = new Set<string>();
+    const arts = registry(entry("art", 2));
+    evaluateRegisteredArtifacts(arts, true, claimed, store);
+    expect(store.getState().activeDetailedViewId).toBe("art:2");
+    store.getState().setActiveDetailedView(null);
+    expect(evaluateRegisteredArtifacts(arts, true, claimed, store)).toBe(false);
+    expect(store.getState().activeDetailedViewId).toBeNull();
+  });
+
+  it("opens the latest registered version of an id", () => {
+    const store = createDetailedViewStore();
+    evaluateRegisteredArtifacts(registry(entry("art", 1), entry("art", 3)), true, new Set(), store);
+    expect(store.getState().activeDetailedViewId).toBe("art:3");
+  });
+
+  it("mayOpen=false (nothing streaming): never opens, still claims", () => {
+    const store = createDetailedViewStore();
+    const claimed = new Set<string>();
+    const arts = registry(entry("old"));
+    const opened = evaluateRegisteredArtifacts(arts, false, claimed, store);
+    expect(opened).toBe(false);
+    expect(store.getState().activeDetailedViewId).toBeNull();
+    expect(claimed.has("old:1")).toBe(true);
+    evaluateRegisteredArtifacts(arts, true, claimed, store);
+    expect(store.getState().activeDetailedViewId).toBeNull();
+  });
+
+  it("only the first artifact of a pass opens; the second is claimed but ignored", () => {
+    const store = createDetailedViewStore();
+    const claimed = new Set<string>();
+    const arts = registry(entry("a1"), entry("a2"));
+    const opened = evaluateRegisteredArtifacts(arts, true, claimed, store);
+    expect(opened).toBe(true);
+    expect(store.getState().activeDetailedViewId).toBe("a1:1");
+    expect(claimed.has("a2:1")).toBe(true);
+    store.getState().setActiveDetailedView(null);
+    expect(evaluateRegisteredArtifacts(arts, true, claimed, store)).toBe(false);
+    expect(store.getState().activeDetailedViewId).toBeNull();
+  });
+
+  it("a new artifact takes over an already-open panel", () => {
+    const store = createDetailedViewStore();
+    const claimed = new Set<string>();
+    store.getState().setActiveDetailedView("user-panel");
+    const opened = evaluateRegisteredArtifacts(registry(entry("art")), true, claimed, store);
+    expect(opened).toBe(true);
+    expect(store.getState().activeDetailedViewId).toBe("art:1");
+  });
+
+  it("thread switch (fresh claim set) re-arms for the next thread", () => {
+    const store = createDetailedViewStore();
+    const arts = registry(entry("art"));
+    evaluateRegisteredArtifacts(arts, true, new Set(), store);
+    expect(store.getState().activeDetailedViewId).toBe("art:1");
+    store.getState().reset();
+    evaluateRegisteredArtifacts(arts, true, new Set(), store);
+    expect(store.getState().activeDetailedViewId).toBe("art:1");
+  });
+});

packages/react-headless/src/store/__tests__/artifactViewId.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { artifactViewId, parseArtifactViewId } from "../artifactViewId";
+
+describe("artifactViewId", () => {
+  it("builds id:version", () => {
+    expect(artifactViewId("art-1", 3)).toBe("art-1:3");
+  });
+
+  it("round-trips through parse", () => {
+    expect(parseArtifactViewId(artifactViewId("art-1", 3))).toEqual({ id: "art-1", version: 3 });
+  });
+
+  it("handles artifact ids that contain colons", () => {
+    expect(parseArtifactViewId(artifactViewId("ns:art", 2))).toEqual({ id: "ns:art", version: 2 });
+  });
+
+  it("returns null for non-artifact view ids", () => {
+    expect(parseArtifactViewId("custom-panel")).toBeNull();
+    expect(parseArtifactViewId("art:not-a-number")).toBeNull();
+    expect(parseArtifactViewId(":r1:")).toBeNull();
+  });
+});

packages/react-headless/src/store/artifactAutoOpenWatcher.ts

@@ -0,0 +1,105 @@
+import { useEffect, useRef } from "react";
+import { artifactViewId } from "./artifactViewId";
+import type { createChatStore } from "./createChatStore";
+import type { createDetailedViewStore } from "./createDetailedViewStore";
+import type { createThreadContextStore } from "./createThreadContextStore";
+import type { ArtifactEntry } from "./threadContextTypes";
+
+/**
+ * One pass over every artifact registered in the thread. Each artifact
+ * version (`id:version`) gets a single chance to auto-open — recorded in
+ * `claimedIds` the first time we see it, whether or not it opens — so an
+ * edit's new version qualifies again. Returns true when a panel opened.
+ */
+export function evaluateRegisteredArtifacts(
+  artifacts: Record<string, ArtifactEntry[]>, // all artifacts in the thread context: id → versions, ascending
+  mayOpen: boolean, // "is opening allowed right now" — streaming and nothing opened yet this stream
+  claimedIds: Set<string>, // "id:version" keys that already used their chance (cleared per thread)
+  detailedViewStore: ReturnType<typeof createDetailedViewStore>,
+): boolean {
+  let opened = false;
+  //  artifacts = {
+  //   "report-abc": [ {id:"report-abc", version:1, …}, {id:"report-abc", version:2, …} ],
+  //   "deck-xyz":   [ {id:"deck-xyz",  version:1, …} ],
+  // }
+  // artifactsWithVersions = [
+  //   [ {id:"report-abc", version:1, …}, {id:"report-abc", version:2, …} ],
+  //   [ {id:"deck-xyz",  version:1, …} ],
+  // ]
+  const artifactsWithVersions = Object.values(artifacts);
+  for (let i = 0; i < artifactsWithVersions.length; i++) {
+    const versions = artifactsWithVersions[i];
+    // versions = [ {id:"report-abc", version:1, …}, {id:"report-abc", version:2, …} ]
+    // no list at this index (can't happen; strict TS guard)
+    if (!versions) continue;
+    // versions are sorted ascending, so the last entry is the newest one
+    // latest = {id:"report-abc", version:2, …}
+    const latest = versions[versions.length - 1];
+    // no versions at all (can't happen in practice; keeps strict TS happy)
+    if (!latest) continue;
+    // claim keyed by id:version so an EDIT (new version, same id) gets a
+    // fresh chance to open, while re-registrations of the same version are
+    // ignored (a user's close sticks)
+    const key = artifactViewId(latest.id, latest.version);
+    if (claimedIds.has(key)) continue;
+    claimedIds.add(key);
+    // allowed to open right now? and only one open per pass
+    if (!mayOpen || opened) continue;
+    // takes over the panel even if it is already open: a new stream's first
+    // artifact (or a streaming edit) re-points an open panel to itself
+    detailedViewStore.getState().setActiveDetailedView(key);
+    opened = true;
+  }
+  return opened;
+}
+
+/**
+ * Runs inside ChatProvider: re-evaluates whenever an artifact registers in
+ * the thread context, opening at most one artifact per stream.
+ */
+export function useArtifactAutoOpenWatcher(
+  artifactAutoOpen: boolean,
+  chatStore: ReturnType<typeof createChatStore>,
+  threadContextStore: ReturnType<typeof createThreadContextStore>,
+  detailedViewStore: ReturnType<typeof createDetailedViewStore>,
+): void {
+  // "did this stream already auto-open something" — re-armed on each new stream
+  const openedThisRunRef = useRef(false);
+  // id:version keys that used their one auto-open chance — cleared on thread switch
+  const claimedIdsRef = useRef(new Set<string>());
+
+  useEffect(() => {
+    if (!artifactAutoOpen) return;
+    const unsubscribeThread = chatStore.subscribe(
+      (s) => s.selectedThreadId,
+      () => {
+        claimedIdsRef.current.clear();
+        openedThisRunRef.current = false;
+      },
+    );
+    const unsubscribeRun = chatStore.subscribe(
+      (s) => s.isRunning,
+      (isRunning) => {
+        if (isRunning) openedThisRunRef.current = false;
+      },
+    );
+    const unsubscribeArtifacts = threadContextStore.subscribe(
+      (s) => s.artifacts,
+      (artifacts) => {
+        const mayOpen = chatStore.getState().isRunning && !openedThisRunRef.current;
+        if (
+          evaluateRegisteredArtifacts(artifacts, mayOpen, claimedIdsRef.current, detailedViewStore)
+        ) {
+          openedThisRunRef.current = true;
+        }
+      },
+      // also evaluate artifacts that registered before this watcher mounted
+      { fireImmediately: true },
+    );
+    return () => {
+      unsubscribeThread();
+      unsubscribeRun();
+      unsubscribeArtifacts();
+    };
+  }, [artifactAutoOpen, chatStore, threadContextStore, detailedViewStore]);
+}

packages/react-headless/src/store/artifactViewId.ts

@@ -0,0 +1,21 @@
+/**
+ * Builds the detailed-view id for an artifact version. This is the contract
+ * between everything that opens artifact panels (auto-open watcher, workspace
+ * rail) and the renderer that registers them — always build/read the id
+ * through these helpers, never hand-roll the string.
+ */
+export function artifactViewId(id: string, version: number): string {
+  return `${id}:${version}`;
+}
+
+/**
+ * Splits a detailed-view id back into artifact id + version. Returns null
+ * when the string isn't an artifact view id (e.g. a useId fallback).
+ */
+export function parseArtifactViewId(viewId: string): { id: string; version: number } | null {
+  const sep = viewId.lastIndexOf(":");
+  if (sep <= 0) return null;
+  const versionPart = viewId.slice(sep + 1);
+  if (!/^\d+$/.test(versionPart)) return null;
+  return { id: viewId.slice(0, sep), version: Number(versionPart) };
+}

packages/react-headless/src/store/types.ts

@@ -91,5 +91,6 @@ export interface ChatProviderProps {
    * artifact browser's pre-applied filters, and workspace section grouping.
    */
   artifactCategories?: ArtifactCategory[];
+  artifactAutoOpen?: boolean;
   children: React.ReactNode;
 }

packages/react-ui/src/components/AgentInterface/AgentInterface.tsx

@@ -183,6 +183,7 @@ export const AgentInterface: AgentInterfaceComponent = ((props: AgentInterfacePr
     llm,
     artifactRenderers,
     artifactCategories,
+    artifactAutoOpen,
     componentLibrary,
     components,
     theme,
@@ -240,6 +241,7 @@ export const AgentInterface: AgentInterfaceComponent = ((props: AgentInterfacePr
         llm={llm}
         artifactRenderers={artifactRenderers}
         artifactCategories={artifactCategories}
+        artifactAutoOpen={artifactAutoOpen}
       >
         <NavProvider path={path} defaultPath={defaultPath} onNavigate={onNavigate}>
           <StartersProvider starters={starters} starterVariant={starterVariant}>

packages/react-ui/src/components/AgentInterface/Workspace.tsx

@@ -1,4 +1,5 @@
 import {
+  artifactViewId,
   useActiveDetailedView,
   useArtifactCategories,
   useArtifactList,
@@ -156,7 +157,7 @@ const WorkspaceSection = ({
 };
 
 const WorkspaceItem = ({ entry }: { entry: ArtifactEntry }) => {
-  const viewId = `${entry.id}:${entry.version}`;
+  const viewId = artifactViewId(entry.id, entry.version);
   const { isActive } = useDetailedView(viewId);
   const store = useDetailedViewStore();
   const onClick = () => store.getState().setActiveDetailedView(viewId);

packages/react-ui/src/components/OpenUIChat/withChatProvider.tsx

@@ -26,6 +26,7 @@ export function withChatProvider<ExtraProps = {}>(WrappedComponent: React.Compon
       llm,
       artifactRenderers,
       artifactCategories,
+      artifactAutoOpen,
       theme,
       disableThemeProvider,
       ...innerProps
@@ -65,6 +66,7 @@ export function withChatProvider<ExtraProps = {}>(WrappedComponent: React.Compon
           llm={llm}
           artifactRenderers={artifactRenderers}
           artifactCategories={artifactCategories}
+          artifactAutoOpen={artifactAutoOpen}
         >
           <WrappedComponent {...finalInnerProps} />
         </ChatProvider>

packages/react-ui/src/components/_shared/tool-renderer/ToolActivityRenderer.tsx

@@ -1,4 +1,6 @@
 import {
+  artifactViewId,
+  parseArtifactViewId,
   useDetailedView,
   useDetailedViewStore,
   useThreadContextStore,
@@ -89,7 +91,7 @@ export function ToolActivityRenderer<Props>({
 
   // viewId derives from meta when present, otherwise from React's useId so
   // `controls.open` still works for an inline-only renderer.
-  const viewId = meta ? `${meta.id}:${meta.version}` : fallbackId;
+  const viewId = meta ? artifactViewId(meta.id, meta.version) : fallbackId;
 
   // Register entry on mount; unregister on unmount or when (id, version) changes.
   useEffect(() => {
@@ -126,9 +128,10 @@ export function ToolActivityRenderer<Props>({
     if (!meta) return;
     const dv = dvStore.getState();
     const active = dv.activeDetailedViewId;
-    if (!active || active === viewId || !active.startsWith(`${meta.id}:`)) return;
-    const activeVersion = Number(active.slice(meta.id.length + 1));
-    if (!Number.isFinite(activeVersion) || meta.version > activeVersion) {
+    if (!active || active === viewId) return;
+    const parsed = parseArtifactViewId(active);
+    if (!parsed || parsed.id !== meta.id) return;
+    if (meta.version > parsed.version) {
       dv.setActiveDetailedView(viewId);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps