Skip to content

Automate browser based workflows with AI

feat(SKY-11813): block search with focus-and-jump in the studio editor (#7103)

Celal Zamanoğlua77a3bbccbce
diff --git a/skyvern-frontend/src/routes/workflows/editor/FlowRenderer.tsx b/skyvern-frontend/src/routes/workflows/editor/FlowRenderer.tsx
index b2e2a6525..c106e5379 100644
--- a/skyvern-frontend/src/routes/workflows/editor/FlowRenderer.tsx
+++ b/skyvern-frontend/src/routes/workflows/editor/FlowRenderer.tsx
@@ -182,6 +182,13 @@ import { useRecordingStore } from "@/store/useRecordingStore";
import { useIsCanvasLocked } from "./controls/useIsCanvasLocked";
import { BlockConfigSidebar } from "./panels/BlockConfigSidebar";
import { STUDIO_COPILOT_TRANSITION_MS } from "../studio/constants";
+import {
+ blockJumpDuration,
+ collectBlockSearchTargets,
+ focusBlockTarget,
+ waitForNodeSettle,
+} from "../studio/blockSearch";
+import { useWorkflowBlockSearchStore } from "@/store/WorkflowBlockSearchStore";
import { duplicateBlockBelow } from "./workflowDuplicate";
// Grace period after nodesInitialized before we start tracking changes.
@@ -1712,6 +1719,102 @@ function FlowRenderer({
[reactFlowInstance],
);
+ const blockSearchFitTimerRef = useRef<number | null>(null);
+ const blockSearchBranchGuardTimerRef = useRef<number | null>(null);
+ useEffect(() => {
+ return () => {
+ if (blockSearchFitTimerRef.current !== null) {
+ window.clearTimeout(blockSearchFitTimerRef.current);
+ blockSearchFitTimerRef.current = null;
+ }
+ // Mirrors BranchesEditor's unmount cleanup: a leaked begin without its
+ // delayed end would suppress dirty-detection for the whole session.
+ if (blockSearchBranchGuardTimerRef.current !== null) {
+ window.clearTimeout(blockSearchBranchGuardTimerRef.current);
+ blockSearchBranchGuardTimerRef.current = null;
+ useWorkflowHasChangesStore.getState().endInternalUpdate();
+ }
+ };
+ }, []);
+
+ const focusBlockForSearch = useCallback(
+ (nodeId: string) => {
+ const duration = blockJumpDuration();
+ const getNodes = () => reactFlowInstance.getNodes() as Array<AppNode>;
+ void focusBlockTarget(nodeId, {
+ getNodes,
+ getInternalNode: (id) => reactFlowInstance.getInternalNode(id),
+ getPaneWidth: () =>
+ editorElementRef.current?.getBoundingClientRect().width ?? 0,
+ viewportZoom: reactFlowInstance.getViewport().zoom,
+ duration,
+ setViewport: (viewport, options) => {
+ // An explicit jump outranks any pending pane-layout recenter and,
+ // like runFitView, must not be clamped by constrainPan mid-flight.
+ lastCanvasInteractionAtRef.current = Date.now();
+ fitViewInProgressRef.current = true;
+ void reactFlowInstance.setViewport(viewport, options);
+ if (blockSearchFitTimerRef.current !== null) {
+ window.clearTimeout(blockSearchFitTimerRef.current);
+ }
+ blockSearchFitTimerRef.current = window.setTimeout(() => {
+ blockSearchFitTimerRef.current = null;
+ fitViewInProgressRef.current = false;
+ }, options.duration + 50);
+ },
+ selectBlock: setSelectedBlockId,
+ expandBlock: (label) =>
+ useNodeCollapseStore
+ .getState()
+ .expandBlock(workflow.workflow_permanent_id ?? "__global__", label),
+ switchBranch: (conditionalId, branchId) => {
+ // Same write and dirty-state guard as the branch tab click
+ // (BranchesEditor.handleSelectBranch): switching branches is UI
+ // state, so the `replace` change must not mark the workflow dirty.
+ const changesStore = useWorkflowHasChangesStore.getState();
+ if (blockSearchBranchGuardTimerRef.current !== null) {
+ window.clearTimeout(blockSearchBranchGuardTimerRef.current);
+ changesStore.endInternalUpdate();
+ }
+ changesStore.beginInternalUpdate();
+ reactFlowInstance.updateNodeData(conditionalId, {
+ activeBranchId: branchId,
+ });
+ blockSearchBranchGuardTimerRef.current = window.setTimeout(() => {
+ blockSearchBranchGuardTimerRef.current = null;
+ changesStore.endInternalUpdate();
+ }, 50);
+ },
+ waitForSettle: (settleNodeId) =>
+ waitForNodeSettle(settleNodeId, {
+ getNodes,
+ getInternalNode: (id) => reactFlowInstance.getInternalNode(id),
+ }),
+ });
+ },
+ [reactFlowInstance, setSelectedBlockId, workflow.workflow_permanent_id],
+ );
+
+ // Registered here (not in shell chrome) because the jump needs this
+ // canvas's React Flow instance. Read-only canvases (comparison view)
+ // never register, so the pane header's search only drives the live
+ // editable canvas.
+ useEffect(() => {
+ if (!embedded || readOnly) {
+ return;
+ }
+ useWorkflowBlockSearchStore.getState().registerHandle({
+ getTargets: () =>
+ collectBlockSearchTargets(
+ reactFlowInstance.getNodes() as Array<AppNode>,
+ ),
+ focusBlock: focusBlockForSearch,
+ });
+ return () => {
+ useWorkflowBlockSearchStore.getState().registerHandle(null);
+ };
+ }, [embedded, readOnly, reactFlowInstance, focusBlockForSearch]);
+
// "initial-load" lands one frame after Dagre positions commit (mid fade-in),
// so fitting here can't read pre-layout node positions. layoutPhase only
// advances once nodesInitialized flips, but guard explicitly so a future
diff --git a/skyvern-frontend/src/routes/workflows/studio/BrowserPaneHeader.tsx b/skyvern-frontend/src/routes/workflows/studio/BrowserPaneHeader.tsx
index 0d4852a2b..c24dc2eb5 100644
--- a/skyvern-frontend/src/routes/workflows/studio/BrowserPaneHeader.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/BrowserPaneHeader.tsx
@@ -31,15 +31,13 @@ import { useRecordingStore } from "@/store/useRecordingStore";
import { useStudioBrowserStore } from "@/store/useStudioBrowserStore";
import { cn } from "@/util/utils";
+import { PANE_HEADER_ICON_BUTTON_CLASS } from "./constants";
import { ControlTooltip } from "./ControlTooltip";
import { PaneHeaderDivider } from "./PaneHeaderDivider";
import { useBrowserPaneView } from "./useBrowserPaneView";
import { useStudioPaneCompact } from "./StudioShellContext";
import { ViewToggle } from "./ViewToggle";
-const ICON_BUTTON =
- "inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-border text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40";
-
const RECORDING_ARCHIVED_LABEL =
"Recording archived — contact [email protected] to request restoration";
@@ -216,7 +214,7 @@ export function BrowserPaneActions() {
aria-label="Reconnect browser stream"
onClick={reload}
disabled={!browserSessionId || debugHidden}
- className={ICON_BUTTON}
+ className={PANE_HEADER_ICON_BUTTON_CLASS}
>
<ReloadIcon className="h-3.5 w-3.5" />
</button>
@@ -230,7 +228,7 @@ export function BrowserPaneActions() {
aria-label="Open browser in new tab"
onClick={openInNewTab}
disabled={!browserSessionId || debugHidden}
- className={ICON_BUTTON}
+ className={PANE_HEADER_ICON_BUTTON_CLASS}
>
<OpenInNewWindowIcon className="h-3.5 w-3.5" />
</button>
@@ -255,7 +253,7 @@ export function BrowserPaneActions() {
disabled={
!workflowPermanentId || !browserSessionId || debugHidden
}
- className={ICON_BUTTON}
+ className={PANE_HEADER_ICON_BUTTON_CLASS}
>
<PowerIcon className="h-3.5 w-3.5" />
</button>
diff --git a/skyvern-frontend/src/routes/workflows/studio/CopilotPaneHeader.tsx b/skyvern-frontend/src/routes/workflows/studio/CopilotPaneHeader.tsx
index 16c778acd..8c817dfd3 100644
--- a/skyvern-frontend/src/routes/workflows/studio/CopilotPaneHeader.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/CopilotPaneHeader.tsx
@@ -8,6 +8,7 @@ import {
import { useCopilotHeaderStore } from "@/store/useCopilotHeaderStore";
import { WorkflowCopilotHistory } from "../copilot/WorkflowCopilotHistory";
+import { PANE_HEADER_ICON_BUTTON_CLASS } from "./constants";
/**
* Copilot pane header chrome: the History and New-chat controls the docked
@@ -36,7 +37,7 @@ export function CopilotPaneControls() {
type="button"
onClick={controls.onNewChat}
aria-label="New chat"
- className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-border text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+ className={PANE_HEADER_ICON_BUTTON_CLASS}
>
<PlusIcon className="h-3.5 w-3.5" aria-hidden="true" />
</button>
diff --git a/skyvern-frontend/src/routes/workflows/studio/EditorPaneHeader.test.tsx b/skyvern-frontend/src/routes/workflows/studio/EditorPaneHeader.test.tsx
new file mode 100644
index 000000000..49b1be52c
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/EditorPaneHeader.test.tsx
@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+
+import {
+ afterAll,
+ afterEach,
+ beforeAll,
+ beforeEach,
+ describe,
+ expect,
+ test,
+ vi,
+} from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { useWorkflowBlockSearchStore } from "@/store/WorkflowBlockSearchStore";
+import { useWorkflowYamlEditorStore } from "@/store/WorkflowYamlEditorStore";
+
+import { type BlockSearchTarget } from "./blockSearch";
+import { EditorPaneBlockSearch } from "./EditorPaneHeader";
+
+// cmdk and Radix Popover need ResizeObserver and scrollIntoView, which jsdom
+// lacks. Install them for this suite only and restore afterward.
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+const originalScrollIntoView = Element.prototype.scrollIntoView;
+
+beforeAll(() => {
+ vi.stubGlobal("ResizeObserver", MockResizeObserver);
+ Element.prototype.scrollIntoView = () => {};
+});
+
+afterAll(() => {
+ vi.unstubAllGlobals();
+ if (originalScrollIntoView) {
+ Element.prototype.scrollIntoView = originalScrollIntoView;
+ } else {
+ delete (Element.prototype as { scrollIntoView?: unknown }).scrollIntoView;
+ }
+});
+
+afterEach(cleanup);
+
+const targets: Array<BlockSearchTarget> = [
+ { nodeId: "login-node", label: "Login", blockType: "login" },
+ { nodeId: "extract-node", label: "Extract rows", blockType: "extraction" },
+ {
+ nodeId: "email-node",
+ label: "Send summary email",
+ blockType: "send_email",
+ },
+];
+
+const focusBlock = vi.fn();
+
+function registerHandle(withTargets = targets) {
+ useWorkflowBlockSearchStore.getState().registerHandle({
+ getTargets: () => withTargets,
+ focusBlock,
+ });
+}
+
+function renderSearch() {
+ return render(
+ <TooltipProvider delayDuration={0}>
+ <EditorPaneBlockSearch />
+ </TooltipProvider>,
+ );
+}
+
+function openSearch() {
+ fireEvent.click(screen.getByRole("button", { name: "Search blocks" }));
+ return screen.getByPlaceholderText("Search blocks…");
+}
+
+beforeEach(() => {
+ focusBlock.mockReset();
+ useWorkflowBlockSearchStore.getState().registerHandle(null);
+ useWorkflowYamlEditorStore.getState().close();
+});
+
+describe("EditorPaneBlockSearch", () => {
+ test("renders nothing while no canvas has registered a handle", () => {
+ renderSearch();
+ expect(screen.queryByRole("button", { name: "Search blocks" })).toBeNull();
+ });
+
+ test("hides while Code mode covers the canvas", () => {
+ registerHandle();
+ useWorkflowYamlEditorStore.getState().open("blocks: []");
+ renderSearch();
+ expect(screen.queryByRole("button", { name: "Search blocks" })).toBeNull();
+ });
+
+ test("lists every block on open and filters by case-insensitive substring", () => {
+ registerHandle();
+ renderSearch();
+ const input = openSearch();
+
+ expect(screen.getAllByRole("option")).toHaveLength(3);
+
+ fireEvent.change(input, { target: { value: "ROWS" } });
+ const options = screen.getAllByRole("option");
+ expect(options).toHaveLength(1);
+ expect(options[0]?.textContent).toContain("Extract rows");
+ });
+
+ test("shows an empty state when nothing matches", () => {
+ registerHandle();
+ renderSearch();
+ const input = openSearch();
+
+ fireEvent.change(input, { target: { value: "no such block" } });
+ expect(screen.queryAllByRole("option")).toHaveLength(0);
+ expect(screen.getByText("No blocks found.")).toBeTruthy();
+ });
+
+ test("clicking a result jumps to that block and closes the popover", () => {
+ registerHandle();
+ renderSearch();
+ const input = openSearch();
+
+ fireEvent.change(input, { target: { value: "email" } });
+ fireEvent.click(screen.getByRole("option"));
+
+ expect(focusBlock).toHaveBeenCalledWith("email-node");
+ expect(screen.queryByPlaceholderText("Search blocks…")).toBeNull();
+ });
+
+ test("Enter selects the highlighted (first) match", () => {
+ registerHandle();
+ renderSearch();
+ const input = openSearch();
+
+ fireEvent.change(input, { target: { value: "extract" } });
+ fireEvent.keyDown(input, { key: "Enter" });
+
+ expect(focusBlock).toHaveBeenCalledWith("extract-node");
+ expect(screen.queryByPlaceholderText("Search blocks…")).toBeNull();
+ });
+
+ test("Escape closes the popover without reaching the canvas's window handler", () => {
+ const windowEscapeSpy = vi.fn();
+ window.addEventListener("keydown", windowEscapeSpy);
+ try {
+ registerHandle();
+ renderSearch();
+ const input = openSearch();
+
+ fireEvent.keyDown(input, { key: "Escape" });
+
+ expect(screen.queryByPlaceholderText("Search blocks…")).toBeNull();
+ expect(focusBlock).not.toHaveBeenCalled();
+ // The stop keeps FlowRenderer's global Escape (clear selection) inert.
+ expect(windowEscapeSpy).not.toHaveBeenCalled();
+ } finally {
+ window.removeEventListener("keydown", windowEscapeSpy);
+ }
+ });
+
+ test("reopening after a search starts from a clean query", () => {
+ registerHandle();
+ renderSearch();
+ const input = openSearch();
+
+ fireEvent.change(input, { target: { value: "email" } });
+ fireEvent.keyDown(input, { key: "Enter" });
+
+ const reopened = openSearch();
+ expect((reopened as HTMLInputElement).value).toBe("");
+ expect(screen.getAllByRole("option")).toHaveLength(3);
+ });
+});
diff --git a/skyvern-frontend/src/routes/workflows/studio/EditorPaneHeader.tsx b/skyvern-frontend/src/routes/workflows/studio/EditorPaneHeader.tsx
index b637c3475..2a215e183 100644
--- a/skyvern-frontend/src/routes/workflows/studio/EditorPaneHeader.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/EditorPaneHeader.tsx
@@ -1,9 +1,30 @@
+import { MagnifyingGlassIcon } from "@radix-ui/react-icons";
+import { useMemo, useState } from "react";
+
+import {
+ Command,
+ CommandEmpty,
+ CommandGroup,
+ CommandInput,
+ CommandItem,
+ CommandList,
+} from "@/components/ui/command";
+import {
+ Popover,
+ PopoverContent,
+ PopoverTrigger,
+} from "@/components/ui/popover";
+import { WorkflowBlockIcon } from "@/routes/workflows/editor/nodes/WorkflowBlockIcon";
import {
commitYamlDraft,
useWorkflowYamlEditorStore,
} from "@/store/WorkflowYamlEditorStore";
+import { useWorkflowBlockSearchStore } from "@/store/WorkflowBlockSearchStore";
import { YamlModeToggle } from "../editor/YamlModeToggle";
+import { filterBlockSearchTargets } from "./blockSearch";
+import { PANE_HEADER_ICON_BUTTON_CLASS, studioPanelId } from "./constants";
+import { ControlTooltip } from "./ControlTooltip";
import { PaneHeaderDivider } from "./PaneHeaderDivider";
import { useStudioPaneCompact } from "./StudioShellContext";
@@ -35,3 +56,109 @@ export function EditorPaneModeToggle() {
</>
);
}
+
+/**
+ * Block search for long flows: a magnifier action opening a label-filtered
+ * list; picking an entry selects the block and centers the canvas on it via
+ * the handle the embedded FlowRenderer registers. Hidden while no editable
+ * canvas is mounted (read-only workflows) or while Code mode covers it.
+ */
+export function EditorPaneBlockSearch() {
+ const [open, setOpen] = useState(false);
+ const [query, setQuery] = useState("");
+ const [paneBoundary, setPaneBoundary] = useState<Element | null>(null);
+ const handle = useWorkflowBlockSearchStore((s) => s.handle);
+ const yamlModeActive = useWorkflowYamlEditorStore((s) => s.active);
+ const targets = useMemo(
+ () => (open && handle ? handle.getTargets() : []),
+ [open, handle],
+ );
+ if (!handle || yamlModeActive) {
+ return null;
+ }
+ const results = filterBlockSearchTargets(targets, query);
+ const closeAndReset = () => {
+ setOpen(false);
+ setQuery("");
+ };
+ return (
+ <Popover
+ open={open}
+ onOpenChange={(next) => {
+ if (next) {
+ // Clamp the popover to the Editor pane so a narrow pane cannot
+ // overflow it (the content is portalled, so Radix only knows the
+ // boundary we hand it).
+ setPaneBoundary(document.getElementById(studioPanelId("editor")));
+ setOpen(true);
+ return;
+ }
+ closeAndReset();
+ }}
+ >
+ <ControlTooltip content="Search blocks">
+ <PopoverTrigger asChild>
+ <button
+ type="button"
+ aria-label="Search blocks"
+ className={PANE_HEADER_ICON_BUTTON_CLASS}
+ >
+ <MagnifyingGlassIcon className="h-3.5 w-3.5" />
+ </button>
+ </PopoverTrigger>
+ </ControlTooltip>
+ <PopoverContent
+ align="end"
+ sideOffset={6}
+ collisionBoundary={paneBoundary}
+ collisionPadding={8}
+ className="w-64 max-w-[var(--radix-popper-available-width)] p-0"
+ >
+ <Command
+ shouldFilter={false}
+ onKeyDown={(event) => {
+ // Escape only dismisses the popover; without the stop it bubbles
+ // to the canvas's window handler and clears the block selection.
+ if (event.key === "Escape") {
+ event.stopPropagation();
+ closeAndReset();
+ }
+ }}
+ >
+ <CommandInput
+ placeholder="Search blocks…"
+ value={query}
+ onValueChange={setQuery}
+ />
+ <CommandList>
+ <CommandEmpty>No blocks found.</CommandEmpty>
+ {results.length > 0 ? (
+ <CommandGroup>
+ {results.map((target) => (
+ <CommandItem
+ key={target.nodeId}
+ value={target.nodeId}
+ onSelect={() => {
+ handle.focusBlock(target.nodeId);
+ closeAndReset();
+ }}
+ >
+ <span className="mr-2 flex h-4 w-4 shrink-0 items-center justify-center text-muted-foreground">
+ {target.blockType ? (
+ <WorkflowBlockIcon
+ workflowBlockType={target.blockType}
+ className="h-4 w-4"
+ />
+ ) : null}
+ </span>
+ <span className="truncate">{target.label}</span>
+ </CommandItem>
+ ))}
+ </CommandGroup>
+ ) : null}
+ </CommandList>
+ </Command>
+ </PopoverContent>
+ </Popover>
+ );
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx b/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx
index 93886f845..fd1d8f647 100644
--- a/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx
@@ -28,7 +28,10 @@ import { useDebugSessionQuery } from "../hooks/useDebugSessionQuery";
import { BrowserPaneActions, BrowserPaneViewPills } from "./BrowserPaneHeader";
import { CopilotActiveDot, CopilotPaneControls } from "./CopilotPaneHeader";
-import { EditorPaneModeToggle } from "./EditorPaneHeader";
+import {
+ EditorPaneBlockSearch,
+ EditorPaneModeToggle,
+} from "./EditorPaneHeader";
import { BrowserTab } from "./BrowserTab";
import { EditorTab, type StudioWorkspaceProps } from "./EditorTab";
import { RunTab } from "./RunTab";
@@ -761,6 +764,7 @@ function StudioStage(props: StudioWorkspaceProps) {
<StudioPane
{...paneProps("editor")}
headerExtras={<EditorPaneModeToggle />}
+ headerActions={<EditorPaneBlockSearch />}
>
{/* The embedded Workspace boots debug sessions, copilot chats
and block-script queries against the workflow — none of
diff --git a/skyvern-frontend/src/routes/workflows/studio/blockSearch.test.ts b/skyvern-frontend/src/routes/workflows/studio/blockSearch.test.ts
new file mode 100644
index 000000000..e2058869b
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/blockSearch.test.ts
@@ -0,0 +1,547 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import type { AppNode } from "../editor/nodes";
+import { START_ANCHOR_TOP_PX } from "../editor/paneFit";
+import {
+ BLOCK_JUMP_DURATION_MS,
+ BRANCH_SETTLE_STABLE_FRAMES,
+ BRANCH_SETTLE_TIMEOUT_MS,
+ blockJumpDuration,
+ collectBlockSearchTargets,
+ filterBlockSearchTargets,
+ focusBlockTarget,
+ resolveConditionalBranchPath,
+ waitForNodeSettle,
+ type FocusBlockDeps,
+} from "./blockSearch";
+
+const startNode = {
+ id: "start-node",
+ type: "start",
+ position: { x: 0, y: 0 },
+ data: { label: "__start_block__" },
+} as AppNode;
+
+const adderNode = {
+ id: "adder-node",
+ type: "nodeAdder",
+ position: { x: 0, y: 900 },
+ data: {},
+} as AppNode;
+
+const loginNode = {
+ id: "login-node",
+ type: "task",
+ position: { x: 0, y: 100 },
+ measured: { width: 400, height: 200 },
+ data: { label: "Login" },
+} as AppNode;
+
+const loopNode = {
+ id: "loop-node",
+ type: "loop",
+ position: { x: 0, y: 400 },
+ data: { label: "Iterate rows", loopKind: "while" },
+} as AppNode;
+
+// Nested inside the loop container: `position` is parent-relative.
+const nestedNode = {
+ id: "nested-node",
+ type: "extraction",
+ parentId: "loop-node",
+ position: { x: 40, y: 80 },
+ data: { label: "Extract row data" },
+} as AppNode;
+
+const unlabeledNode = {
+ id: "unlabeled-node",
+ type: "task",
+ position: { x: 0, y: 700 },
+ data: { label: " " },
+} as AppNode;
+
+const nodes = [
+ startNode,
+ loginNode,
+ loopNode,
+ nestedNode,
+ unlabeledNode,
+ adderNode,
+];
+
+// A conditional flow: branch A active, branch B hidden. Branch B holds a task
+// plus a loop with a cascaded (affinity-less) child, and a nested conditional
+// whose branch Y holds the deepest target.
+function makeConditionalNodes(): Array<AppNode> {
+ return [
+ startNode,
+ {
+ id: "cond-node",
+ type: "conditional",
+ position: { x: 0, y: 100 },
+ data: { label: "Route by type", activeBranchId: "branch-a" },
+ } as AppNode,
+ {
+ id: "branch-a-block",
+ type: "task",
+ parentId: "cond-node",
+ position: { x: 20, y: 120 },
+ data: {
+ label: "Handle type A",
+ conditionalNodeId: "cond-node",
+ conditionalBranchId: "branch-a",
+ },
+ } as AppNode,
+ {
+ id: "branch-b-block",
+ type: "task",
+ parentId: "cond-node",
+ position: { x: 20, y: 120 },
+ hidden: true,
+ data: {
+ label: "Handle type B",
+ conditionalNodeId: "cond-node",
+ conditionalBranchId: "branch-b",
+ },
+ } as AppNode,
+ {
+ id: "branch-b-loop",
+ type: "loop",
+ parentId: "cond-node",
+ position: { x: 20, y: 360 },
+ hidden: true,
+ data: {
+ label: "Iterate type B rows",
+ conditionalNodeId: "cond-node",
+ conditionalBranchId: "branch-b",
+ },
+ } as AppNode,
+ {
+ id: "branch-b-loop-child",
+ type: "extraction",
+ parentId: "branch-b-loop",
+ position: { x: 30, y: 60 },
+ hidden: true,
+ data: { label: "Extract type B row" },
+ } as AppNode,
+ {
+ id: "inner-cond-node",
+ type: "conditional",
+ parentId: "cond-node",
+ position: { x: 20, y: 600 },
+ hidden: true,
+ data: {
+ label: "Route type B result",
+ activeBranchId: "branch-x",
+ conditionalNodeId: "cond-node",
+ conditionalBranchId: "branch-b",
+ },
+ } as AppNode,
+ {
+ id: "inner-branch-y-block",
+ type: "sendEmail",
+ parentId: "inner-cond-node",
+ position: { x: 10, y: 80 },
+ hidden: true,
+ data: {
+ label: "Email type B result",
+ conditionalNodeId: "inner-cond-node",
+ conditionalBranchId: "branch-y",
+ },
+ } as AppNode,
+ ];
+}
+
+describe("collectBlockSearchTargets", () => {
+ test("keeps workflow blocks (including nested ones) in canvas order and maps block types", () => {
+ expect(collectBlockSearchTargets(nodes)).toEqual([
+ { nodeId: "login-node", label: "Login", blockType: "task" },
+ { nodeId: "loop-node", label: "Iterate rows", blockType: "while_loop" },
+ {
+ nodeId: "nested-node",
+ label: "Extract row data",
+ blockType: "extraction",
+ },
+ ]);
+ });
+
+ test("skips utility nodes and blank labels", () => {
+ const targets = collectBlockSearchTargets(nodes);
+ const ids = targets.map((target) => target.nodeId);
+ expect(ids).not.toContain("start-node");
+ expect(ids).not.toContain("adder-node");
+ expect(ids).not.toContain("unlabeled-node");
+ });
+
+ test("includes blocks hidden inside inactive conditional branches", () => {
+ const ids = collectBlockSearchTargets(makeConditionalNodes()).map(
+ (target) => target.nodeId,
+ );
+ expect(ids).toContain("branch-b-block");
+ expect(ids).toContain("branch-b-loop-child");
+ expect(ids).toContain("inner-branch-y-block");
+ });
+});
+
+describe("filterBlockSearchTargets", () => {
+ const targets = collectBlockSearchTargets(nodes);
+
+ test("returns every target for an empty or whitespace query", () => {
+ expect(filterBlockSearchTargets(targets, "")).toEqual(targets);
+ expect(filterBlockSearchTargets(targets, " ")).toEqual(targets);
+ });
+
+ test("matches case-insensitive substrings", () => {
+ expect(
+ filterBlockSearchTargets(targets, "ROW").map((t) => t.nodeId),
+ ).toEqual(["loop-node", "nested-node"]);
+ expect(
+ filterBlockSearchTargets(targets, "login").map((t) => t.nodeId),
+ ).toEqual(["login-node"]);
+ });
+
+ test("trims the query before matching", () => {
+ expect(
+ filterBlockSearchTargets(targets, " login ").map((t) => t.nodeId),
+ ).toEqual(["login-node"]);
+ });
+
+ test("returns nothing when no label matches", () => {
+ expect(filterBlockSearchTargets(targets, "does-not-exist")).toEqual([]);
+ });
+});
+
+describe("blockJumpDuration", () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ test("is instant when matchMedia is unavailable (jsdom default)", () => {
+ expect(blockJumpDuration()).toBe(0);
+ });
+
+ test("is instant under prefers-reduced-motion", () => {
+ vi.stubGlobal("matchMedia", () => ({ matches: true }));
+ expect(blockJumpDuration()).toBe(0);
+ });
+
+ test("animates otherwise", () => {
+ vi.stubGlobal("matchMedia", () => ({ matches: false }));
+ expect(blockJumpDuration()).toBe(BLOCK_JUMP_DURATION_MS);
+ });
+});
+
+describe("resolveConditionalBranchPath", () => {
+ test("is empty for targets outside conditionals or in the active branch", () => {
+ expect(resolveConditionalBranchPath(nodes, "nested-node")).toEqual([]);
+ expect(
+ resolveConditionalBranchPath(makeConditionalNodes(), "branch-a-block"),
+ ).toEqual([]);
+ });
+
+ test("resolves a direct child of an inactive branch", () => {
+ expect(
+ resolveConditionalBranchPath(makeConditionalNodes(), "branch-b-block"),
+ ).toEqual([
+ {
+ conditionalId: "cond-node",
+ conditionalLabel: "Route by type",
+ branchId: "branch-b",
+ },
+ ]);
+ });
+
+ test("reaches the branch chain through parentId nesting (block in a loop)", () => {
+ expect(
+ resolveConditionalBranchPath(
+ makeConditionalNodes(),
+ "branch-b-loop-child",
+ ),
+ ).toEqual([
+ {
+ conditionalId: "cond-node",
+ conditionalLabel: "Route by type",
+ branchId: "branch-b",
+ },
+ ]);
+ });
+
+ test("orders nested conditional switches root→leaf", () => {
+ expect(
+ resolveConditionalBranchPath(
+ makeConditionalNodes(),
+ "inner-branch-y-block",
+ ),
+ ).toEqual([
+ {
+ conditionalId: "cond-node",
+ conditionalLabel: "Route by type",
+ branchId: "branch-b",
+ },
+ {
+ conditionalId: "inner-cond-node",
+ conditionalLabel: "Route type B result",
+ branchId: "branch-y",
+ },
+ ]);
+ });
+
+ test("skips levels whose branch is already active", () => {
+ const alreadySwitched = makeConditionalNodes().map((node) =>
+ node.id === "cond-node"
+ ? ({
+ ...node,
+ data: { ...node.data, activeBranchId: "branch-b" },
+ } as AppNode)
+ : node,
+ );
+ expect(
+ resolveConditionalBranchPath(alreadySwitched, "inner-branch-y-block"),
+ ).toEqual([
+ {
+ conditionalId: "inner-cond-node",
+ conditionalLabel: "Route type B result",
+ branchId: "branch-y",
+ },
+ ]);
+ });
+
+ test("stops at a dangling conditional reference", () => {
+ const orphan = {
+ id: "orphan-node",
+ type: "task",
+ position: { x: 0, y: 0 },
+ data: {
+ label: "Orphan",
+ conditionalNodeId: "gone-node",
+ conditionalBranchId: "branch-z",
+ },
+ } as AppNode;
+ expect(resolveConditionalBranchPath([orphan], "orphan-node")).toEqual([]);
+ });
+});
+
+describe("waitForNodeSettle", () => {
+ function makeFrameQueue() {
+ const queue: Array<() => void> = [];
+ return {
+ requestFrame: (callback: () => void) => {
+ queue.push(callback);
+ },
+ async tick() {
+ queue.splice(0).forEach((callback) => callback());
+ await Promise.resolve();
+ },
+ };
+ }
+
+ test("resolves once the node is visible and its position holds still", async () => {
+ const frames = makeFrameQueue();
+ const node = {
+ id: "n",
+ type: "task",
+ hidden: true,
+ position: { x: 0, y: 0 },
+ data: { label: "N" },
+ } as AppNode;
+ let resolved = false;
+ void waitForNodeSettle("n", {
+ getNodes: () => [node],
+ getInternalNode: () => undefined,
+ requestFrame: frames.requestFrame,
+ now: () => 0,
+ }).then(() => {
+ resolved = true;
+ });
+
+ await frames.tick(); // hidden
+ (node as { hidden?: boolean }).hidden = false;
+ node.position = { x: 10, y: 10 };
+ await frames.tick(); // visible, but the position just moved
+ for (let i = 0; i < BRANCH_SETTLE_STABLE_FRAMES; i++) {
+ expect(resolved).toBe(false);
+ await frames.tick(); // stable frames accumulate
+ }
+ expect(resolved).toBe(true);
+ });
+
+ test("times out instead of hanging when the node never becomes visible", async () => {
+ const frames = makeFrameQueue();
+ let clock = 0;
+ let resolved = false;
+ void waitForNodeSettle("missing", {
+ getNodes: () => [],
+ getInternalNode: () => undefined,
+ requestFrame: frames.requestFrame,
+ now: () => {
+ clock += BRANCH_SETTLE_TIMEOUT_MS / 2;
+ return clock;
+ },
+ }).then(() => {
+ resolved = true;
+ });
+
+ await frames.tick();
+ await frames.tick();
+ expect(resolved).toBe(true);
+ });
+});
+
+describe("focusBlockTarget", () => {
+ function makeDeps(
+ depsNodes: Array<AppNode> = nodes,
+ overrides?: Partial<FocusBlockDeps>,
+ ): FocusBlockDeps {
+ return {
+ getNodes: () => depsNodes,
+ getInternalNode: () => undefined,
+ getPaneWidth: () => 1000,
+ viewportZoom: 0.75,
+ duration: 300,
+ setViewport: vi.fn(),
+ selectBlock: vi.fn(),
+ expandBlock: vi.fn(),
+ switchBranch: vi.fn(),
+ waitForSettle: vi.fn().mockResolvedValue(undefined),
+ ...overrides,
+ };
+ }
+
+ test("selects the block (feeding the selected-block URL sync) and expands it", async () => {
+ const deps = makeDeps();
+ await expect(focusBlockTarget("login-node", deps)).resolves.toBe(true);
+ expect(deps.selectBlock).toHaveBeenCalledWith("login-node");
+ expect(deps.expandBlock).toHaveBeenCalledWith("Login");
+ });
+
+ test("visible targets never switch branches or wait", async () => {
+ const deps = makeDeps();
+ await focusBlockTarget("login-node", deps);
+ expect(deps.switchBranch).not.toHaveBeenCalled();
+ expect(deps.waitForSettle).not.toHaveBeenCalled();
+ expect(deps.selectBlock).toHaveBeenCalledTimes(1);
+ expect(deps.setViewport).toHaveBeenCalledTimes(1);
+ });
+
+ test("top-anchors the block at its absolute position, horizontally centered, at the current zoom", async () => {
+ const deps = makeDeps(nodes, {
+ getInternalNode: (nodeId) =>
+ nodeId === "nested-node"
+ ? {
+ internals: { positionAbsolute: { x: 140, y: 480 } },
+ measured: { width: 300, height: 120 },
+ }
+ : undefined,
+ });
+ await focusBlockTarget("nested-node", deps);
+ expect(deps.setViewport).toHaveBeenCalledWith(
+ {
+ x: 1000 / 2 - (140 + 150) * 0.75,
+ y: START_ANCHOR_TOP_PX - 480 * 0.75,
+ zoom: 0.75,
+ },
+ { duration: 300 },
+ );
+ });
+
+ test("falls back to the node's own position and measurements", async () => {
+ const deps = makeDeps();
+ await focusBlockTarget("login-node", deps);
+ expect(deps.setViewport).toHaveBeenCalledWith(
+ {
+ x: 1000 / 2 - (0 + 200) * 0.75,
+ y: START_ANCHOR_TOP_PX - 100 * 0.75,
+ zoom: 0.75,
+ },
+ { duration: 300 },
+ );
+ });
+
+ test("refuses unknown ids and utility nodes without side effects", async () => {
+ const deps = makeDeps();
+ await expect(focusBlockTarget("missing-node", deps)).resolves.toBe(false);
+ await expect(focusBlockTarget("start-node", deps)).resolves.toBe(false);
+ expect(deps.selectBlock).not.toHaveBeenCalled();
+ expect(deps.setViewport).not.toHaveBeenCalled();
+ expect(deps.switchBranch).not.toHaveBeenCalled();
+ });
+
+ test("hidden-branch target: focuses the conditional, switches the branch, settles, then centers the target on fresh geometry", async () => {
+ const conditionalNodes = makeConditionalNodes();
+ const calls: Array<string> = [];
+ const deps = makeDeps(conditionalNodes, {
+ getInternalNode: (nodeId) =>
+ nodeId === "cond-node"
+ ? {
+ internals: { positionAbsolute: { x: 0, y: 100 } },
+ measured: { width: 480, height: 300 },
+ }
+ : undefined,
+ selectBlock: vi.fn((id) => calls.push(`select:${id}`)),
+ expandBlock: vi.fn((label) => calls.push(`expand:${label}`)),
+ setViewport: vi.fn((viewport) =>
+ calls.push(`anchor:${viewport.x},${viewport.y}`),
+ ),
+ switchBranch: vi.fn((conditionalId, branchId) =>
+ calls.push(`switch:${conditionalId}:${branchId}`),
+ ),
+ waitForSettle: vi.fn(async () => {
+ calls.push("settle");
+ // Simulate the visibility cascade + re-layout moving the target.
+ const target = conditionalNodes.find(
+ (node) => node.id === "branch-b-block",
+ )!;
+ (target as { hidden?: boolean }).hidden = false;
+ target.position = { x: 500, y: 700 };
+ (target as { measured?: { width: number; height: number } }).measured =
+ { width: 400, height: 100 };
+ }),
+ });
+
+ await expect(focusBlockTarget("branch-b-block", deps)).resolves.toBe(true);
+ // Conditional: internal (0,100) 480 wide -> x=500-240*0.75, y=24-100*0.75.
+ // Target post-settle (500,700) 400 wide -> x=500-700*0.75, y=24-700*0.75.
+ expect(calls).toEqual([
+ "select:cond-node",
+ "expand:Route by type",
+ `anchor:320,${START_ANCHOR_TOP_PX - 75}`,
+ "switch:cond-node:branch-b",
+ "settle",
+ "select:branch-b-block",
+ "expand:Handle type B",
+ // Post-settle geometry, not the stale pre-switch position.
+ `anchor:-25,${START_ANCHOR_TOP_PX - 525}`,
+ ]);
+ });
+
+ test("nested conditionals switch every level root→leaf with a settle between", async () => {
+ const conditionalNodes = makeConditionalNodes();
+ const calls: Array<string> = [];
+ const deps = makeDeps(conditionalNodes, {
+ selectBlock: vi.fn((id) => calls.push(`select:${id}`)),
+ switchBranch: vi.fn((conditionalId, branchId) =>
+ calls.push(`switch:${conditionalId}:${branchId}`),
+ ),
+ waitForSettle: vi.fn(async () => {
+ calls.push("settle");
+ }),
+ });
+
+ await expect(focusBlockTarget("inner-branch-y-block", deps)).resolves.toBe(
+ true,
+ );
+ expect(
+ calls.filter(
+ (entry) => entry.startsWith("switch:") || entry === "settle",
+ ),
+ ).toEqual([
+ "switch:cond-node:branch-b",
+ "settle",
+ "switch:inner-cond-node:branch-y",
+ "settle",
+ ]);
+ expect(calls[calls.length - 1]).toBe("select:inner-branch-y-block");
+ });
+});
diff --git a/skyvern-frontend/src/routes/workflows/studio/blockSearch.ts b/skyvern-frontend/src/routes/workflows/studio/blockSearch.ts
new file mode 100644
index 000000000..dd39fb6bb
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/blockSearch.ts
@@ -0,0 +1,268 @@
+// Pure helpers for the studio Editor pane's block search: collecting the
+// searchable targets from the canvas nodes (hidden-branch blocks included),
+// the label matcher, and the jump — conditional-branch resolution plus the
+// focus sequence — expressed against injectable seams so it unit-tests
+// without a live React Flow instance.
+
+import {
+ type AppNode,
+ isWorkflowBlockNode,
+} from "@/routes/workflows/editor/nodes";
+import { blockTypeFromNode } from "@/routes/workflows/editor/nodes/blockTypeFromNode";
+import { isConditionalNode } from "@/routes/workflows/editor/nodes/ConditionalNode/types";
+import { START_ANCHOR_TOP_PX } from "@/routes/workflows/editor/paneFit";
+import { type WorkflowBlockType } from "@/routes/workflows/types/workflowTypes";
+
+export type BlockSearchTarget = {
+ nodeId: string;
+ label: string;
+ // Null when the node type has no block-type mapping (see blockTypeFromNode);
+ // consumers skip the icon rather than guess one.
+ blockType: WorkflowBlockType | null;
+};
+
+export function collectBlockSearchTargets(
+ nodes: Array<AppNode>,
+): Array<BlockSearchTarget> {
+ return nodes.filter(isWorkflowBlockNode).flatMap((node) => {
+ if (node.data.label.trim() === "") {
+ return [];
+ }
+ return [
+ {
+ nodeId: node.id,
+ label: node.data.label,
+ blockType: blockTypeFromNode(node) as WorkflowBlockType | null,
+ },
+ ];
+ });
+}
+
+// Case-insensitive substring match over block labels; an empty query keeps
+// every target so the open popover lists the whole flow in canvas order.
+export function filterBlockSearchTargets(
+ targets: Array<BlockSearchTarget>,
+ query: string,
+): Array<BlockSearchTarget> {
+ const needle = query.trim().toLowerCase();
+ if (needle === "") {
+ return targets;
+ }
+ return targets.filter((target) =>
+ target.label.toLowerCase().includes(needle),
+ );
+}
+
+export const BLOCK_JUMP_DURATION_MS = 300;
+
+export function blockJumpDuration(): number {
+ if (
+ typeof window === "undefined" ||
+ typeof window.matchMedia !== "function"
+ ) {
+ return 0;
+ }
+ return window.matchMedia("(prefers-reduced-motion: reduce)").matches
+ ? 0
+ : BLOCK_JUMP_DURATION_MS;
+}
+
+// Structural slice of React Flow's InternalNode: positionAbsolute is the
+// canvas-space position even for blocks nested inside loop containers, whose
+// own `position` is parent-relative.
+type InternalNodeLike = {
+ internals: { positionAbsolute: { x: number; y: number } };
+ measured?: { width?: number; height?: number };
+};
+
+export type ConditionalBranchSwitch = {
+ conditionalId: string;
+ conditionalLabel: string;
+ branchId: string;
+};
+
+/**
+ * Conditional levels (root→leaf) whose active branch must change before
+ * `targetNodeId` can be visible. Nodes in a branch chain carry the
+ * (conditionalNodeId, conditionalBranchId) affinity; blocks nested deeper
+ * (e.g. inside a loop within a branch) reach the chain via parentId.
+ */
+export function resolveConditionalBranchPath(
+ nodes: Array<AppNode>,
+ targetNodeId: string,
+): Array<ConditionalBranchSwitch> {
+ const byId = new Map(nodes.map((node) => [node.id, node]));
+ const path: Array<ConditionalBranchSwitch> = [];
+ const visited = new Set<string>();
+ let current = byId.get(targetNodeId);
+ while (current && !visited.has(current.id)) {
+ visited.add(current.id);
+ const conditionalId = isWorkflowBlockNode(current)
+ ? (current.data.conditionalNodeId ?? null)
+ : null;
+ if (conditionalId !== null) {
+ const conditional = byId.get(conditionalId);
+ if (!conditional || !isConditionalNode(conditional)) {
+ break;
+ }
+ const branchId = isWorkflowBlockNode(current)
+ ? (current.data.conditionalBranchId ?? null)
+ : null;
+ if (branchId !== null && conditional.data.activeBranchId !== branchId) {
+ path.push({
+ conditionalId: conditional.id,
+ conditionalLabel: conditional.data.label,
+ branchId,
+ });
+ }
+ current = conditional;
+ continue;
+ }
+ current = current.parentId ? byId.get(current.parentId) : undefined;
+ }
+ return path.reverse();
+}
+
+export const BRANCH_SETTLE_STABLE_FRAMES = 3;
+export const BRANCH_SETTLE_TIMEOUT_MS = 2000;
+
+type NodeSettleDeps = {
+ getNodes: () => Array<AppNode>;
+ getInternalNode: (nodeId: string) => InternalNodeLike | undefined;
+ requestFrame?: (callback: () => void) => void;
+ now?: () => number;
+};
+
+/**
+ * Resolves once `nodeId` is visible and its canvas position has held still
+ * for a few consecutive frames. A branch switch cascades visibility (the
+ * BranchesEditor effect) and then a full re-layout (Workspace's
+ * conditional-branch-changed listener) on staggered timeouts, so positions
+ * read before this settles are stale. Times out rather than hanging when the
+ * node never becomes visible.
+ */
+export function waitForNodeSettle(
+ nodeId: string,
+ deps: NodeSettleDeps,
+): Promise<void> {
+ const requestFrame =
+ deps.requestFrame ??
+ ((callback) => window.requestAnimationFrame(() => callback()));
+ const now = deps.now ?? (() => performance.now());
+ const startedAt = now();
+ let lastX: number | null = null;
+ let lastY: number | null = null;
+ let stableFrames = 0;
+ return new Promise((resolve) => {
+ const step = () => {
+ const node = deps.getNodes().find((candidate) => candidate.id === nodeId);
+ const position =
+ deps.getInternalNode(nodeId)?.internals.positionAbsolute ??
+ node?.position ??
+ null;
+ const visible = node !== undefined && node.hidden !== true;
+ if (
+ visible &&
+ position !== null &&
+ position.x === lastX &&
+ position.y === lastY
+ ) {
+ stableFrames += 1;
+ } else {
+ stableFrames = 0;
+ }
+ lastX = position?.x ?? null;
+ lastY = position?.y ?? null;
+ if (
+ (visible && stableFrames >= BRANCH_SETTLE_STABLE_FRAMES) ||
+ now() - startedAt >= BRANCH_SETTLE_TIMEOUT_MS
+ ) {
+ resolve();
+ return;
+ }
+ requestFrame(step);
+ };
+ requestFrame(step);
+ });
+}
+
+export type FocusBlockDeps = {
+ getNodes: () => Array<AppNode>;
+ getInternalNode: (nodeId: string) => InternalNodeLike | undefined;
+ getPaneWidth: () => number;
+ viewportZoom: number;
+ duration: number;
+ setViewport: (
+ viewport: { x: number; y: number; zoom: number },
+ options: { duration: number },
+ ) => void;
+ selectBlock: (nodeId: string) => void;
+ expandBlock: (label: string) => void;
+ // Writes activeBranchId into the conditional's node data — the same write
+ // the branch tab click makes (the binding supplies the dirty-state guards).
+ switchBranch: (conditionalId: string, branchId: string) => void;
+ waitForSettle: (nodeId: string) => Promise<void>;
+};
+
+// Horizontally centers the block but anchors its TOP edge at the
+// start-anchored-fit offset below the pane top, at the current zoom: a tall
+// container lands on its header instead of vertically centering on its
+// unrelated inner children.
+function anchorViewportToNode(node: AppNode, deps: FocusBlockDeps): void {
+ const internal = deps.getInternalNode(node.id);
+ const position = internal?.internals.positionAbsolute ?? node.position;
+ const width = internal?.measured?.width ?? node.measured?.width ?? 0;
+ const zoom = deps.viewportZoom;
+ deps.setViewport(
+ {
+ x: deps.getPaneWidth() / 2 - (position.x + width / 2) * zoom,
+ y: START_ANCHOR_TOP_PX - position.y * zoom,
+ zoom,
+ },
+ { duration: deps.duration },
+ );
+}
+
+/**
+ * Selects the block (which the selected-block URL sync mirrors into
+ * `?selected-block=`), reveals its inline editor, and top-anchors the
+ * viewport on it at the current zoom. A target hidden inside inactive
+ * conditional branches is first revealed level by level (root→leaf): focus
+ * the conditional, switch it to the target's branch, wait for the visibility
+ * cascade + re-layout to settle, then continue. Returns false when the node
+ * no longer exists or is not a workflow block.
+ */
+export async function focusBlockTarget(
+ nodeId: string,
+ deps: FocusBlockDeps,
+): Promise<boolean> {
+ const findNode = (id: string) =>
+ deps.getNodes().find((candidate) => candidate.id === id);
+ const target = findNode(nodeId);
+ if (!target || !isWorkflowBlockNode(target)) {
+ return false;
+ }
+
+ const branchPath = resolveConditionalBranchPath(deps.getNodes(), nodeId);
+ for (const { conditionalId, conditionalLabel, branchId } of branchPath) {
+ const conditional = findNode(conditionalId);
+ if (conditional) {
+ deps.selectBlock(conditionalId);
+ // A collapsed conditional renders header-only without its BranchesEditor,
+ // whose mounted effect is what applies the branch visibility switch.
+ deps.expandBlock(conditionalLabel);
+ anchorViewportToNode(conditional, deps);
+ }
+ deps.switchBranch(conditionalId, branchId);
+ await deps.waitForSettle(nodeId);
+ }
+
+ const settled = findNode(nodeId);
+ if (!settled || !isWorkflowBlockNode(settled)) {
+ return false;
+ }
+ deps.selectBlock(nodeId);
+ deps.expandBlock(settled.data.label);
+ anchorViewportToNode(settled, deps);
+ return true;
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/constants.ts b/skyvern-frontend/src/routes/workflows/studio/constants.ts
index 9ee890baa..5f7510bd1 100644
--- a/skyvern-frontend/src/routes/workflows/studio/constants.ts
+++ b/skyvern-frontend/src/routes/workflows/studio/constants.ts
@@ -5,3 +5,8 @@ export const STUDIO_COPILOT_TRANSITION_MS = 300;
// Stable element ids linking each top-bar toggle to the pane it controls.
export const studioTabId = (tab: string) => `studio-tab-${tab}`;
export const studioPanelId = (tab: string) => `studio-panel-${tab}`;
+
+// Bordered icon-square pane-header action per the studio button grammar
+// (cloud_docs/frontend/studio-button-system.md).
+export const PANE_HEADER_ICON_BUTTON_CLASS =
+ "inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-border text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40";
diff --git a/skyvern-frontend/src/store/WorkflowBlockSearchStore.ts b/skyvern-frontend/src/store/WorkflowBlockSearchStore.ts
new file mode 100644
index 000000000..cac8cc120
--- /dev/null
+++ b/skyvern-frontend/src/store/WorkflowBlockSearchStore.ts
@@ -0,0 +1,26 @@
+import { create } from "zustand";
+
+import { type BlockSearchTarget } from "@/routes/workflows/studio/blockSearch";
+
+type WorkflowBlockSearchHandle = {
+ // Searchable blocks in canvas order, read fresh on each popover open.
+ getTargets: () => Array<BlockSearchTarget>;
+ // Selects the block and centers the canvas on it.
+ focusBlock: (nodeId: string) => void;
+};
+
+type WorkflowBlockSearchState = {
+ // Registered by the studio's embedded FlowRenderer (which owns the React
+ // Flow instance) so the Editor pane header's search can jump the canvas
+ // without owning it. Null while no searchable canvas is mounted — the
+ // header hides the control.
+ handle: WorkflowBlockSearchHandle | null;
+ registerHandle: (handle: WorkflowBlockSearchHandle | null) => void;
+};
+
+export const useWorkflowBlockSearchStore = create<WorkflowBlockSearchState>(
+ (set) => ({
+ handle: null,
+ registerHandle: (handle) => set({ handle }),
+ }),
+);