@principal-ai/subsystems-react 0.55.1 → 0.55.3

package/src/stories/{Subsystem → Components}/AgentsPanel.stories.tsx

@@ -16,7 +16,7 @@ const AGENTS: SubsystemAgent[] = [
 ];
 
 const meta = {
-  title: 'Subsystem/Agents Panel',
+  title: 'Components/AgentsPanel',
   component: SubsystemAgentsPanel,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentDeclarationAudit.stories.tsx → Components/ComponentDeclaration/Audit.stories.tsx}

@@ -2,12 +2,12 @@ import React from 'react';
 import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
-import { ComponentDeclaration } from '../../subsystem/ComponentDeclaration';
-import type { SubsystemComponent } from '../../subsystem/model';
-import type { GraphifyComponentDetail } from '../../graphify';
+import { ComponentDeclaration } from '../../../subsystem/ComponentDeclaration';
+import type { SubsystemComponent } from '../../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../../graphify';
 
 const meta = {
-  title: 'Subsystem/ComponentDeclarationAudit',
+  title: 'Components/ComponentDeclaration/Audit',
   component: ComponentDeclaration,
   parameters: { layout: 'padded' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentDeclarationSymbols.stories.tsx → Components/ComponentDeclaration/Symbols.stories.tsx}

@@ -2,13 +2,13 @@ import React, { useState } from 'react';
 import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
-import { ComponentDeclaration } from '../../subsystem/ComponentDeclaration';
-import type { SubsystemComponent } from '../../subsystem/model';
-import type { GraphifyComponentDetail } from '../../graphify';
-import type { SymbolInspection } from '../../subsystem/symbolRefs';
+import { ComponentDeclaration } from '../../../subsystem/ComponentDeclaration';
+import type { SubsystemComponent } from '../../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../../graphify';
+import type { SymbolInspection } from '../../../subsystem/symbolRefs';
 
 const meta = {
-  title: 'Subsystem/ComponentDeclarationSymbols',
+  title: 'Components/ComponentDeclaration/Symbols',
   component: ComponentDeclaration,
   parameters: { layout: 'padded' },
   tags: ['autodocs'],

package/src/stories/{Subsystem → Components}/ConstructsCatalog.stories.tsx

@@ -9,7 +9,7 @@ import type { SymbolInspection } from '../../subsystem/symbolRefs';
 import type { GraphifyComponentDetail } from '../../graphify';
 
 const meta = {
-  title: 'Subsystem/ConstructsCatalog',
+  title: 'Components/ConstructsCatalog',
   component: ConstructsCatalog,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/Sidebar → Components}/GraphSidebar.stories.tsx

@@ -1,13 +1,13 @@
 import React, { useMemo, useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
-import { GraphSidebar } from '../../../subsystem/GraphSidebar';
-import { TrailsPanel } from '../../../subsystem/TrailsPanel';
+import { GraphSidebar } from '../../subsystem/GraphSidebar';
+import { TrailsPanel } from '../../subsystem/TrailsPanel';
 import {
   DRILLDOWN_COMPONENTS,
   DRILLDOWN_DOC,
   DRILLDOWN_TRAILS,
-} from '../../../subsystem/__fixtures__/c4Drilldown';
+} from '../../subsystem/__fixtures__/c4Drilldown';
 
 /**
  * `GraphSidebar` — the side panel extracted out of `SubsystemComponentGraph`,
@@ -176,7 +176,7 @@ function PanelDemo({ controlled = false }: { controlled?: boolean }) {
 }
 
 const meta = {
-  title: 'Subsystem/Sidebar/GraphSidebar',
+  title: 'Components/GraphSidebar',
   component: GraphSidebar,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/IssueIcons.stories.tsx → Components/IssueList.stories.tsx}

@@ -11,7 +11,7 @@ import { FileCodeCorner } from 'lucide-react';
  * No "?" badge (removed by request).
  */
 const meta = {
-  title: 'Subsystem/IssueIcons',
+  title: 'Components/IssueList',
   parameters: { layout: 'fullscreen' },
 } satisfies Meta;
 

package/src/stories/{Subsystem/StoreValueTypeDeclaration.stories.tsx → Components/StoreValueType.stories.tsx}

@@ -17,7 +17,7 @@ import type { SubsystemComponent } from '../../subsystem/model';
  * storage backing. The value type is panel-only.
  */
 const meta = {
-  title: 'Subsystem/StoreValueTypeDeclaration',
+  title: 'Components/StoreValueType',
   parameters: { layout: 'padded' },
   tags: ['autodocs'],
   decorators: [

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -32,7 +32,7 @@ import {
   applyNodeChanges,
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { FileText, X } from 'lucide-react';
+import { FileText, ArrowDown, ArrowRight, Unlink, X } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
   buildSubsystemGraph,
@@ -45,10 +45,12 @@ import {
   MECHANISM_DESCRIPTIONS,
   subsystemGraphLayoutKey,
   trailStepGraphEdgeId,
+  unroutedEdgeIds,
   type SubsystemComponentEdge,
   type SubsystemComponent,
   type SubsystemEdgeProvenance,
   type SubsystemEdgeView,
+  type SubsystemLayoutDirection,
   type SubsystemGraphifyRelation,
   type SubsystemNodeIssue,
   type SubsystemRegionIssue,
@@ -80,7 +82,7 @@ import {
 } from './IssueList';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
-import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
+import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle, LAYOUT_FLIP_CLASS, LAYOUT_FLIP_EDGE_MS, LAYOUT_FLIP_NODE_MS } from './graphChrome';
 import { ComponentDeclaration } from './ComponentDeclaration';
 import type { ComponentVerificationState } from './ComponentDeclaration';
 import type { DeclarationSymbolRef, SymbolInspection } from './symbolRefs';
@@ -160,6 +162,8 @@ interface PersistedViewState {
   sidebarWidth?: number;
   sidebarView?: 'files' | 'trails';
   diagnosticsTab?: 'issues' | 'agents';
+  /** Flow direction chosen with the canvas toggle, restored on the next visit. */
+  layoutDirection?: SubsystemLayoutDirection;
 }
 
 const VIEW_STATE_PREFIX = 'principal.subsystems.viewState.';
@@ -216,6 +220,40 @@ export interface SubsystemComponentGraphProps {
    * `line` for this to have any effect. @default false
    */
   orderByLine?: boolean;
+  /**
+   * Flow direction of the layered layout. `horizontal` (default) runs layers
+   * left-to-right; `vertical` runs them top-to-bottom. Edge-less containment
+   * graphs keep their DOWN + grid treatment either way.
+   *
+   * Pass this to control the direction from the host; leave it unset to let
+   * the graph own it (seeded by `defaultLayoutDirection`, updated by the
+   * built-in toggle, and persisted under `persistKey`).
+   */
+  layoutDirection?: SubsystemLayoutDirection;
+  /**
+   * Initial flow direction when uncontrolled. Ignored when `layoutDirection`
+   * is provided. @default 'horizontal'
+   */
+  defaultLayoutDirection?: SubsystemLayoutDirection;
+  /**
+   * Fired when the built-in toggle (or a host control) requests a different
+   * direction. Hosts that pass `layoutDirection` must update it here; hosts
+   * that don't can use it to observe the change.
+   */
+  onLayoutDirectionChange?: (direction: SubsystemLayoutDirection) => void;
+  /**
+   * Hide the built-in horizontal/vertical toggle in the canvas corner.
+   * @default false
+   */
+  hideLayoutToggle?: boolean;
+  /**
+   * Refit the camera to the new layout after a layout flip — a direction
+   * change or a trail-focus change. On by default: a vertical layout grows
+   * downward and would otherwise leave the graph half off-screen. Turn off for
+   * embeds that own their own camera.
+   * @default true
+   */
+  refocusOnLayoutFlip?: boolean;
   /**
    * Deep-link target: when set, the matching trail is selected on mount
    * — its steps expanded and its flow focused on the canvas. Hosts use this
@@ -574,7 +612,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, trails, graphifyRelations, orderByLine, initialTrailId, onTrailSelect, onTrailStepHover, onReorderTrails, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, title, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, laneStatus, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, codeProcessKeys, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
+function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirection: layoutDirectionProp, defaultLayoutDirection = 'horizontal', onLayoutDirectionChange, hideLayoutToggle = false, refocusOnLayoutFlip = true, initialTrailId, onTrailSelect, onTrailStepHover, onReorderTrails, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, title, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, laneStatus, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, codeProcessKeys, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
   const { theme } = useTheme();
   const { fitView, fitBounds, screenToFlowPosition } = useReactFlow();
   const viewport = useViewport();
@@ -595,6 +633,151 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     absoluteRects: new Map(),
   });
   const [layoutReady, setLayoutReady] = useState(false);
+
+  // --- Layout direction -----------------------------------------------------
+  // The graph owns direction unless the host passes `layoutDirection`. A change
+  // is sequenced so old edge routes never cut across the new layout: edges fade
+  // out, ELK re-lays out while the nodes slide to their new slots, then the
+  // edges fade back in. Two values keep that honest: `requestedDirection` is
+  // what the toggle shows, `committedDirection` is what ELK last ran with.
+  const [ownDirection, setOwnDirection] = useState<SubsystemLayoutDirection>(
+    () => persisted.layoutDirection ?? defaultLayoutDirection,
+  );
+  const requestedDirection = layoutDirectionProp ?? ownDirection;
+  const [committedDirection, setCommittedDirection] =
+    useState<SubsystemLayoutDirection>(requestedDirection);
+  const [layoutFlipping, setLayoutFlipping] = useState(false);
+  const flipSawPendingLayoutRef = useRef(false);
+  /** Pending fade-out timer; non-null only between request and commit. */
+  const flipFadeTimerRef = useRef<number | null>(null);
+  /** Set when a layout flip starts; the camera refits once layout lands. */
+  const refitAfterLayoutRef = useRef(false);
+
+  /** Solo layout: only this trail's components and edges are laid out. */
+  const [layoutTrailId, setLayoutTrailId] = useState<string | null>(null);
+  const [committedTrailId, setCommittedTrailId] = useState<string | null>(null);
+
+  const changeLayoutDirection = useCallback(
+    (next: SubsystemLayoutDirection) => {
+      if (next === requestedDirection) return;
+      if (layoutDirectionProp == null) setOwnDirection(next);
+      onLayoutDirectionChange?.(next);
+    },
+    [layoutDirectionProp, onLayoutDirectionChange, requestedDirection],
+  );
+
+  const toggleLayoutFocus = useCallback((trailId: string) => {
+    setLayoutTrailId((cur) => (cur === trailId ? null : trailId));
+  }, []);
+
+  // A focused trail that disappears (model reload) releases the solo layout
+  // instead of pinning the canvas to a slice that no longer exists.
+  useEffect(() => {
+    if (layoutTrailId && !(trails ?? []).some((t) => t.id === layoutTrailId)) {
+      setLayoutTrailId(null);
+    }
+  }, [trails, layoutTrailId]);
+
+  const requestedLayoutKey = `${requestedDirection}|${layoutTrailId ?? ''}`;
+  const committedLayoutKey = `${committedDirection}|${committedTrailId ?? ''}`;
+
+  // Beat 1: request → fade the edges out, then commit the direction / focus
+  // (which re-runs ELK). Reduced-motion users get the new layout immediately.
+  useEffect(() => {
+    if (requestedLayoutKey === committedLayoutKey) {
+      // A host can revert a request before the fade-out commits. Drop the
+      // pending flip instead of leaving the canvas edge-less until the safety
+      // timeout. A normal commit also lands here (request now equals
+      // committed), but by then the timer ref is already null — and the
+      // pending refit must survive that pass.
+      if (flipFadeTimerRef.current != null) {
+        clearTimeout(flipFadeTimerRef.current);
+        flipFadeTimerRef.current = null;
+        setLayoutFlipping(false);
+        refitAfterLayoutRef.current = false;
+      }
+      return;
+    }
+    refitAfterLayoutRef.current = refocusOnLayoutFlip;
+    const reduceMotion =
+      typeof window !== 'undefined' &&
+      typeof window.matchMedia === 'function' &&
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    if (reduceMotion) {
+      setCommittedDirection(requestedDirection);
+      setCommittedTrailId(layoutTrailId);
+      return;
+    }
+    flipSawPendingLayoutRef.current = false;
+    setLayoutFlipping(true);
+    flipFadeTimerRef.current = window.setTimeout(() => {
+      flipFadeTimerRef.current = null;
+      setCommittedDirection(requestedDirection);
+      setCommittedTrailId(layoutTrailId);
+    }, LAYOUT_FLIP_EDGE_MS);
+    return () => {
+      if (flipFadeTimerRef.current != null) {
+        clearTimeout(flipFadeTimerRef.current);
+        flipFadeTimerRef.current = null;
+      }
+    };
+  }, [
+    requestedLayoutKey,
+    committedLayoutKey,
+    refocusOnLayoutFlip,
+    requestedDirection,
+    layoutTrailId,
+  ]);
+
+  // Beat 3: the committed layout has settled → the node slide is over, fade
+  // the edges back in. The ref keeps the OLD `layoutReady` (still true until
+  // the new pass 1 commits) from ending the flip before the layout swaps.
+  useEffect(() => {
+    if (!layoutFlipping) return;
+    if (!layoutReady) {
+      flipSawPendingLayoutRef.current = true;
+      return;
+    }
+    if (!flipSawPendingLayoutRef.current) return;
+    const t = setTimeout(() => setLayoutFlipping(false), LAYOUT_FLIP_NODE_MS);
+    return () => clearTimeout(t);
+  }, [layoutFlipping, layoutReady]);
+
+  // Camera: a direction flip moves the whole graph, and a vertical layout grows
+  // downward, so keeping the old viewport would leave most of it off-screen.
+  // Refit once the new layout is final — for both the animated flip and the
+  // reduced-motion instant swap. The edge reveal is separate (beat 3 above).
+  // Keyed on `built` as well as `layoutReady`: whichever of the two passes
+  // lands last is the one that has the final positions.
+  useEffect(() => {
+    if (!layoutReady || !refitAfterLayoutRef.current) return;
+    refitAfterLayoutRef.current = false;
+    requestAnimationFrame(() => {
+      fitView({
+        padding: 0.1,
+        includeHiddenNodes: false,
+        minZoom: 0.05,
+        maxZoom: 2,
+        duration: LAYOUT_FLIP_NODE_MS,
+      });
+    });
+  }, [built, layoutReady, fitView]);
+
+  // Persist the choice so a model reopens the way it was left.
+  useEffect(() => {
+    if (!persistKey) return;
+    writeViewState(persistKey, { layoutDirection: requestedDirection });
+  }, [persistKey, requestedDirection]);
+
+  // Safety net: never leave the canvas edge-less if a layout pass stalls
+  // (measurement never lands, ELK hangs). The edges come back; the layout
+  // stays wherever it got to.
+  useEffect(() => {
+    if (!layoutFlipping) return;
+    const t = setTimeout(() => setLayoutFlipping(false), 5000);
+    return () => clearTimeout(t);
+  }, [layoutFlipping]);
+
   const [selected, setSelected] = useState<SubsystemComponent | null>(null);
   /** Bottom drawer: single file or trail multi-snippet mode. */
   const [drawerTarget, setDrawerTarget] = useState<DrawerTarget | null>(null);
@@ -717,8 +900,11 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   // Trails draws runtime step edges. Without visible tabs (no trails,
   // or a sidebar-less embed) fall back to trail edges.
   const sidebarTabsVisible = !hideSidebar && (trails?.length ?? 0) > 0;
-  const resolvedEdgeView: SubsystemEdgeView =
-    edgeView ??
+  // A solo trail layout only draws that flow's steps, so the trail edge source
+  // is the only one that can render anything.
+  const resolvedEdgeView: SubsystemEdgeView = committedTrailId
+    ? 'trails'
+    : edgeView ??
     (sidebarTabsVisible
       ? (sidebarView === 'trails' ? 'trails' : 'graphify')
       : (trails?.length ?? 0) > 0
@@ -903,16 +1089,39 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   // Pass 1: build with estimated widths so React Flow can measure the DOM.
   // The pane stays hidden until Pass 2 completes. Key off layout-affecting
   // fields only — declarationSpan updates after verify must not re-run ELK.
+  // Solo layout: a trail focus filters the model down to that flow's endpoints
+  // (and drops graphify relations) before it reaches ELK. Built from the
+  // COMMITTED trail, not the requested one, so the swap happens behind the
+  // edge fade like every other layout flip.
+  const layoutDoc = useMemo(() => {
+    if (!committedTrailId) return { components, trails };
+    const trail = (trails ?? []).find((t) => t.id === committedTrailId);
+    if (!trail) return { components, trails };
+    const aliases = new Set<string>();
+    for (const step of trail.steps) {
+      aliases.add(step.from);
+      aliases.add(step.to);
+    }
+    return {
+      components: components.filter((c) => aliases.has(c.alias)),
+      trails: [trail],
+    };
+  }, [components, trails, committedTrailId]);
+  const layoutRelations = committedTrailId ? undefined : graphifyRelations;
+
   const layoutKey = useMemo(
-    () => subsystemGraphLayoutKey({ components, trails, graphifyRelations }),
-    [components, trails, graphifyRelations],
+    () =>
+      subsystemGraphLayoutKey({
+        components: layoutDoc.components,
+        trails: layoutDoc.trails,
+        graphifyRelations: layoutRelations,
+      }),
+    [layoutDoc, layoutRelations],
   );
-  const componentsRef = useRef(components);
-  const trailsRef = useRef(trails);
-  const graphifyRelationsRef = useRef(graphifyRelations);
-  componentsRef.current = components;
-  trailsRef.current = trails;
-  graphifyRelationsRef.current = graphifyRelations;
+  const layoutDocRef = useRef(layoutDoc);
+  const layoutRelationsRef = useRef(layoutRelations);
+  layoutDocRef.current = layoutDoc;
+  layoutRelationsRef.current = layoutRelations;
 
   // Track measured dimensions from React Flow's dimension changes.
   // These arrive as { type: 'dimensions', id, dimensions } in onNodesChange.
@@ -929,17 +1138,15 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     prevMeasuredSigRef.current = '';
     // Bump generation so any in-flight Pass 2 from the prior layoutKey is ignored.
     pass2GenRef.current += 1;
-    const doc = {
-      components: componentsRef.current,
-      trails: trailsRef.current,
-    };
+    const doc = layoutDocRef.current;
     void buildSubsystemGraph(doc, {
       maxNodeWidth,
       showEdgeLabels,
       showSingletonFrames,
       moduleNesting,
-      graphifyRelations: graphifyRelationsRef.current,
+      graphifyRelations: layoutRelationsRef.current,
       orderByLine,
+      layoutDirection: committedDirection,
       codeProcessKeys,
     })
       .then(({ nodes, edges: e, absoluteRects }) => {
@@ -963,7 +1170,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
         setLayoutReady(true);
       });
     return () => { alive = false; };
-  }, [layoutKey, maxNodeWidth, showEdgeLabels, moduleNesting]);
+  }, [layoutKey, maxNodeWidth, showEdgeLabels, moduleNesting, committedDirection]);
 
   // Pass 2: once every leaf node has a measured dimension, re-run ELK.
   // Group parents are sized by ELK, not measured — exclude them or pass 2
@@ -989,8 +1196,8 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     const measuredHeights = new Map(leafNodes.map((n) => [n.id, dims.get(n.id)!.height]));
     const gen = ++pass2GenRef.current;
     void buildSubsystemGraph(
-      { components, trails },
-      { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights, showSingletonFrames, moduleNesting, graphifyRelations, orderByLine, codeProcessKeys },
+      layoutDoc,
+      { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights, showSingletonFrames, moduleNesting, graphifyRelations: layoutRelations, orderByLine, layoutDirection: committedDirection, codeProcessKeys },
     )
       .then(({ nodes, edges: e, absoluteRects }) => {
         if (gen !== pass2GenRef.current) return;
@@ -1003,7 +1210,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
         // Reveal Pass 1 layout rather than leaving the cover up forever.
         setLayoutReady(true);
       });
-  }, [built.nodes, components, trails, graphifyRelations, orderByLine, maxNodeWidth, showEdgeLabels, moduleNesting]);
+  }, [built.nodes, layoutDoc, layoutRelations, orderByLine, maxNodeWidth, showEdgeLabels, moduleNesting, committedDirection]);
 
   // After Pass 1 commits, try Pass 2 immediately with retained measurements.
   // Same-id live updates often get no new React Flow `dimensions` events, so
@@ -1652,6 +1859,12 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     return proposedStampedEdges.map((e) => ({ ...e, hidden: !edgeInView(e) }));
   }, [proposedStampedEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds, issueFocusEdgeIds, resolvedEdgeView]);
 
+  // Gated on layoutReady so the pre-reveal Pass 1 swap never flashes a count.
+  const unroutedIds = useMemo(
+    () => (layoutReady ? unroutedEdgeIds(dispEdges) : []),
+    [dispEdges, layoutReady],
+  );
+
   const onNodesChange = useCallback(
     (changes: NodeChange[]) => {
       // Capture dimension changes (React Flow's measurement callback).
@@ -1681,6 +1894,9 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   );
 
   useEffect(() => {
+    // A layout flip runs its own camera refit when the new layout lands. This
+    // mount/edit fit would otherwise fire mid-flip and fight it.
+    if (layoutFlipping) return;
     const t = setTimeout(() => {
       fitView({ padding: 0.1, includeHiddenNodes: false, minZoom: 0.05, maxZoom: 2, duration: 200 });
     }, 200);
@@ -2768,7 +2984,13 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
       focusedStepIndex={focusedStepIndex}
       hoveredTrailStep={hoveredTrailStep}
       onToggleCollapsed={toggleTrailCollapsed}
-      onFocusFlow={focusTrailEdges}
+      onFocusFlow={(tl) => {
+        // While a solo layout is on, following the selection keeps the canvas
+        // and the highlighted flow in agreement instead of leaving the graph
+        // pinned to a flow the user just navigated away from.
+        if (layoutTrailId != null) setLayoutTrailId(tl.id);
+        focusTrailEdges(tl);
+      }}
       onClearFocus={clearTrailFocus}
       onFocusStep={focusTrailStep}
       onHoverStep={(tl, i) => {
@@ -2785,6 +3007,8 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
       }}
       onReorder={onReorderTrails}
       proposedAliases={proposedAliases}
+      layoutFocusedTrailId={layoutTrailId}
+      onFocusLayout={toggleLayoutFocus}
     />
   ) : treeFilePaths.length > 0 ? (
     <>
@@ -2851,6 +3075,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
             overlays shift with the canvas, not the labels. Collapses when the
             file drawer fills the column (whole-file reading). */}
         <div
+          className={layoutFlipping ? LAYOUT_FLIP_CLASS : undefined}
           style={{
             position: 'relative',
             flex: collapseCanvas ? 0 : 1,
@@ -2870,6 +3095,8 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
             overflow: 'hidden',
             pointerEvents: 'none',
             zIndex: 5,
+            opacity: layoutFlipping ? 0 : 1,
+            transition: `opacity ${LAYOUT_FLIP_EDGE_MS}ms ease`,
           }}
         >
           {edgeLabels.map((lbl) => {
@@ -3044,6 +3271,11 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
         nodeTypes={nodeTypes}
         edgeTypes={edgeTypes}
         className={GRAPH_CANVAS_CLASS}
+        // The key above remounts ReactFlow when the node/edge SET changes (a
+        // trail-focus layout, a filtered model). A remount otherwise resets the
+        // viewport to identity — a visible jump to scale 1 before the post-flip
+        // refit. Seed the new instance with the viewport the old one had.
+        defaultViewport={viewport}
         {...GRAPH_NAV_PROPS}
         onNodeClick={onNodeClick}
         onNodeDoubleClick={onNodeDoubleClick}
@@ -3062,6 +3294,78 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
       >
         <GraphChrome />
       </ReactFlow>
+      {!hideLayoutToggle && (
+        <button
+          type="button"
+          onClick={() =>
+            changeLayoutDirection(
+              requestedDirection === 'horizontal' ? 'vertical' : 'horizontal',
+            )
+          }
+          disabled={layoutFlipping}
+          title={
+            requestedDirection === 'horizontal'
+              ? 'Switch to a vertical layout (top-to-bottom)'
+              : 'Switch to a horizontal layout (left-to-right)'
+          }
+          aria-label={
+            requestedDirection === 'horizontal'
+              ? 'Switch to vertical layout'
+              : 'Switch to horizontal layout'
+          }
+          style={{
+            position: 'absolute',
+            top: 10,
+            right: 10,
+            zIndex: 6,
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 5,
+            padding: '4px 9px',
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 6,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            color: theme.colors.textSecondary,
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+            cursor: layoutFlipping ? 'default' : 'pointer',
+            opacity: layoutFlipping ? 0.55 : 1,
+          }}
+        >
+          {requestedDirection === 'horizontal' ? (
+            <ArrowDown size={13} aria-hidden="true" />
+          ) : (
+            <ArrowRight size={13} aria-hidden="true" />
+          )}
+          {requestedDirection === 'horizontal' ? 'Vertical' : 'Horizontal'}
+        </button>
+      )}
+      {unroutedIds.length > 0 && (
+        <div
+          role="status"
+          title={`Edges with no routed path (not drawn):\n${unroutedIds.join('\n')}`}
+          style={{
+            position: 'absolute',
+            top: 10,
+            left: 10,
+            zIndex: 6,
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 6,
+            padding: '4px 10px',
+            fontSize: theme.fontSizes[0],
+            fontFamily: theme.fonts.body,
+            color: theme.colors.text,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${theme.colors.warning ?? '#d4a017'}`,
+            borderRadius: 6,
+            boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+          }}
+        >
+          <Unlink size={13} color={theme.colors.warning ?? '#d4a017'} aria-hidden />
+          {unroutedIds.length} {unroutedIds.length === 1 ? 'edge' : 'edges'} not drawn
+        </div>
+      )}
       {/* Graph / trail / step titles — non-interactive chips at the top
           of the canvas. Graph-only embeds use these without opening the sidebar. */}
       {(graphTitle || overlayTrailTitle || overlayTrailStep) && (
@@ -3322,8 +3626,10 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
           </div>
         </div>
       )}
-      {/* Startup cover — hides measurement, layout swap, and camera settle. */}
-      <GraphLayoutCover revealed={layoutReady} />
+      {/* Startup cover — hides measurement, layout swap, and camera settle.
+          Kept away during a direction flip: the flip is meant to be watched,
+          and the cover would swallow the node slide. */}
+      <GraphLayoutCover revealed={layoutReady || layoutFlipping} />
       {canvasOverlay}
       {liveEvents ? <MaintainLivePanel {...liveEvents} /> : null}
       </div>