diff --git a/packages/apollo-react/src/canvas/README.md b/packages/apollo-react/src/canvas/README.md
index 7395e635e..5802b72b4 100644
--- a/packages/apollo-react/src/canvas/README.md
+++ b/packages/apollo-react/src/canvas/README.md
@@ -195,3 +195,71 @@ If you already use `@uipath/apollo-react/canvas/styles/variables.css` with shado
**Cause:** The Tailwind base layer includes `* { border-color: var(--color-border-de-emp) }` and `body { background-color: var(--background) }`. These may conflict with existing component styles.
**Fix:** These rules are in `@layer base`, so they lose to un-layered styles. If conflicts persist in Shadow DOM, override with more specific selectors in your injected CSS.
+
+---
+
+## Sequential view
+
+`SequentialCanvas` is an n8n/Zapier-style vertical projection of the same flow graph, built on the existing `BaseCanvas`. It reuses the same node manifests, icons, execution status, validation badges, and theming as the flow view; only the layout is different. A `ViewSwitcher` lets the host toggle a canvas between the free-form `flow` layout and the vertical `sequential` layout.
+
+### Projection model
+
+The consumer keeps one canonical `nodes`/`edges` array. `SequentialCanvas` derives vertical geometry from graph structure and never writes that geometry back. Entering Flow through `prepareCanvasViewTransition` computes a deterministic left-to-right layout and updates only canonical presentation fields (`position` and container dimensions); ids, data, containment, handles, and edges are unchanged. Nodes added in Sequential are normalized during the same transition.
+
+Sequential is not a symmetric conversion for every graph. `prepareCanvasViewTransition('sequential', ...)` returns a compatibility report: exact graphs are safely editable, degraded graphs (cycles, multiple roots, unstructured merges, orphans) should be presented read-only, and malformed containment is unsupported. Presentation-only nodes and edges can be excluded from the projection and preserved in the canonical graph.
+
+### Minimal usage
+
+```tsx
+import { useState } from 'react';
+import { applyEdgeChanges, applyNodeChanges } from '@uipath/apollo-react/canvas/xyflow/react';
+import {
+ prepareCanvasViewTransition,
+ SequentialCanvas,
+ useCanvasViewMode,
+ ViewSwitcher,
+} from '@uipath/apollo-react/canvas';
+
+function MyFlow({ initialNodes, initialEdges }) {
+ const [view, setView] = useCanvasViewMode('my-flow.view');
+ const [nodes, setNodes] = useState(initialNodes);
+ const [edges, setEdges] = useState(initialEdges);
+
+ const changeView = (nextView) => {
+ const transition = prepareCanvasViewTransition(nextView, nodes, edges);
+ setNodes(transition.nodes);
+ setView(nextView);
+ };
+
+ return (
+
+ ),
+}));
+
+import { SEQ_HANDLE_LEFT_OFFSET } from '../../constants';
+import { BaseNode } from './BaseNode';
+import { INVISIBLE_HANDLE_STYLE } from './BaseNodeBar';
+import { BaseNodeBarNode } from './BaseNodeBarNode';
+
+const defaultProps: NodeProps> = {
+ id: 'step-1',
+ type: 'uipath.http',
+ data: {},
+ selected: false,
+ dragging: false,
+ draggable: true,
+ zIndex: 0,
+ isConnectable: true,
+ positionAbsoluteX: 0,
+ positionAbsoluteY: 0,
+ selectable: true,
+ deletable: true,
+};
+
+describe('BaseNodeBar (sequential bar variant)', () => {
+ afterEach(() => {
+ mockUpdateNode.mockClear();
+ mockNodeState.current = { height: undefined };
+ mockHandleConfigs.current = undefined;
+ mockOverrideConfig.current = {};
+ mockMode.current = 'design';
+ mockNodeLabel.mockClear();
+ mockSelectionState.current = { multipleNodesSelected: false };
+ mockManifest.current = {
+ display: { label: 'HTTP Request', shape: 'rectangle', icon: 'globe' },
+ handleConfiguration: [],
+ };
+ });
+
+ // The core visual-drift contract: the same node resolves to the same display
+ // (label / icon / color source) whether it renders as a card or a bar.
+ describe('display parity with the card variant', () => {
+ it('renders the identical resolved label and icon', () => {
+ const { unmount } = render();
+ const cardLabel = screen.getByTestId('node-label').textContent;
+ expect(screen.getAllByTestId('node-icon').length).toBeGreaterThan(0);
+ unmount();
+
+ render();
+ expect(screen.getByTestId('node-label').textContent).toBe(cardLabel);
+ expect(screen.getAllByTestId('node-icon').length).toBeGreaterThan(0);
+ });
+
+ it('feeds the icon shape from the same color source', () => {
+ const { unmount } = render();
+ const cardShape = screen.getByTestId('inner-shape');
+ const cardBg = cardShape.getAttribute('data-background');
+ const cardColor = cardShape.getAttribute('data-color');
+ unmount();
+
+ render();
+ const barShape = screen.getByTestId('inner-shape');
+ expect(barShape.getAttribute('data-background')).toBe(cardBg);
+ expect(barShape.getAttribute('data-color')).toBe(cardColor);
+ expect(cardBg).toBe('#611f69');
+ });
+ });
+
+ describe('bar geometry', () => {
+ it('renders at the fixed 896x56 bar size regardless of handle count', () => {
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar.style.getPropertyValue('--node-w')).toBe('896px');
+ expect(bar.style.getPropertyValue('--node-h')).toBe('56px');
+ });
+
+ it('writes the fixed bar height (56) back to node.height', () => {
+ render();
+ expect(mockUpdateNode).toHaveBeenCalledWith('step-1', { height: 56 });
+ });
+ });
+
+ it('paints the left accent strip from the resolved icon background', () => {
+ render();
+ const accent = screen.getByTestId('sequential-bar-accent');
+ // Rendered as an inset box-shadow so the stripe follows the bar's rounded
+ // corners rather than a square-cornered strip.
+ expect(accent.style.boxShadow).toContain('#611f69');
+ });
+
+ it('keeps inline rename enabled in design mode (readonly=false, onChange wired)', () => {
+ render();
+ const labelProps = mockNodeLabel.mock.calls.at(-1)?.[0];
+ expect(labelProps.readonly).toBe(false);
+ expect(typeof labelProps.onChange).toBe('function');
+ expect(labelProps.shape).toBe('rectangle');
+ });
+
+ it('disables rename outside design mode', () => {
+ mockMode.current = 'view';
+ render();
+ expect(mockNodeLabel.mock.calls.at(-1)?.[0].readonly).toBe(true);
+ });
+
+ describe('trailing group', () => {
+ it('renders the toolbar actions as a kebab when selected', () => {
+ mockOverrideConfig.current = {
+ toolbarConfig: {
+ actions: [{ id: 'delete', icon: , label: 'Delete', onAction: vi.fn() }],
+ },
+ };
+ render();
+ expect(screen.getByLabelText('More options')).toBeInTheDocument();
+ });
+
+ it('fires the toolbar action with the node id when the item is selected', () => {
+ const onAction = vi.fn();
+ mockOverrideConfig.current = {
+ toolbarConfig: {
+ actions: [{ id: 'delete', icon: , label: 'Delete', onAction }],
+ },
+ };
+ render();
+ fireEvent.click(screen.getByText('Delete'));
+ expect(onAction).toHaveBeenCalledWith('step-1');
+ });
+
+ it('resolves a string toolbar icon through the icon registry instead of rendering it as literal text', () => {
+ mockOverrideConfig.current = {
+ toolbarConfig: {
+ actions: [{ id: 'delete', icon: 'trash', label: 'Delete', onAction: vi.fn() }],
+ },
+ };
+ render();
+ expect(screen.getByTestId('canvas-icon-trash')).toBeInTheDocument();
+ expect(screen.queryByText('trash')).not.toBeInTheDocument();
+ });
+
+ it('still renders a custom React node icon as-is (no double resolution)', () => {
+ mockOverrideConfig.current = {
+ toolbarConfig: {
+ actions: [
+ {
+ id: 'delete',
+ icon: ,
+ label: 'Delete',
+ onAction: vi.fn(),
+ },
+ ],
+ },
+ };
+ render();
+ expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+ });
+
+ it('hides the kebab when multiple nodes are selected, mirroring the card toolbar gating', () => {
+ mockOverrideConfig.current = {
+ toolbarConfig: {
+ actions: [{ id: 'delete', icon: , label: 'Delete', onAction: vi.fn() }],
+ },
+ };
+ mockSelectionState.current = { multipleNodesSelected: true };
+ render();
+ expect(screen.queryByLabelText('More options')).not.toBeInTheDocument();
+ });
+
+ it('shows the status indicator when not action-needed', () => {
+ render();
+ expect(screen.getByTestId('status-indicator')).toBeInTheDocument();
+ expect(screen.queryByText('Action needed')).not.toBeInTheDocument();
+ });
+
+ it('gives the Action needed pill precedence over the status indicator', () => {
+ const onActionNeeded = vi.fn();
+ mockOverrideConfig.current = { executionStatusOverride: 'ActionNeeded', onActionNeeded };
+ render();
+
+ expect(screen.queryByTestId('status-indicator')).not.toBeInTheDocument();
+ const pill = screen.getByText('Action needed');
+ fireEvent.click(pill);
+ expect(onActionNeeded).toHaveBeenCalledWith('step-1');
+ });
+ });
+
+ describe('extraMenuItems passthrough', () => {
+ it('shows the kebab from extraMenuItems alone, with no toolbar configured', () => {
+ render(
+
+ );
+ expect(screen.getByLabelText('More options')).toBeInTheDocument();
+ expect(screen.getByText('Move up')).toBeInTheDocument();
+ });
+
+ it('appends extraMenuItems after the toolbar actions with a divider between the two groups', () => {
+ mockOverrideConfig.current = {
+ toolbarConfig: {
+ actions: [{ id: 'delete', icon: , label: 'Delete', onAction: vi.fn() }],
+ },
+ };
+ const { container } = render(
+
+ );
+ expect(screen.getByText('Delete')).toBeInTheDocument();
+ expect(screen.getByText('Move up')).toBeInTheDocument();
+ // DropdownMenuSeparator is mocked to (see the @uipath/apollo-wind mock above).
+ expect(container.querySelectorAll('hr')).toHaveLength(1);
+ });
+
+ it('fires an extraMenuItems action on click', () => {
+ const onClick = vi.fn();
+ render(
+
+ );
+ fireEvent.click(screen.getByText('Move up'));
+ expect(onClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('renders a disabled extraMenuItems action as disabled', () => {
+ render(
+
+ );
+ expect(screen.getByText('Move up').closest('button')).toBeDisabled();
+ });
+
+ it('renders no kebab at all when there is neither a toolbar nor extraMenuItems', () => {
+ render();
+ expect(screen.queryByLabelText('More options')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('display parity: background and shadow', () => {
+ it('applies display.background as an inline background style, like BaseContainer', () => {
+ mockManifest.current = {
+ display: {
+ label: 'HTTP Request',
+ shape: 'rectangle',
+ icon: 'globe',
+ background: 'linear-gradient(90deg, #611f69, #0ea5e9)',
+ },
+ handleConfiguration: [],
+ };
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar.style.background).toContain('linear-gradient');
+ });
+
+ it('renders the rest shadow class by default (display.shadow unset)', () => {
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar.className).toContain('shadow-(--canvas-node-shadow-rest)');
+ });
+
+ it('omits the rest shadow class when display.shadow is false, like BaseContainer', () => {
+ mockManifest.current = {
+ display: { label: 'HTTP Request', shape: 'rectangle', icon: 'globe', shadow: false },
+ handleConfiguration: [],
+ };
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar.className).not.toContain('shadow-(--canvas-node-shadow-rest)');
+ });
+ });
+
+ describe('loading accessibility', () => {
+ it('sets aria-busy on the bar shell while loading, matching BaseContainer', () => {
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar).toHaveAttribute('aria-busy', 'true');
+ });
+
+ it('omits aria-busy when not loading', () => {
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar).not.toHaveAttribute('aria-busy');
+ });
+ });
+
+ // Connectors anchor to the bar's bottom-left / top-left
+ // region instead of its horizontal center. `Handle` itself is stubbed to
+ // `null` above (BaseNode's Handle-rendering internals aren't under test
+ // here), so this asserts directly against the shared style object BOTH the
+ // top target and bottom source handles use -- the actual source of truth
+ // xyflow reads to position the real handle DOM nodes in production.
+ describe('handle anchoring', () => {
+ it('anchors the invisible top/bottom handles at SEQ_HANDLE_LEFT_OFFSET from the bar left edge, not the horizontal center', () => {
+ expect(INVISIBLE_HANDLE_STYLE.left).toBe(SEQ_HANDLE_LEFT_OFFSET);
+ });
+ });
+
+ // A collapsed collapsible sequential row renders the same
+ // decorative "stacked" treatment BaseContainer applies to drillable/collapsed
+ // cards (a layered bar peeking out behind), driven by a `stacked` prop
+ // (threaded via context by SequentialStepNode, never node.data) rather than
+ // any state BaseNodeBar derives itself.
+ describe('collapsed stacked treatment', () => {
+ it('renders no stacked-layer classes or data-stacked attribute by default', () => {
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar).not.toHaveAttribute('data-stacked');
+ expect(bar.className).not.toContain('before:border-brand');
+ });
+
+ it('renders the stacked-layer classes and data-stacked when stacked=true', () => {
+ render();
+ const bar = screen.getByTestId('sequential-bar');
+ expect(bar).toHaveAttribute('data-stacked', 'true');
+ expect(bar.className).toContain('before:border-brand');
+ expect(bar.className).toContain('before:-z-10');
+ expect(bar.className).toContain('before:translate-y-[6px]');
+ });
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/BaseNode/BaseNodeBar.tsx b/packages/apollo-react/src/canvas/components/BaseNode/BaseNodeBar.tsx
new file mode 100644
index 000000000..490747d7b
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/BaseNode/BaseNodeBar.tsx
@@ -0,0 +1,390 @@
+import { Handle, Position } from '@uipath/apollo-react/canvas/xyflow/react';
+import { cn } from '@uipath/apollo-wind';
+import { memo, useMemo, useState } from 'react';
+import { useSafeLingui } from '../../../i18n';
+import { SEQ_BAR_HEIGHT, SEQ_BAR_WIDTH, SEQ_HANDLE_LEFT_OFFSET } from '../../constants';
+import type { SuggestionType } from '../../types';
+import type { ElementStatusValues } from '../../types/execution';
+import type { ValidationErrorSeverity } from '../../types/validation';
+import { CanvasIcon } from '../../utils/icon-registry';
+import type { NodeMenuItem } from '../NodeContextMenu';
+import { CanvasDropdownMenu } from '../shared/CanvasDropdownMenu';
+import type { NodeToolbarConfig } from '../Toolbar';
+import { getStatusBorder } from './BaseNodeContainer';
+import { BaseInnerShape } from './BaseNodeInnerShape';
+import { NodeLabel, type NodeLabelProps } from './NodeLabel';
+
+/**
+ * Bar geometry as CSS custom properties, shared by the manifest-backed step bar
+ * (BaseNodeBar) and the synthetic start / placeholder bars so all three render
+ * at an identical size. Fixed values (not the card's ratio math) because a
+ * compact row needs a constant icon box rather than one that scales with the
+ * container aspect ratio. Icon box shrunk to ~32px (from 40px) to stay
+ * balanced against the tightened `SEQ_BAR_HEIGHT`; the
+ * icon-to-box and radius-to-box ratios are unchanged from the original.
+ */
+export const SEQ_BAR_VARS = {
+ '--node-w': `${SEQ_BAR_WIDTH}px`,
+ '--node-h': `${SEQ_BAR_HEIGHT}px`,
+ '--node-radius': '12px',
+ '--inner-w': '32px',
+ '--inner-h': '32px',
+ '--inner-radius': '8px',
+ '--icon-size': '16px',
+} as React.CSSProperties;
+
+/** Returns the shared bar CSS variables with optional layout-owned dimensions. */
+export function getSeqBarVars(width = SEQ_BAR_WIDTH, height = SEQ_BAR_HEIGHT): React.CSSProperties {
+ return {
+ ...SEQ_BAR_VARS,
+ '--node-w': `${width}px`,
+ '--node-h': `${height}px`,
+ } as React.CSSProperties;
+}
+
+/**
+ * Static base classes for the bar shell. Mirrors BaseContainer's channel
+ * discipline (surface + border) in a horizontal layout. The rest/hover/lifted
+ * shadow classes are layered on per instance (gated by the `shadow` prop, like
+ * BaseContainer), along with status border, hover, and selection classes.
+ * Padding/gap tightened (`px-4`/`gap-3` -> `px-3`/`gap-2`) alongside the
+ * shorter `SEQ_BAR_HEIGHT` so the row reads balanced rather than cramped.
+ */
+export const SEQ_BAR_SHELL_CLASS =
+ 'relative flex flex-row items-center gap-2 px-3 bg-surface-overlay border border-border w-(--node-w) h-(--node-h) rounded-(--node-radius) outline-offset-0 transition-[box-shadow,border-color] duration-150';
+
+/**
+ * Handle ids used by every sequential bar. Rows expose one invisible top target
+ * and one invisible bottom source; connectors and the assembly wire
+ * edges between `source` of row N and `target` of row N+1.
+ */
+export const SEQUENTIAL_BAR_HANDLE_IDS = {
+ target: 'seq-target',
+ source: 'seq-source',
+ // Mid-left target used only by `branch-entry` connectors: a branch/container
+ // lane's first row is entered from its LEFT side at mid-height (not the top),
+ // so the elbow off the owner's spine reads as an indent. Left handles sit at
+ // the bar's left edge, vertically centered, with no left-offset.
+ branchTarget: 'seq-branch-target',
+} as const;
+
+/**
+ * Transparent 8px handle: sequential bars are not user-connectable in v1.
+ * `left` is pinned to `SEQ_HANDLE_LEFT_OFFSET` so the handle anchors to the
+ * bar's bottom-left / top-left region instead of xyflow's
+ * default horizontal center; the vertical placement and centering transform
+ * still come from xyflow's `.react-flow__handle-{top,bottom}` classes; this
+ * inline style only overrides `left`, not `transform`, so the handle's CENTER
+ * point lands exactly `SEQ_HANDLE_LEFT_OFFSET`px from the bar's left edge.
+ * Shared by the manifest-backed bar (below) and the synthetic start/placeholder
+ * bars (nodes/SequentialStartNode.tsx, nodes/SequentialPlaceholderNode.tsx) so
+ * every row -- real or synthetic -- anchors its connectors identically.
+ */
+export const INVISIBLE_HANDLE_STYLE: React.CSSProperties = {
+ background: 'transparent',
+ border: 'none',
+ width: 8,
+ height: 8,
+ left: SEQ_HANDLE_LEFT_OFFSET,
+};
+
+/**
+ * Decorative stacked layer for a collapsed sequential row, mirroring
+ * BaseContainer's `isStacked` recipe (components/BaseNode/BaseNodeContainer.tsx)
+ * adapted to the bar's horizontal shape: a `::before` pseudo-element the same
+ * size as the bar, offset down and pushed behind it (`-z-10`), so a thin arc of
+ * a second bar peeks out below -- signalling that collapsed content sits
+ * underneath. Kept as a local copy (not a shared export) so this file's owner
+ * doesn't need to also own BaseNodeContainer.tsx; keep the two class strings in
+ * sync if BaseContainer's recipe changes.
+ */
+const SEQ_BAR_STACKED_LAYER_CLASS =
+ 'before:content-[""] before:absolute before:inset-x-0 before:top-0 before:h-full before:rounded-[inherit] before:bg-surface-overlay before:border before:border-brand before:translate-y-[6px] before:-z-10 before:pointer-events-none';
+
+export interface BaseNodeBarProps {
+ nodeId: string;
+ width?: number;
+ height?: number;
+ mode?: 'design' | 'view' | 'readonly';
+ selected?: boolean;
+ dragging?: boolean;
+ disabled?: boolean;
+ label?: string;
+ subLabel?: NodeLabelProps['subLabel'];
+ labelTooltip?: string;
+ labelBackgroundColor?: string;
+ icon: React.ReactNode;
+ loading?: boolean;
+ /** Drives both the icon-box background and the left accent strip. */
+ iconBackground?: string;
+ iconColor?: string;
+ /** Same resolved display.background the card applies via BaseContainer. */
+ background?: string;
+ /** Same resolved display.shadow the card applies via BaseContainer. Defaults to true. */
+ shadow?: boolean;
+ executionStatus?: ElementStatusValues;
+ validationStatus?: ValidationErrorSeverity;
+ suggestionType?: SuggestionType;
+ /** The resolved trailing status/validation indicator (adornments.topRight). */
+ statusIndicator?: React.ReactNode;
+ /** Same resolved toolbar as the card; its actions feed the kebab menu (D3). */
+ toolbarConfig?: NodeToolbarConfig;
+ /** Hides the kebab during rubber-band multi-select, mirroring the card toolbar (BaseNode.tsx `hidden`). */
+ multipleNodesSelected?: boolean;
+ /**
+ * True when this row is a collapsed collapsible step. Driven by
+ * view-local collapsed state threaded through context (SequentialStepNode ->
+ * SequentialCollapsedRowsContext), never `node.data`, so the sequential
+ * clone's data stays reference-stable (D12). Renders the same decorative
+ * stacked-layer treatment BaseContainer uses for `isStacked` cards.
+ */
+ stacked?: boolean;
+ /**
+ * Extra kebab items appended after the resolved toolbar actions, with
+ * a divider between the two groups when both are non-empty. See
+ * `BaseNodeBarNodeProps.extraMenuItems`'s doc comment (BaseNodeBarNode.tsx) for the D3
+ * rationale (a direct prop, not a new `BaseNodeOverrideConfig` field).
+ */
+ extraMenuItems?: NodeMenuItem[];
+ /**
+ * Manifest source/target handle ids to expose as extra INVISIBLE anchor
+ * handles alongside the generic seq-source/seq-target. A bar collapses
+ * each side to one point visually, but the Add Node connection validator
+ * resolves a node's handle by id against its manifest, so the insert preview
+ * must be able to anchor on a real manifest handle id that the bar actually
+ * renders. Derived connectors keep using seq-source/seq-target.
+ */
+ manifestSourceHandleIds?: string[];
+ manifestTargetHandleIds?: string[];
+ onLabelChange?: (values: { label: string; subLabel: string }) => void;
+ onActionNeeded?: (nodeId: string) => void;
+}
+
+/**
+ * Horizontal "bar" rendering of a node for the Sequential Canvas view. Fed by
+ * the same resolved display / adornments / toolbar sources as BaseNode through
+ * useBaseNodePresentation, so a node looks and behaves identically in both
+ * views. Card geometry and interactions remain owned by BaseNode.
+ */
+function BaseNodeBarComponent({
+ nodeId,
+ width,
+ height,
+ mode,
+ selected,
+ dragging,
+ disabled,
+ label,
+ subLabel,
+ labelTooltip,
+ labelBackgroundColor,
+ icon,
+ loading,
+ iconBackground,
+ iconColor,
+ background,
+ shadow = true,
+ executionStatus,
+ validationStatus,
+ suggestionType,
+ statusIndicator,
+ toolbarConfig,
+ multipleNodesSelected,
+ stacked,
+ extraMenuItems,
+ manifestSourceHandleIds,
+ manifestTargetHandleIds,
+ onLabelChange,
+ onActionNeeded,
+}: BaseNodeBarProps) {
+ const { _ } = useSafeLingui();
+ const [isHovered, setIsHovered] = useState(false);
+ const [menuOpen, setMenuOpen] = useState(false);
+
+ // Same priority as BaseContainer: suggestion > validation > execution. The
+ // status border stays the border channel; selection stays the outline channel.
+ const activeStatus = suggestionType ?? validationStatus ?? executionStatus;
+ const statusBorder = getStatusBorder(activeStatus);
+ const hasStatusBorder = statusBorder.length > 0;
+
+ const isActionNeeded = executionStatus === 'ActionNeeded';
+
+ // Kebab items are the resolved toolbar actions (design-mode delete/duplicate/
+ // etc.), flattened from the same NodeToolbarConfig the card toolbar consumes,
+ // with the extraMenuItems (Sequential Canvas move actions) appended after
+ // a divider when both groups are present.
+ const menuItems = useMemo(() => {
+ const toolbarItems: NodeMenuItem[] = !toolbarConfig
+ ? []
+ : [...toolbarConfig.actions, ...(toolbarConfig.overflowActions ?? [])].map(
+ (action) => {
+ if (!('onAction' in action)) {
+ return { type: 'divider' };
+ }
+ return {
+ id: action.id,
+ label: action.label ?? action.id,
+ icon:
+ typeof action.icon === 'string' ? (
+
+ ) : (
+ action.icon
+ ),
+ disabled: action.disabled,
+ onClick: () => action.onAction(nodeId),
+ };
+ }
+ );
+
+ if (!extraMenuItems || extraMenuItems.length === 0) return toolbarItems;
+ if (toolbarItems.length === 0) return extraMenuItems;
+ return [...toolbarItems, { type: 'divider' }, ...extraMenuItems];
+ }, [toolbarConfig, nodeId, extraMenuItems]);
+
+ const showKebab =
+ menuItems.length > 0 && !multipleNodesSelected && (isHovered || selected || menuOpen);
+
+ const className = cn(
+ SEQ_BAR_SHELL_CLASS,
+ 'cursor-pointer',
+ shadow && 'shadow-(--canvas-node-shadow-rest)',
+ statusBorder,
+ shadow && isHovered && 'shadow-(--canvas-node-shadow-hover)',
+ isHovered && !hasStatusBorder && 'border-border-hover',
+ selected && 'outline outline-2 outline-foreground-accent-muted',
+ disabled && 'opacity-50 cursor-not-allowed',
+ dragging && cn('cursor-grabbing', shadow && 'shadow-(--canvas-node-shadow-lifted)'),
+ stacked && SEQ_BAR_STACKED_LAYER_CLASS
+ );
+
+ return (
+
setIsHovered(true)}
+ onMouseLeave={() => setIsHovered(false)}
+ >
+
+ {/* Mid-left entry for branch-entry connectors (no left-offset: a Left
+ handle already anchors at the bar's left edge, vertically centered). */}
+
+ {manifestTargetHandleIds?.map((hid) =>
+ hid === SEQUENTIAL_BAR_HANDLE_IDS.target ? null : (
+
+ )
+ )}
+
+ {iconBackground && (
+ // Left accent stripe painted as an inset box-shadow on a bar-sized
+ // overlay so it follows the bar's rounded corners exactly. A plain
+ // `w-1` strip can't carry a matching corner radius (its 4px width clamps
+ // the curve), so its square corners poked past the rounded bar edge.
+ // `-inset-px` grows the overlay to the border-box edge (the overlay
+ // paints on top of the border), so the stripe sits flush against the
+ // selection outline instead of leaving the 1px border as a dark gap.
+
+ )}
+
+ {(icon || loading) && (
+
+
+ );
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialInsertGapContext.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialInsertGapContext.tsx
new file mode 100644
index 000000000..effb6e3df
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialInsertGapContext.tsx
@@ -0,0 +1,27 @@
+import { createContext, useContext } from 'react';
+import type { InsertionSlot } from '../../utils/sequential/sequential.types';
+
+export type SetSequentialInsertGapSlot = (slot: InsertionSlot) => void;
+
+const NOOP_SET: SetSequentialInsertGapSlot = () => {};
+
+const SequentialInsertGapContext = createContext(NOOP_SET);
+
+/** Provided by `SequentialCanvas.tsx`, which owns the actual state + the auto-clear-on-close effect. */
+export const SequentialInsertGapProvider = SequentialInsertGapContext.Provider;
+
+/**
+ * The setter every `useSequentialInsert()` call site's `startInsert` invokes
+ * to report the slot an Add Node panel just opened for -- both
+ * `SequentialCanvas.tsx`'s own terminal-placeholder callsite and every
+ * `SequentialConnectorEdge`'s "+" button are independent hook instances with
+ * no state of their own, so the slot needs a SHARED sink for the insert
+ * -preview -gap post-pass to react regardless of which
+ * affordance started the insert. `SequentialCanvas.tsx` owns clearing it
+ * (via `usePreviewNode` transitioning closed, covering both cancel and
+ * commit). A no-op default keeps isolated edge stories/tests (no
+ * `SequentialCanvas` mounted) working unchanged.
+ */
+export function useSetSequentialInsertGapSlot(): SetSequentialInsertGapSlot {
+ return useContext(SequentialInsertGapContext);
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialInsertStateContext.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialInsertStateContext.tsx
new file mode 100644
index 000000000..f0948df1d
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialInsertStateContext.tsx
@@ -0,0 +1,22 @@
+import { createContext, type MutableRefObject, type ReactNode, useContext, useRef } from 'react';
+import type { PendingSequentialInsert } from './edges/sequentialInsert';
+
+interface SequentialInsertState {
+ pending: MutableRefObject;
+}
+
+const SequentialInsertStateContext = createContext(undefined);
+
+/** Per-canvas insertion state shared by connector buttons and AddNodeManager. */
+export function SequentialInsertStateProvider({ children }: { children: ReactNode }) {
+ const pending = useRef(undefined);
+ return (
+
+ {children}
+
+ );
+}
+
+export function useOptionalSequentialInsertState(): SequentialInsertState | undefined {
+ return useContext(SequentialInsertStateContext);
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialMoveActionsContext.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialMoveActionsContext.tsx
new file mode 100644
index 000000000..b580290c9
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialMoveActionsContext.tsx
@@ -0,0 +1,35 @@
+import { createContext, useContext } from 'react';
+import type { InsertionSlot } from '../../utils/sequential/sequential.types';
+import type { SequentialMoveOptions } from './sequentialMoveActions';
+
+export interface SequentialMoveActionsContextValue {
+ /** The four move candidates for `nodeId` (disabled direction => `undefined`). */
+ getMoveOptions: (nodeId: string) => SequentialMoveOptions;
+ /**
+ * Applies `moveSubtree(projection, nodeId, slot, {nodes, edges})` through
+ * `onNodesChange`/`onEdgesChange` (D10: the public API stays the standard
+ * change callbacks, never a parallel mutation channel). A no-op for a
+ * degenerate/self-targeting slot, matching `moveSubtree`'s own guard
+ * (an empty `GraphChangeSet`).
+ */
+ commitMove: (nodeId: string, slot: InsertionSlot) => void;
+ /** Centers the viewport on a node (used by the `goto` reference chip, D9). */
+ centerOnNode: (nodeId: string) => void;
+}
+
+const SequentialMoveActionsContext = createContext(
+ undefined
+);
+
+/** Provided by `SequentialCanvas.tsx`. */
+export const SequentialMoveActionsProvider = SequentialMoveActionsContext.Provider;
+
+/**
+ * Returns the current move-actions binding, or `undefined` outside a provider
+ * (isolated node/edge stories and tests render `SequentialStepNode` /
+ * `SequentialConnectorEdge` standalone; both must degrade gracefully -- no
+ * kebab move items, no reference-chip navigation -- rather than throw).
+ */
+export function useOptionalSequentialMoveActions(): SequentialMoveActionsContextValue | undefined {
+ return useContext(SequentialMoveActionsContext);
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialViewContext.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialViewContext.tsx
new file mode 100644
index 000000000..bcd67846a
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/SequentialViewContext.tsx
@@ -0,0 +1,71 @@
+import type { Viewport } from '@uipath/apollo-react/canvas/xyflow/react';
+import { createContext, type ReactNode, useCallback, useContext, useMemo, useRef } from 'react';
+import type { CanvasView } from '../../utils/sequential/sequential.types';
+import { useCanvasViewMode } from './useCanvasViewMode';
+
+/**
+ * Coordination hub for a flow/sequential toggle composition. It owns the current
+ * view (persisted via {@link useCanvasViewMode}) and a per-view viewport store so
+ * switching views restores the viewport you left behind (the HierarchicalCanvas
+ * save/restore pattern applied to the view axis, D11).
+ *
+ * It is OPTIONAL: SequentialCanvas works standalone without it. A consumer that
+ * wants a real toggle wraps the canvas in {@link SequentialViewProvider} and
+ * feeds `view` / `onChange` to the canvas and ViewSwitcher.
+ */
+export interface SequentialViewContextValue {
+ view: CanvasView;
+ setView: (view: CanvasView) => void;
+ /** Remember a view's viewport before switching away. */
+ saveViewport: (view: CanvasView, viewport: Viewport) => void;
+ /** The viewport to restore when a view mounts (undefined = fit fresh). */
+ getViewport: (view: CanvasView) => Viewport | undefined;
+}
+
+const SequentialViewContext = createContext(undefined);
+
+export interface SequentialViewProviderProps {
+ children: ReactNode;
+ /** localStorage key backing the persisted view choice. */
+ storageKey: string;
+ initialView?: CanvasView;
+}
+
+export function SequentialViewProvider({
+ children,
+ storageKey,
+ initialView = 'flow',
+}: SequentialViewProviderProps) {
+ const [view, setView] = useCanvasViewMode(storageKey, initialView);
+ const viewportByView = useRef>(new Map());
+
+ const saveViewport = useCallback((forView: CanvasView, viewport: Viewport) => {
+ viewportByView.current.set(forView, viewport);
+ }, []);
+
+ const getViewport = useCallback(
+ (forView: CanvasView): Viewport | undefined => viewportByView.current.get(forView),
+ []
+ );
+
+ const value = useMemo(
+ () => ({ view, setView, saveViewport, getViewport }),
+ [view, setView, saveViewport, getViewport]
+ );
+
+ return {children};
+}
+
+/** Returns the context or throws when used outside a {@link SequentialViewProvider}. */
+export function useSequentialView(): SequentialViewContextValue {
+ const context = useContext(SequentialViewContext);
+ if (!context) {
+ throw new Error('useSequentialView must be used within a SequentialViewProvider');
+ }
+ return context;
+}
+
+/** Returns the context or undefined, so SequentialCanvas can run standalone. */
+export function useOptionalSequentialView(): SequentialViewContextValue | undefined {
+ return useContext(SequentialViewContext);
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/ToggleHarness.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/ToggleHarness.tsx
new file mode 100644
index 000000000..e96de55cf
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/ToggleHarness.tsx
@@ -0,0 +1,89 @@
+import type { Edge, Node } from '@uipath/apollo-react/canvas/xyflow/react';
+import { applyEdgeChanges, applyNodeChanges } from '@uipath/apollo-react/canvas/xyflow/react';
+import { useCallback, useRef, useState } from 'react';
+import { BaseNode } from '../BaseNode/BaseNode';
+import { prepareCanvasViewTransition } from './prepareCanvasViewTransition';
+import { SequentialCanvas } from './SequentialCanvas';
+import { SequentialViewProvider, useSequentialView } from './SequentialViewContext';
+import { ViewSwitcher } from './ViewSwitcher';
+
+export interface ToggleHarnessProps {
+ initialNodes: Node[];
+ initialEdges: Edge[];
+ storageKey?: string;
+ mode?: 'design' | 'view' | 'readonly';
+}
+
+const FLOW_NODE_TYPES = { default: BaseNode };
+
+/**
+ * Minimal composition demonstrating the flow<->sequential toggle (D11): a single
+ * canonical nodes/edges state, a ViewSwitcher, and one mounted SequentialCanvas
+ * that swaps its derived arrays in place. On toggle back to flow, nodes inserted
+ * while in sequential view are normalized and the canonical graph receives a
+ * deterministic left-to-right layout through prepareCanvasViewTransition.
+ *
+ * Used by tests and stories; not part of the public barrel (D13).
+ */
+export function ToggleHarness({
+ initialNodes,
+ initialEdges,
+ storageKey = 'sequential-canvas.toggle-harness',
+ mode = 'design',
+}: ToggleHarnessProps) {
+ return (
+
+
+
+ );
+}
+
+function ToggleHarnessInner({
+ initialNodes,
+ initialEdges,
+ mode,
+}: Required>) {
+ const { view, setView } = useSequentialView();
+ const [nodes, setNodes] = useState(initialNodes);
+ const [edges, setEdges] = useState(initialEdges);
+
+ const edgesRef = useRef(edges);
+ edgesRef.current = edges;
+ const handleViewChange = useCallback(
+ (nextView: typeof view) => {
+ setNodes((current) => prepareCanvasViewTransition(nextView, current, edgesRef.current).nodes);
+ setView(nextView);
+ },
+ [setView]
+ );
+
+ const onNodesChange = useCallback(
+ (changes: Parameters>[0]) =>
+ setNodes((current) => applyNodeChanges(changes, current)),
+ []
+ );
+ const onEdgesChange = useCallback(
+ (changes: Parameters>[0]) =>
+ setEdges((current) => applyEdgeChanges(changes, current)),
+ []
+ );
+
+ return (
+
+
+
+
+
+
+
+
+ );
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/ViewSwitcher.test.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/ViewSwitcher.test.tsx
new file mode 100644
index 000000000..f461d2f09
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/ViewSwitcher.test.tsx
@@ -0,0 +1,15 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ViewSwitcher } from './ViewSwitcher';
+
+describe('ViewSwitcher', () => {
+ it('renders both view options and calls onChange when the other is picked', () => {
+ const onChange = vi.fn();
+ render();
+
+ expect(screen.getByRole('radio', { name: 'Flow' })).toBeInTheDocument();
+ const sequential = screen.getByRole('radio', { name: 'Sequential' });
+ fireEvent.click(sequential);
+ expect(onChange).toHaveBeenCalledWith('sequential');
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/ViewSwitcher.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/ViewSwitcher.tsx
new file mode 100644
index 000000000..27a837f3c
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/ViewSwitcher.tsx
@@ -0,0 +1,44 @@
+import { ToggleGroup, ToggleGroupItem } from '@uipath/apollo-wind';
+import { memo } from 'react';
+import { useSafeLingui } from '../../../i18n';
+import { CanvasIcon } from '../../utils/icon-registry';
+import type { CanvasView } from '../../utils/sequential/sequential.types';
+import type { ViewSwitcherProps } from './SequentialCanvas.types';
+
+/**
+ * Segmented flow/sequential control (D11). It is a controlled component: the
+ * host owns `value` and `onChange` (typically wired to useCanvasViewMode /
+ * SequentialViewProvider).
+ */
+function ViewSwitcherComponent({ value, onChange }: ViewSwitcherProps) {
+ const { _ } = useSafeLingui();
+
+ const flowLabel = _({ id: 'sequential-canvas.view.flow', message: 'Flow' });
+ const sequentialLabel = _({ id: 'sequential-canvas.view.sequential', message: 'Sequential' });
+
+ return (
+
+ {
+ // Radix emits '' when the active item is re-pressed; keep the current
+ // view rather than clearing it (a segmented control is never empty).
+ if (next === 'flow' || next === 'sequential') onChange(next as CanvasView);
+ }}
+ aria-label={_({ id: 'sequential-canvas.view.label', message: 'Canvas view' })}
+ >
+
+
+ {flowLabel}
+
+
+
+ {sequentialLabel}
+
+
+
+ );
+}
+
+export const ViewSwitcher = memo(ViewSwitcherComponent);
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialBranchHeader.test.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialBranchHeader.test.tsx
new file mode 100644
index 000000000..c92032212
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialBranchHeader.test.tsx
@@ -0,0 +1,15 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { SequentialBranchHeader } from './SequentialBranchHeader';
+
+describe('SequentialBranchHeader', () => {
+ it('aligns an edge-styled label immediately above the branch target', () => {
+ render();
+
+ const header = screen.getByTestId('sequential-branch-header');
+ expect(header).toHaveStyle({ transform: 'translate(128px, 238px) translateY(-100%)' });
+ const label = screen.getByText('False');
+ expect(label).toHaveClass('react-flow__edge-label');
+ expect(label.getAttribute('style')).toContain('var(--canvas-primary)');
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialBranchHeader.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialBranchHeader.tsx
new file mode 100644
index 000000000..d2c2ab506
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialBranchHeader.tsx
@@ -0,0 +1,37 @@
+import { EdgeLabelRenderer } from '@uipath/apollo-react/canvas/xyflow/react';
+import { EdgeLabelContent } from '../../Edges/shared/primitives';
+
+const BRANCH_HEADER_BOTTOM_GAP = 2;
+
+export interface SequentialBranchHeaderProps {
+ x: number;
+ targetTopY: number;
+ label: string;
+ selected?: boolean;
+}
+
+/**
+ * Introduces a branch with the shared edge-label treatment immediately above
+ * its first row. The header is owned by the branch's content area and therefore
+ * remains stable when connector routes change.
+ */
+export function SequentialBranchHeader({
+ x,
+ targetTopY,
+ label,
+ selected,
+}: SequentialBranchHeaderProps) {
+ const anchorY = targetTopY - BRANCH_HEADER_BOTTOM_GAP;
+
+ return (
+
+
+
+
+
+ );
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.test.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.test.tsx
new file mode 100644
index 000000000..ec4cacc6a
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.test.tsx
@@ -0,0 +1,109 @@
+import { render, screen } from '@testing-library/react';
+import { Position } from '@uipath/apollo-react/canvas/xyflow/react';
+import { describe, expect, it } from 'vitest';
+import type { BaseCanvasProps } from '../../BaseCanvas/BaseCanvas.types';
+import { BaseCanvasModeProvider } from '../../BaseCanvas/BaseCanvasModeProvider';
+import { getLeftEntryArrowTargetY, SequentialConnectorEdge } from './SequentialConnectorEdge';
+import type {
+ SequentialConnectorData,
+ SequentialConnectorEdgeProps,
+} from './SequentialConnectorEdge.types';
+
+const baseProps = {
+ id: 'e1',
+ source: 'a',
+ target: 'b',
+ sourceX: 0,
+ sourceY: 0,
+ sourcePosition: Position.Bottom,
+ targetX: 100,
+ targetY: 200,
+ targetPosition: Position.Top,
+} as unknown as SequentialConnectorEdgeProps;
+
+function renderEdge(data: SequentialConnectorData, mode: BaseCanvasProps['mode'] = 'design') {
+ return render(
+
+
+
+ );
+}
+
+describe('SequentialConnectorEdge', () => {
+ describe('goto kind', () => {
+ it('renders a dashed path', () => {
+ const { container } = renderEdge({ kind: 'goto' });
+
+ const visiblePath = container.querySelector('.react-flow__edge-path') as SVGPathElement;
+ expect(visiblePath.style.strokeDasharray).toBe('5,5');
+ });
+ });
+
+ describe('merge-back kind', () => {
+ it('renders a straight container continuation solid', () => {
+ const { container } = renderEdge({
+ kind: 'merge-back',
+ waypoints: [],
+ slot: { id: 'container-continuation' },
+ });
+
+ const visiblePath = container.querySelector('.react-flow__edge-path') as SVGPathElement;
+ expect(visiblePath.style.strokeDasharray).toBe('0');
+ expect(screen.getByRole('button', { name: 'Insert step' }).parentElement).toHaveStyle({
+ transform: 'translate(-50%, -50%) translate(100px, 180px)',
+ });
+ });
+
+ it('renders an elbowed branch rejoin solid', () => {
+ const { container } = renderEdge({
+ kind: 'merge-back',
+ waypoints: [
+ { x: 0, y: 100 },
+ { x: 100, y: 100 },
+ ],
+ });
+
+ const visiblePath = container.querySelector('.react-flow__edge-path') as SVGPathElement;
+ expect(visiblePath.style.strokeDasharray).toBe('0');
+ });
+ });
+
+ it('centers a left-entry arrow using the target node height', () => {
+ expect(getLeftEntryArrowTargetY(200, 999, 48)).toBe(224);
+ expect(getLeftEntryArrowTargetY(undefined, 200, undefined)).toBe(228);
+ });
+
+ describe('step kind insert affordance', () => {
+ it('renders the insert button when a slot is present and the canvas is in design mode', () => {
+ renderEdge({ kind: 'step', slot: { id: 's-1', graphEdgeId: 'e1' } }, 'design');
+ const button = screen.getByRole('button', { name: 'Insert step' });
+ expect(button).toBeInTheDocument();
+ // Faint at rest (discoverable without hover), full on hover/focus.
+ expect(button).toHaveClass(
+ 'opacity-40',
+ 'group-hover:opacity-100',
+ 'group-focus-within:opacity-100'
+ );
+ });
+
+ it('does not render the insert button outside design mode, even with a slot', () => {
+ renderEdge({ kind: 'step', slot: { id: 's-1', graphEdgeId: 'e1' } }, 'view');
+ expect(screen.queryByRole('button', { name: 'Insert step' })).not.toBeInTheDocument();
+ });
+
+ it('does not render the insert button in design mode without a slot', () => {
+ renderEdge({ kind: 'step' }, 'design');
+ expect(screen.queryByRole('button', { name: 'Insert step' })).not.toBeInTheDocument();
+ });
+ });
+
+ it('renders a branch-entry label above the row using the shared edge-label style', () => {
+ const { container } = renderEdge({ kind: 'branch-entry', label: 'True' });
+
+ expect(screen.getByTestId('sequential-branch-header')).toHaveTextContent('True');
+ expect(container.querySelector('.react-flow__edge-label')).toBeInTheDocument();
+ expect(container.querySelector('foreignObject')).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.tsx
new file mode 100644
index 000000000..fd8ac7f50
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.tsx
@@ -0,0 +1,285 @@
+import { Position, useStore } from '@uipath/apollo-react/canvas/xyflow/react';
+import { memo, useCallback, useState } from 'react';
+import { useSafeLingui } from '../../../../i18n';
+import { SEQ_BAR_HEIGHT, SEQ_EDGE_CORNER_RADIUS } from '../../../constants';
+import { useBaseCanvasMode } from '../../BaseCanvas/BaseCanvasModeProvider';
+import { areEdgePropsEqual } from '../../Edges/shared/areEdgePropsEqual';
+import { EMPTY_WAYPOINTS } from '../../Edges/shared/constants';
+import { useEdgeGeometry, useExecutionEdge } from '../../Edges/shared/hooks';
+import { EdgeArrow, EdgeLabel, EdgePath } from '../../Edges/shared/primitives';
+import { resolveEdgeColor } from '../../Edges/shared/resolveEdgeColor';
+import { SequentialBranchHeader } from './SequentialBranchHeader';
+import type { SequentialConnectorEdgeProps } from './SequentialConnectorEdge.types';
+import { SequentialInsertButton } from './SequentialInsertButton';
+import { resolveConnectorStrokeStyle } from './sequentialConnectorStyle';
+import { useSequentialInsert } from './useSequentialInsert';
+
+/**
+ * Vertical offset (flow px) between a NON-branch connector's label pill and its
+ * centered ⊕ (the ⊕ owns the connector's true midpoint; the label is nudged up).
+ * Branch-entry connectors instead split the two onto separate segments of their
+ * elbow (label on the vertical spine, ⊕ on the horizontal jog) so they never
+ * crowd - see the branch placement below.
+ */
+const INSERT_BUTTON_LABEL_OFFSET_PX = 26;
+
+/**
+ * Sequential arrowhead placement. Flow-view edges translate the arrow
+ * ARROW_OFFSET px INTO the target node so the node paints over the tuck;
+ * sequential bars are opaque and connectors render behind them, so a big tuck is
+ * clipped. The tip is anchored to the target bar's real top edge (read from the
+ * store, see `targetTopY`); this 1px nudge lets it bite just into the bar so it
+ * reads as connected rather than leaving a hairline gap, with the body in the
+ * clear row gap above it so it stays fully visible without elevating the edge.
+ */
+/**
+ * Vertical offset (flow px) that anchors a merge-back connector's insert plus
+ * to an endpoint instead of the line midpoint. A merge-back's midpoint drifts
+ * onto whichever row sits alongside it (e.g. a collapsed child), colliding with
+ * that row's own add points; anchoring near an endpoint reads as "add right
+ * here" and never lands on an unrelated row.
+ */
+const MERGE_BACK_INSERT_OFFSET_PX = 20;
+
+const ARROW_TIP_AT_BAR_EDGE = { x: 0, y: 1 } as const;
+/** Same 1px bite, but into the LEFT face for branch-entry (mid-left) arrows. */
+const ARROW_TIP_AT_BAR_LEFT_EDGE = { x: 1, y: 0 } as const;
+
+export function getLeftEntryArrowTargetY(
+ targetTopY: number | undefined,
+ targetY: number,
+ targetHeight: number | undefined
+): number {
+ return (targetTopY ?? targetY) + (targetHeight ?? SEQ_BAR_HEIGHT) / 2;
+}
+
+/**
+ * Sequential-view connector edge. Composes the shared edge primitives
+ * (EdgePath / EdgeArrow / EdgeLabel) and renders behavior from `data`:
+ *
+ * - stroke style by kind (ordinary structural flow solid; irregular `goto`
+ * references and transient previews dashed) via {@link resolveConnectorStrokeStyle};
+ * - an edge-styled label above the first row of each labeled branch;
+ * - `data.waypoints` rendered verbatim (elbows supplied by layoutSequence; no
+ * router, no waypoint editing);
+ * - a statically centered ⊕ insert affordance, revealed on hover/focus and
+ * available only in design mode when `data.slot` is present.
+ *
+ * See ./SequentialConnectorEdge.types.ts for the field-by-field `data` contract
+ * the assembly builds. `data` is compared by reference (areEdgePropsEqual), so the assembly must
+ * keep it reference-stable across data-only changes (D12).
+ */
+export const SequentialConnectorEdge = memo(function SequentialConnectorEdge({
+ id,
+ selected,
+ source,
+ target,
+ sourceX,
+ sourceY,
+ sourcePosition = Position.Bottom,
+ targetX,
+ targetY,
+ targetPosition = Position.Top,
+ sourceHandleId,
+ targetHandleId,
+ style,
+ data,
+}: SequentialConnectorEdgeProps) {
+ const { _ } = useSafeLingui();
+ const isDesignMode = useBaseCanvasMode().mode === 'design';
+ const { startInsert } = useSequentialInsert();
+
+ // Real top-left corner of the target bar. The handle-derived `targetX/Y` sit
+ // slightly off the bar's painted edge, so anchoring the arrowhead to the
+ // node's absolute position lands the tip exactly on the bar — its top edge for
+ // a normal (Top) entry, its left edge at mid-height for a branch (Left) entry.
+ const targetTopY = useStore((s) => s.nodeLookup.get(target)?.internals.positionAbsolute.y);
+ const targetLeftX = useStore((s) => s.nodeLookup.get(target)?.internals.positionAbsolute.x);
+ const targetHeight = useStore((s) => {
+ const targetNode = s.nodeLookup.get(target);
+ // Sequential rows publish their layout-owned height immediately. Prefer it
+ // over the measured value, which can trail a slider update by one render.
+ return targetNode?.height ?? targetNode?.measured?.height;
+ });
+ // Branch-entry connectors carry a Left target handle, so React Flow reports
+ // Position.Left here — the arrow then points right into the bar's mid-left.
+ const isLeftEntry = targetPosition === Position.Left;
+
+ const [isHovered, setIsHovered] = useState(false);
+ const onMouseEnter = useCallback(() => setIsHovered(true), []);
+ const onMouseLeave = useCallback(() => setIsHovered(false), []);
+
+ const kind = data?.kind ?? 'step';
+ const label = data?.label;
+ const slot = data?.slot;
+ const hideArrowHead = !!data?.hideArrowHead;
+ const isPreview = !!data?.preview;
+ const waypoints = data?.waypoints ?? EMPTY_WAYPOINTS;
+
+ // Waypoint routing is used for every kind: elbowed connectors carry explicit
+ // waypoints, and straight step connectors get a clean orthogonal path between
+ // the two anchors from an empty waypoint list.
+ const geometry = useEdgeGeometry({
+ routing: 'waypoint',
+ sourceNodeId: source,
+ targetNodeId: target,
+ sourceHandleId,
+ targetHandleId,
+ sourceX,
+ sourceY,
+ sourcePosition,
+ targetX,
+ targetY,
+ targetPosition,
+ waypoints,
+ enableSegments: false,
+ hideArrowHead,
+ // Pronounced smooth-step corners for the sequential view: the elbowed
+ // branch/merge-back connectors read as soft rounded steps rather than the
+ // subtler default. createRoundedPath clamps this to half the shorter
+ // adjacent segment, so tight jogs degrade gracefully.
+ borderRadius: SEQ_EDGE_CORNER_RADIUS,
+ });
+
+ const execution = useExecutionEdge({
+ edgeId: id,
+ target,
+ edgePath: geometry.edgePath,
+ enabled: !!data?.enableExecution,
+ });
+
+ const color = resolveEdgeColor({
+ selected,
+ isHovered,
+ previewEdge: isPreview,
+ statusColor: execution.statusColor,
+ });
+
+ // Merge-backs are ordinary structural flow regardless of whether they are a
+ // straight container continuation or an elbowed branch rejoin. Only
+ // irregular goto references and transient previews use a dashed stroke.
+ const strokeStyle = isPreview ? 'dashed' : resolveConnectorStrokeStyle(kind);
+ const showInsert = isDesignMode && !!slot;
+ const hasLabel = typeof label === 'string' && label.length > 0;
+
+ // Branch-entry connectors elbow: a vertical spine drop from the owner then a
+ // horizontal jog into the target (waypoints [spineBottom, jogEnd] from
+ // layoutSequence). The ⊕ stays on that horizontal jog. Its label is rendered
+ // separately above the target row, so labels no longer
+ // compete with connector geometry or one another.
+ const wp0 = waypoints[0];
+ const wp1 = waypoints[1];
+ const isBranchElbow = kind === 'branch-entry' && wp0 !== undefined && wp1 !== undefined;
+ // Merge-back placement: a straight merge-back (a container's continuation,
+ // no waypoints) anchors just ABOVE its target, so "add after the container"
+ // sits after the whole body rather than in the middle of it. An elbowed
+ // merge-back (a branch lane rejoining the flow) anchors just BELOW its source,
+ // so "add at the end of this branch" sits under the branch's last step.
+ const insertPoint = isBranchElbow
+ ? { x: (wp0.x + wp1.x) / 2, y: wp0.y }
+ : kind === 'merge-back'
+ ? waypoints.length === 0
+ ? { x: targetX, y: targetY - MERGE_BACK_INSERT_OFFSET_PX }
+ : { x: sourceX, y: sourceY + MERGE_BACK_INSERT_OFFSET_PX }
+ : geometry.labelPoint;
+ const labelPoint = showInsert
+ ? { x: geometry.labelPoint.x, y: geometry.labelPoint.y - INSERT_BUTTON_LABEL_OFFSET_PX }
+ : geometry.labelPoint;
+ const resolvedTargetHeight = typeof targetHeight === 'number' ? targetHeight : SEQ_BAR_HEIGHT;
+ const resolvedTargetTopY =
+ typeof targetTopY === 'number'
+ ? targetTopY
+ : isLeftEntry
+ ? targetY - resolvedTargetHeight / 2
+ : targetY;
+ const resolvedTargetLeftX = typeof targetLeftX === 'number' ? targetLeftX : targetX;
+
+ const onInsert = useCallback(() => {
+ if (!slot) return;
+ startInsert({
+ slot,
+ source,
+ sourceHandleId,
+ target,
+ targetHandleId,
+ sourcePosition,
+ position: { x: (sourceX + targetX) / 2, y: (sourceY + targetY) / 2 },
+ // This edge's OWN rendered id — the store in sequential view holds
+ // derived connector edges, never canonical ids, so the split connector
+ // must be found (and stashed for cancel-restore) by this id, not
+ // slot.graphEdgeId.
+ connectorEdgeId: id,
+ });
+ }, [
+ slot,
+ source,
+ sourceHandleId,
+ target,
+ targetHandleId,
+ sourcePosition,
+ sourceX,
+ sourceY,
+ targetX,
+ targetY,
+ startInsert,
+ id,
+ ]);
+
+ const opacity = (style?.opacity as number | undefined) ?? 1;
+
+ return (
+ <>
+
+
+
+ {!hideArrowHead && (
+
+ )}
+
+ {execution.animation}
+
+ {hasLabel && kind !== 'branch-entry' && (
+
+ )}
+
+
+ {hasLabel && kind === 'branch-entry' && (
+
+ )}
+
+ {showInsert && (
+
+ )}
+
+ );
+}, areEdgePropsEqual);
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.types.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.types.ts
new file mode 100644
index 000000000..9cb86bc2f
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialConnectorEdge.types.ts
@@ -0,0 +1,69 @@
+import type { Edge, EdgeProps } from '@uipath/apollo-react/canvas/xyflow/react';
+import type {
+ InsertionSlot,
+ SequenceConnectorKind,
+} from '../../../utils/sequential/sequential.types';
+import type { Waypoint } from '../../Edges/shared/types';
+
+/**
+ * Reference-stable `data` payload for a sequential connector edge.
+ *
+ * The assembly builds one of these per {@link SequenceConnector} when it derives the
+ * xyflow edge array (see useSequentialGraph). The object MUST be built only on
+ * structural change and reused by reference otherwise, so `areEdgePropsEqual`
+ * (which compares `data` by reference, see components/Edges/shared/areEdgePropsEqual.ts)
+ * can short-circuit the memo during pan/zoom and data-only edits (D12).
+ *
+ * Field-by-field contract:
+ * - `kind` copy from `connector.kind`. Drives stroke style: `step`
+ * `branch-entry`, and `merge-back` render solid; only
+ * irregular `goto` references render dashed. See
+ * {@link resolveConnectorStrokeStyle}.
+ * - `label` copy from `connector.label`. Branch-entry labels render
+ * above their first row using the shared edge-label style;
+ * other kinds
+ * retain the centered edge pill. Omit or use an empty
+ * string to render no label.
+ * - `waypoints` elbow geometry from `layoutSequence().connectorWaypoints`
+ * keyed by the connector id. Rendered verbatim (no router,
+ * no editing). When absent, the edge draws a clean
+ * orthogonal path between the two handle anchors. Reuse the
+ * SAME array reference across renders; a fresh `[]` each
+ * render defeats geometry memoization (prefer the shared
+ * EMPTY_WAYPOINTS fallback).
+ * - `slot` copy from `connector.slot`. The centered insert (+)
+ * button renders IFF this is present AND the canvas is in
+ * design mode. `goto` connectors carry no slot and so get
+ * no button.
+ * - `enableExecution` opt in to id-keyed execution coloring + the in-progress
+ * dot, via the existing ExecutionStatusContext. Defaults to
+ * off; turning it on matches CanvasEdge behavior.
+ * - `hideArrowHead` suppress the arrow head. Defaults to showing an arrow
+ * pointing into the target for every kind.
+ */
+// A `type` (not an `interface`) so it implicitly satisfies xyflow's
+// `Edge>` constraint, matching CanvasEdgeData.
+export type SequentialConnectorData = {
+ kind: SequenceConnectorKind;
+ label?: string | null;
+ waypoints?: Waypoint[];
+ slot?: InsertionSlot;
+ /** Transient Add Node connector: selected color + dashed preview stroke. */
+ preview?: boolean;
+ /** Visual-only preview join that AddNodeManager must not materialize. */
+ ignorePreviewConnection?: boolean;
+ /**
+ * Canonical manifest handle on the existing endpoint of a preview edge.
+ * The rendered edge stays on the guaranteed sequential bar handle while
+ * AddNodeManager uses this id for connection filtering and materialization.
+ */
+ previewConnectionHandleId?: string;
+ enableExecution?: boolean;
+ hideArrowHead?: boolean;
+};
+
+/** The xyflow edge shape rendered by {@link SequentialConnectorEdge}. */
+export type SequentialConnectorEdgeType = Edge;
+
+/** Props xyflow hands the edge component. */
+export type SequentialConnectorEdgeProps = EdgeProps;
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialInsertButton.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialInsertButton.tsx
new file mode 100644
index 000000000..d7473bf24
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/SequentialInsertButton.tsx
@@ -0,0 +1,59 @@
+import { EdgeLabelRenderer, type XYPosition } from '@uipath/apollo-react/canvas/xyflow/react';
+import { type MouseEvent as ReactMouseEvent, useCallback } from 'react';
+import { CanvasInlineButton } from '../../ButtonHandle/CanvasInlineButton';
+
+export interface SequentialInsertButtonProps {
+ /** Center point in flow coordinates (the connector midpoint). */
+ point: XYPosition;
+ /** Accessible label, already localized. */
+ label: string;
+ /** Invoked on click; opens the Add Node panel for the connector's slot. */
+ onInsert: () => void;
+}
+
+/**
+ * Statically centered ⊕ affordance for a sequential connector (design mode
+ * only; the caller gates on slot presence + mode). It rests at a low opacity so
+ * every insertable connector shows a quiet ⊕, then brightens to full on
+ * hover/focus. This keeps add points discoverable without a wall of
+ * full-strength buttons when several nested slots are nearby, and pairs with the
+ * plus variant of SequentialPlaceholderNode so "add a step" looks identical
+ * everywhere. Unlike the
+ * hover-following EdgeToolbar (see Toolbar/EdgeToolbar/useEdgeToolbarPositioning.ts),
+ * this sits at a fixed point on the connector and never tracks the pointer.
+ *
+ * It stops mousedown/click propagation so opening the Add Node panel does not
+ * trip the Toolbox's outside-mousedown close (components/Toolbox/Toolbox.tsx:621-625).
+ */
+export function SequentialInsertButton({ point, label, onInsert }: SequentialInsertButtonProps) {
+ const stopMouseDown = useCallback((event: ReactMouseEvent) => {
+ event.stopPropagation();
+ }, []);
+
+ const handleClick = useCallback(
+ (event: ReactMouseEvent) => {
+ event.stopPropagation();
+ event.preventDefault();
+ onInsert();
+ },
+ [onInsert]
+ );
+
+ return (
+
+
+
+
+
+ );
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/index.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/index.ts
new file mode 100644
index 000000000..9443e7101
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/index.ts
@@ -0,0 +1,24 @@
+// Local barrel for the sequential connector + insert pipeline. This is NOT
+// re-exported from components/index.ts; the feature stays out of the public
+// canvas barrel until GA (D13). Types first, component/helpers after.
+
+export { SequentialBranchHeader } from './SequentialBranchHeader';
+export { SequentialConnectorEdge } from './SequentialConnectorEdge';
+export type {
+ SequentialConnectorData,
+ SequentialConnectorEdgeProps,
+ SequentialConnectorEdgeType,
+} from './SequentialConnectorEdge.types';
+export type { SequentialInsertButtonProps } from './SequentialInsertButton';
+export { SequentialInsertButton } from './SequentialInsertButton';
+export { resolveConnectorStrokeStyle } from './sequentialConnectorStyle';
+export type { SequentialInsertArgs } from './sequentialInsert';
+export {
+ buildSequentialPreviewOptions,
+ getSequentialIgnoredNodeTypes,
+ SEQ_INSERTED_FLAG,
+ SEQUENTIAL_IGNORED_NODE_TYPES,
+ sequentialOnBeforeNodeAdded,
+} from './sequentialInsert';
+export type { UseSequentialInsertResult } from './useSequentialInsert';
+export { useSequentialInsert } from './useSequentialInsert';
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialConnectorStyle.test.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialConnectorStyle.test.ts
new file mode 100644
index 000000000..4dc52748d
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialConnectorStyle.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import type { SequenceConnectorKind } from '../../../utils/sequential/sequential.types';
+import { resolveConnectorStrokeStyle } from './sequentialConnectorStyle';
+
+describe('resolveConnectorStrokeStyle', () => {
+ it('renders structural flow connectors solid', () => {
+ expect(resolveConnectorStrokeStyle('step')).toBe('solid');
+ expect(resolveConnectorStrokeStyle('branch-entry')).toBe('solid');
+ expect(resolveConnectorStrokeStyle('merge-back')).toBe('solid');
+ });
+
+ it('renders irregular references dashed', () => {
+ expect(resolveConnectorStrokeStyle('goto')).toBe('dashed');
+ });
+
+ it('covers every connector kind', () => {
+ const kinds: SequenceConnectorKind[] = ['step', 'branch-entry', 'merge-back', 'goto'];
+ for (const kind of kinds) {
+ expect(['solid', 'dashed']).toContain(resolveConnectorStrokeStyle(kind));
+ }
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialConnectorStyle.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialConnectorStyle.ts
new file mode 100644
index 000000000..b1ba9d2b6
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialConnectorStyle.ts
@@ -0,0 +1,15 @@
+import type { SequenceConnectorKind } from '../../../utils/sequential/sequential.types';
+import type { EdgeStrokeStyle } from '../../Edges/shared/types';
+
+/**
+ * Maps a connector kind to its stroke style.
+ *
+ * - `step` / `branch-entry` / `merge-back` are all structural control flow:
+ * solid.
+ * - `goto` is an irregular reference (cycle or already-visited target): dashed.
+ * - transient preview connectors are handled by SequentialConnectorEdge and
+ * remain dashed independently of this mapping.
+ */
+export function resolveConnectorStrokeStyle(kind: SequenceConnectorKind): EdgeStrokeStyle {
+ return kind === 'goto' ? 'dashed' : 'solid';
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialInsert.test.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialInsert.test.ts
new file mode 100644
index 000000000..267ee1a64
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialInsert.test.ts
@@ -0,0 +1,450 @@
+import type { Edge, Node, ReactFlowInstance } from '@uipath/apollo-react/canvas/xyflow/react';
+import { Position } from '@uipath/apollo-react/canvas/xyflow/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ DEFAULT_SOURCE_HANDLE_ID,
+ DEFAULT_TARGET_HANDLE_ID,
+ SEQ_BAR_HEIGHT,
+ SEQ_BAR_WIDTH,
+ SEQ_PLACEHOLDER_NODE_TYPE,
+ SEQ_START_NODE_TYPE,
+} from '../../../constants';
+import { SEQ_CONTINUATION_EDGE_KEY } from '../../../utils/sequential/graph-helpers';
+import type { InsertionSlot } from '../../../utils/sequential/sequential.types';
+import { SEQUENTIAL_BAR_HANDLE_IDS } from '../nodes';
+import {
+ buildSequentialPreviewOptions,
+ getSequentialIgnoredNodeTypes,
+ type PendingSequentialInsert,
+ resolvePendingSequentialInsert,
+ SEQ_INSERTED_FLAG,
+ SEQUENTIAL_IGNORED_NODE_TYPES,
+ sequentialOnBeforeNodeAdded,
+} from './sequentialInsert';
+
+const FAKE_UUID = '00000000-0000-0000-0000-000000000001';
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('SEQUENTIAL_IGNORED_NODE_TYPES', () => {
+ it('lists exactly the synthetic sequential row types (clones keep real types)', () => {
+ expect(SEQUENTIAL_IGNORED_NODE_TYPES).toEqual([SEQ_START_NODE_TYPE, SEQ_PLACEHOLDER_NODE_TYPE]);
+ });
+
+ it('merges host extras into a fresh array', () => {
+ const merged = getSequentialIgnoredNodeTypes(['sticky']);
+ expect(merged).toEqual([...SEQUENTIAL_IGNORED_NODE_TYPES, 'sticky']);
+ expect(merged).not.toBe(SEQUENTIAL_IGNORED_NODE_TYPES);
+ });
+});
+
+describe('sequentialOnBeforeNodeAdded', () => {
+ const previousId = 'uipath.slack-1720000000000';
+
+ const seedNode = (): Node =>
+ ({
+ id: previousId,
+ type: 'uipath.slack',
+ position: { x: 420, y: 96 },
+ data: { label: 'Slack', display: { label: 'Send message' } },
+ }) as Node;
+
+ const seedEdges = (): Edge[] => [
+ {
+ id: `edge_srcA-output-${previousId}-input`,
+ source: 'srcA',
+ sourceHandle: 'output',
+ target: previousId,
+ targetHandle: 'input',
+ type: 'default',
+ } as Edge,
+ {
+ id: `edge_${previousId}-output-tgtB-input`,
+ source: previousId,
+ sourceHandle: 'output',
+ target: 'tgtB',
+ targetHandle: 'input',
+ type: 'default',
+ } as Edge,
+ ];
+
+ it('re-ids the node with crypto.randomUUID()', () => {
+ const spy = vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newNode } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges());
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(newNode.id).toBe(FAKE_UUID);
+ });
+
+ it('keeps the preview-derived position and does not force draggable false', () => {
+ // The sequential clone derivation (useSequentialGraph) already stamps
+ // draggable:false on every row unconditionally, so onBeforeNodeAdded must
+ // not also write it into canonical state, or it leaks permanently once the
+ // user toggles back to flow view (synthesizePositionsForFlow only clears it
+ // on that boundary; nothing clears it while still in sequential view).
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const seed = seedNode();
+ const { newNode } = sequentialOnBeforeNodeAdded(seed, seedEdges());
+ expect(newNode.position).toEqual(seed.position);
+ expect(newNode.draggable).toBeUndefined();
+ });
+
+ it('stamps seqInserted while preserving existing data and type', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newNode } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges());
+ expect(newNode.type).toBe('uipath.slack');
+ expect((newNode.data as Record)[SEQ_INSERTED_FLAG]).toBe(true);
+ expect((newNode.data as Record).label).toBe('Slack');
+ });
+
+ it('rewrites edges that reference the seed id and regenerates their ids', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges());
+
+ const incoming = newEdges.find((edge) => edge.source === 'srcA');
+ const outgoing = newEdges.find((edge) => edge.target === 'tgtB');
+
+ expect(incoming?.target).toBe(FAKE_UUID);
+ expect(incoming?.id).toBe(`edge_srcA-output-${FAKE_UUID}-input`);
+ expect(outgoing?.source).toBe(FAKE_UUID);
+ expect(outgoing?.id).toBe(`edge_${FAKE_UUID}-output-tgtB-input`);
+ });
+
+ it('leaves an unrelated edge untouched by reference', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const unrelated = {
+ id: 'edge_x-output-y-input',
+ source: 'x',
+ target: 'y',
+ type: 'default',
+ } as Edge;
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), [unrelated]);
+ expect(newEdges[0]).toBe(unrelated);
+ });
+
+ describe('with a pending slot (canonical handle/containment rewriting)', () => {
+ const barEdges = (): Edge[] => [
+ {
+ id: `edge_srcA-${SEQUENTIAL_BAR_HANDLE_IDS.source}-${previousId}-${SEQUENTIAL_BAR_HANDLE_IDS.target}`,
+ source: 'srcA',
+ sourceHandle: SEQUENTIAL_BAR_HANDLE_IDS.source,
+ target: previousId,
+ targetHandle: SEQUENTIAL_BAR_HANDLE_IDS.target,
+ type: 'default',
+ } as Edge,
+ {
+ id: `edge_${previousId}-${SEQUENTIAL_BAR_HANDLE_IDS.source}-tgtB-${SEQUENTIAL_BAR_HANDLE_IDS.target}`,
+ source: previousId,
+ sourceHandle: SEQUENTIAL_BAR_HANDLE_IDS.source,
+ target: 'tgtB',
+ targetHandle: SEQUENTIAL_BAR_HANDLE_IDS.target,
+ type: 'default',
+ } as Edge,
+ ];
+
+ it('restores only the original nodes canonical handles', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const pending: PendingSequentialInsert = {
+ sourceNodeId: 'srcA',
+ targetNodeId: 'tgtB',
+ sourceHandleId: 'true',
+ targetHandleId: 'input',
+ };
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), barEdges(), pending);
+
+ const incoming = newEdges.find((edge) => edge.source === 'srcA');
+ const outgoing = newEdges.find((edge) => edge.target === 'tgtB');
+
+ expect(incoming?.sourceHandle).toBe('true');
+ expect(outgoing?.targetHandle).toBe('input');
+ // The inserted node's own handles are not replaced with handles that
+ // belong to the original source/target nodes.
+ expect(incoming?.targetHandle).toBe(SEQUENTIAL_BAR_HANDLE_IDS.target);
+ expect(outgoing?.sourceHandle).toBe(SEQUENTIAL_BAR_HANDLE_IDS.source);
+ });
+
+ it('restores implicit defaults only on the original node endpoints', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), barEdges(), {
+ sourceNodeId: 'srcA',
+ targetNodeId: 'tgtB',
+ });
+
+ const incoming = newEdges.find((edge) => edge.source === 'srcA');
+ const outgoing = newEdges.find((edge) => edge.target === 'tgtB');
+
+ expect(incoming?.sourceHandle).toBeUndefined();
+ expect(outgoing?.targetHandle).toBeUndefined();
+ expect(incoming?.targetHandle).toBe(SEQUENTIAL_BAR_HANDLE_IDS.target);
+ expect(outgoing?.sourceHandle).toBe(SEQUENTIAL_BAR_HANDLE_IDS.source);
+ });
+
+ it('regenerates the edge id from the rewritten handles so the id matches the fields', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const pending: PendingSequentialInsert = {
+ sourceNodeId: 'srcA',
+ targetNodeId: 'tgtB',
+ sourceHandleId: 'true',
+ targetHandleId: 'input',
+ };
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), barEdges(), pending);
+ const outgoing = newEdges.find((edge) => edge.source === FAKE_UUID);
+ expect(outgoing?.id).toBe(`edge_${FAKE_UUID}-${SEQUENTIAL_BAR_HANDLE_IDS.source}-tgtB-input`);
+ });
+
+ it('tags both split halves with the exact canonical edge id', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges(), {
+ sourceNodeId: 'srcA',
+ targetNodeId: 'tgtB',
+ graphEdgeId: 'canonical-edge-7',
+ sourceHandleId: 'output',
+ targetHandleId: 'input',
+ });
+
+ expect(newEdges).toHaveLength(2);
+ for (const edge of newEdges) {
+ expect((edge.data as Record).__sequentialSplitEdgeId).toBe(
+ 'canonical-edge-7'
+ );
+ }
+ });
+
+ it('marks the inserted-node-to-downstream half as a continuation', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges(), {
+ sourceNodeId: 'srcA',
+ targetNodeId: 'tgtB',
+ graphEdgeId: 'canonical-edge-7',
+ });
+
+ const incoming = newEdges.find((edge) => edge.target === FAKE_UUID);
+ const outgoing = newEdges.find((edge) => edge.source === FAKE_UUID);
+ expect(
+ (incoming?.data as Record)[SEQ_CONTINUATION_EDGE_KEY]
+ ).toBeUndefined();
+ expect((outgoing?.data as Record)[SEQ_CONTINUATION_EDGE_KEY]).toBe(true);
+ });
+
+ it('preserves an existing continuation marker on the source half when splitting it again', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges(), {
+ sourceNodeId: 'srcA',
+ targetNodeId: 'tgtB',
+ graphEdgeId: 'canonical-edge-7',
+ splitEdgeWasContinuation: true,
+ });
+
+ for (const edge of newEdges) {
+ expect((edge.data as Record)[SEQ_CONTINUATION_EDGE_KEY]).toBe(true);
+ }
+ });
+
+ it('leaves non-bar handle ids untouched even when a pending value is present', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const pending: PendingSequentialInsert = {
+ sourceNodeId: 'srcA',
+ targetNodeId: 'tgtB',
+ sourceHandleId: 'ignored',
+ targetHandleId: 'ignored',
+ };
+ const { newEdges } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges(), pending);
+ const incoming = newEdges.find((edge) => edge.source === 'srcA');
+ const outgoing = newEdges.find((edge) => edge.target === 'tgtB');
+ expect(incoming?.sourceHandle).toBe('ignored');
+ expect(outgoing?.targetHandle).toBe('ignored');
+ expect(incoming?.targetHandle).toBe('input');
+ expect(outgoing?.sourceHandle).toBe('output');
+ });
+
+ it('applies the slot containerId as canonical parentId/extent on the materialized node', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newNode } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges(), {
+ containerId: 'loop-1',
+ });
+ expect(newNode.parentId).toBe('loop-1');
+ expect(newNode.extent).toBe('parent');
+ });
+
+ it('omits parentId/extent when the slot has no container', () => {
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+ const { newNode } = sequentialOnBeforeNodeAdded(seedNode(), seedEdges(), {});
+ expect(newNode.parentId).toBeUndefined();
+ expect(newNode.extent).toBeUndefined();
+ });
+ });
+});
+
+describe('resolvePendingSequentialInsert', () => {
+ it('captures the slot canonical handle ids and containerId', () => {
+ const slot: InsertionSlot = {
+ id: 'slot-1',
+ source: { nodeId: 'a', handleId: 'true' },
+ target: { nodeId: 'b', handleId: 'input' },
+ containerId: 'loop-1',
+ };
+ expect(resolvePendingSequentialInsert(slot)).toEqual({
+ sourceNodeId: 'a',
+ targetNodeId: 'b',
+ graphEdgeId: undefined,
+ sourceHandleId: 'true',
+ targetHandleId: 'input',
+ containerId: 'loop-1',
+ splitEdgeWasContinuation: undefined,
+ });
+ });
+
+ it('captures continuation semantics when inserting into an already-healed spine', () => {
+ const pending = resolvePendingSequentialInsert({
+ id: 'slot-1',
+ source: { nodeId: 'a' },
+ target: { nodeId: 'b' },
+ continuation: true,
+ });
+ expect(pending.splitEdgeWasContinuation).toBe(true);
+ });
+
+ it('yields undefined handle ids (never a bar handle) when the slot endpoint omits one', () => {
+ const slot: InsertionSlot = { id: 'slot-1', source: { nodeId: 'a' }, target: { nodeId: 'b' } };
+ const pending = resolvePendingSequentialInsert(slot);
+ expect(pending.sourceHandleId).toBeUndefined();
+ expect(pending.targetHandleId).toBeUndefined();
+ });
+
+ it('yields no containerId when the slot is not scoped to a container', () => {
+ const slot: InsertionSlot = { id: 'slot-1' };
+ expect(resolvePendingSequentialInsert(slot).containerId).toBeUndefined();
+ });
+});
+
+describe('buildSequentialPreviewOptions', () => {
+ // The connector's rendered id deliberately DIFFERS from the canonical edge id
+ // it wraps (as the projection's `conn:${edge.id}` scheme actually produces), proving the
+ // lookup uses connectorEdgeId (the rendered id) and not slot.graphEdgeId (the
+ // canonical id) — those live in different id spaces in sequential view, since
+ // the store here only ever holds derived connector edges.
+ const connectorEdge = {
+ id: 'conn:e-1',
+ source: 'row-a',
+ sourceHandle: SEQUENTIAL_BAR_HANDLE_IDS.source,
+ target: 'row-b',
+ targetHandle: SEQUENTIAL_BAR_HANDLE_IDS.target,
+ type: 'sequentialConnector',
+ } as Edge;
+
+ const makeInstance = (edges: Edge[] = [connectorEdge]) =>
+ ({ getEdges: () => edges }) as unknown as ReactFlowInstance;
+
+ const baseArgs = {
+ source: 'a',
+ sourceHandleId: SEQUENTIAL_BAR_HANDLE_IDS.source,
+ target: 'b',
+ targetHandleId: SEQUENTIAL_BAR_HANDLE_IDS.target,
+ sourcePosition: Position.Bottom,
+ position: { x: 100, y: 200 },
+ };
+
+ it('rides the existing pipeline with bar-sized preview + ignored sequential types', () => {
+ const slot: InsertionSlot = { id: 'slot-1', graphEdgeId: 'e-1' };
+ const options = buildSequentialPreviewOptions(makeInstance(), {
+ ...baseArgs,
+ slot,
+ connectorEdgeId: 'conn:e-1',
+ });
+
+ expect(options.previewNodeSize).toEqual({ width: SEQ_BAR_WIDTH, height: SEQ_BAR_HEIGHT });
+ expect(options.ignoredNodeTypes).toBe(SEQUENTIAL_IGNORED_NODE_TYPES);
+ expect(options.positionMode).toBe('drop');
+ expect(options.sourceHandleType).toBe('source');
+ expect(options.handlePosition).toBe(Position.Bottom);
+ expect(options.position).toEqual({ x: 100, y: 200 });
+ });
+
+ it('anchors preview edges on the slot canonical handle ids so connection filtering can resolve them', () => {
+ const slot: InsertionSlot = {
+ id: 'slot-1',
+ source: { nodeId: 'container', handleId: 'true' },
+ target: { nodeId: 'b', handleId: 'input' },
+ };
+ const options = buildSequentialPreviewOptions(makeInstance(), { ...baseArgs, slot });
+ // Node id and handle id both come from the slot: bars now render an
+ // invisible handle per manifest handle id (BaseNodeBar
+ // manifestSource/TargetHandleIds), so the preview edge renders AND
+ // usePreviewNode can resolve the existing node's handle manifest for the
+ // Add Node connection filter (bar handle ids never appeared in the manifest).
+ expect(options.source).toEqual({ nodeId: 'container', handleId: 'true' });
+ expect(options.target).toEqual({ nodeId: 'b', handleId: 'input' });
+ });
+
+ it('falls back to the default handle ids when the slot omits them (tail append)', () => {
+ const slot: InsertionSlot = { id: 'slot-tail', source: { nodeId: 'last' } };
+ const options = buildSequentialPreviewOptions(makeInstance([]), {
+ ...baseArgs,
+ slot,
+ target: '',
+ targetHandleId: undefined,
+ });
+ expect(options.source).toEqual({ nodeId: 'last', handleId: DEFAULT_SOURCE_HANDLE_ID });
+ expect('target' in options).toBe(false);
+ });
+
+ it('drives a head insertion from the first canonical target without using the synthetic start row', () => {
+ const slot: InsertionSlot = { id: 'slot-head', target: { nodeId: 'first' } };
+ const options = buildSequentialPreviewOptions(makeInstance(), {
+ ...baseArgs,
+ source: '__sequential-start__',
+ target: 'first',
+ slot,
+ });
+
+ expect(options.source).toEqual({ nodeId: 'first', handleId: DEFAULT_TARGET_HANDLE_ID });
+ expect(options.sourceHandleType).toBe('target');
+ expect(options.handlePosition).toBe(Position.Top);
+ expect('target' in options).toBe(false);
+ });
+
+ it('stashes the split CONNECTOR edge (found by its own rendered id) on data.originalEdge', () => {
+ const slot: InsertionSlot = { id: 'slot-1', graphEdgeId: 'e-1' };
+ const options = buildSequentialPreviewOptions(makeInstance(), {
+ ...baseArgs,
+ slot,
+ connectorEdgeId: 'conn:e-1',
+ });
+ expect(options.data).toEqual({ originalEdge: connectorEdge });
+ });
+
+ it('never finds an edge via slot.graphEdgeId alone (different id space)', () => {
+ // Regression: slot.graphEdgeId ('e-1') is the CANONICAL edge id; the store
+ // here only holds the derived connector edge ('conn:e-1'). Omitting
+ // connectorEdgeId must not accidentally match by falling back to graphEdgeId.
+ const slot: InsertionSlot = { id: 'slot-1', graphEdgeId: 'e-1' };
+ const options = buildSequentialPreviewOptions(makeInstance(), { ...baseArgs, slot });
+ expect(options.data).toEqual({});
+ });
+
+ it('omits originalEdge when the insert has no backing connector (tail append)', () => {
+ const slot: InsertionSlot = { id: 'slot-1' };
+ const options = buildSequentialPreviewOptions(makeInstance(), { ...baseArgs, slot });
+ expect(options.data).toEqual({});
+ });
+
+ it('never forwards slot.containerId into the preview graph options', () => {
+ // createPreviewGraph would reparent the preview onto the container's
+ // rendered clone with extent:'parent'; in sequential view that clone is a
+ // flattened bar, so the preview would clamp onto the container's own row.
+ // Canonical containment is applied to the materialized node instead (see
+ // resolvePendingSequentialInsert / sequentialOnBeforeNodeAdded).
+ const withContainer = buildSequentialPreviewOptions(makeInstance(), {
+ ...baseArgs,
+ slot: { id: 'slot-1', containerId: 'loop-1' },
+ });
+ expect('containerId' in withContainer).toBe(false);
+
+ const withoutContainer = buildSequentialPreviewOptions(makeInstance(), {
+ ...baseArgs,
+ slot: { id: 'slot-1' },
+ });
+ expect('containerId' in withoutContainer).toBe(false);
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialInsert.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialInsert.ts
new file mode 100644
index 000000000..e725a4d77
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/sequentialInsert.ts
@@ -0,0 +1,309 @@
+import type {
+ Edge,
+ Node,
+ ReactFlowInstance,
+ XYPosition,
+} from '@uipath/apollo-react/canvas/xyflow/react';
+import { Position } from '@uipath/apollo-react/canvas/xyflow/react';
+import {
+ DEFAULT_SOURCE_HANDLE_ID,
+ DEFAULT_TARGET_HANDLE_ID,
+ SEQ_BAR_HEIGHT,
+ SEQ_BAR_WIDTH,
+ SEQ_PLACEHOLDER_NODE_TYPE,
+ SEQ_START_NODE_TYPE,
+} from '../../../constants';
+import type { CreatePreviewGraphOptions } from '../../../utils/createPreviewGraph';
+import { SEQ_CONTINUATION_EDGE_KEY } from '../../../utils/sequential/graph-helpers';
+import type { InsertionSlot } from '../../../utils/sequential/sequential.types';
+
+/**
+ * Node `type` values excluded from the Add Node collision passes
+ * (shiftForEdgeInsertion / resolveCollisions, utils/NodeUtils.ts) so they never
+ * reposition the layout-owned vertical stack (D5).
+ *
+ * IMPORTANT: this covers ONLY the synthetic rows. Real step clones KEEP their
+ * manifest node type, so `ignoredNodeTypes` cannot enumerate them — the
+ * robust guarantee that layout owns clone positions lives in the change
+ * filtering, which drops every position/dimension change for clones before
+ * forwarding onNodesChange to the consumer (seam 2). Listing the synthetic types
+ * here is defense in depth so the collision pass can't nudge the start bar or
+ * terminal placeholder either.
+ *
+ * The names are re-exported from constants.ts, the single source of truth shared
+ * with the node components (nodes/index.ts).
+ */
+export const SEQUENTIAL_IGNORED_NODE_TYPES: string[] = [
+ SEQ_START_NODE_TYPE,
+ SEQ_PLACEHOLDER_NODE_TYPE,
+];
+
+/** Returns a fresh ignored-types array, optionally merged with host-specific extras. */
+export function getSequentialIgnoredNodeTypes(extra: readonly string[] = []): string[] {
+ return [...SEQUENTIAL_IGNORED_NODE_TYPES, ...extra];
+}
+
+/** Marker written on nodes inserted while in sequential view (D4). */
+export const SEQ_INSERTED_FLAG = 'seqInserted';
+
+/**
+ * Marker stashed on a forwarded edge's `data` carrying the exact canonical edge
+ * id that an insert split, so `forwardSequentialEdgeChanges` can drop that edge
+ * precisely instead of inferring it. Stripped before the edge reaches the host.
+ */
+export const SEQ_SPLIT_EDGE_ID_KEY = '__sequentialSplitEdgeId';
+
+/** Arguments the ⊕ button gives the insert wiring. */
+export interface SequentialInsertArgs {
+ /** The slot carried by the clicked connector. */
+ slot: InsertionSlot;
+ /** Fallback source endpoint (the connector's own source), used when the slot omits one. */
+ source: string;
+ /**
+ * The connector's own rendered source handle (always one of
+ * the sequential bar's view-only handles). No longer consulted for handle-id
+ * resolution (see {@link buildSequentialPreviewOptions} and
+ * {@link resolvePendingSequentialInsert}) — propagating it into canonical
+ * state is exactly the bug those functions guard against. Kept on the arg
+ * shape for call-site stability.
+ */
+ sourceHandleId?: string | null;
+ /** Fallback target endpoint (the connector's own target), used when the slot omits one. */
+ target: string;
+ /** The connector's own rendered target handle. See {@link sourceHandleId}. */
+ targetHandleId?: string | null;
+ /** Side of the source node the preview edge leaves from (bar bottom). */
+ sourcePosition: Position;
+ /** Drop point for the preview, in flow coordinates (the connector midpoint). */
+ position: XYPosition;
+ /**
+ * The id of the connector edge AS RENDERED (the `id` xyflow gives
+ * {@link SequentialConnectorEdge}), used to find and stash the split
+ * connector for cancel-restore. Undefined for slots with no backing edge
+ * (a tail append, or an empty branch/container body).
+ */
+ connectorEdgeId?: string;
+}
+
+/**
+ * Builds the {@link CreatePreviewGraphOptions} for a sequential insertion,
+ * riding the existing Add Node preview pipeline verbatim (D5). Splits into a
+ * pure builder so the option shape is unit-testable without a live canvas.
+ *
+ * The preview node is sized to a bar (SEQ_BAR_WIDTH x SEQ_BAR_HEIGHT) so the
+ * stack visibly opens a slot. These options retain canonical manifest handles
+ * as the preview is created. When the sequential projection rebuilds those
+ * edges, `buildSequentialEdges` renders them on the guaranteed bar handles and
+ * carries the canonical existing-endpoint handle separately for Add Node
+ * filtering/materialization. This keeps preview geometry reliable without
+ * losing connection semantics. The exact slot endpoints are also captured by
+ * {@link resolvePendingSequentialInsert} and restored by
+ * {@link sequentialOnBeforeNodeAdded}.
+ *
+ * The split connector (found by its OWN rendered id, `connectorEdgeId` — the
+ * store in sequential view holds derived connector edges, never canonical
+ * ids) is stashed on `data.originalEdge` so AddNodeManager can hide it while
+ * the panel is open and restore it if the panel is cancelled.
+ */
+export function buildSequentialPreviewOptions(
+ reactFlowInstance: ReactFlowInstance,
+ args: SequentialInsertArgs
+): CreatePreviewGraphOptions {
+ const { slot, source, target, sourcePosition, position, connectorEdgeId } = args;
+
+ const originalEdge = connectorEdgeId
+ ? reactFlowInstance.getEdges().find((edge) => edge.id === connectorEdgeId)
+ : undefined;
+
+ // Any target-only slot has no canonical source node. Drive the same preview
+ // pipeline from its canonical target handle; sourceHandleType='target' makes
+ // the preview the upstream source. The Workflow-start connector is one user
+ // of this general slot shape, without making the synthetic start bar part of
+ // canonical state or registry constraint checks.
+ const targetEndpoint = slot.target;
+ const isTargetOnlyInsert = slot.source === undefined && targetEndpoint !== undefined;
+ const previewSourceNodeId = isTargetOnlyInsert
+ ? targetEndpoint.nodeId
+ : (slot.source?.nodeId ?? source);
+ const previewSourceHandleId = isTargetOnlyInsert
+ ? (targetEndpoint.handleId ?? DEFAULT_TARGET_HANDLE_ID)
+ : (slot.source?.handleId ?? DEFAULT_SOURCE_HANDLE_ID);
+
+ // The target is optional: a tail append (the terminal placeholder) has a source
+ // but no downstream node. When neither the slot nor the fallback supplies a
+ // target node id, omit `target` entirely so the pipeline builds a source-only
+ // preview instead of wiring an edge to an empty id.
+ const targetNodeId = isTargetOnlyInsert ? undefined : (slot.target?.nodeId ?? target);
+
+ return {
+ reactFlowInstance,
+ source: {
+ nodeId: previewSourceNodeId,
+ // Preserve the canonical handle in the semantic preview graph. The
+ // derived sequential edge remaps its visual anchor to the bar handle and
+ // carries this id as previewConnectionHandleId for registry filtering.
+ handleId: previewSourceHandleId,
+ },
+ ...(targetNodeId
+ ? {
+ target: {
+ nodeId: targetNodeId,
+ handleId: slot.target?.handleId ?? DEFAULT_TARGET_HANDLE_ID,
+ },
+ }
+ : {}),
+ position,
+ positionMode: 'drop',
+ data: originalEdge ? { originalEdge } : {},
+ sourceHandleType: isTargetOnlyInsert ? 'target' : 'source',
+ handlePosition: isTargetOnlyInsert ? Position.Top : sourcePosition,
+ ignoredNodeTypes: SEQUENTIAL_IGNORED_NODE_TYPES,
+ previewNodeSize: { width: SEQ_BAR_WIDTH, height: SEQ_BAR_HEIGHT },
+ // containerId is intentionally NOT forwarded here: createPreviewGraph would
+ // reparent the preview onto the container's RENDERED clone with
+ // extent:'parent', but that clone is a flattened 896x72 bar (sequential
+ // view has no flow-view container body), so the preview would clamp to
+ // exactly overlap the container's row instead of showing in the lane. The
+ // canonical containment the slot describes is applied to the MATERIALIZED
+ // node instead — see resolvePendingSequentialInsert / sequentialOnBeforeNodeAdded.
+ };
+}
+
+/** Canonical containment/handle data resolved from a slot at insert time (D5). */
+export interface PendingSequentialInsert {
+ sourceNodeId?: string;
+ targetNodeId?: string;
+ graphEdgeId?: string;
+ /** slot.source's canonical handle id, if the split edge had an explicit one. */
+ sourceHandleId?: string;
+ /** slot.target's canonical handle id, if the split edge had an explicit one. */
+ targetHandleId?: string;
+ /** parentId for the materialized node, if the slot is scoped to a container. */
+ containerId?: string;
+ /** Whether the split source edge already represented an explicit continuation. */
+ splitEdgeWasContinuation?: boolean;
+}
+
+/**
+ * Captures the slot's canonical handle/containment data at the moment
+ * `startInsert` opens the panel, for {@link sequentialOnBeforeNodeAdded} to
+ * apply once the user picks a node (D5). Handle ids fall back to `undefined`
+ * (default-handle semantics), never to the connector's own bar handle — the
+ * bar handle is a view-rendering detail (see buildSequentialPreviewOptions)
+ * that must never reach canonical state.
+ */
+export function resolvePendingSequentialInsert(slot: InsertionSlot): PendingSequentialInsert {
+ return {
+ sourceNodeId: slot.source?.nodeId,
+ targetNodeId: slot.target?.nodeId,
+ graphEdgeId: slot.graphEdgeId,
+ sourceHandleId: slot.source?.handleId,
+ targetHandleId: slot.target?.handleId,
+ containerId: slot.containerId,
+ splitEdgeWasContinuation: slot.continuation,
+ };
+}
+
+/**
+ * Adapter for `AddNodeManager.onBeforeNodeAdded` (D4/D5). It:
+ * 1. keeps the preview's position as a harmless placement hint — layout owns
+ * positions in sequential view and the projection recomputes them on the
+ * next structural change (D12), so any value here is transient; reusing
+ * the preview's position (instead of zeroing it) just avoids piling the
+ * node onto the head of the stack before the collision pass runs;
+ * 2. stamps `data.seqInserted = true` so `synthesizePositionsForFlow` can
+ * place the node when the user toggles back to flow view (D4). Does NOT
+ * stamp `draggable: false` — the sequential clone derivation already forces
+ * that unconditionally for every row (useSequentialGraph), so doing it here
+ * too would only leak into canonical state and permanently disable dragging
+ * once the user toggles back to flow view;
+ * 3. re-ids the node with `crypto.randomUUID()` and rewrites the new edges to
+ * reference the new id (the pipeline seeds a `type-Date.now()` id, which can
+ * collide within the same millisecond);
+ * 4. applies the slot's canonical containment (`parentId`/`extent`) and
+ * restores the two existing-node endpoints to the slot's exact canonical
+ * handles. The inserted node's endpoints are deliberately left alone:
+ * AddNodeManager resolves those from the inserted node's own manifest.
+ * `pending` is captured by `useSequentialInsert` from the slot at the
+ * moment the panel opened (see resolvePendingSequentialInsert);
+ * 5. marks the inserted-node-to-existing-target edge as the sequence
+ * continuation. This keeps the old downstream sequence at the insertion
+ * scope instead of treating it as a branch/body child of the new node.
+ */
+export function sequentialOnBeforeNodeAdded(
+ newNode: Node,
+ newEdges: Edge[],
+ pending?: PendingSequentialInsert
+): { newNode: Node; newEdges: Edge[] } {
+ const seqId = crypto.randomUUID();
+ const previousId = newNode.id;
+
+ const finalNode: Node = {
+ ...newNode,
+ id: seqId,
+ ...(pending?.containerId ? { parentId: pending.containerId, extent: 'parent' as const } : {}),
+ data: { ...newNode.data, [SEQ_INSERTED_FLAG]: true },
+ };
+
+ const finalEdges = newEdges.map((edge) => {
+ const nextSource = edge.source === previousId ? seqId : edge.source;
+ const nextTarget = edge.target === previousId ? seqId : edge.target;
+ let nextSourceHandle = edge.sourceHandle;
+ let nextTargetHandle = edge.targetHandle;
+ // Preview edges use concrete handles so registry filtering works, while
+ // the split canonical edge may have relied on implicit defaults. Restore
+ // only the EXISTING nodes' exact endpoint semantics before forwarding;
+ // the inserted node's handles already came from its own manifest.
+ if (
+ pending?.sourceNodeId &&
+ edge.source === pending.sourceNodeId &&
+ edge.target === previousId
+ ) {
+ nextSourceHandle = pending.sourceHandleId;
+ }
+ if (
+ pending?.targetNodeId &&
+ edge.source === previousId &&
+ edge.target === pending.targetNodeId
+ ) {
+ nextTargetHandle = pending.targetHandleId;
+ }
+ const preservesSplitContinuation =
+ pending?.splitEdgeWasContinuation === true &&
+ edge.source === pending.sourceNodeId &&
+ edge.target === previousId;
+ const keepsDownstreamOutsideInsertedNode =
+ pending?.targetNodeId !== undefined &&
+ edge.source === previousId &&
+ edge.target === pending.targetNodeId;
+ const carriesContinuation = preservesSplitContinuation || keepsDownstreamOutsideInsertedNode;
+ const data =
+ pending?.graphEdgeId || carriesContinuation
+ ? {
+ ...edge.data,
+ ...(pending?.graphEdgeId ? { [SEQ_SPLIT_EDGE_ID_KEY]: pending.graphEdgeId } : {}),
+ ...(carriesContinuation ? { [SEQ_CONTINUATION_EDGE_KEY]: true } : {}),
+ }
+ : edge.data;
+ if (
+ nextSource === edge.source &&
+ nextTarget === edge.target &&
+ nextSourceHandle === edge.sourceHandle &&
+ nextTargetHandle === edge.targetHandle &&
+ data === edge.data
+ ) {
+ return edge;
+ }
+ return {
+ ...edge,
+ source: nextSource,
+ target: nextTarget,
+ sourceHandle: nextSourceHandle,
+ targetHandle: nextTargetHandle,
+ data,
+ id: `edge_${nextSource}-${nextSourceHandle}-${nextTarget}-${nextTargetHandle}`,
+ };
+ });
+
+ return { newNode: finalNode, newEdges: finalEdges };
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/useSequentialInsert.test.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/useSequentialInsert.test.tsx
new file mode 100644
index 000000000..2fb095ac3
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/useSequentialInsert.test.tsx
@@ -0,0 +1,106 @@
+import { renderHook } from '@testing-library/react';
+import type { Node } from '@uipath/apollo-react/canvas/xyflow/react';
+import { Position } from '@uipath/apollo-react/canvas/xyflow/react';
+import type { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import type { InsertionSlot } from '../../../utils/sequential/sequential.types';
+import { SequentialInsertGapProvider } from '../SequentialInsertGapContext';
+import { SequentialInsertStateProvider } from '../SequentialInsertStateContext';
+import { useSequentialInsert } from './useSequentialInsert';
+
+// The preview pipeline needs a live RF store; this hook test only exercises the
+// pending-slot bookkeeping, so stub the side effect out.
+vi.mock('../../../utils/createPreviewGraph', async (importOriginal) => ({
+ ...(await importOriginal()),
+ showPreviewGraph: vi.fn(),
+}));
+
+describe('useSequentialInsert', () => {
+ it('publishes the clicked slot so the placeholder is swapped for the preview row', () => {
+ const setGapSlot = vi.fn();
+ const wrapper = ({ children }: { children: ReactNode }) => (
+
+ {children}
+
+ );
+ const hook = renderHook(() => useSequentialInsert(), { wrapper });
+ const slot: InsertionSlot = { id: 'tail', source: { nodeId: 'last-step' } };
+
+ hook.result.current.startInsert({
+ slot,
+ source: 'last-step',
+ target: '',
+ sourcePosition: Position.Bottom,
+ position: { x: 0, y: 72 },
+ });
+
+ expect(setGapSlot).toHaveBeenCalledWith(slot);
+ });
+
+ it('shares the pending slot across separate hook instances so container parenting survives commit', () => {
+ // Regression: the connector plus (startInsert) and AddNodeManager's
+ // onBeforeNodeAdded are DIFFERENT useSequentialInsert instances. A
+ // per-instance ref left the commit side blind to the slot's containerId, so
+ // inserts into a For Each body / branch lane dropped parentId and orphaned
+ // the node. Both hook instances share one per-canvas provider.
+ const hooks = renderHook(
+ () => ({ opener: useSequentialInsert(), committer: useSequentialInsert() }),
+ { wrapper: SequentialInsertStateProvider }
+ );
+
+ const slot: InsertionSlot = {
+ id: 'slot-then',
+ source: { nodeId: 'if', handleId: 'true' },
+ target: { nodeId: 'javascript-1', handleId: 'input' },
+ graphEdgeId: 'e-if-then',
+ containerId: 'for-each',
+ };
+
+ hooks.result.current.opener.startInsert({
+ slot,
+ source: 'if',
+ target: 'javascript-1',
+ sourcePosition: Position.Bottom,
+ position: { x: 0, y: 0 },
+ });
+
+ const previewNode: Node = {
+ id: 'preview-node-id',
+ type: 'uipath.blank-node',
+ position: { x: 0, y: 0 },
+ data: {},
+ };
+ const { newNode } = hooks.result.current.committer.onBeforeNodeAdded(previewNode, []);
+
+ // The other instance's commit sees the opener's slot: container parent is
+ // stamped so the node splices into the lane rather than orphaning at the end.
+ expect(newNode.parentId).toBe('for-each');
+ expect(newNode.extent).toBe('parent');
+ });
+
+ it('isolates pending inserts between canvas providers', () => {
+ const canvasA = renderHook(() => useSequentialInsert(), {
+ wrapper: SequentialInsertStateProvider,
+ });
+ const canvasB = renderHook(() => useSequentialInsert(), {
+ wrapper: SequentialInsertStateProvider,
+ });
+ canvasA.result.current.startInsert({
+ slot: { id: 'a', source: { nodeId: 'a' }, containerId: 'container-a' },
+ source: 'a',
+ target: '',
+ sourcePosition: Position.Bottom,
+ position: { x: 0, y: 0 },
+ });
+ canvasB.result.current.startInsert({
+ slot: { id: 'b', source: { nodeId: 'b' }, containerId: 'container-b' },
+ source: 'b',
+ target: '',
+ sourcePosition: Position.Bottom,
+ position: { x: 0, y: 0 },
+ });
+ const seed: Node = { id: 'preview-node-id', position: { x: 0, y: 0 }, data: {} };
+ expect(canvasA.result.current.onBeforeNodeAdded(seed, []).newNode.parentId).toBe('container-a');
+ expect(canvasB.result.current.onBeforeNodeAdded(seed, []).newNode.parentId).toBe('container-b');
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/useSequentialInsert.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/useSequentialInsert.ts
new file mode 100644
index 000000000..e21208c76
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/edges/useSequentialInsert.ts
@@ -0,0 +1,68 @@
+import type { Edge, Node } from '@uipath/apollo-react/canvas/xyflow/react';
+import { useReactFlow } from '@uipath/apollo-react/canvas/xyflow/react';
+import { useCallback, useRef } from 'react';
+import { showPreviewGraph } from '../../../utils/createPreviewGraph';
+import { useSetSequentialInsertGapSlot } from '../SequentialInsertGapContext';
+import { useOptionalSequentialInsertState } from '../SequentialInsertStateContext';
+import {
+ buildSequentialPreviewOptions,
+ resolvePendingSequentialInsert,
+ type SequentialInsertArgs,
+ sequentialOnBeforeNodeAdded,
+} from './sequentialInsert';
+
+export interface UseSequentialInsertResult {
+ /**
+ * Opens the Add Node panel for a connector's insertion slot by riding the
+ * existing preview pipeline (D5). Call this from the ⊕ button's click handler.
+ */
+ startInsert: (args: SequentialInsertArgs) => void;
+ /**
+ * Bound `AddNodeManager.onBeforeNodeAdded` adapter. Closes over the slot
+ * captured by the most recent `startInsert` call so materialization can
+ * apply the slot's canonical handle ids / containment (D5) — `onBeforeNodeAdded`
+ * itself only receives the new node and edges, not the slot that started the
+ * insert, so this hook is the side channel between the two.
+ */
+ onBeforeNodeAdded: (newNode: Node, newEdges: Edge[]) => { newNode: Node; newEdges: Edge[] };
+}
+
+/**
+ * Wires the ⊕ insert affordance to the existing Add Node preview pipeline. It
+ * only kicks off the preview; the panel, constraint filtering, materialization,
+ * and cancel-restore all run through the unchanged AddNodeManager (which the
+ * assembly mounts as a child of the canvas with `onBeforeNodeAdded` from this hook and
+ * `ignoredNodeTypes` from ./sequentialInsert).
+ */
+export function useSequentialInsert(): UseSequentialInsertResult {
+ const reactFlowInstance = useReactFlow();
+ const setInsertGapSlot = useSetSequentialInsertGapSlot();
+ const localPending = useRef | undefined>(
+ undefined
+ );
+ const sharedState = useOptionalSequentialInsertState();
+ const pending = sharedState?.pending ?? localPending;
+
+ const startInsert = useCallback(
+ (args: SequentialInsertArgs) => {
+ pending.current = resolvePendingSequentialInsert(args.slot);
+ // Surfaces the active slot for the insert-preview-gap post-pass:
+ // SequentialCanvas.tsx owns the state and clears it again
+ // on cancel/commit (usePreviewNode transitioning closed).
+ setInsertGapSlot(args.slot);
+ showPreviewGraph(buildSequentialPreviewOptions(reactFlowInstance, args));
+ },
+ [reactFlowInstance, setInsertGapSlot, pending]
+ );
+
+ const onBeforeNodeAdded = useCallback(
+ (newNode: Node, newEdges: Edge[]) => {
+ const result = sequentialOnBeforeNodeAdded(newNode, newEdges, pending.current);
+ pending.current = undefined;
+ return result;
+ },
+ [pending]
+ );
+
+ return { startInsert, onBeforeNodeAdded };
+}
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/index.ts b/packages/apollo-react/src/canvas/components/SequentialCanvas/index.ts
new file mode 100644
index 000000000..b0793f856
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/index.ts
@@ -0,0 +1,23 @@
+export type {
+ CanvasViewTransitionResult,
+ PrepareCanvasViewTransitionOptions,
+} from './prepareCanvasViewTransition';
+export { prepareCanvasViewTransition } from './prepareCanvasViewTransition';
+export { SequentialCanvas } from './SequentialCanvas';
+export type { SequentialCanvasProps, ViewSwitcherProps } from './SequentialCanvas.types';
+export type {
+ SequentialViewContextValue,
+ SequentialViewProviderProps,
+} from './SequentialViewContext';
+export { SequentialViewProvider, useSequentialView } from './SequentialViewContext';
+export { synthesizePositionsForFlow } from './synthesizePositionsForFlow';
+export { useCanvasViewMode } from './useCanvasViewMode';
+export type { SequentialGraph, UseSequentialGraphArgs } from './useSequentialGraph';
+export { deriveSequentialGraph, useSequentialGraph } from './useSequentialGraph';
+export type {
+ SequentialKeyboardRow,
+ UseSequentialKeyboardArgs,
+ UseSequentialKeyboardResult,
+} from './useSequentialKeyboard';
+export { useSequentialKeyboard } from './useSequentialKeyboard';
+export { ViewSwitcher } from './ViewSwitcher';
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/BarVariant.stories.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/BarVariant.stories.tsx
new file mode 100644
index 000000000..3dba72d9e
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/BarVariant.stories.tsx
@@ -0,0 +1,123 @@
+/**
+ * Sequential bar variant, visual-drift contract.
+ *
+ * Renders the same representative manifests twice: as free-form cards (left) and
+ * as sequential bars (right), plus the synthetic start and placeholder rows. The
+ * bar reuses BaseNode's resolved display, so icon, label, and colors match the
+ * card for every node. This is an early seed of the fuller card/bar contract.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import type { Node, NodeTypes } from '@uipath/apollo-react/canvas/xyflow/react';
+import { ReactFlowProvider } from '@uipath/apollo-react/canvas/xyflow/react';
+import { useMemo } from 'react';
+import { useNodeTypeRegistry } from '../../../core';
+import {
+ createNode,
+ useNodeTypesFromRegistry,
+ withCanvasProviders,
+} from '../../../storybook-utils';
+import { BaseCanvas } from '../../BaseCanvas';
+import { BaseNode } from '../../BaseNode/BaseNode';
+import {
+ SEQ_PLACEHOLDER_NODE_TYPE,
+ SEQ_START_NODE_TYPE,
+ SEQUENTIAL_SYNTHETIC_NODE_TYPES,
+ SequentialStepNode,
+} from './index';
+
+const meta: Meta = {
+ title: 'Components/Nodes/Sequential Bar',
+ parameters: { layout: 'fullscreen' },
+ decorators: [withCanvasProviders()],
+};
+
+export default meta;
+type Story = StoryObj;
+
+// Representative manifests: a trigger, a branch, a container, a data step, and an
+// agent. All exist in the default workflow manifest installed by the decorator.
+const REPRESENTATIVE_TYPES = [
+ 'uipath.manual-trigger',
+ 'uipath.control-flow.decision',
+ 'uipath.control-flow.foreach',
+ 'uipath.data.transform',
+ 'uipath.agent',
+] as const;
+
+const CARD_PITCH = 176;
+const BAR_PITCH = 128;
+
+function cardNodes(): Node[] {
+ return REPRESENTATIVE_TYPES.map((type, i) =>
+ createNode({ id: `card-${i}`, type, position: { x: 0, y: i * CARD_PITCH } })
+ );
+}
+
+function barNodes(): Node[] {
+ const start: Node = {
+ id: 'seq-start',
+ type: SEQ_START_NODE_TYPE,
+ position: { x: 0, y: 0 },
+ data: { onAddTrigger: () => {} },
+ draggable: false,
+ };
+ const steps = REPRESENTATIVE_TYPES.map((type, i) =>
+ createNode({ id: `bar-${i}`, type, position: { x: 0, y: (i + 1) * BAR_PITCH } })
+ );
+ const placeholder: Node = {
+ id: 'seq-placeholder',
+ type: SEQ_PLACEHOLDER_NODE_TYPE,
+ position: { x: 0, y: (REPRESENTATIVE_TYPES.length + 1) * BAR_PITCH },
+ data: { onAdd: () => {} },
+ draggable: false,
+ };
+ return [start, ...steps, placeholder];
+}
+
+function BarVariantStory() {
+ const registry = useNodeTypeRegistry();
+ const cardTypes = useNodeTypesFromRegistry(BaseNode);
+ const barTypes = useMemo(() => {
+ const types: NodeTypes = { default: SequentialStepNode, ...SEQUENTIAL_SYNTHETIC_NODE_TYPES };
+ for (const manifest of registry.getAllManifests()) {
+ types[manifest.nodeType] = SequentialStepNode;
+ }
+ return types;
+ }, [registry]);
+
+ const cards = useMemo(cardNodes, []);
+ const bars = useMemo(barNodes, []);
+
+ return (
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+
+export const CardVsBar: Story = {
+ name: 'Card vs Bar',
+ render: () => ,
+};
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialInsertPreviewNode.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialInsertPreviewNode.tsx
new file mode 100644
index 000000000..e5958a88c
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialInsertPreviewNode.tsx
@@ -0,0 +1,75 @@
+import type { NodeProps } from '@uipath/apollo-react/canvas/xyflow/react';
+import { Handle, Position } from '@uipath/apollo-react/canvas/xyflow/react';
+import { cn } from '@uipath/apollo-wind';
+import { memo, useMemo } from 'react';
+import { useSafeLingui } from '../../../../i18n';
+import { getIcon } from '../../../utils/icon-registry';
+import {
+ getSeqBarVars,
+ INVISIBLE_HANDLE_STYLE,
+ SEQ_BAR_SHELL_CLASS,
+ SEQUENTIAL_BAR_HANDLE_IDS,
+} from '../../BaseNode/BaseNodeBar';
+import { BaseInnerShape } from '../../BaseNode/BaseNodeInnerShape';
+
+/**
+ * Sequential-view Add Node preview bar. The shared {@link AddNodePreview}
+ * centers a `min(w,h)`-sized glyph, which in the 896x56 bar leaves a nearly
+ * empty slab with a lonely icon. This mirrors the real bar layout instead: a
+ * dashed, de-emphasized bar with the icon box on the LEFT and a "New step"
+ * label, so the slot the insert will fill reads like a ghost of a real row.
+ *
+ * Registered as the `preview` node type only in the sequential view (see
+ * SequentialCanvas.tsx); the flow view keeps AddNodePreview. Its handle ids
+ * (`input`/`output`) match the Add Node preview edges, offset to the connector
+ * spine (SEQ handle offset) so those edges align like a real bar's connectors.
+ */
+function SequentialInsertPreviewNodeComponent({ width, height }: NodeProps) {
+ const { _ } = useSafeLingui();
+ const label = _({ id: 'sequential-canvas.new-step', message: 'New step' });
+ const icon = useMemo(() => {
+ const IconComponent = getIcon('square-dashed');
+ return ;
+ }, []);
+
+ return (
+
+
+
+ {icon}
+ {label}
+
+
+ );
+}
+
+export const SequentialInsertPreviewNode = memo(SequentialInsertPreviewNodeComponent);
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialPlaceholderNode.test.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialPlaceholderNode.test.tsx
new file mode 100644
index 000000000..5576d7ccd
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialPlaceholderNode.test.tsx
@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '../../../utils/testing';
+import { BaseCanvasModeProvider } from '../../BaseCanvas/BaseCanvasModeProvider';
+import { SequentialPlaceholderNode } from './SequentialPlaceholderNode';
+
+// The node renders xyflow s, which need a store provider. This test
+// only exercises the affordance rendering, so stub them out.
+vi.mock('@uipath/apollo-react/canvas/xyflow/react', async (importOriginal) => {
+ const actual = await importOriginal();
+ return { ...actual, Handle: () => null };
+});
+
+// Minimal NodeProps stand-in for a focused render test.
+// biome-ignore lint/suspicious/noExplicitAny: minimal NodeProps stub.
+const props = (data: object) => ({ id: 'ph', data, width: 896, height: 44 }) as any;
+
+function renderNode(data: object, mode: 'design' | 'view' = 'design') {
+ return render(
+
+
+
+ );
+}
+
+describe('SequentialPlaceholderNode', () => {
+ it('renders the dashed Add step row for the row variant (empty lane/body)', () => {
+ renderNode({ variant: 'row', onAdd: () => {} });
+ expect(screen.getByTestId('sequential-placeholder-bar')).toBeInTheDocument();
+ // The row shows a visible label.
+ expect(screen.getByText('Add step')).toBeInTheDocument();
+ expect(screen.queryByTestId('sequential-placeholder-plus')).not.toBeInTheDocument();
+ });
+
+ it('renders a quiet plus (no visible label) for the plus variant (append)', () => {
+ renderNode({ variant: 'plus', onAdd: () => {} });
+ expect(screen.getByTestId('sequential-placeholder-plus')).toBeInTheDocument();
+ // The plus is icon-only: labelled for a11y, but no visible text.
+ expect(screen.getByRole('button', { name: 'Add step' })).toBeInTheDocument();
+ expect(screen.queryByText('Add step')).not.toBeInTheDocument();
+ expect(screen.queryByTestId('sequential-placeholder-bar')).not.toBeInTheDocument();
+ });
+
+ it('defaults to the row variant when none is given', () => {
+ renderNode({ onAdd: () => {} });
+ expect(screen.getByTestId('sequential-placeholder-bar')).toBeInTheDocument();
+ });
+
+ it('calls onAdd when the plus is clicked in design mode', () => {
+ const onAdd = vi.fn();
+ renderNode({ variant: 'plus', onAdd });
+ fireEvent.click(screen.getByRole('button', { name: 'Add step' }));
+ expect(onAdd).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not add outside design mode', () => {
+ const onAdd = vi.fn();
+ renderNode({ variant: 'plus', onAdd }, 'view');
+ fireEvent.click(screen.getByRole('button', { name: 'Add step' }));
+ expect(onAdd).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialPlaceholderNode.tsx b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialPlaceholderNode.tsx
new file mode 100644
index 000000000..28f45c5f8
--- /dev/null
+++ b/packages/apollo-react/src/canvas/components/SequentialCanvas/nodes/SequentialPlaceholderNode.tsx
@@ -0,0 +1,140 @@
+import type { Node, NodeProps } from '@uipath/apollo-react/canvas/xyflow/react';
+import { Handle, Position } from '@uipath/apollo-react/canvas/xyflow/react';
+import { cn } from '@uipath/apollo-wind';
+import { memo } from 'react';
+import { useSafeLingui } from '../../../../i18n';
+import { SEQ_HANDLE_LEFT_OFFSET } from '../../../constants';
+import { CanvasIcon } from '../../../utils/icon-registry';
+import { useBaseCanvasMode } from '../../BaseCanvas/BaseCanvasModeProvider';
+import {
+ getSeqBarVars,
+ INVISIBLE_HANDLE_STYLE,
+ SEQ_BAR_SHELL_CLASS,
+ SEQUENTIAL_BAR_HANDLE_IDS,
+} from '../../BaseNode/BaseNodeBar';
+import { CanvasInlineButton } from '../../ButtonHandle/CanvasInlineButton';
+
+/**
+ * The faint-until-hover treatment shared by every sequential insert affordance
+ * (the connector plus in SequentialInsertButton and this node's plus variant),
+ * so "add a step" reads and behaves identically wherever it appears.
+ */
+const SEQ_INSERT_REST_CLASS =
+ 'opacity-40 transition-opacity group-hover:opacity-100 group-focus-within:opacity-100';
+
+export interface SequentialPlaceholderNodeData extends Record {
+ /** Invoked when the affordance is clicked to add a step into this scope. */
+ onAdd?: () => void;
+ /** View-only slot identity used to recover this row's position when clicked. */
+ insertionSlotId?: string;
+ /**
+ * Which affordance to render (see `SequenceRow.placeholderKind`):
+ * - 'row' (default): a dashed "Add step" bar for a genuinely empty lane/body.
+ * - 'plus': a quiet plus matching the between-step insert, for the trailing
+ * add point after a populated lane's last step (or the tail).
+ */
+ variant?: 'row' | 'plus';
+}
+
+/**
+ * Synthetic "add a step" row. Two shapes, chosen by `data.variant`:
+ * - 'row': a dashed, bar-sized drop target with a centered plus and label,
+ * styled after AddNodePreview. Used where a lane or body is genuinely empty
+ * and there is no connector to host a plus.
+ * - 'plus': the same quiet plus used between steps, anchored on the incoming
+ * connector, so appending at the end of a list looks identical to inserting
+ * between two steps.
+ *
+ * It carries a top target handle (the tail follows the last step) and a mid-left
+ * handle (an empty lane is entered from the side). Injected view-only and
+ * filtered out of the change callbacks by the canvas assembly.
+ */
+function SequentialPlaceholderNodeComponent({
+ data,
+ width,
+ height,
+}: NodeProps>) {
+ const { _ } = useSafeLingui();
+ const onAdd = data?.onAdd;
+ const isDesignMode = useBaseCanvasMode().mode === 'design';
+ const label = _({ id: 'sequential-canvas.placeholder.add', message: 'Add step' });
+ const variant = data?.variant ?? 'row';
+
+ const handles = (
+ <>
+
+ {/* Mid-left entry so an empty-branch-lane placeholder is entered from the
+ side like a real branch child (the tail placeholder still uses Top). */}
+
+
+ );
+
+ if (variant === 'plus') {
+ // The box spans the row gap (no reserved row). Center the plus on the shared
+ // handle column so it sits in the gap below the last step, exactly like a
+ // between-step insert. The box itself is non-interactive so only the plus
+ // takes clicks, and it hides cleanly in readonly without moving any node.
+ return (
+