@stigmer/react 3.4.0 → 3.4.1

package/skill/useSkillCount.d.ts

@@ -12,6 +12,8 @@ export interface UseSkillCountOptions {
      * @default "org"
      */
     readonly scope?: ResourceListScope;
+    /** Opaque token that forces a recount when its value changes. */
+    readonly refetchToken?: unknown;
 }
 /** Return value of {@link useSkillCount}. */
 export interface UseSkillCountReturn {

package/skill/useSkillCount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSkillCount.d.ts","sourceRoot":"","sources":["../../src/skill/useSkillCount.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE9E,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,mBAAmB,CAUrB"}
+{"version":3,"file":"useSkillCount.d.ts","sourceRoot":"","sources":["../../src/skill/useSkillCount.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE9E,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,mBAAmB,CAUrB"}

package/skill/useSkillCount.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSkillCount.js","sourceRoot":"","sources":["../../src/skill/useSkillCount.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAA0B,MAAM,oBAAoB,CAAC;AAgC9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAkB,EAClB,OAA8B;IAE9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,MAAgD,EAAE,EAAE,CACnD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAC5B,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"useSkillCount.js","sourceRoot":"","sources":["../../src/skill/useSkillCount.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAA0B,MAAM,oBAAoB,CAAC;AAkC9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAkB,EAClB,OAA8B;IAE9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,MAAgD,EAAE,EAAE,CACnD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAC5B,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/src/agent/useAgentCount.ts

@@ -17,6 +17,8 @@ export interface UseAgentCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useAgentCount}. */

package/src/api-key/CreateApiKeyForm.tsx

@@ -22,6 +22,12 @@ export interface CreateApiKeyFormProps {
   readonly onCreated?: (apiKey: ApiKey) => void;
   /** Fired when the user cancels creation. */
   readonly onCancel?: () => void;
+  /**
+   * Seeds the name field on mount (e.g. a suggested key name, or a demo
+   * scenario depicting the form mid-fill). One-time: consumed on mount;
+   * subsequent changes are ignored. The field stays fully editable.
+   */
+  readonly initialName?: string;
   /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
@@ -51,11 +57,12 @@ export function CreateApiKeyForm({
   org,
   onCreated,
   onCancel,
+  initialName = "",
   className,
 }: CreateApiKeyFormProps) {
   const { create, isCreating, error, clearError } = useCreateApiKey();
 
-  const [name, setName] = useState("");
+  const [name, setName] = useState(initialName);
   const [expiry, setExpiry] = useState<ExpiryOption>("never");
 
   const trimmedName = name.trim();

package/src/api-key/__tests__/CreateApiKeyForm.test.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { CreateApiKeyForm } from "../CreateApiKeyForm";
+
+afterEach(cleanup);
+
+function createWrapper() {
+  const mockClient = {
+    apiKey: { create: vi.fn() },
+  } as unknown as Stigmer;
+
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={mockClient}>
+      {children}
+    </StigmerContext.Provider>
+  );
+}
+
+function nameInput(): HTMLInputElement {
+  return screen.getByLabelText("Name") as HTMLInputElement;
+}
+
+function submitButton(): HTMLButtonElement {
+  return screen.getByRole("button", {
+    name: "Create API key",
+  }) as HTMLButtonElement;
+}
+
+describe("CreateApiKeyForm initialName", () => {
+  it("starts with an empty name and a disabled submit by default", () => {
+    render(<CreateApiKeyForm org="acme" />, { wrapper: createWrapper() });
+
+    expect(nameInput().value).toBe("");
+    expect(submitButton().disabled).toBe(true);
+  });
+
+  it("seeds the name field and enables submit when initialName is set", () => {
+    render(<CreateApiKeyForm org="acme" initialName="quickstart-key" />, {
+      wrapper: createWrapper(),
+    });
+
+    expect(nameInput().value).toBe("quickstart-key");
+    expect(submitButton().disabled).toBe(false);
+  });
+
+  it("keeps the seeded field editable — initialName is a seed, not a lock", () => {
+    render(<CreateApiKeyForm org="acme" initialName="quickstart-key" />, {
+      wrapper: createWrapper(),
+    });
+
+    fireEvent.change(nameInput(), { target: { value: "renamed-key" } });
+
+    expect(nameInput().value).toBe("renamed-key");
+  });
+});

package/src/datastore/useDatastoreCount.ts

@@ -17,6 +17,8 @@ export interface UseDatastoreCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useDatastoreCount}. */

package/src/index.ts

@@ -156,7 +156,9 @@ export {
   channelSessionExternalUserKey,
   SessionViewer,
   NewSessionViewer,
+  SessionViewerLayout,
   useSessionPanel,
+  useSessionRailViews,
   usePlanDraft,
   planDraftKey,
   PlanEditor,
@@ -201,8 +203,10 @@ export type {
   SearchResultGroup,
   SessionViewerProps,
   NewSessionViewerProps,
+  SessionViewerLayoutProps,
   SessionPanelController,
   UseSessionPanelOptions,
+  UseSessionRailViewsOptions,
   PlanDraftController,
   PlanEditorProps,
   PlanStreamingDocumentProps,
@@ -526,6 +530,10 @@ export {
   useUpdateMcpServer,
   mcpServerToInput,
   toServerKey,
+  IdentityTransportStep,
+  EnvironmentAuthStep,
+  ReviewStep,
+  createInitialMcpServerWizardData,
 } from "./mcp-server/index.js";
 export type {
   UseMcpServerReturn,
@@ -563,6 +571,9 @@ export type {
   McpServerCreationWizardProps,
   McpServerCreationResult,
   McpServerWizardData,
+  IdentityTransportStepProps,
+  EnvironmentAuthStepProps,
+  ReviewStepProps,
 } from "./mcp-server/index.js";
 
 // Skill — data hooks, upload, file browser, and mutation

package/src/manifest/ApplyManifestDialog.tsx

@@ -23,10 +23,15 @@ export interface ApplyManifestDialogProps {
   /** Target organization slug for documents that omit `metadata.org`. */
   readonly org: string;
   /**
-   * Called after every document applied successfully, with the per-document
-   * results in apply order. Use for navigation or list refresh.
+   * Called when the dialog closes after at least one document applied,
+   * with the applied entries in apply order — on full success, and also
+   * when the operator dismisses the dialog after a partial apply (some
+   * documents applied, a later one failed). Use it to refresh a list so
+   * the newly applied resources appear without a reload. It never fires
+   * when nothing applied, and fires once per close. Mirrors
+   * {@link EditResourceYamlDialog}'s `onApplied`.
    */
-  readonly onSuccess?: (entries: readonly ManifestPreviewEntry[]) => void;
+  readonly onApplied?: (applied: readonly ManifestPreviewEntry[]) => void;
 }
 
 /**
@@ -56,7 +61,7 @@ export interface ApplyManifestDialogProps {
  *   open={open}
  *   onOpenChange={setOpen}
  *   org={activeOrg}
- *   onSuccess={() => refetchList()}
+ *   onApplied={() => refetchList()}
  * />
  * ```
  */
@@ -64,7 +69,7 @@ export function ApplyManifestDialog({
   open,
   onOpenChange,
   org,
-  onSuccess,
+  onApplied,
 }: ApplyManifestDialogProps) {
   const dialogRef = useRef<HTMLDialogElement>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
@@ -90,12 +95,26 @@ export function ApplyManifestDialog({
     }
   }, [open, reset]);
 
+  // Close the dialog and, if any document applied this session, refresh
+  // the caller's list. This is the dismiss-after-partial path: some
+  // documents applied before a later one failed, and the operator closes
+  // the dialog rather than retrying — those applied resources must still
+  // appear. The full-success path in `handleApply` fires `onApplied`
+  // itself (it holds the fresh applied list), so it never routes here.
+  const closeAndMaybeRefresh = useCallback(() => {
+    onOpenChange(false);
+    const applied = (manifest.entries ?? []).filter(
+      (e) => e.status === "applied",
+    );
+    if (applied.length > 0) onApplied?.(applied);
+  }, [onOpenChange, manifest.entries, onApplied]);
+
   const handleCancel = useCallback(
     (e: React.SyntheticEvent) => {
       e.preventDefault();
-      onOpenChange(false);
+      closeAndMaybeRefresh();
     },
-    [onOpenChange],
+    [closeAndMaybeRefresh],
   );
 
   const handleFileChange = useCallback(
@@ -107,18 +126,23 @@ export function ApplyManifestDialog({
   );
 
   const handleApply = useCallback(async () => {
-    const allApplied = await manifest.applyAll();
-    if (allApplied && manifest.entries) {
-      const count = manifest.entries.length;
+    const results = await manifest.applyAll();
+    const applied = results.filter((e) => e.status === "applied");
+    const allApplied = results.length > 0 && applied.length === results.length;
+    if (allApplied) {
       toast.success(
-        count === 1 ? "Resource applied" : `${count} resources applied`,
+        applied.length === 1
+          ? "Resource applied"
+          : `${applied.length} resources applied`,
       );
       onOpenChange(false);
-      onSuccess?.(manifest.entries);
+      onApplied?.(applied);
     }
-    // On failure the dialog stays open — per-entry status shows what
-    // applied and what failed.
-  }, [manifest, onOpenChange, onSuccess]);
+    // On partial/total failure the dialog stays open — per-entry status
+    // shows what applied and what failed. Any entries that DID apply
+    // still refresh the caller's list when the dialog is dismissed
+    // (closeAndMaybeRefresh), so successful writes are never hidden.
+  }, [manifest, onOpenChange, onApplied]);
 
   const canApply =
     manifest.entries !== null &&
@@ -198,7 +222,7 @@ export function ApplyManifestDialog({
           <div className="flex gap-2">
             <button
               type="button"
-              onClick={() => onOpenChange(false)}
+              onClick={closeAndMaybeRefresh}
               disabled={manifest.isApplying}
               className={cn(
                 "rounded-md px-3 py-1.5 text-sm font-medium transition-colors",

package/src/manifest/__tests__/ApplyManifestDialog.test.tsx

@@ -0,0 +1,147 @@
+// Tests for ApplyManifestDialog's onApplied contract — the refresh
+// signal every Library list page wires to appear-without-reload. It must
+// fire on full success AND when the operator dismisses the dialog after a
+// partial apply (some documents applied, a later one failed), and must
+// never fire when nothing applied. Historically onApplied's predecessor
+// had zero coverage and stayed unwired at every call site; this locks the
+// contract the list pages now depend on.
+
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent, waitFor } from "@testing-library/react";
+import { ApplyManifestDialog } from "../ApplyManifestDialog";
+import type {
+  ManifestPreviewEntry,
+  UseApplyManifestReturn,
+} from "../useApplyManifest";
+
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// A preview entry in a chosen terminal status; the document shape is only
+// what the dialog's preview row and apply flow read.
+function entry(
+  slug: string,
+  status: ManifestPreviewEntry["status"],
+): ManifestPreviewEntry {
+  return {
+    document: {
+      handler: { yamlKind: "datastore", displayName: "Datastore" },
+      name: slug,
+      slug,
+      org: "acme",
+    },
+    action: "create",
+    status,
+  } as ManifestPreviewEntry;
+}
+
+// The mock's mutable knobs: the entries the hook exposes and the terminal
+// entries applyAll resolves to. Set per test before rendering.
+let mockEntries: readonly ManifestPreviewEntry[] | null;
+let applyAllResult: readonly ManifestPreviewEntry[];
+const applyAllMock = vi.fn(async () => applyAllResult);
+
+vi.mock("../useApplyManifest", () => ({
+  useApplyManifest: (): UseApplyManifestReturn =>
+    ({
+      content: "kind: Datastore",
+      setContent: vi.fn(),
+      readFile: vi.fn(),
+      entries: mockEntries,
+      validationError: null,
+      isValidating: false,
+      hasRedactedSecrets: false,
+      applyAll: applyAllMock,
+      isApplying: false,
+      reset: vi.fn(),
+    }) as UseApplyManifestReturn,
+}));
+
+// CodeMirror stays out of the test environment.
+vi.mock("../YamlEditor", () => ({
+  YamlEditor: () => <div data-testid="yaml-editor" />,
+}));
+
+describe("ApplyManifestDialog — onApplied", () => {
+  it("fires with the applied entries on full success and closes", async () => {
+    mockEntries = [entry("a", "pending"), entry("b", "pending")];
+    applyAllResult = [entry("a", "applied"), entry("b", "applied")];
+    const onApplied = vi.fn();
+    const onOpenChange = vi.fn();
+
+    render(
+      <ApplyManifestDialog
+        open
+        onOpenChange={onOpenChange}
+        org="acme"
+        onApplied={onApplied}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /apply/i }));
+
+    await waitFor(() => expect(onApplied).toHaveBeenCalledTimes(1));
+    expect(
+      onApplied.mock.calls[0][0].map((e: ManifestPreviewEntry) => e.document.slug),
+    ).toEqual(["a", "b"]);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("fires with only the applied subset when a partial apply is dismissed", async () => {
+    // Applied one, failed the next — the dialog stays open on failure.
+    mockEntries = [entry("a", "applied"), entry("b", "failed")];
+    applyAllResult = [entry("a", "applied"), entry("b", "failed")];
+    const onApplied = vi.fn();
+    const onOpenChange = vi.fn();
+
+    render(
+      <ApplyManifestDialog
+        open
+        onOpenChange={onOpenChange}
+        org="acme"
+        onApplied={onApplied}
+      />,
+    );
+
+    // Apply first: full success did not happen, so onApplied has not fired.
+    fireEvent.click(screen.getByRole("button", { name: /apply/i }));
+    await waitFor(() => expect(applyAllMock).toHaveBeenCalled());
+    expect(onApplied).not.toHaveBeenCalled();
+
+    // Dismiss with an applied entry present → refresh the list.
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onApplied).toHaveBeenCalledTimes(1);
+    expect(
+      onApplied.mock.calls[0][0].map((e: ManifestPreviewEntry) => e.document.slug),
+    ).toEqual(["a"]);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("does not fire when the dialog is dismissed with nothing applied", () => {
+    mockEntries = [entry("a", "pending")];
+    const onApplied = vi.fn();
+
+    render(
+      <ApplyManifestDialog
+        open
+        onOpenChange={vi.fn()}
+        org="acme"
+        onApplied={onApplied}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onApplied).not.toHaveBeenCalled();
+  });
+});

package/src/manifest/__tests__/useApplyManifest.test.tsx

@@ -174,12 +174,12 @@ describe("useApplyManifest", () => {
     });
     await act(settleValidation);
 
-    let allApplied = false;
+    let applied: readonly { status: string }[] = [];
     await act(async () => {
-      allApplied = await result.current.applyAll();
+      applied = await result.current.applyAll();
     });
 
-    expect(allApplied).toBe(true);
+    expect(applied.map((e) => e.status)).toEqual(["applied", "applied"]);
     expect(apply).toHaveBeenCalledTimes(2);
     expect(result.current.entries!.map((e) => e.status)).toEqual([
       "applied",
@@ -201,12 +201,12 @@ describe("useApplyManifest", () => {
     });
     await act(settleValidation);
 
-    let allApplied = true;
+    let applied: readonly { status: string }[] = [];
     await act(async () => {
-      allApplied = await result.current.applyAll();
+      applied = await result.current.applyAll();
     });
 
-    expect(allApplied).toBe(false);
+    expect(applied.map((e) => e.status)).toEqual(["failed", "skipped"]);
     expect(apply).toHaveBeenCalledTimes(1);
     expect(result.current.entries!.map((e) => e.status)).toEqual([
       "failed",

package/src/manifest/useApplyManifest.ts

@@ -55,9 +55,13 @@ export interface UseApplyManifestReturn {
   /**
    * Apply all documents sequentially in dependency order. Entries update
    * live. Stops at the first failure (later entries become `"skipped"`).
-   * Resolves `true` when every document applied.
+   * Resolves to the final per-document entries with terminal statuses —
+   * the caller derives full success (`every applied`) and the applied
+   * subset (for a list refresh) without re-reading React state, which is
+   * still stale in the calling closure. Empty when there was nothing to
+   * apply.
    */
-  readonly applyAll: () => Promise<boolean>;
+  readonly applyAll: () => Promise<readonly ManifestPreviewEntry[]>;
   /** `true` while applies are in flight. */
   readonly isApplying: boolean;
   /** Clear all state (content, preview, errors). */
@@ -194,8 +198,8 @@ export function useApplyManifest(org: string): UseApplyManifestReturn {
     return () => clearTimeout(timer);
   }, [content, stigmer, isApplying]);
 
-  const applyAll = useCallback(async (): Promise<boolean> => {
-    if (!entries || entries.length === 0) return false;
+  const applyAll = useCallback(async (): Promise<readonly ManifestPreviewEntry[]> => {
+    if (!entries || entries.length === 0) return [];
 
     // Invalidate any in-flight validation so it cannot clobber apply statuses.
     validateSeq.current++;
@@ -206,10 +210,10 @@ export function useApplyManifest(org: string): UseApplyManifestReturn {
     const working = entries.map((entry): ManifestPreviewEntry => ({ ...entry, status: "pending" }));
     const commit = () => setEntries([...working]);
 
-    let allApplied = true;
+    let stopped = false;
 
     for (let i = 0; i < working.length; i++) {
-      if (!allApplied) {
+      if (stopped) {
         working[i] = { ...working[i], status: "skipped" };
         continue;
       }
@@ -226,14 +230,14 @@ export function useApplyManifest(org: string): UseApplyManifestReturn {
           status: "failed",
           errorMessage: toError(err).message,
         };
-        allApplied = false;
+        stopped = true;
       }
       commit();
     }
 
     commit();
     setIsApplying(false);
-    return allApplied;
+    return working;
   }, [entries, stigmer]);
 
   const hasRedactedSecrets = useMemo(

package/src/mcp-server/McpServerDetailView.tsx

@@ -14,6 +14,7 @@ import type { ToolApprovalPolicy, McpServerSpec } from "@stigmer/protos/ai/stigm
 import { ValidationState } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
 import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { useMcpServer } from "./useMcpServer.js";
+import type { UseMcpServerReturn } from "./useMcpServer.js";
 import { useUpdateMcpServer } from "./useUpdateMcpServer.js";
 import { mcpServerToInput } from "./internal/mcpServerToInput.js";
 import { useMcpServerConnect } from "./useMcpServerConnect.js";
@@ -51,6 +52,31 @@ export interface McpServerDetailViewProps {
   readonly org: string;
   /** MCP server slug (URL-friendly identifier unique within the org). */
   readonly slug: string;
+  /**
+   * Hoisted resource state from {@link useMcpServer}, for callers that
+   * already own the fetch. When provided, the view issues **no**
+   * `getByReference` RPC of its own and renders entirely from this state —
+   * loading, error, and not-found included, so a caller mid-fetch still
+   * gets the loading skeleton rather than a false not-found.
+   *
+   * Ownership contract: supplying this state means supplying its
+   * lifecycle. The view calls `mcpServerState.refetch()` after connect,
+   * disconnect, and inline edits, so the `refetch` you pass must refresh
+   * the data behind `mcpServer` or the view will render stale state after
+   * those actions.
+   *
+   * Two callers this serves:
+   * - A page that already fetched the server (e.g. for export/YAML
+   *   actions) passes `useMcpServer(org, slug)` straight through instead
+   *   of paying a duplicate RPC.
+   * - A guided tour or demo supplies frozen state
+   *   (`{ mcpServer, isLoading: false, isRefetching: false, error: null,
+   *   refetch: noop }`) so every depicted beat renders deterministically
+   *   from data the tour owns (scenar-cloud DD-006).
+   *
+   * When omitted, the view fetches by `org`/`slug` itself, as before.
+   */
+  readonly mcpServerState?: UseMcpServerReturn;
   /**
    * Called once when the MCP server resource has been fetched successfully.
    * Provides the resource display name for use cases like breadcrumbs,
@@ -115,7 +141,8 @@ export interface McpServerDetailViewProps {
 /**
  * Detail view for an MCP Server integration.
  *
- * Fetches the server via {@link useMcpServer} internally and renders
+ * Fetches the server via {@link useMcpServer} internally — or renders
+ * from hoisted state when the caller passes `mcpServerState` — and shows
  * its full configuration: validation banner (if invalid), header,
  * a **Connect bar** with a single Connect/Reconnect action, and a
  * **tabbed capabilities panel** (Tools, Policies, and optionally
@@ -135,10 +162,20 @@ export interface McpServerDetailViewProps {
  * // Minimal — self-contained, fetches its own data
  * <McpServerDetailView org="acme" slug="github" />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Hoisted — the page already fetched the server (e.g. for YAML
+ * // export actions), so pass that state through instead of paying a
+ * // second getByReference RPC.
+ * const state = useMcpServer(org, slug);
+ * <McpServerDetailView org={org} slug={slug} mcpServerState={state} />
+ * ```
  */
 export function McpServerDetailView({
   org,
   slug,
+  mcpServerState,
   onResourceLoad,
   defaultCapabilityTab = "tools",
   defaultShowCredentialForm = false,
@@ -150,7 +187,16 @@ export function McpServerDetailView({
   onResourceUpdated,
   className,
 }: McpServerDetailViewProps) {
-  const { mcpServer, isLoading, error, refetch } = useMcpServer(org, slug);
+  // Hoisted-state mode: when the caller supplies `mcpServerState`, disable
+  // the internal fetch via the hook's documented null-skip (a stable no-op,
+  // so `fetched` reports isLoading=false with no RPC) and render from the
+  // caller's state instead — all four states (loading/error/not-found/data)
+  // transfer intact.
+  const fetched = useMcpServer(
+    mcpServerState ? null : org,
+    mcpServerState ? null : slug,
+  );
+  const { mcpServer, isLoading, error, refetch } = mcpServerState ?? fetched;
   const { update: updateMcpServer, isUpdating } = useUpdateMcpServer();
 
   const saveMcpField = useCallback(
@@ -493,7 +539,9 @@ export function McpServerDetailView({
         />
       )}
 
-      <Section title="Connection">
+      {/* scrollTarget: guided tours/demos bring the connect flow into view
+          (see IdentityTransportStep's "mcp-transport" for the convention). */}
+      <Section title="Connection" scrollTarget="mcp-connection">
         <StdioSandboxNotice serverType={spec?.serverType} className="mb-3" />
         <OAuthRequiredNotice oauthOnly={spec?.auth?.oauthOnly} className="mb-3" />
         <ConnectBar
@@ -582,7 +630,7 @@ export function McpServerDetailView({
         />
       </dialog>
 
-      <Section title="Capabilities">
+      <Section title="Capabilities" scrollTarget="mcp-capabilities">
         <Tabs
           tabs={capabilityTabs}
           activeTab={capabilityTab}